[reakaleek]

Every indexed API operation now carries its own api.words, api.group and api.id_words fields. Nothing changes for readers yet; the API search query that reads them follows in the next pull request.

Affects: Search, API reference

Prompt summary: The API search box ranks search retriever perfectly but returns bogus results for cluster flat_settings and nothing useful for es|ql drop_null_columns, although both are real query parameters. Asked why, and then asked to design the fix properly instead of patching the rule, the work became a per-token query model delivered as a stack of three changes. This is the bottom layer, the index fields that model reads.

Why

The API search reads an operation's name words only inside search_title, where they sit next to the product label, the HTTP method and the group. A query cannot weight a word of the operation id (cluster, esql) apart from a word of its title or its group, and it has no way to prefer esql-query over esql-async-query-stop when both carry the typed field. The new query model needs each of those signals as a field of its own.

What

Words and group as fields of their own

ApiOperationMetadata gains Words, the plain words of the operation id and its literal path segments that ApiSearchWords.Of already computes for search_title, and Group, the title of the operation's group as the explorer shows it. Both are text fields with the synonym analyzers, and api.words also has a completion search-as-you-type multi-field for prefix matching. #4666 kept the group out of api.* because its query never read it; the test that asserted the absence now asserts the field.

A specificity prior

IdWords counts the words of the operation id alone and is mapped as a rank_feature with negative score impact, like navigation.depth. Fewer id words is a more specific operation, so a query can break ties toward it.

The exporter fills them

OpenApiDocumentExporter sets the three fields next to the existing operation metadata. The document hash already covers the whole api record, so an incremental index run re-syncs every operation.

Verify

dotnet test tests/Elastic.ApiExplorer.Tests/
# OfOperationId_OperationId_ReturnsIdWordsOnly, ConvertToDocuments_TaggedOperations_IndexGroupAndWordsInSearchTitle
dotnet test tests/Elastic.Documentation.Api.Tests/
# Mapping_ApiWordsAndGroup_AreSynonymText, Mapping_ApiIdWords_IsRankFeatureWithNegativeImpact

Out of scope: the query that reads the new fields, and the removal of the two-reading parse it replaces. Both follow in this stack.

Risk: the api mapping changes, so the first index run after deploy rolls the indices over to new dated indices, about six minutes on dev, as the last mapping change did.

Stack: 1 of 3. #4699 (the per-word query) and #4700 (the removal of the legacy readings) sit on top of this branch.

🤖 Generated with Claude Code

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4698/