# 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](https://docs.pinot.apache.org/reference/api-reference)
* [Broker Query API](https://docs.pinot.apache.org/reference/api-reference/query-api)
* [Query using Cursors](https://docs.pinot.apache.org/build-with-pinot/querying-and-sql/query-execution-controls/query-using-cursors)
* [Querying Pinot](https://docs.pinot.apache.org/build-with-pinot/querying-and-sql/querying-pinot)