# Query Response Format

Pinot query responses are SQL-like tabular payloads with a small set of execution statistics around them. This page documents the fields you are most likely to inspect when debugging query behavior or paging through large results.

## Response Shape

Standard broker query responses include a `resultTable` with:

| Field                                    | Meaning                             |
| ---------------------------------------- | ----------------------------------- |
| `resultTable.dataSchema.columnNames`     | Names returned by the query         |
| `resultTable.dataSchema.columnDataTypes` | Data types for each returned column |
| `resultTable.rows`                       | Row values in column order          |

Cursor-backed responses still use the same `resultTable` shape, but the `rows` array contains only the current page.

## Cursor Fields

When a query is submitted with `getCursor=true`, Pinot adds cursor metadata around the normal broker response:

| Field                     | Meaning                                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `requestId`               | Cursor identifier used with `/responseStore/{requestId}`                                                                    |
| `numRowsResultSet`        | Total rows available across the full result set                                                                             |
| `offset`                  | Zero-based offset of the current page                                                                                       |
| `numRows`                 | Number of rows returned in the current page                                                                                 |
| `brokerHost`              | Broker host that owns the response store                                                                                    |
| `brokerPort`              | Broker port that owns the response store                                                                                    |
| `submissionTimeMs`        | Timestamp when Pinot created the response-store entry                                                                       |
| `expirationTimeMs`        | Timestamp when Pinot considers the cursor expired                                                                           |
| `cursorResultWriteTimeMs` | Time spent writing the original result into the response store; typically populated on the initial cursor-creating response |
| `cursorFetchTimeMs`       | Time spent reading the current page from the response store                                                                 |
| `bytesWritten`            | Serialized size of the stored result                                                                                        |

## Execution Stats

| Field                          | Meaning                                                                                  |
| ------------------------------ | ---------------------------------------------------------------------------------------- |
| `timeUsedMs`                   | Broker-side time spent handling the query                                                |
| `numServersQueried`            | Number of servers asked to process the query                                             |
| `numServersResponded`          | Number of servers that returned a response                                               |
| `numSegmentsQueried`           | Number of segments considered for the query                                              |
| `numSegmentsProcessed`         | Number of segments actually processed                                                    |
| `numSegmentsMatched`           | Number of segments with at least one match                                               |
| `numDocsScanned`               | Number of documents selected after filtering                                             |
| `numEntriesScannedInFilter`    | Filter-phase entries scanned                                                             |
| `numEntriesScannedPostFilter`  | Post-filter entries scanned                                                              |
| `numGroupsLimitReached`        | Whether group-by trimming hit the limit                                                  |
| `numGroupsWarningLimitReached` | Whether group-by execution crossed the configured warning threshold for number of groups |
| `stageStats`                   | Per-stage stats for multi-stage queries                                                  |
| `exceptions`                   | Query-processing exceptions, if any                                                      |
| `rlsFiltersApplied`            | Whether row-level security predicates were injected                                      |

## Example

```bash
curl -H "Content-Type: application/json" -X POST \
  -d '{"sql":"SELECT moo, bar, foo FROM myTable ORDER BY foo DESC"}' \
  http://localhost:8099/query/sql
```

Cursor example:

```bash
curl -H "Content-Type: application/json" -X POST \
  -d '{"sql":"SELECT * FROM myTable LIMIT 100000"}' \
  'http://localhost:8099/query/sql?getCursor=true&numRows=1000'
```

## What this page covered

* The structure of Pinot broker responses.
* The execution stats that matter most when debugging performance or correctness.
* The fields that differ between a plain result and a multi-stage query response.

## Next step

If the field names look right but the data is not, inspect the query plan and response-store flow next.

## Related pages

* [API Reference](/reference/api-reference.md)
* [Broker Query API](/reference/api-reference/query-api.md)
* [Query using Cursors](/build-with-pinot/querying-and-sql/query-execution-controls/query-using-cursors.md)
* [Querying Pinot](/build-with-pinot/querying-and-sql/querying-pinot.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/api-reference/query-response-format.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.