> 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/build-with-pinot/indexing/compression-stats.md).

# Compression Stats

Measure forward-index and dictionary compression coverage for a Pinot table.

Compression stats let you inspect how much serialized column-value data Pinot stores in forward indexes and dictionaries after compression. The feature is off by default and surfaces through the existing controller table size and metadata APIs.

## Enable collection

Set `tableIndexConfig.compressionStatsEnabled` to `true` in the table config:

```json
{
  "tableIndexConfig": {
    "compressionStatsEnabled": true
  }
}
```

Pinot records stats only for segments built, or forward indexes rewritten, while the flag is enabled. Existing segments are not backfilled.

## Query the stats

Use the controller APIs documented in [Controller API Examples](/reference/api-reference/controller-api.md):

* `GET /tables/{tableName}/size` returns a `compressionStats` summary for each covered offline or realtime sub-table. Add `includeColumnCompressionStats=true` to include `columnCompressionStats`.
* `GET /tables/{tableName}/metadata?type=OFFLINE` returns the offline table's aggregate `compressionStats` summary. Add `columns=...` to scope the metadata response and `includeColumnCompressionStats=true` to include per-column entries.

The table-level summary reports:

| Field                                                   | Meaning                                                                                          |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `uncompressedValueSizePerReplicaInBytes`                | Tracked serialized value bytes for one logical copy of the covered segments                      |
| `forwardIndexAndDictionaryStorageSizePerReplicaInBytes` | Forward-index and dictionary bytes on disk for the same logical copy                             |
| `compressionRatio`                                      | `uncompressedValueSizePerReplicaInBytes / forwardIndexAndDictionaryStorageSizePerReplicaInBytes` |
| `segmentsWithCompleteStats`                             | Number of logical segments that contributed complete stats                                       |
| `totalSegments`                                         | Total logical segments in the sub-table                                                          |
| `partialCoverage`                                       | `true` when one or more logical segments could not contribute stats                              |

Per-column entries break out the column name, observed index types, aggregate sizes, ratio, and `encodingBreakdown`. Raw forward indexes report the chunk compression type; dictionary-encoded columns report combined forward-index and dictionary bytes. V7 raw forward indexes selected by `codecSpec` also report uncompressed value size and contribute to the ratio, including after a forward-index rewrite. Their codec pipeline is not one legacy chunk compression type, so `chunkCompressionType` is omitted for those entries.

## Coverage caveats

Only eligible forward-index columns contribute to the ratio. Columns without a forward index, and older segments that do not have persisted value-size metadata, are excluded from the summary and from per-column coverage.

In verbose `GET /tables/{tableName}/size` responses, Pinot selects one complete replica for each logical segment when it attaches segment-level compression fields under `segments.<segment>.serverInfo.<server>`. Other replicas still report disk size, but not segment-level compression details.

`GET /tables/{tableName}/metadata` currently supports offline tables only. During rolling upgrades or mixed old/new segment populations, `partialCoverage` stays `true` until Pinot can read stats for every covered logical segment.

## Controller gauges

When compression stats are available for a table, the lead controller emits these gauges:

| Gauge                                                                 | Unit    |
| --------------------------------------------------------------------- | ------- |
| `tableCompressionStatsRatioPercent`                                   | Percent |
| `tableCompressionStatsUncompressedValueSizePerReplica`                | Bytes   |
| `tableCompressionStatsForwardIndexAndDictionaryStorageSizePerReplica` | Bytes   |

These gauges are removed when collection is disabled or when no covered segment remains.


---

# 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/build-with-pinot/indexing/compression-stats.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.