# Cluster Configuration

Cluster configuration values are stored centrally and applied across Pinot components. Use this page when the setting should affect the cluster as a whole instead of a single broker, server, or controller process.

## Key Areas

| Area                                        | Why it matters                                                                 | Jump to               |
| ------------------------------------------- | ------------------------------------------------------------------------------ | --------------------- |
| [Cluster configs](#cluster-configs)         | Global config values stored in ZooKeeper and read by Pinot components          | Core cluster behavior |
| [Query safety](#query-safety)               | Broker query limits, query-console visibility, and multi-stage engine controls | Query guardrails      |
| [Resource accounting](#resource-accounting) | CPU and memory sampling plus automatic query killing                           | Workload isolation    |
| [Cluster config APIs](#cluster-config-apis) | Controller endpoints for reading and updating cluster config                   | Operational workflows |

## Cluster Configs

These settings control baseline cluster behavior and compatibility semantics.

| Property                                                 | Default            | Description                                                                                                                                                                                                                                                                                                                  |
| -------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allowParticipantAutoJoin                                 | true               | Helix property that allows Pinot servers, brokers, and controllers to automatically join the cluster. When set to `false`, you must explicitly invoke the `/Instance/addInstance` API. Pinot checks this property only when a node starts and it has no effect once the node is already connected.                           |
| enable.case.insensitive                                  | true               | Pinot queries are case insensitive by default, including table and column names. If you set this to `false`, Pinot uses the exact case defined in the schema. This property is applicable to brokers and is read only when the broker starts, so changing it requires a broker restart.                                      |
| default.hyperloglog.log2m                                | 8                  | Default `log2m` value for HyperLogLog-based approximate distinct-count functions.                                                                                                                                                                                                                                            |
| max.segment.completion.time.millis                       | 300000 (5 minutes) | Cluster config for the maximum time allowed for LLC real-time segment completion after `segmentCommitStart`. Increase this when large segments, deep-store upload time, or retries can push real-time segment completion beyond 5 minutes. Removing the cluster config reverts Pinot to the default.                         |
| pinot.field.spec.default.json.max.length                 | 512                | Default `maxLength` Pinot applies to `JSON` columns when the field spec does not set one explicitly. Set this as a cluster config for a cluster-wide default, or in local instance config for a node-local override.                                                                                                         |
| pinot.field.spec.default.json.max.length.exceed.strategy | NO\_ACTION         | Default `maxLengthExceedStrategy` Pinot applies to `JSON` columns when the field spec does not set one explicitly. Supported values are `TRIM_LENGTH`, `SUBSTITUTE_DEFAULT_VALUE`, `NO_ACTION`, and `ERROR`. Set this as a cluster config for a cluster-wide default, or in local instance config for a node-local override. |

## Query Safety

These settings control broker-side query protection, query-console exposure, and cluster-wide query engine behavior.

| Property                                                               | Default | Description                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pinot.broker.enable.query.limit.override                               | false   | Protects the cluster from queries with very large `LIMIT` values. When enabled, Pinot brokers override query limits that exceed the broker config `pinot.broker.query.response.limit` (default `2147483647`). For example, if `pinot.broker.query.response.limit=1000`, then `SELECT * FROM myTable LIMIT 25000` is rewritten to use `LIMIT 1000`.        |
| queryConsoleOnlyView                                                   | false   | Shows only the query console in the controller web UI. Use this when you do not want to expose cluster or ZooKeeper UI pages to end users.                                                                                                                                                                                                                |
| hideQueryConsoleTab                                                    | false   | Hides the query console tab from the controller web UI.                                                                                                                                                                                                                                                                                                   |
| pinot.multistage.engine.tls.enabled                                    | false   | Enables TLS on brokers and servers for the multi-stage query engine. When enabled, Pinot uses TLS for gRPC connections between brokers and servers for plan dispatch and final results, and between servers for data shuffle and exchange.                                                                                                                |
| pinot.lucene.max.clause.count                                          | 1024    | Maximum number of clauses allowed in Lucene text-search queries. Increase this value when complex text queries hit Lucene `TooManyClauses` exceptions.                                                                                                                                                                                                    |
| pinot.multistage.engine.enabled                                        | true    | Enables the multi-stage query engine for the cluster. When set to `false`, all queries use the single-stage engine.                                                                                                                                                                                                                                       |
| pinot.beta.multistage.engine.max.server.query.threads                  | -1      | Cluster-wide fallback for multi-stage query concurrency controls. Brokers use this value when `pinot.broker.mse.max.server.query.threads` is not set to a positive number. Servers also use it as the base value for deriving a hard limit when `pinot.server.query.executor.mse.max.execution.threads` is not set to a positive number.                  |
| pinot.beta.multistage.engine.max.server.query.threads.hardlimit.factor | 4       | Multiplier used by servers to derive a hard limit for multi-stage executor tasks when no server-local limit is configured. The derived hard limit is `pinot.beta.multistage.engine.max.server.query.threads * pinot.beta.multistage.engine.max.server.query.threads.hardlimit.factor`. If either value is non-positive, server hard limiting is disabled. |

## Resource Accounting

These settings enable per-query CPU and memory tracking plus optional protection against runaway queries.

| Property                                       | Default | Description                                                                                                                                                 |
| ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accounting.factory.name                        |         | Fully qualified class name for the resource-accounting factory. Resource accounting tracks CPU time and memory allocation per query for workload isolation. |
| accounting.enable.thread.cpu.sampling          | false   | Enables per-thread CPU time sampling for resource accounting. This adds visibility into CPU usage per query, but also adds measurement overhead.            |
| accounting.enable.thread.memory.sampling       | false   | Enables per-thread memory-allocation sampling for resource accounting.                                                                                      |
| accounting.oom.enable.killing.query            | false   | When `true` and resource accounting is enabled, Pinot can kill queries that consume excessive memory in order to prevent `OutOfMemoryError`.                |
| accounting.cpu.time.based.killing.enabled      | false   | When `true`, Pinot can kill queries that exceed the CPU time threshold configured by `accounting.cpu.time.based.killing.threshold.ms`.                      |
| accounting.cpu.time.based.killing.threshold.ms | 30000   | CPU time threshold in milliseconds beyond which a query may be killed when CPU-based killing is enabled.                                                    |

## Cluster Config APIs

Use the controller APIs to inspect or update cluster-level configuration.

### List All Cluster Configs

<mark style="color:blue;">`GET`</mark> `http://<controller>:<port>/cluster/configs`

**Description**

* Lists all configurations set at the cluster level.

{% tabs %}
{% tab title="200 " %}

```json
{
  "allowParticipantAutoJoin": "true",
  "enable.case.insensitive": "false",
  "pinot.broker.enable.query.limit.override": "false",
  "default.hyperloglog.log2m": "8"
}
```

{% endtab %}
{% endtabs %}

### Update Cluster Configs

<mark style="color:green;">`POST`</mark> `http://<controller>:<port>/cluster/configs`

Add new cluster configs or update existing ones.

#### Request Body

| Name | Type   | Description                                                                                                    |
| ---- | ------ | -------------------------------------------------------------------------------------------------------------- |
|      | string | JSON body containing the configs map for new or updated values. Example: `{\"queryConsoleOnlyView\":\"true\"}` |

{% tabs %}
{% tab title="200 " %}

```json
{
  "status": "Updated cluster config."
}
```

{% endtab %}
{% endtabs %}

Example:

## Related Pages

* [Configuration Reference](/reference/configuration-reference.md)
* [Table Configuration](/reference/configuration-reference/table.md)
* [Broker](/reference/configuration-reference/broker.md)
* [Multi-Stage Query Engine](/build-with-pinot/querying-and-sql/sse-vs-mse.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pinot.apache.org/reference/configuration-reference/cluster.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.