> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/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={"dark"}
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