T digest field type docs by not-napoleon · Pull Request #140478 · elastic/elasticsearch

not-napoleon · 2026-01-09T21:46:26Z

This adds documentation for the new t-digest field type.

elasticsearchmachine · 2026-01-09T21:46:51Z

Pinging @elastic/es-storage-engine (Team:StorageEngine)

elasticsearchmachine · 2026-01-09T21:46:51Z

Pinging @elastic/core-docs (Team:Docs)

github-actions · 2026-01-09T21:48:35Z

🔍 Preview links for changed docs

github-actions · 2026-01-09T21:48:36Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

Conflicts: docs/reference/query-languages/esql/limitations.md

kkrik-es · 2026-01-13T06:47:35Z

docs/reference/elasticsearch/mapping-reference/t-digest.md

+  In general, the higher this number, the more space on disk the field will use
+  but the more accurate the sketch approximations will be.  Default is `100`
+* `digest_type`, which selects the merge strategy to use with the sketch.  Valid
+  values are `hybrid`, `avl_tree`, and `merging`. The default is `hybrid`.


I missed this, we shouldn't expose such details. I'd say we hide it entirely, and maybe add something like [execution_hint: high_accuracy] if there's an ask for it.

I created #140736 to address this. For now, I'll just pull this bit out of the docs so we can merge it, and I'll update them when I change the parameter.

This is addressed in this PR.

kkrik-es · 2026-01-13T06:49:05Z

docs/reference/elasticsearch/mapping-reference/t-digest.md

+indexed.
+
+`tdigest` fields are supported in ES|QL; see the
+[ES|QL reference](/reference/query-languages/esql.md) for details.


Maybe add a note here about notable aggregation functions, i.e. percentile, min, max, sum and count.

kkrik-es · 2026-01-13T06:50:36Z

docs/reference/elasticsearch/mapping-reference/t-digest.md

+}
+```
+
+Indexing a minimal document


Nit: add newline after this one.

docs/reference/elasticsearch/mapping-reference/t-digest.md

leemthompo

I left a few wording and structural suggestions, along with a few nits :)

Let me know if anything is unclear, I'll defer to @kkrik-es for the final approval, because this smells a lot more like math than I'm comfortable with 😉

[sorry some of the comments are out of order, so the changes aren't 100% linear]

docs/reference/elasticsearch/mapping-reference/t-digest.md

leemthompo · 2026-01-15T16:38:41Z

docs/reference/elasticsearch/mapping-reference/t-digest.md

+will compute them based on the given `centroids` and `counts`, with some loss of
+accuracy.
+
+::::{important}


I'd move this to ## Limitations subheading instead of an admonition like this

I can do that if you want, but I'm just copying how it is in the Exponential Histogram Field Docs

I think it's easier to scan and find if we use a subheading, but it's not a huge deal :)

Maybe update both pages?

Done, updated both.

docs/reference/elasticsearch/mapping-reference/t-digest.md

docs/reference/elasticsearch/mapping-reference/field-data-types.md

docs/reference/elasticsearch/mapping-reference/t-digest.md

Co-authored-by: Liam Thompson <leemthompo@gmail.com>

…d-type-docs' into t-digest-field-type-docs

…s.md Co-authored-by: Liam Thompson <leemthompo@gmail.com>

…d-type-docs' into t-digest-field-type-docs

elasticsearchmachine · 2026-01-20T18:19:34Z

Hi @not-napoleon, I've created a changelog YAML for you.

not-napoleon · 2026-01-20T18:20:06Z

I folded the change for the digest type parameter into this PR, and marked it as an enhancement as result.

…d-type-docs' into t-digest-field-type-docs

kkrik-es · 2026-01-21T07:17:11Z

docs/reference/elasticsearch/mapping-reference/t-digest.md

+  In general, the higher this number, the more space on disk the field will use
+  but the more accurate the sketch approximations will be.  Default is `100`
+* `digest_type`, which selects the merge strategy to use with the sketch.  Valid
+  values are `default` and `high_accuracy`.  The default is `default`.


Maybe explain that the high_accuracy one is slower and allocates more memory? While the default is optimized for merging speed and constant memory footprint.

docs/reference/elasticsearch/mapping-reference/t-digest.md

…d-type-docs' into t-digest-field-type-docs

docs/reference/elasticsearch/mapping-reference/t-digest.md

elasticsearchmachine · 2026-01-27T15:05:28Z

💔 Backport failed

Status	Branch	Result
❌	9.3	Commit could not be cherrypicked due to conflicts

You can use sqren/backport to manually backport by running backport --upstream elastic/elasticsearch --pr 140478

Adds documentation for the T-Digest field type, and makes a small change to the Exponential Histogram field type docs for consistency. While working on this, we decided the initial way of specifying the digest type for the t-digest field was overly complex, and moved to a simpler set of choices. That code change is also included in this mostly docs update. --------- Co-authored-by: Liam Thompson <leemthompo@gmail.com> Co-authored-by: elasticsearchmachine <infra-root+elasticsearchmachine@elastic.co> Conflicts: docs/reference/elasticsearch/mapping-reference/exponential-histogram.md docs/reference/elasticsearch/toc.yml docs/reference/query-languages/esql/limitations.md

Adds documentation for the T-Digest field type, and makes a small change to the Exponential Histogram field type docs for consistency. While working on this, we decided the initial way of specifying the digest type for the t-digest field was overly complex, and moved to a simpler set of choices. That code change is also included in this mostly docs update. --------- Co-authored-by: Liam Thompson <leemthompo@gmail.com> Co-authored-by: elasticsearchmachine <infra-root+elasticsearchmachine@elastic.co>

not-napoleon added 2 commits January 9, 2026 15:41

main field type doc

c6a1c39

references

5fd58cd

not-napoleon added >docs General docs changes auto-backport Automatically create backport pull requests when merged :StorageEngine/Mapping The storage related side of mappings v9.3.0 v9.4.0 labels Jan 9, 2026

elasticsearchmachine added Team:Docs Meta label for docs team Team:StorageEngine labels Jan 9, 2026

Merge branch 'main' into t-digest-field-type-docs

3e9b64f

Conflicts: docs/reference/query-languages/esql/limitations.md

kkrik-es reviewed Jan 13, 2026

View reviewed changes

docs/reference/elasticsearch/mapping-reference/t-digest.md Show resolved Hide resolved

kkrik-es requested a review from marciw January 13, 2026 06:52

marciw requested review from a team and removed request for marciw January 13, 2026 15:00

leemthompo reviewed Jan 15, 2026

View reviewed changes

not-napoleon mentioned this pull request Jan 15, 2026

Add support for storing and querying T-Digest sketches #137649

Closed

57 tasks

kpatticha mentioned this pull request Jan 20, 2026

[Metrics][Discover] Ingest and validate histogram data in a cluster elastic/kibana#248722

Closed

6 tasks

not-napoleon and others added 5 commits January 20, 2026 11:11

Merge branch 'main' into t-digest-field-type-docs

0657deb

Apply suggestions from code review

ae59b37

Co-authored-by: Liam Thompson <leemthompo@gmail.com>

Merge remote-tracking branch 'refs/remotes/not-napoleon/t-digest-fiel…

3bc161b

…d-type-docs' into t-digest-field-type-docs

Update docs/reference/elasticsearch/mapping-reference/field-data-type…

f590230

…s.md Co-authored-by: Liam Thompson <leemthompo@gmail.com>

Merge remote-tracking branch 'refs/remotes/not-napoleon/t-digest-fiel…

edea0bd

…d-type-docs' into t-digest-field-type-docs

not-napoleon removed the >docs General docs changes label Jan 20, 2026

elasticsearchmachine removed the Team:Docs Meta label for docs team label Jan 20, 2026

Update docs/changelog/140478.yaml

612c151

not-napoleon and others added 6 commits January 20, 2026 13:22

requeted changes

d920edb

Merge remote-tracking branch 'refs/remotes/not-napoleon/t-digest-fiel…

111a92b

…d-type-docs' into t-digest-field-type-docs

Merge branch 'main' into t-digest-field-type-docs

0692e14

[CI] Auto commit changes from spotless

a5de408

spotless apply

2bf78a7

Merge remote-tracking branch 'refs/remotes/not-napoleon/t-digest-fiel…

6d239a1

…d-type-docs' into t-digest-field-type-docs

kkrik-es reviewed Jan 21, 2026

View reviewed changes

not-napoleon added 2 commits January 21, 2026 08:46

requeted changes

2e7423a

Merge branch 'main' into t-digest-field-type-docs

826bad6

leemthompo reviewed Jan 21, 2026

View reviewed changes

docs/reference/elasticsearch/mapping-reference/t-digest.md Outdated Show resolved Hide resolved

not-napoleon added 2 commits January 21, 2026 09:04

fix internal links

c5b6014

Merge remote-tracking branch 'refs/remotes/not-napoleon/t-digest-fiel…

c9a4f0c

…d-type-docs' into t-digest-field-type-docs

kkrik-es reviewed Jan 21, 2026

View reviewed changes

docs/reference/elasticsearch/mapping-reference/t-digest.md Outdated Show resolved Hide resolved

not-napoleon added 3 commits January 23, 2026 14:23

requeted changes

80cb581

Merge branch 'main' into t-digest-field-type-docs

1fbe1b0

Merge branch 'main' into t-digest-field-type-docs

4aa5c1d

not-napoleon requested a review from kkrik-es January 26, 2026 20:05

kkrik-es approved these changes Jan 27, 2026

View reviewed changes

not-napoleon merged commit 0f8e5d8 into elastic:main Jan 27, 2026
35 checks passed

elasticsearchmachine added the backport pending label Jan 27, 2026

This was referenced Jan 27, 2026

[9.3] T digest field type docs #140478 #141368

Merged

TDigest Field should use higher level algorithm abstractions #140736

Closed

Conversation

not-napoleon commented Jan 9, 2026

elasticsearchmachine commented Jan 9, 2026

elasticsearchmachine commented Jan 9, 2026

github-actions bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

github-actions bot commented Jan 9, 2026

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kkrik-es Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

leemthompo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elasticsearchmachine commented Jan 20, 2026

not-napoleon commented Jan 20, 2026

kkrik-es Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

elasticsearchmachine commented Jan 27, 2026

💔 Backport failed

Labels

4 participants

github-actions bot commented Jan 9, 2026 •

edited

Loading

kkrik-es Jan 13, 2026 •

edited

Loading

leemthompo left a comment •

edited

Loading

kkrik-es Jan 21, 2026 •

edited

Loading