Skip to content

API search: list the child fields of a path that ends with a dot - #4670

Merged
reakaleek merged 37 commits into
mainfrom
api-search-attribute-auto-98dbb1c4
Nov 4, 2026
Merged

API search: list the child fields of a path that ends with a dot#4670
reakaleek merged 37 commits into
mainfrom
api-search-attribute-auto-98dbb1c4

Conversation

@reakaleek

@reakaleek reakaleek commented Nov 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Why

  • In the API search, typing a field path such as retriever.standard found the field but gave no hint of what is nested under it. Readers had to open the operation page to see the child fields.
  • A path ending in a dot (retriever.standard.) matched nothing, which is exactly what someone about to type the next segment enters.
  • Field rows put the path, type, location and description on one line, so most of it was cut off at the dropdown's width.

What

  • Typing a path that ends in a dot (retriever.) lists every field directly under it as its own result row, right after the parent row. Each row links to that field's anchor. Without the dot, the result is the name matches it always was.
  • A field row now uses two lines: the path (the last segment in full weight, cut at the start so it stays visible) and a chip that says where the field lives (path, query, header, request body, response body); then the type and the description. A braces icon marks field rows, and the path turns link-blue and underlined on hover.
  • Operation rows always show their route in place of the description.
  • Result rows are plain boosted links. The dropdown closes on the click, stays open for Cmd, Ctrl or Shift clicks (new tab), and reopens in the right place after a jump to an anchor.

Notes

  • The index stores a new parent keyword on each API property, with array and map markers removed ([].retriever is listed under retriever). Each environment needs one assembler index run, which rolls the dated indices over (about 6 minutes on dev). The preview shows no child rows until its index is rebuilt.
  • In the API-filtered lookup, operations that list children of the typed path rank above operations that only contain a field with that name. Exact name matches otherwise tie, and the tie put get-script above _search for retriever.
  • The snapshot test from Pilot snapshot tests with Nullean.Snapshots in the API Explorer tests #4654 is updated here; it fails on main too, because Suppress additionalInfo in popover when all lifecycles are negative #4311 hides the popover's extra availability text for a deprecated badge.
  • Verified on a local assembled site against the reindexed dev cluster with Playwright, in headless Chromium and in real Chrome. All C# unit tests and the frontend suite pass.

🤖 Generated with Claude Code

reakaleek and others added 4 commits November 4, 2026 10:38
@reakaleek @claude
Index the direct children of each API property
e500ee6 
The exporter already walks the property tree, so each indexed row now
stores the suffixes that extend its path to its direct children, such
as `.query`, `[].query` or `.<string>.terms`. The list is an unindexed
keyword. `Flatten` and the child lists both derive from one
`DirectChildren` definition, so the flat index and the suggestions
cannot drift apart.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Return a property's children from API search and read a trailing dot
0ed08a4 
`retriever.standard.` is a child field not yet typed, so the query now
reads it as `retriever.standard` instead of a bare name that matches
nothing. Each property in the response carries `children`, always an
array and capped at 100 entries.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
List a field's children under its row in API search results
86f6f01 
A property row now shows the fields nested under it as one muted line
in code font, so typing `retriever.standard` tells the reader that
`filter`, `min_score`, `query` and the rest come next. The line
ellipsizes and the row's title carries the full list. Nothing is
interactive; the reader types the next segment.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Document the child field list in API search
39e2fc8 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek
reakaleek requested a review from a team as a code owner November 4, 2026 10:07
@reakaleek
reakaleek requested a review from Mpdreamz November 4, 2026 10:07
@reakaleek @claude
Use the page's tooltip on API search property rows
1c2ca60 
The operation page shows a property's JSON path in a tippy tooltip,
and the search row showed its own hover text through native title
attributes, which look different and appear a second later. The row's
path, type, description and child list now carry data-tippy-content,
which the delegate in tooltip.ts already covers, so one hover style
serves both surfaces.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
reakaleek and others added 4 commits November 4, 2026 11:23
@reakaleek @claude
Put a field's path and description on separate lines in API search
25b1b85 
One line held the path, type, location and description, so at the
dropdown's width almost all of it ellipsized. The row now takes two
lines: the path with its leaf in full weight, cut at the start so the
leaf stays visible, then the type chip and the description. The
location chip shows only when the same path appears in two locations.
This is direction A of the three mockups from the search redesign
exploration, kept in the same grouping and keyboard order.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Mark API search field rows with a braces icon on a subdued tint
e03e853 
The indent and guide line that set a field row apart from its
operation are replaced by EUI's tokenObject icon in a gutter, and the
row sits on a subdued background that brightens when selected, as in
direction A of the search redesign mockups.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Keep API search field rows white and show the braces icon at 16px
a0d06b8 
A field row is white like the operation row and turns grey only on
hover or when selected. The gutter icon goes from 12px to 16px, the
size the mockup drew it at.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Draw the field icon as strokes, delay its tooltips, and link-style th…
e653967 
…e path

Three fixes from reviewing the two-line field row in the dropdown.
EUI's tokenObject is a filled token glyph that blurs at 16px, so the
gutter draws the braces as strokes instead and the icon cache goes
back to what main has. The row's tooltips wait 500ms, since the page's
80ms opened one on every row the mouse crossed. The path turns
link-blue and underlined on hover and on the selected row, the way the
operation title does.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Docs preview (local build)

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

Sample changed pages:

reakaleek and others added 2 commits November 4, 2026 12:56
@reakaleek @claude
Show a field's children as chips that complete the typed path
2b99cc0 
One ellipsized line hid most children of a wide field. The children
now wrap as chips under the row, at most twelve with a `+N more` note
that holds the rest in its tooltip. A click on a chip replaces the
typed field word with the child's path and searches again, so
`retriever` then `knn` reads `retriever.knn` with its own children.
The chips sit beside the row's link rather than inside it, since a
button inside an anchor is not valid HTML.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Document the child field chips in API search
5d53ca2 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
reakaleek and others added 3 commits November 4, 2026 13:10
@reakaleek @claude
Show a field's children as informational tokens
c3379bc 
A click on a child rewrote the query, and the re-ranked results could
put a different operation first, which read as the row changing under
the reader. The children are now plain tokens inside the row's link,
styled like the type chip, wrapping so every child shows, twelve at
most with a `+N more` note. Typing the next segment is how the search
narrows. The fill handler and the container that kept buttons out of
the anchor go away with it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Label the child tokens of an API search field row
c2c3e5d 
A row of bare tokens under a field did not say what they were. The
line now starts with "Child properties", and the group and the row's
accessible name say the same.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Always show an operation's route in API search results
55bc62a 
An operation row showed its route only when a query word named a
path, and its description otherwise. The description mostly repeated
the title, while the route is what tells two search operations apart.
The row now shows the route a query word names, else the page's
primary route, and keeps the description only for a row without
routes, such as a docs page.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
reakaleek and others added 4 commits November 4, 2026 13:25
@reakaleek @claude
Put the child tokens in a labelled column
088269e 
The inline label made wrapped token lines start at different x
positions. The block is now a two-column grid with "Contains" on the
left and the wrapping tokens on the right, stacked on small screens.
"Contains" names the relation, so it cannot be misread under a row
that is itself a field; the accessible name keeps "Child properties".

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
List the children of a typed path as rows in API search results
6defd18 
Each indexed property now stores the path of the row it is listed
under, with array and map markers removed so that `[].retriever`
(an `msearch` body) is listed under `retriever`, the way a reader
types it. The child suffix list goes away with the token block that
used it.

In the API lookup the nested property query gains a `parent` option
at a lower weight than any name match, so the typed path's direct
children come back as ordinary rows: up to five after their parent,
or twenty when the field ends with a dot, in page order. A reading
also lifts an operation that lists children of the typed path above
one that merely contains a field of that name; every exact name match
otherwise ties and the tie broke towards `get-script`'s
`script.source.retriever`. Name matches and children are told apart
by named clauses, and inner hits grow from 5 to 20.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Show child rows flat with the location of every field
cf612c9 
The children of a typed path arrive from the server as ordinary
properties and render as ordinary rows; the dimmed parent segment of
the path shows the relation. Every property row now carries a chip
saying where the field lives (path, query, header, request body,
response body) instead of only when a path appears twice. The token
block, its "Contains" column and the "+N more" note are gone.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Document child rows and field locations in API search
680e698 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
reakaleek and others added 3 commits November 4, 2026 14:36
@reakaleek @claude
List a field's children only when the query ends with a dot
0c8dd8e 
Five children under every exact path blurred the line between
"find this field" and "show me what is under it". A query without a
trailing dot is the name match it always was, with no children clause
sent; a query ending with a dot lists every child the inner-hits
window returns, up to 100, after the parent row. The lift that ranks
an operation listing children of the typed path first applies either
way, so the operation whose row is the typed path still comes first.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Document the trailing dot that lists a field's children
bfb3bce 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@reakaleek @claude
Make API search results plain boosted links that close on click
76df915 
A result row went through a per-row hook that normalised its href and
processed it for htmx, and the dropdown closed and blurred its input
only when a later `htmx:afterSwap` reached the component. That event
reaches a same-page target differently from a cross-page one, since
the search element survives one swap and is replaced by the other,
and after a same-page result the box would not reopen on focus.

Rows are now `<a href>` as given, the list runs one `htmx.process`
over itself after each render, and a click or Enter closes the
dropdown and blurs the input on the spot. A ref keeps that blur from
logging a second close for the same navigation.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
reakaleek and others added 10 commits November 4, 2026 15:24
@reakaleek @claude
Reposition the API search dropdown when the page scrolls under it
1290849 
The dropdown stays mounted while the box has text and is hidden with
CSS. EUI positions the portaled panel in page coordinates when it
opens, so a result that jumps to an anchor scrolled the page about
3,700px while the sticky box stayed put. Focusing the box again showed
the panel at its old coordinates, far above the viewport, which looked
like the dropdown not opening. `repositionOnScroll` recomputes the
position on scroll.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
Simplify the API property search plumbing
8e9a6bb 
The child cap becomes a flag, since it only ever took "none" or "the
whole window". Name options are composed into one dis_max instead of
lists mutated across helpers, the boosts that must stay ordered are
named together, and the ranking lift gets a name that says what it
lifts. The array and map path markers move into the contract so the
exporter and `ParentKey` share them, and the response drops a `parent`
field no client reads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
Simplify the API search dropdown
e20b997 
Highlight terms are computed once per list instead of once per row,
the slow tooltip delay lives next to the delegate's own delay, and a
single close helper that logs only when the dropdown was open replaces
the flag that suppressed a second close log.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
fix: fetch 5 inner hits for the docs-wide property lookup (per review…
6df4265 
… by @infra-vault-gh-plugin-prod)

The docs-wide search keeps only three property rows and never lists children, so fetching 20 per document wasted payload; the API lookup keeps 20 and an expanded one 100.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
fix: normalise the typed path before matching api.properties.parent (…
f42ed42 
…per review by @infra-vault-gh-plugin-prod)

The index stores each row's parent as ApiPropertyPath.ParentKey, so a typed path with [] or <string> markers matched no children and lifted no operation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
fix: list children under the parent row of their own location (per re…
1ad7685 
…view by @infra-vault-gh-plugin-prod)

A query parameter and a body field can share a path, so matching the parent row on path alone put body children under the query parameter and mixed request and response children.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
fix: highlight nothing on the fallback API route (per review by @infr…
140f45d 
…a-vault-gh-plugin-prod)

When no query word names a route the row shows the page's primary route, so marking query words inside it pointed at a match that is not there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
fix: keep the search open when a click opens a result elsewhere (per …
f288deb 
…review by @infra-vault-gh-plugin-prod)

A Cmd, Ctrl or Shift click opens the result in a new tab or window and leaves the reader on this page, so closing and blurring the search threw away what they were browsing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
fix: destroy row tooltips when search results unmount or change (per …
3227403 
…review by @infra-vault-gh-plugin-prod)

The page's tippy delegate mounts tooltips on the body and only drops them on an htmx swap, so a tooltip shown over a row stayed on screen after Escape removed the row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek
Merge remote-tracking branch 'origin/main' into api-search-attribute-…
2e18c7d 
…auto-98dbb1c4
@reakaleek reakaleek changed the title List the child fields of a matching field in API search results API search: list the child fields of a path that ends with a dot Nov 4, 2026
reakaleek and others added 3 commits November 4, 2026 16:28
@reakaleek @claude
Update the search operation snapshot for the deprecated badge popover
1f85679 
The snapshot from #4654 was recorded before #4311 landed. #4311 hides
the popover's additional availability info when every lifecycle is
negative, and the deprecated badge on the search operation is such a
case. `main` fails the same test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
Leave modifier clicks on boosted links to htmx and the browser
27663a2 
htmx 2 already skips a Ctrl or Cmd click on a boosted link, so the
browser opens it in a new tab. The hook also cancelled Shift-clicks
and opened them with `window.open`; a Shift-click is now an ordinary
htmx navigation like any other click.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
fix: close the API search dropdown on Shift-click (per review by @inf…
a8b4011 
…ra-vault-gh-plugin-prod)

A Shift-click on a result is now an ordinary htmx navigation, so it
closes the dropdown like a plain click; only Ctrl and Cmd clicks,
which htmx leaves to the browser, keep it open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
reakaleek and others added 3 commits November 4, 2026 16:45
@reakaleek @claude
Revert "fix: close the API search dropdown on Shift-click"
e6541d7 
This reverts commit a8b4011. The site
hook opens a Shift-click in a new tab again, so the dropdown stays
open for it like for Cmd and Ctrl.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek @claude
Revert "Leave modifier clicks on boosted links to htmx and the browser"
bcf6c6d 
This reverts commit 27663a2. Measured
against production, Cmd and Ctrl clicks already open a new tab either
way, so the only effect was that a Shift-click on any boosted link
navigated in place instead of opening a new tab. The site-wide hook is
out of scope for this PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@reakaleek
Merge branch 'main' into api-search-attribute-auto-98dbb1c4
16c2bbf
@reakaleek
reakaleek merged commit 7bd38c2 into main Nov 4, 2026
36 checks passed
@reakaleek
reakaleek deleted the api-search-attribute-auto-98dbb1c4 branch November 4, 2026 17:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@infra-vault-gh-plugin-prod infra-vault-gh-plugin-prod[bot] infra-vault-gh-plugin-prod[bot] approved these changes
@akira28 akira28 akira28 approved these changes
@Mpdreamz Mpdreamz Awaiting requested review from Mpdreamz Mpdreamz is a code owner automatically assigned from elastic/docs-engineering

Assignees

No one assigned

Labels

enhancement

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@reakaleek @akira28