> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-claude-gallant-ramanujan-8g6i2k.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Apache Pinot

> Broker-level connection details and required Pinot SQL features for wiring Cube to an Apache Pinot cluster via environment variables.

[Apache Pinot][link-pinot] is a real-time distributed OLAP datastore purpose-built
for low-latency, high-throughput analytics, and perfect for user-facing analytical
workloads. [StarTree][link-startree] is a fully-managed platform for Pinot.

## Prerequisites

* The hostname for the [Pinot][pinot] broker
* The port for the [Pinot][pinot] broker

Note that the following features should be enabled in your Pinot cluster:

* [Multi-stage query engine][link-pinot-msqe].
* [Advanced null value support][link-pinot-nvs].

## Setup

<Note>
  Currently, Apache Pinot is not shown in the list of available data sources in the UI.
  However, you can still [configure](https://github.com/cube-js/cube/issues/8579#issuecomment-2453545048)
  it using environment variables.
</Note>

### Manual

Add the following to a `.env` file in your Cube project:

```dotenv theme={null}
CUBEJS_DB_TYPE=pinot
CUBEJS_DB_HOST=http[s]://pinot.broker.host
CUBEJS_DB_PORT=8099
CUBEJS_DB_USER=pinot_user
CUBEJS_DB_PASS=**********
```

## Environment Variables

| Environment Variable | Description | Possible Values | Required |
| - | - | - | :-: |
| [`CUBEJS_DB_HOST`](/reference/configuration/environment-variables#cubejs_db_host) | The host URL for your Pinot broker | A valid host URL | ✅ |
| [`CUBEJS_DB_PORT`](/reference/configuration/environment-variables#cubejs_db_port) | The port for the database connection | A valid port number | ✅ |
| [`CUBEJS_DB_USER`](/reference/configuration/environment-variables#cubejs_db_user) | The username used to connect to the broker | A valid username | ❌ |
| [`CUBEJS_DB_PASS`](/reference/configuration/environment-variables#cubejs_db_pass) | The password used to connect to the broker | A valid password | ❌ |
| [`CUBEJS_DB_NAME`](/reference/configuration/environment-variables#cubejs_db_name) | The database name for StarTree | A valid name | ❌ |
| [`CUBEJS_DB_PINOT_NULL_HANDLING`](/reference/configuration/environment-variables#cubejs_db_pinot_null_handling) | If `true`, enables null handling. Default is `false` | `true`, `false` | ❌ |
| [`CUBEJS_DB_PINOT_AUTH_TOKEN`](/reference/configuration/environment-variables#cubejs_db_pinot_auth_token) | The authentication token for StarTree | A valid token | ❌ |
| [`CUBEJS_CONCURRENCY`](/reference/configuration/environment-variables#cubejs_concurrency) | The number of [concurrent queries][ref-data-source-concurrency] to the data source | A valid number | ❌ |

[ref-data-source-concurrency]: /admin/connect-to-data/concurrency#data-source-concurrency

## Pre-Aggregation Feature Support

### count\_distinct\_approx

Measures of type
[`count_distinct_approx`][ref-schema-ref-types-formats-countdistinctapprox] can
be used in pre-aggregations when using Pinot as a source database. To learn more
about Pinot support for approximate aggregate functions, [click
here][pinot-docs-approx-agg-fns].

## Pre-aggregation build strategies

<Info>
  To learn more about pre-aggregation build strategies, \[head
  here]\[ref-caching-using-preaggs-build-strats].
</Info>

| Feature | Works with read-only mode? | Is default? |
| - | :-: | :-: |
| Simple | ✅ | ✅ |
| Batching | - | - |
| Export bucket | - | - |

By default, Pinot uses a simple strategy to build pre-aggregations.

### Simple

No extra configuration is required to configure simple pre-aggregation builds
for Pinot.

### Batching

Pinot does not support batching.

### Export bucket

Pinot does not support export buckets.

## SSL

Cube does not require any additional configuration to enable SSL as Pinot connections are made over HTTPS.

[link-pinot]: https://pinot.apache.org/

[pinot]: https://docs.pinot.apache.org/

[link-pinot-msqe]: https://docs.pinot.apache.org/reference/multi-stage-engine

[link-pinot-nvs]: https://docs.pinot.apache.org/developers/advanced/null-value-support#advanced-null-handling-support

[pinot-docs-approx-agg-fns]: https://docs.pinot.apache.org/users/user-guide-query/query-syntax/how-to-handle-unique-counting

[ref-schema-ref-types-formats-countdistinctapprox]: /reference/data-modeling/measures#type

[link-startree]: https://startree.ai