Skip to content

Search: preserve operation id (e.g. _bulk) in OpenAPI search_title#3614

Merged
Mpdreamz merged 2 commits into
mainfrom
fix/openapi-search-title-operation-id
Jul 6, 2026
Merged

Search: preserve operation id (e.g. _bulk) in OpenAPI search_title#3614
Mpdreamz merged 2 commits into
mainfrom
fix/openapi-search-title-operation-id

Conversation

@Mpdreamz

@Mpdreamz Mpdreamz commented Jul 6, 2026

Copy link
Copy Markdown
Member

Summary

For OpenAPI-exported docs (e.g. the Elasticsearch Bulk API, operation id _bulk), search_title currently reads "Bulk index or delete documents - Elasticsearch API - doc operation" — the operation id never appears, and its leading underscore would be lost even if it did. Users search Elasticsearch docs by REST endpoint name a lot (_bulk, _search, _cat, dotted ids like ml.start_datafeed), so this is a real, missing search token.

Root cause: OpenAPI docs are built in two stages, and the second silently overwrites the first's search_title. OpenApiDocumentExporter sets Title == SearchTitle, but ElasticsearchMarkdownExporter.CommonEnrichments then unconditionally rebuilds SearchTitle via CreateSearchTitle(), which derives extra tokens from the URL by splitting on /, , -, ., and _. For the Bulk API (URL segment operation-_bulk), that split turns _bulk into a bare bulk, which then gets deduplicated against the title's existing Bulk token and dropped entirely.

Fix: let OpenAPI docs own their SearchTitle.

  • CommonEnrichments now only rebuilds SearchTitle via CreateSearchTitle() for non-API content (doc.ContentType != "api") — markdown docs are unaffected.
  • OpenApiDocumentExporter builds a dedicated search title appending the raw operation id verbatim (underscore/casing intact): "Bulk index or delete documents - Elasticsearch API - _bulk". Also drops a stray trailing space in Title that caused the reported double space.

website-search-data check: no mapping/analyzer change needed. search_title is analyzed by synonyms_fixed_analyzer/synonyms_analyzer, both using group_tokenizer, whose delimiter set doesn't include _ or . — so _bulk (and dotted ids like ml.start_datafeed) index and search as a single token, both index- and search-time, including on the completion (search_as_you_type) sub-field. Flagged separately, not blocking: title.starts_with's EdgeNGram tokenizer token_chars omits "punctuation" and would strip a leading underscore if operation ids are ever added to Title too.

Test plan

  • dotnet build for Elastic.Markdown and Elastic.ApiExplorer succeeds
  • New OpenApiSearchTitleTests (Elastic.Markdown.Tests) — asserts CommonEnrichments preserves the API exporter's search_title and still rebuilds it for markdown docs
  • New OpenApiOperationIdSearchTitleTests (Elastic.ApiExplorer.Tests) — exercises OpenApiDocumentExporter.ConvertToDocuments against an in-memory Bulk API spec (no network), asserts search_title == "Bulk index or delete documents - Elasticsearch API - _bulk"
  • Full Elastic.Markdown.Tests and Elastic.ApiExplorer.Tests suites run; pre-existing failures are unrelated ScopedFileSystem/git-checkout tests failing in this worktree environment
  • dotnet format / lint clean (pre-push hook passed)
  • Coordinate a reindex with the website-search-data owner once merged, alongside the companion relevance-tweaks PRs (Search: sync agg/aggs synonym with website-search-data #3606, Search: guard navigation_* rank features against penalty default #3607, Search: bump contract to 0.12.0 and populate content_tier #3608)

@Mpdreamz Mpdreamz requested a review from a team as a code owner July 6, 2026 09:30
@Mpdreamz Mpdreamz requested a review from reakaleek July 6, 2026 09:30
OpenAPI docs are built in two stages, and the second silently
overwrote the first's search_title: OpenApiDocumentExporter set
Title == SearchTitle, but ElasticsearchMarkdownExporter's
CommonEnrichments then unconditionally rebuilt SearchTitle via
CreateSearchTitle(), which derives extra tokens from the URL by
splitting on '/', ' ', '-', '.', and '_'. For the Bulk API
(operation id "_bulk", URL segment "operation-_bulk"), that split
turned "_bulk" into a bare "bulk" token, which then got
deduplicated against the title's existing "Bulk" token and
dropped entirely — the literal, highly-searched "_bulk" endpoint
name never made it into search_title.

Fix: let OpenAPI docs own their SearchTitle. CommonEnrichments now
only rebuilds it for non-API content (doc.ContentType != "api");
OpenApiDocumentExporter builds a dedicated search title that appends
the raw operation id verbatim (underscore/casing intact). Also drops
a stray trailing space in Title that caused a visible double space
in the reported string.

Checked website-search-data's search_title mapping/analysis: no
change needed there. search_title is analyzed by
synonyms_fixed_analyzer/synonyms_analyzer, both using
group_tokenizer, whose delimiter set doesn't include '_' or '.', so
_bulk (and dotted ids like ml.start_datafeed) index and search as a
single token. Flagged separately (not blocking, not part of this
fix): title.starts_with's EdgeNGram tokenizer token_chars omits
"punctuation" and would strip a leading underscore if operation ids
are ever also added to Title.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@Mpdreamz Mpdreamz force-pushed the fix/openapi-search-title-operation-id branch from 114eab9 to 93a2f13 Compare July 6, 2026 09:39
@Mpdreamz Mpdreamz temporarily deployed to integration-tests July 6, 2026 09:39 — with GitHub Actions Inactive
@Mpdreamz Mpdreamz added the fix label Jul 6, 2026
…tle-operation-id

# Conflicts:
#	src/Elastic.Markdown/Exporters/Elasticsearch/ElasticsearchMarkdownExporter.Export.cs
@Mpdreamz Mpdreamz temporarily deployed to integration-tests July 6, 2026 09:54 — with GitHub Actions Inactive
@Mpdreamz Mpdreamz merged commit d698f80 into main Jul 6, 2026
24 checks passed
@Mpdreamz Mpdreamz deleted the fix/openapi-search-title-operation-id branch July 6, 2026 10:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants