Clarifies that the docs.count field in the _cat/indices API includes hidden nested documents.

[mridula-s109]

Summary

Clarifies that the docs.count field in the _cat/indices API includes hidden nested documents, which can lead to higher counts than expected when using field types like semantic_text.

Changes

• Updated the documentation for docs.count in CatIndicesRequest.ts to explicitly state that it includes nested documents
• Added guidance to use _count or _cat/count APIs for logical document count

Related Issues

Fixes #127354

Related PRs

• elasticsearch #136329 (semantic_text documentation update)

[mridula-s109]

Hi @leemthompo @kderusso,

I've reviewed the CatIndicesRequest.ts file and noticed that the API-level documentation already includes the necessary clarification about nested documents:

/**
 * These metrics are retrieved directly from Lucene, which Elasticsearch uses internally 
 * to power indexing and search. As a result, all document counts include hidden nested documents.
 * To get an accurate count of Elasticsearch documents, use the cat count or count APIs.
 */

These lines are already present in the main branch at lines 39-40 of the JSDoc comment for the Request interface.

Therefore, I've only updated IndicesRecord.ts to add field-level documentation for the docs.count field, which provides users with specific guidance when they encounter this field in the API response.

The documentation is now complete with:

• ✅ API-level explanation in CatIndicesRequest.ts (already existed)
• ✅ Field-level explanation in IndicesRecord.ts (added in this PR)

Please let me know if you'd like me to make any additional changes!

[Mikep86]

Thanks for addressing this! I left a couple questions/suggestions.

[leemthompo]

@mridula-s109 not sure if I shared this already, but if you want to preview your changes (or if you're curious about the the API specs workflow) you can check out https://www.elastic.co/docs/contribute-docs/api-docs/quickstart

[leemthompo]

Validation is not supported from forks

Unfortunately, need to make PRs from branches in this repo :/

[pquentin]

To get CI passing, can you please send your pull request from a branch? As mentioned in CONTRIBUTING.md. I realize that it's confusing as it's the opposite of Elasticsearch, sorry.

[mridula-s109]

Thanks everyone for the reviews and feedback! 👋

As suggested, I’ve recreated this PR from a branch within the Elastic repository to enable CI validation and unblock merging.
The new PR is available here: #5492.

I’ve carried forward all the same changes (field-level clarification for docs.count in _cat/indices) and incorporated review feedback. Closing this one in favor of the new PR.