> For the complete documentation index, see [llms.txt](https://docs.pinot.apache.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pinot.apache.org/release-1.4.0/for-users/user-guide-query/query-correlation-id.md).

# Query Correlation ID

Tracking queries on a distributed cluster may be difficult. To facilitate tracking a query, Pinot assigns a correlation ID (also known as *cid*) to each received query. This correlation ID is then included in the Mapped Diagnostic Context (also known as MDC) and can be included in the logs. For example, a query whose correlation ID is "1234" will print logs as follows using the default Log4j2 configuration provided by pinot-tools:

> 2025/06/04 13:59:17.405 INFO \[QueryLogger] \[jersey-server-managed-async-executor-0] **\[cid=1234]** SQL query for request 1234: SELECT ...

### Custom Correlation ID

By default, Pinot assigns a random correlation ID to the query as soon as the broker receives it, but clients can provide their ID by using the `clientQueryId` query option. When this option is set, Pinot will use its value as the correlation ID. For example, the following query:

```sql
set clientQueryId='myCustomCid';
select * 
from userAttributes
limit 10
```

Will use `myCustomCid` as a correlation ID, which means that logs will be something like:

> 2025/06/04 13:59:17.405 INFO \[QueryLogger] \[jersey-server-managed-async-executor-0] **\[cid=**myCustomCid**]** SQL query for request 1234: SELECT ...

This feature can be helpful in cases where queries are produced by programs that already have their correlation IDs. Remember that correlation IDs generated by Pinot are unique, but different clients can provide the same `clientQueryId` or even the same client may use the same `clientQueryId` for two different queries. This is why it is recommended to use high cardinality IDs like UUIDs when custom `clientQueryId` are provided.

The `clientQueryId` option is also used for [Query Cancellation](/release-1.4.0/for-users/user-guide-query/query-cancellation.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pinot.apache.org/release-1.4.0/for-users/user-guide-query/query-correlation-id.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.