Skip to content

Document change in default percentiles agg compression to 200 #11344

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Document change in default percentiles agg compression to 200 #11344

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
910694b
change default to 200
Oct 17, 2025
cec49e9
Apply suggestions from code review
kolchfa-aws Oct 17, 2025
dfcdb2e
Update _aggregations/metric/percentile.md
kolchfa-aws Oct 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions _aggregations/metric/percentile-ranks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
| `field` | String | Required | The numeric field used to compute percentile ranks. |
| `values` | Array of doubles | Required | The values used to calculate percentile ranks. |
| `keyed` | Boolean | Optional | If set to `false`, returns results as an array. Otherwise returns results as a JSON object. Default is `true`. |
| `tdigest.compression` | Double | Optional | Controls accuracy and memory usage of the `tdigest` algorithm. See [Precision tuning with tdigest](#precision-tuning-with-tdigest). |
| `tdigest.compression` | Double | Optional | Controls accuracy and memory usage of the `tdigest` algorithm. See [Precision tuning with tdigest](#precision-tuning-with-tdigest). Default value is `200`. |

Check failure on line 25 in _aggregations/metric/percentile-ranks.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: tdigest. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: tdigest. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_aggregations/metric/percentile-ranks.md", "range": {"start": {"line": 25, "column": 4}}}, "severity": "ERROR"}
| `hdr.number_of_significant_value_digits` | Integer | Optional | The precision setting for the HDR histogram. See [HDR histogram](#hdr-histogram). |
| `missing` | Number | Optional | The default value used when the target field is missing in a document. |
| `script` | Object | Optional | The script used to compute custom values instead of using a field. Supports inline and stored scripts. |
Expand Down Expand Up @@ -165,9 +165,9 @@

## Precision tuning with tdigest

By default, percentile ranks are calculated using the `tdigest` algorithm. You can control the trade-off between accuracy and memory usage by specifying the `tdigest.compression` parameter. Higher values provide better accuracy but require more memory. For more information about how tdigest works, see [Precision tuning with tdigest]({{site.url}}{{site.baseurl}}/aggregations/metric/percentile/#precision-tuning-with-tdigest).
By default, percentile ranks are calculated using the `tdigest` algorithm. You can control the trade-off between accuracy and memory usage by specifying the `tdigest.compression` parameter. Higher values provide better accuracy but require more memory. The default value is `200`. For more information about how tdigest works, see [Precision tuning with tdigest]({{site.url}}{{site.baseurl}}/aggregations/metric/percentile/#precision-tuning-with-tdigest).

Check failure on line 168 in _aggregations/metric/percentile-ranks.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: tdigest. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: tdigest. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_aggregations/metric/percentile-ranks.md", "range": {"start": {"line": 168, "column": 56}}}, "severity": "ERROR"}

The following example is configured with `tdigest.compression` set to `200`:
The following example is configured with `tdigest.compression` set to `300`:

```json
GET /transaction_data/_search
Expand All @@ -179,7 +179,7 @@
"field": "amount",
"values": [25, 55],
"tdigest": {
"compression": 200
"compression": 300
}
}
}
Expand Down
8 changes: 4 additions & 4 deletions _aggregations/metric/percentile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
| `field` | String | Required | The numeric field used to compute percentiles. |
| `percents` | Array of doubles | Optional | The list of percentiles returned in the response. Default is `[1, 5, 25, 50, 75, 95, 99]`. |
| `keyed` | Boolean | Optional | If set to `false`, returns results as an array. Otherwise, returns results as a JSON object. Default is `true`. |
| `tdigest.compression` | Double | Optional | Controls accuracy and memory usage of the `tdigest` algorithm. See [Precision tuning with tdigest](#precision-tuning-with-tdigest). |
| `tdigest.compression` | Double | Optional | Controls accuracy and memory usage of the `tdigest` algorithm. See [Precision tuning with tdigest](#precision-tuning-with-tdigest). Default value is 200. |

Check failure on line 27 in _aggregations/metric/percentile.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: tdigest. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: tdigest. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_aggregations/metric/percentile.md", "range": {"start": {"line": 27, "column": 4}}}, "severity": "ERROR"}
| `hdr.number_of_significant_value_digits` | Integer | Optional | The precision setting for the HDR histogram. See [HDR histogram](#hdr-histogram). |
| `missing` | Number | Optional | The default value used when the target field is missing in a document. |
| `script` | Object | Optional | The script used to compute custom values instead of using a field. Supports inline and stored scripts. |
Expand Down Expand Up @@ -218,7 +218,7 @@

The algorithm is designed to be highly accurate near the tails of the distribution---the low percentiles (such as 1st) and high percentiles (such as 99th)---which are often the most important for performance analysis. You can control the precision of the results using the `compression` parameter.

A higher `compression` value means that more centroids are used, which increases accuracy (especially in the tails) but requires more memory and CPU. A lower `compression` value reduces memory usage and speeds up execution, but the results may be less accurate.
A higher `compression` value means that more centroids are used, which increases accuracy (especially in the tails) but requires more memory and CPU. A lower `compression` value reduces memory usage and speeds up execution, but the results may be less accurate. The default value is `200`. Lower `compression` values such as `100` may perform especially poorly on low-cardinality data, such as HTTP status codes.


Use `tdigest` when:
Expand All @@ -231,7 +231,7 @@
* You are working only with integer data and want maximum speed.
* You care less about accuracy in the distribution tails and prefer faster aggregation (consider using [`hdr`](#hdr-histogram) instead).

The following example sets `tdigest.compression` to `200`:
The following example sets `tdigest.compression` to `300`:

```json
GET /latency_data/_search
Expand All @@ -242,7 +242,7 @@
"percentiles": {
"field": "load_time",
"tdigest": {
"compression": 200
"compression": 300
}
}
}
Expand Down
Loading