Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(search-bar): explain filter tokens on hover (LFE-14447) (#15896)

Nikita Kabardin786496d02f1d
diff --git a/web/src/features/filters/components/FilterToken.stories.tsx b/web/src/features/filters/components/FilterToken.stories.tsx
index 2edc3b1bbf..c1b5ed7b09 100644
--- a/web/src/features/filters/components/FilterToken.stories.tsx
+++ b/web/src/features/filters/components/FilterToken.stories.tsx
@@ -16,6 +16,14 @@ export const Default = meta.story({
},
});
+export const Highlighted = meta.story({
+ args: {
+ children: "-environment:langfuse-experiments",
+ deactivated: false,
+ highlighted: true,
+ },
+});
+
export const Deactivated = meta.story({
args: {
children: "environment:none of development",
diff --git a/web/src/features/filters/components/FilterToken.tsx b/web/src/features/filters/components/FilterToken.tsx
index 102bb2cd15..5035d53897 100644
--- a/web/src/features/filters/components/FilterToken.tsx
+++ b/web/src/features/filters/components/FilterToken.tsx
@@ -9,6 +9,12 @@ const filterTokenVariants = cva(
true: "opacity-50 line-through decoration-1",
false: "",
},
+ // Pointer-independent hover treatment: the caret/keyboard path marks the
+ // token an open explanation refers to.
+ highlighted: {
+ true: "border-ring bg-accent",
+ false: "",
+ },
},
},
);
@@ -16,7 +22,8 @@ const filterTokenVariants = cva(
type FilterTokenProps = {
children: ReactNode;
deactivated: boolean;
- title: string | undefined;
+ title?: string | undefined;
+ highlighted?: boolean;
} & {
[key: `data-${string}`]: string | boolean | undefined;
};
@@ -25,6 +32,7 @@ export function FilterToken({
children,
deactivated,
title,
+ highlighted = false,
...dataAttributes
}: FilterTokenProps) {
return (
@@ -32,7 +40,7 @@ export function FilterToken({
{...dataAttributes}
data-deactivated={deactivated || undefined}
title={title}
- className={filterTokenVariants({ deactivated })}
+ className={filterTokenVariants({ deactivated, highlighted })}
>
{children}
</span>
diff --git a/web/src/features/search-bar/components/ComposerTokens.tsx b/web/src/features/search-bar/components/ComposerTokens.tsx
index 2441eef313..b4ba04b5d7 100644
--- a/web/src/features/search-bar/components/ComposerTokens.tsx
+++ b/web/src/features/search-bar/components/ComposerTokens.tsx
@@ -18,6 +18,7 @@ import {
type FilterSegment,
} from "@/src/features/search-bar/lib/composer-segments";
import { indexOfOutsideQuotes } from "@/src/features/search-bar/lib/langQ";
+import { deactivationReason } from "@/src/features/search-bar/components/presentation";
import { FilterToken } from "@/src/features/filters/components/FilterToken";
// Word joiner around pills: gives the DOM caret boundaries between tokens
@@ -46,10 +47,13 @@ export const composerTokenVariants = cva("max-w-full", {
},
// A filter that the current surface can't apply (e.g. the chart view can't
// filter on this column). Dimmed + dashed so it reads as "shown but not
- // applied"; the reason is on hover (`title`).
+ // applied"; the reason is in the explanation tooltip.
deactivated: { true: "opacity-50 line-through decoration-1", false: "" },
+ // The token whose explanation is showing. Mirrors the hover treatment, so
+ // the caret (keyboard) path highlights exactly like the pointer does.
+ highlighted: { true: "border-border bg-accent", false: "" },
},
- defaultVariants: { kind: "freeText", deactivated: false },
+ defaultVariants: { kind: "freeText", deactivated: false, highlighted: false },
});
type TokenKind = "filter" | "freeText" | "operator" | "paren" | "invalid";
@@ -113,10 +117,13 @@ export function ComposerTokens({
scoreTypes,
fieldReason,
freeTextReason,
+ highlightedSegmentId,
}: {
draft: string;
showDiagnostics: boolean;
scoreTypes?: ScoreTypeContext;
+ /** Segment whose explanation tooltip is open β€” rendered highlighted. */
+ highlightedSegmentId?: string | null;
/**
* Given a filter token's field name, the reason it is NOT applied on the
* current surface, or `null` if it is. When it returns a reason the pill
@@ -142,27 +149,13 @@ export function ComposerTokens({
? "freeText"
: segment.kind;
// "Not applied on this surface" β€” a filter column the chart can't honour,
- // or free text a chart ignores. Only filter/free-text tokens can deactivate
- // (operators/parens/invalid never do).
- const deactivatedReason =
- segment.kind === "filter"
- ? (fieldReason?.(segment.displayField) ?? null)
- : segment.kind === "freeText"
- ? (freeTextReason ?? null)
- : null;
- const deactivated = deactivatedReason !== null;
- // Invalid tokens get the styled per-token error tooltip (a positioned
- // overlay in SearchComposer), not the native browser title. A deactivated
- // token explains why it is ignored. Free text is a full-text search β€” say so
- // on hover so a standalone text chip explains itself instead of looking like
- // a stray block.
- const title = deactivated
- ? deactivatedReason
- : segment.kind === "invalid"
- ? undefined
- : segment.kind === "freeText"
- ? `Full-text search β€” matches results containing "${segment.raw}". Searches ids, names, input and output by default; use input: or output: to search one payload, or name:/id: to narrow.`
- : segment.raw;
+ // or free text a chart ignores.
+ const deactivated =
+ deactivationReason(segment, fieldReason, freeTextReason) !== null;
+ const highlighted = segment.id === highlightedSegmentId;
+ // No native `title`: hover copy is the styled per-token tooltip that
+ // SearchComposer positions (explanation, or the error once diagnostics are
+ // revealed). A second, slower browser tooltip on top of it just doubles up.
const content = (
<>
{segment.kind === "filter" ? (
@@ -186,8 +179,8 @@ export function ComposerTokens({
data-testid="search-bar-token"
data-kind={visibleKind}
data-segment-id={segment.id}
- title={title}
deactivated={deactivated}
+ highlighted={highlighted}
>
{content}
</FilterToken>
@@ -198,8 +191,11 @@ export function ComposerTokens({
data-kind={visibleKind}
data-deactivated={deactivated || undefined}
data-segment-id={segment.id}
- title={title}
- className={composerTokenVariants({ kind: visibleKind, deactivated })}
+ className={composerTokenVariants({
+ kind: visibleKind,
+ deactivated,
+ highlighted,
+ })}
>
{content}
</span>
diff --git a/web/src/features/search-bar/components/SearchComposer.tsx b/web/src/features/search-bar/components/SearchComposer.tsx
index 06d85abf71..bd994404e0 100644
--- a/web/src/features/search-bar/components/SearchComposer.tsx
+++ b/web/src/features/search-bar/components/SearchComposer.tsx
@@ -29,6 +29,7 @@ import {
scoreTypeContextFromObserved,
type ObservedOptions,
} from "@/src/features/search-bar/lib/observed-options";
+import { explainSegment } from "@/src/features/search-bar/lib/explain";
import { getRecentSearches } from "@/src/features/search-bar/lib/recent-searches";
import {
applyPick,
@@ -50,6 +51,7 @@ import {
} from "@/src/features/search-bar/components/ComposerTokens";
import {
COMPOSER_PLACEHOLDER,
+ deactivationReason,
optionDomId,
} from "@/src/features/search-bar/components/presentation";
import {
@@ -63,6 +65,11 @@ const LISTBOX_ID = "search-bar-listbox";
// reaches the model or clipboard.
const WORD_JOINER_RE = new RegExp(WORD_JOINER, "g");
+// Shared by the visible tooltip and its screen-reader description, so a
+// deactivated token reads the same either way.
+const notAppliedNote = (reason: string) =>
+ `Not applied on this view: ${reason}`;
+
// Stable empty recents reference so the plan memo doesn't churn when recents
// are intentionally suppressed (popover closed, or a non-empty draft β€” recents
// show only on an empty bar; see the recents memo).
@@ -1166,18 +1173,18 @@ export function SearchComposer({
setHoveredTokenId(token?.getAttribute("data-segment-id") ?? null);
};
- const describedBy =
- visibleDiagnostics.length > 0 ? "search-bar-diagnostics" : undefined;
-
const segments = deriveComposerSegments(draft, scoreTypes);
- // The remove affordance targets the hovered token, or β€” while the editor is
- // focused β€” the token holding a collapsed caret. Not at the trailing
- // insertion point, where the user is appending, not editing.
- const focusTokenId =
+ // The token holding a collapsed caret β€” the keyboard counterpart to hover.
+ // Not at the trailing insertion point, where the user is appending, not
+ // editing. Every segment kind qualifies: an operator explains itself on the
+ // caret path exactly as it does on hover (it just can't be removed, below).
+ const caretSegment =
editorFocused && selectionCollapsed && caret < draft.length
- ? (segments.find((s) => s.editable && s.from <= caret && caret <= s.to)
- ?.id ?? null)
+ ? (segments.find((s) => s.from <= caret && caret <= s.to) ?? null)
: null;
+ // The remove affordance targets the hovered token, or the caret token β€” but
+ // only an editable one, since operators/parens have nothing to remove.
+ const focusTokenId = caretSegment?.editable === true ? caretSegment.id : null;
const removeTargetId = hoveredTokenId ?? focusTokenId;
const removeTarget =
segments.find((s) => s.editable && s.id === removeTargetId) ?? null;
@@ -1191,6 +1198,53 @@ export function SearchComposer({
? removeTarget
: null;
+ // Plain-language explanation of a token (LFE-14447), in the same slot β€” an
+ // error wins it. Hover always explains; the caret path only while the popover
+ // is closed, so it never stacks a tooltip over the suggestions you are typing
+ // against.
+ const explainTarget =
+ errorTarget !== null
+ ? null
+ : hoveredTokenId !== null
+ ? (segments.find((s) => s.id === hoveredTokenId) ?? null)
+ : plan === null
+ ? caretSegment
+ : null;
+ const explainTargetId = explainTarget?.id ?? null;
+ const explanation =
+ explainTarget === null ? null : explainSegment(explainTarget);
+ const explainDeactivatedReason =
+ explainTarget === null
+ ? null
+ : deactivationReason(explainTarget, fieldReason, freeTextReason);
+ // Keyboard/AT path: the caret token's explanation, read through the combobox's
+ // description regardless of the popover β€” including the "not applied" note,
+ // which the visible tooltip also carries.
+ const caretExplanation =
+ caretSegment === null ? null : explainSegment(caretSegment);
+ const caretDeactivatedReason =
+ caretSegment === null
+ ? null
+ : deactivationReason(caretSegment, fieldReason, freeTextReason);
+ const caretHelp =
+ caretExplanation === null
+ ? null
+ : [
+ `${caretExplanation.subject} ${caretExplanation.predicate}`.trim(),
+ caretDeactivatedReason === null
+ ? null
+ : notAppliedNote(caretDeactivatedReason),
+ ]
+ .filter((part) => part !== null)
+ .join(" ");
+ const describedBy =
+ [
+ visibleDiagnostics.length > 0 ? "search-bar-diagnostics" : null,
+ caretHelp !== null ? "search-bar-token-help" : null,
+ ]
+ .filter((id) => id !== null)
+ .join(" ") || undefined;
+
// Measure the remove target's last client rect in the parent's layout
// effect: it runs after every commit that can move text, and after all
// subtree refs (root + container) are attached.
@@ -1198,7 +1252,7 @@ export function SearchComposer({
left: number;
top: number;
} | null>(null);
- // Anchors for the per-token error tooltip β€” left edge of the token, plus its
+ // Anchors for the per-token tooltip β€” left edge of the token, plus its
// bottom (default placement, just under the block) and top (used to flip the
// tooltip ABOVE the block while the suggestions popover is open below). These
// are VIEWPORT coordinates (not container-relative): the tooltip portals to
@@ -1206,61 +1260,70 @@ export function SearchComposer({
// getClientRects() directly. The bar's band is sticky (it doesn't scroll out
// from under the token), so a fixed anchor stays put; it re-measures on draft
// change and the container ResizeObserver below, same as the X button.
- const [errorPosition, setErrorPosition] = React.useState<{
+ const [tooltipPosition, setTooltipPosition] = React.useState<{
left: number;
belowTop: number;
aboveTop: number;
} | null>(null);
const removeTargetIdActual = removeTarget?.id ?? null;
- const measureRemovePosition = React.useCallback(() => {
+ // Measured separately from the remove target: an operator token explains
+ // itself but is not editable, so it never has a remove X to anchor to.
+ const tooltipTargetId =
+ errorTarget !== null
+ ? errorTarget.id
+ : explanation !== null
+ ? explainTargetId
+ : null;
+ const measurePositions = React.useCallback(() => {
const root = rootRef.current;
const container = containerRef.current;
- if (root === null || container === null || removeTargetIdActual === null) {
+ const rectsOf = (id: string | null): DOMRectList | null => {
+ if (root === null || id === null) return null;
+ const el = root.querySelector(`[data-segment-id="${CSS.escape(id)}"]`);
+ return el === null ? null : el.getClientRects();
+ };
+
+ const removeRects = rectsOf(removeTargetIdActual);
+ const lastRect = removeRects?.[removeRects.length - 1] ?? null;
+ if (container === null || lastRect === null) {
setRemovePosition(null);
- setErrorPosition(null);
- return;
+ } else {
+ const containerRect = container.getBoundingClientRect();
+ setRemovePosition({
+ left: lastRect.right - containerRect.left - 6,
+ top: lastRect.top - containerRect.top - 8,
+ });
}
- const el = root.querySelector(
- `[data-segment-id="${CSS.escape(removeTargetIdActual)}"]`,
+
+ const tooltipRect = rectsOf(tooltipTargetId)?.[0] ?? null;
+ setTooltipPosition(
+ tooltipRect === null
+ ? null
+ : {
+ left: tooltipRect.left,
+ belowTop: tooltipRect.bottom + 6,
+ aboveTop: tooltipRect.top,
+ },
);
- if (el === null) {
- setRemovePosition(null);
- setErrorPosition(null);
- return;
- }
- const rects = el.getClientRects();
- const rect =
- rects.length > 0 ? rects[rects.length - 1]! : el.getBoundingClientRect();
- const firstRect = rects.length > 0 ? rects[0]! : rect;
- const containerRect = container.getBoundingClientRect();
- setRemovePosition({
- left: rect.right - containerRect.left - 6,
- top: rect.top - containerRect.top - 8,
- });
- setErrorPosition({
- left: firstRect.left,
- belowTop: firstRect.bottom + 6,
- aboveTop: firstRect.top,
- });
- }, [removeTargetIdActual]);
-
- // Re-measure when the target or draft text changes.
+ }, [removeTargetIdActual, tooltipTargetId]);
+
+ // Re-measure when a target or the draft text changes.
React.useLayoutEffect(() => {
- measureRemovePosition();
- }, [measureRemovePosition, draft]);
+ measurePositions();
+ }, [measurePositions, draft]);
// Those deps miss layout reflows that don't change React state β€” window
// resize, browser zoom, sidebar collapse β€” which re-wrap the full-width bar
// and move the token. Observe the composer surface so the absolutely-
// positioned X re-anchors to its token instead of leaving a stale ghost X.
React.useEffect(() => {
- if (removeTargetIdActual === null) return;
+ if (removeTargetIdActual === null && tooltipTargetId === null) return;
const container = containerRef.current;
if (container === null || typeof ResizeObserver === "undefined") return;
- const observer = new ResizeObserver(() => measureRemovePosition());
+ const observer = new ResizeObserver(() => measurePositions());
observer.observe(container);
return () => observer.disconnect();
- }, [measureRemovePosition, removeTargetIdActual]);
+ }, [measurePositions, removeTargetIdActual, tooltipTargetId]);
return (
<div
@@ -1368,6 +1431,9 @@ export function SearchComposer({
scoreTypes={scoreTypes}
fieldReason={fieldReason}
freeTextReason={freeTextReason}
+ highlightedSegmentId={
+ explanation !== null ? explainTargetId : errorTarget?.id
+ }
/>
</div>
{/* "Ask AI" affordance β€” a plain button, always available so filters can
@@ -1441,6 +1507,12 @@ export function SearchComposer({
</div>
)}
+ {caretHelp !== null && (
+ <div id="search-bar-token-help" className="sr-only">
+ {caretHelp}
+ </div>
+ )}
+
{plan !== null && (
<AutocompletePopover
plan={plan}
@@ -1453,35 +1525,60 @@ export function SearchComposer({
/>
)}
- {/* Per-token error tooltip. The "tooltip" <Layer> renders it on a
- body-level container so it escapes the page header's overflow:hidden
- clip and z-50 stacking context when it flips above the bar β€” an
- in-flow z-index can't win against either. `fixed` + viewport anchors.
- pointer-events-none so moving onto it doesn't change the hovered token
- (which would flicker it away). */}
- {errorTarget !== null && errorPosition !== null && (
- <Layer name="tooltip">
- <div
- role="tooltip"
- style={
- plan !== null
- ? {
- left: errorPosition.left,
- top: errorPosition.aboveTop,
- transform: "translateY(calc(-100% - 6px))",
- }
- : { left: errorPosition.left, top: errorPosition.belowTop }
- }
- className={cn(
- "pointer-events-none fixed max-w-[min(360px,calc(100vw-32px))]",
- "border-destructive/40 bg-popover text-destructive rounded-md border",
- "px-2 py-1 font-sans text-xs leading-snug shadow-md",
- )}
- >
- {errorTarget.message}
- </div>
- </Layer>
- )}
+ {/* Per-token tooltip β€” the error diagnostic, or the token's plain-language
+ explanation. The "tooltip" <Layer> renders it on a body-level container
+ so it escapes the page header's overflow:hidden clip and z-50 stacking
+ context when it flips above the bar β€” an in-flow z-index can't win
+ against either. `fixed` + viewport anchors. pointer-events-none so
+ moving onto it doesn't change the hovered token (which would flicker it
+ away). */}
+ {(errorTarget !== null || explanation !== null) &&
+ tooltipPosition !== null && (
+ <Layer name="tooltip">
+ <div
+ role="tooltip"
+ data-testid="search-bar-token-tooltip"
+ style={
+ plan !== null
+ ? {
+ left: tooltipPosition.left,
+ top: tooltipPosition.aboveTop,
+ transform: "translateY(calc(-100% - 6px))",
+ }
+ : {
+ left: tooltipPosition.left,
+ top: tooltipPosition.belowTop,
+ }
+ }
+ className={cn(
+ "pointer-events-none fixed max-w-[min(360px,calc(100vw-32px))]",
+ "bg-popover rounded-md border",
+ "px-2 py-1 font-sans text-xs leading-snug shadow-md",
+ errorTarget !== null
+ ? "border-destructive/40 text-destructive"
+ : "border-border text-popover-foreground",
+ )}
+ >
+ {errorTarget !== null ? (
+ errorTarget.message
+ ) : (
+ <>
+ <span className="font-bold">{explanation?.subject}</span>
+ {/* A boolean token's phrase IS the whole explanation β€” no
+ predicate, so no dangling space before the period. */}
+ {explanation?.predicate !== "" && (
+ <> {explanation?.predicate}</>
+ )}
+ {explainDeactivatedReason !== null && (
+ <span className="text-muted-foreground block pt-0.5">
+ {notAppliedNote(explainDeactivatedReason)}
+ </span>
+ )}
+ </>
+ )}
+ </div>
+ </Layer>
+ )}
</div>
);
}
diff --git a/web/src/features/search-bar/components/presentation.ts b/web/src/features/search-bar/components/presentation.ts
index 9540e81a16..c5ea61635d 100644
--- a/web/src/features/search-bar/components/presentation.ts
+++ b/web/src/features/search-bar/components/presentation.ts
@@ -2,6 +2,8 @@
// the autocomplete popover. A separate module (not a component file) so the
// component files keep Fast Refresh eligibility.
+import type { ComposerSegment } from "@/src/features/search-bar/lib/composer-segments";
+
// Page-neutral: the bar mounts on both the Observations and Traces tables.
export const COMPOSER_PLACEHOLDER =
"Search β€” e.g. level:ERROR, -env:dev, latency:>2, scores.accuracy:>0.8";
@@ -16,3 +18,19 @@ export const COMPOSER_PLACEHOLDER =
export function optionDomId(listboxId: string, optionId: string): string {
return `${listboxId}-opt-${encodeURIComponent(optionId)}`;
}
+
+/**
+ * Why this token is NOT applied on the current surface (e.g. a column the chart
+ * view can't filter on), or null when it is. Shared by the token styling (dim +
+ * strike) and the hover tooltip so both read the same source.
+ */
+export function deactivationReason(
+ segment: ComposerSegment,
+ fieldReason?: (field: string) => string | null,
+ freeTextReason?: string | null,
+): string | null {
+ if (segment.kind === "filter")
+ return fieldReason?.(segment.displayField) ?? null;
+ if (segment.kind === "freeText") return freeTextReason ?? null;
+ return null;
+}
diff --git a/web/src/features/search-bar/lib/composer-segments.ts b/web/src/features/search-bar/lib/composer-segments.ts
index 65f8a4e549..624793d207 100644
--- a/web/src/features/search-bar/lib/composer-segments.ts
+++ b/web/src/features/search-bar/lib/composer-segments.ts
@@ -9,7 +9,7 @@
// (langQ.ts, edits.ts).
import type { ScoreTypeContext } from "./adapter";
-import type { ASTNode, FilterNode, Span, TextNode } from "./ast";
+import type { ASTNode, CompareOp, FilterNode, Span, TextNode } from "./ast";
import { lexTokens, type Diagnostic } from "./langQ";
import { validateQuery } from "./validate";
@@ -23,6 +23,9 @@ export type FilterSegment = {
displayField: string;
/** Parsed values β€” used to color numeric values distinctly. */
values: string[];
+ /** Parsed operator + value grouping β€” the token's semantics, for explain.ts. */
+ op: CompareOp;
+ valueOp?: "or" | "and";
negated: boolean;
editable: true;
};
@@ -205,6 +208,8 @@ export function deriveComposerSegments(
raw,
displayField: node.rawKey ?? node.key,
values: node.values,
+ op: node.op,
+ valueOp: node.valueOp,
negated: leaf.negated,
editable: true,
});
diff --git a/web/src/features/search-bar/lib/explain.clienttest.ts b/web/src/features/search-bar/lib/explain.clienttest.ts
new file mode 100644
index 0000000000..3e6df9c14a
--- /dev/null
+++ b/web/src/features/search-bar/lib/explain.clienttest.ts
@@ -0,0 +1,101 @@
+import { deriveComposerSegments } from "@/src/features/search-bar/lib/composer-segments";
+import { explainSegment } from "@/src/features/search-bar/lib/explain";
+import { FIELDS } from "@/src/features/search-bar/lib/fields";
+
+/** Explain the nth token of `query` as the tooltip reads it. */
+function explain(query: string, index = 0): string | null {
+ const segment = deriveComposerSegments(query)[index];
+ const explanation = segment === undefined ? null : explainSegment(segment);
+ return explanation === null
+ ? null
+ : `${explanation.subject} ${explanation.predicate}`.trim();
+}
+
+describe("explainSegment", () => {
+ it("explains the shapes users misread", () => {
+ // The reported confusion: what does a leading dash mean, and what is `env`?
+ expect(explain("-env:langfuse-experiments")).toBe(
+ 'Environment is not "langfuse-experiments".',
+ );
+ expect(explain("name:(a OR b)")).toBe('Name is exactly "a" or "b".');
+ expect(explain("latency:>2")).toBe("Latency is above 2 seconds.");
+ });
+
+ it("names the operator each `=` default actually lowers to", () => {
+ // Same-looking syntax, three different operators β€” the whole point of the
+ // tooltip. Text columns contain, option columns and metadata match exactly.
+ expect(explain("name:chat")).toBe('Name contains "chat".');
+ expect(explain("name:=chat")).toBe('Name is exactly "chat".');
+ expect(explain("metadata.region:eu")).toBe(
+ 'Metadata "region" is exactly "eu".',
+ );
+ expect(explain("level:ERROR")).toBe('Level is "ERROR".');
+ expect(explain("statusMessage:chat*")).toBe(
+ 'Status message starts with "chat".',
+ );
+ // `:=` and the bare form lower to the same numeric filter, so a number
+ // never reads as a quoted string.
+ expect(explain("latency:=2")).toBe(explain("latency:2"));
+ expect(explain("latency:=2")).toBe("Latency is 2 seconds.");
+ });
+
+ it("reads a negated comparison as its flipped operator, like the lowering", () => {
+ // Comparisons and booleans invert (INVERTED_COMPARISON / !value) instead of
+ // hiding, so the copy must too.
+ expect(explain("-latency:>2")).toBe("Latency is 2 seconds or less.");
+ expect(explain("isRootObservation:true")).toBe("Is root observation.");
+ expect(explain("-isRootObservation:true")).toBe("Is not root observation.");
+ expect(explain("isRootObservation:false")).toBe("Is not root observation.");
+ expect(explain("hasInput:false")).toBe("Has no input.");
+ expect(explain("-name:*chat*")).toBe('Name does not contain "chat".');
+ expect(explain("startTime:>2026-06-01")).toBe(
+ "Start time is after 2026-06-01.",
+ );
+ expect(explain("-level:(ERROR OR WARNING)")).toBe(
+ 'Level is none of "ERROR", "WARNING".',
+ );
+ });
+
+ it("explains groups, null checks, scores, free text and keywords", () => {
+ expect(explain("tags:(a AND b)")).toBe(
+ 'Trace tags include all of "a" and "b".',
+ );
+ expect(explain("tags:a")).toBe('Trace tags include "a".');
+ expect(explain("has:endTime")).toBe("End time is set.");
+ expect(explain("-has:endTime")).toBe("End time is not set.");
+ expect(explain("scores.accuracy:>0.8")).toBe(
+ 'Score "accuracy" is above 0.8.',
+ );
+ expect(explain("totalCost:>0.5")).toBe("Total cost is above $0.5.");
+ // The label already says "per second" β€” don't spell the unit out twice.
+ expect(explain("tps:>=50")).toBe("Tokens per second is 50 or more.");
+ expect(explain("refund policy")).toBe(
+ 'Full-text search for "refund policy" β€” matches id, name, input and output.',
+ );
+ expect(explain("level:ERROR AND latency:>2", 1)).toBe(
+ "AND β€” every filter has to match.",
+ );
+ });
+
+ it("says nothing where it has nothing to say", () => {
+ expect(explain("nope:1")).toBeNull(); // unknown field β†’ its own diagnostic
+ expect(explain("(")).toBeNull();
+ });
+
+ it("gives every registry field a usable label", () => {
+ for (const field of FIELDS) {
+ // A camelCase id or a unit suffix reads as broken English in a sentence.
+ expect(field.label, field.id).not.toMatch(/[a-z][A-Z]|[()$]/);
+ if (field.kind === "boolean") {
+ // Without this the false case silently falls back to the true phrase.
+ expect(field.negatedLabel, field.id).toBeDefined();
+ continue;
+ }
+ // Only array fields get a plural verb ("Trace tags include"); everything
+ // else is followed by "is", so a plural label would read "… tokens is".
+ if (field.syncMode !== "arrayOption") {
+ expect(field.label, field.id).not.toMatch(/s$/);
+ }
+ }
+ });
+});
diff --git a/web/src/features/search-bar/lib/explain.ts b/web/src/features/search-bar/lib/explain.ts
new file mode 100644
index 0000000000..a7c9014f97
--- /dev/null
+++ b/web/src/features/search-bar/lib/explain.ts
@@ -0,0 +1,235 @@
+// Plain-language explanation of a single query token: the field in bold, then
+// what the token asks of it β€” "Name is exactly "gpt-5.4"". Pure, no React.
+//
+// Derived from the parsed token (registry field + operator + values), never a
+// per-filter string table β€” so a new field explains itself. The operator
+// semantics mirror adapter.ts's lowering: a negated comparison flips through
+// the SAME `INVERTED_COMPARISON` map, and `=` reads as "contains" or "is"
+// exactly where the adapter lowers it that way.
+//
+// The bold lead-in is the FIELD, not the operator: an operator lead-in repeats
+// the word the predicate already carries ("Exactly. … is exactly …"), and the
+// field is the half users actually misread (`env`, `tps`, `-`).
+
+import { INVERTED_COMPARISON } from "./adapter";
+import type { CompareOp } from "./ast";
+import type { ComposerSegment, FilterSegment } from "./composer-segments";
+import { resolveField, type FieldDef, type FieldRef } from "./fields";
+
+export type TokenExplanation = {
+ /** Bold lead-in: the field this token filters on. */
+ subject: string;
+ /** The rest of the sentence, ending in a period. Empty when the subject is
+ * the whole explanation (a boolean token states itself). */
+ predicate: string;
+};
+
+type ComparisonOp = keyof typeof INVERTED_COMPARISON;
+
+function isComparison(op: CompareOp): op is ComparisonOp {
+ return op === ">" || op === "<" || op === ">=" || op === "<=";
+}
+
+function quote(value: string): string {
+ return `"${value}"`;
+}
+
+/** `"a"` Β· `"a" or "b"` Β· `"a", "b" or "c"` */
+function joinValues(values: string[], conjunction: "or" | "and"): string {
+ const quoted = values.map(quote);
+ if (quoted.length <= 1) return quoted[0] ?? '""';
+ return `${quoted.slice(0, -1).join(", ")} ${conjunction} ${quoted.at(-1)}`;
+}
+
+/** Plain list β€” reads better than "or" after a "none of". */
+function commaList(values: string[]): string {
+ return values.map(quote).join(", ");
+}
+
+/**
+ * Number spelled out β€” "2 seconds", "$0.5". Only units the field's label does
+ * not already carry are spelled out ("Tokens per second is 50", not "50 tok/s").
+ */
+function amount(raw: string, field: FieldDef | undefined): string {
+ const value = raw.trim();
+ if (field?.unit === "s")
+ return `${value} ${value === "1" ? "second" : "seconds"}`;
+ if (field?.unit === "$") return `$${value}`;
+ return value;
+}
+
+/** The token's subject β€” a field's human name, or a user-defined key. */
+function subjectOf(ref: FieldRef): string {
+ switch (ref.type) {
+ case "field":
+ return ref.field.label;
+ case "metadata":
+ return `Metadata ${quote(ref.key)}`;
+ case "scores":
+ return ref.level === "trace"
+ ? `Trace score ${quote(ref.key)}`
+ : `Score ${quote(ref.key)}`;
+ case "pseudo":
+ return ref.id;
+ }
+}
+
+function comparisonPredicate(
+ op: ComparisonOp,
+ ref: FieldRef,
+ values: string[],
+ negated: boolean,
+): string {
+ const effective = negated ? INVERTED_COMPARISON[op] : op;
+ const field = ref.type === "field" ? ref.field : undefined;
+ const raw = values[0] ?? "";
+ if (field?.kind === "datetime") {
+ return {
+ ">": `is after ${raw}`,
+ ">=": `is on or after ${raw}`,
+ "<": `is before ${raw}`,
+ "<=": `is on or before ${raw}`,
+ }[effective];
+ }
+ const value = amount(raw, field);
+ return {
+ ">": `is above ${value}`,
+ ">=": `is ${value} or more`,
+ "<": `is below ${value}`,
+ "<=": `is ${value} or less`,
+ }[effective];
+}
+
+/** Predicate for `=`, whose meaning depends on the field's sync mode. */
+function defaultOpPredicate(ref: FieldRef, seg: FilterSegment): string {
+ const { values, valueOp, negated } = seg;
+ const many = values.length > 1;
+
+ // stringObject `=` is an exact match β€” unlike the contains default on a
+ // plain text column.
+ if (ref.type === "metadata") {
+ return negated
+ ? `is not exactly ${joinValues(values, "or")}`
+ : `is exactly ${joinValues(values, "or")}`;
+ }
+ if (ref.type === "scores") {
+ if (negated)
+ return many
+ ? `is none of ${commaList(values)}`
+ : `is not ${quote(values[0] ?? "")}`;
+ return `is ${joinValues(values, "or")}`;
+ }
+ if (ref.type === "field" && ref.field.syncMode === "arrayOption") {
+ if (valueOp === "and") return `include all of ${joinValues(values, "and")}`;
+ if (negated)
+ return many
+ ? `include none of ${commaList(values)}`
+ : `do not include ${quote(values[0] ?? "")}`;
+ return `include ${joinValues(values, "or")}`;
+ }
+ // Bare `=` on a text column is a substring search; grouped values are an
+ // exact set (stringOptions), so they read differently.
+ if (ref.type === "field" && ref.field.syncMode === "textSearch" && !many) {
+ return negated
+ ? `does not contain ${quote(values[0] ?? "")}`
+ : `contains ${quote(values[0] ?? "")}`;
+ }
+ const exactly =
+ ref.type === "field" && ref.field.syncMode === "textSearch"
+ ? "exactly "
+ : "";
+ if (negated)
+ return many
+ ? `is none of ${commaList(values)}`
+ : `is not ${exactly}${quote(values[0] ?? "")}`;
+ return `is ${exactly}${joinValues(values, "or")}`;
+}
+
+function predicateOf(ref: FieldRef, seg: FilterSegment): string {
+ const { op, values, negated } = seg;
+
+ if (isComparison(op)) return comparisonPredicate(op, ref, values, negated);
+
+ // Number equality, before the string-operator switch: `latency:2` and
+ // `latency:=2` lower to the SAME numeric filter, so both must read "is 2
+ // seconds" β€” not a quoted, unitless "is exactly "2"" for the `:=` spelling.
+ if (ref.type === "field" && ref.field.kind === "number") {
+ const value = amount(values[0] ?? "", ref.field);
+ return negated ? `is not ${value}` : `is ${value}`;
+ }
+
+ switch (op) {
+ case "exact":
+ return negated
+ ? `is not exactly ${joinValues(values, "or")}`
+ : `is exactly ${joinValues(values, "or")}`;
+ case "~":
+ return negated
+ ? `does not contain ${joinValues(values, "or")}`
+ : `contains ${joinValues(values, "or")}`;
+ case "^":
+ return `starts with ${quote(values[0] ?? "")}`;
+ case "$":
+ return `ends with ${quote(values[0] ?? "")}`;
+ default:
+ return defaultOpPredicate(ref, seg);
+ }
+}
+
+/** A boolean token needs no value in the copy: "Is not root observation." */
+function explainBoolean(field: FieldDef, seg: FilterSegment): TokenExplanation {
+ const asked = (seg.values[0] ?? "").trim().toLowerCase() === "true";
+ const holds = seg.negated ? !asked : asked;
+ const phrase = holds ? field.label : (field.negatedLabel ?? field.label);
+ return { subject: `${phrase}.`, predicate: "" };
+}
+
+/** `has:` reads about its VALUE β€” the field that is (or isn't) set. */
+function explainHas(seg: FilterSegment): TokenExplanation {
+ const labels = seg.values.map((value) => {
+ const ref = resolveField(value);
+ return ref === null ? value : subjectOf(ref);
+ });
+ const verb = labels.length > 1 ? "are" : "is";
+ return {
+ subject: labels.join(" and "),
+ predicate: seg.negated ? `${verb} not set.` : `${verb} set.`,
+ };
+}
+
+const KEYWORDS: Record<string, TokenExplanation> = {
+ AND: { subject: "AND", predicate: "β€” every filter has to match." },
+ OR: { subject: "OR", predicate: "β€” either side can match." },
+ NOT: { subject: "NOT", predicate: "β€” excludes the filter that follows." },
+};
+
+/**
+ * Explain one token in plain language, or null when there is nothing useful to
+ * say (parentheses, an unknown field, an invalid token β€” those carry their own
+ * diagnostic).
+ */
+export function explainSegment(seg: ComposerSegment): TokenExplanation | null {
+ switch (seg.kind) {
+ case "filter": {
+ const ref = resolveField(seg.displayField);
+ if (ref === null) return null;
+ if (ref.type === "pseudo") return explainHas(seg);
+ if (ref.type === "field" && ref.field.kind === "boolean") {
+ return explainBoolean(ref.field, seg);
+ }
+ return {
+ subject: subjectOf(ref),
+ predicate: `${predicateOf(ref, seg)}.`,
+ };
+ }
+ case "freeText":
+ return {
+ subject: "Full-text search",
+ predicate: `for ${quote(seg.raw.trim())} β€” matches id, name, input and output.`,
+ };
+ case "operator":
+ return KEYWORDS[seg.raw.toUpperCase()] ?? null;
+ default:
+ return null;
+ }
+}
diff --git a/web/src/features/search-bar/lib/fields.ts b/web/src/features/search-bar/lib/fields.ts
index 24e5c35ada..179caf442a 100644
--- a/web/src/features/search-bar/lib/fields.ts
+++ b/web/src/features/search-bar/lib/fields.ts
@@ -29,6 +29,15 @@ export type FieldDef = {
aliases: string[];
kind: FieldKind;
syncMode: SyncMode;
+ /** Human name, used as the subject of a token's explanation ("Total cost is
+ * above $0.5") β€” the canonical id is camelCase and does not read as prose.
+ * On a `boolean` field this is the whole affirmative phrase instead ("Is
+ * root observation"), since such a token is a yes/no statement, not a
+ * subject with a value. */
+ label: string;
+ /** Boolean fields only: the phrase for the false case ("Is not root
+ * observation") β€” English negates these irregularly (is not / has no). */
+ negatedLabel?: string;
description: string;
/** Display unit for numeric suggestion labels (filter-config units). */
unit?: string;
@@ -45,50 +54,50 @@ export type FieldDef = {
// prettier-ignore
export const FIELDS: FieldDef[] = [
- { id: "id", aliases: ["spanid", "span_id", "observationid", "observation_id"], kind: "text", syncMode: "textSearch", suggestObservedValues: true, description: "Observation/span identifier" },
- { id: "traceId", aliases: ["traceid", "trace_id"], kind: "text", syncMode: "textSearch", description: "Trace identifier" },
- { id: "name", aliases: [], kind: "text", syncMode: "textSearch", suggestObservedValues: true, description: "Observation name", nullable: true },
- { id: "traceName", aliases: ["tracename", "trace_name"], kind: "text", syncMode: "exactOption", description: "Trace name", nullable: true },
- { id: "type", aliases: [], kind: "text", syncMode: "exactOption", description: "Observation type" },
- { id: "environment", aliases: ["env"], kind: "text", syncMode: "exactOption", description: "Environment", nullable: true },
- { id: "ingestionApiKey", aliases: ["ingestionapikey", "ingestion_api_key", "apikey", "api_key", "publickey", "public_key"], kind: "text", syncMode: "exactOption", description: "Public ingestion API key" },
- { id: "userId", aliases: ["userid", "user_id", "user"], kind: "text", syncMode: "exactOption", description: "Trace user id", nullable: true },
- { id: "sessionId", aliases: ["sessionid", "session_id", "session"], kind: "text", syncMode: "exactOption", description: "Trace session id", nullable: true },
- { id: "level", aliases: [], kind: "text", syncMode: "exactOption", description: "Observation level" },
- { id: "statusMessage", aliases: ["statusmessage", "status_message", "status"], kind: "text", syncMode: "textSearch", description: "Status message", nullable: true },
- { id: "modelId", aliases: ["modelid", "model_id"], kind: "text", syncMode: "exactOption", description: "Internal model id", nullable: true },
- { id: "providedModelName", aliases: ["providedmodelname", "provided_model_name", "model"], kind: "text", syncMode: "exactOption", description: "Provided model name", nullable: true },
- { id: "promptName", aliases: ["promptname", "prompt_name", "prompt"], kind: "text", syncMode: "exactOption", description: "Prompt name", nullable: true },
- { id: "promptVersion", aliases: ["promptversion", "prompt_version"], kind: "number", syncMode: "textSearch", description: "Prompt version", nullable: true },
- { id: "startTime", aliases: ["starttime", "start_time"], kind: "datetime", syncMode: "textSearch", description: "Observation start time" },
- { id: "endTime", aliases: ["endtime", "end_time"], kind: "datetime", syncMode: "textSearch", description: "Observation end time", nullable: true },
- { id: "latency", aliases: [], kind: "number", syncMode: "textSearch", description: "Observation latency in seconds", unit: "s", nullable: true },
- { id: "timeToFirstToken", aliases: ["timetofirsttoken", "time_to_first_token", "ttft"], kind: "number", syncMode: "textSearch", description: "Time to first token in seconds", unit: "s", nullable: true },
- { id: "tokensPerSecond", aliases: ["tokenspersecond", "tokens_per_second", "tps"], kind: "number", syncMode: "textSearch", description: "Output tokens per second", unit: "tok/s", nullable: true },
- { id: "inputTokens", aliases: ["inputtokens", "input_tokens"], kind: "number", syncMode: "textSearch", description: "Input token count", nullable: true },
- { id: "outputTokens", aliases: ["outputtokens", "output_tokens"], kind: "number", syncMode: "textSearch", description: "Output token count", nullable: true },
- { id: "totalTokens", aliases: ["totaltokens", "total_tokens", "tokens"], kind: "number", syncMode: "textSearch", description: "Total token count", nullable: true },
- { id: "inputCost", aliases: ["inputcost", "input_cost"], kind: "number", syncMode: "textSearch", description: "Input cost in USD", unit: "$", nullable: true },
- { id: "outputCost", aliases: ["outputcost", "output_cost"], kind: "number", syncMode: "textSearch", description: "Output cost in USD", unit: "$", nullable: true },
- { id: "totalCost", aliases: ["totalcost", "total_cost", "cost"], kind: "number", syncMode: "textSearch", description: "Total cost in USD", unit: "$", nullable: true },
- { id: "version", aliases: [], kind: "text", syncMode: "exactOption", description: "Version tag", nullable: true },
- { id: "release", aliases: [], kind: "text", syncMode: "exactOption", description: "Release tag", nullable: true },
- { id: "traceTags", aliases: ["tracetags", "trace_tags", "tags", "tag"], kind: "text", syncMode: "arrayOption", description: "Trace tags" },
- { id: "isRootObservation", aliases: ["isrootobservation", "is_root_observation", "root"], kind: "boolean", syncMode: "textSearch", description: "Whether the observation is a trace root" },
- { id: "hasParentObservation", aliases: ["hasparentobservation", "has_parent_observation"], kind: "boolean", syncMode: "textSearch", description: "Whether the observation has a parent (inverse of root)" },
- { id: "hasInput", aliases: ["hasinput", "has_input"], kind: "boolean", syncMode: "textSearch", description: "Whether the observation has input" },
- { id: "hasOutput", aliases: ["hasoutput", "has_output"], kind: "boolean", syncMode: "textSearch", description: "Whether the observation has output" },
- { id: "toolNames", aliases: ["toolnames", "tool_names"], kind: "text", syncMode: "arrayOption", description: "Available tool names", nullable: true },
- { id: "calledToolNames", aliases: ["calledtoolnames", "called_tool_names", "calledtools", "called_tools"], kind: "text", syncMode: "arrayOption", description: "Called tool names", nullable: true },
- { id: "toolDefinitions", aliases: ["tooldefinitions", "tool_definitions"], kind: "number", syncMode: "textSearch", description: "Available tool count", nullable: true },
- { id: "toolCalls", aliases: ["toolcalls", "tool_calls"], kind: "number", syncMode: "textSearch", description: "Tool call count", nullable: true },
- { id: "commentCount", aliases: ["commentcount", "comment_count"], kind: "number", syncMode: "textSearch", description: "Comment count" },
- { id: "commentContent", aliases: ["commentcontent", "comment_content", "comment"], kind: "text", syncMode: "textSearch", description: "Comment text", nullable: true },
- { id: "experimentDatasetId", aliases: ["experimentdatasetid", "experiment_dataset_id", "dataset"], kind: "text", syncMode: "exactOption", description: "Experiment dataset identifier", nullable: true },
- { id: "experimentId", aliases: ["experimentid", "experiment_id"], kind: "text", syncMode: "exactOption", description: "Experiment identifier", nullable: true },
- { id: "experimentName", aliases: ["experimentname", "experiment_name", "experiment"], kind: "text", syncMode: "exactOption", description: "Experiment name", nullable: true },
- { id: "input", aliases: [], kind: "text", syncMode: "textSearch", description: "Observation input", nullable: true },
- { id: "output", aliases: [], kind: "text", syncMode: "textSearch", description: "Observation output", nullable: true },
+ { id: "id", aliases: ["spanid", "span_id", "observationid", "observation_id"], kind: "text", syncMode: "textSearch", suggestObservedValues: true, label: "Observation ID", description: "Observation/span identifier" },
+ { id: "traceId", aliases: ["traceid", "trace_id"], kind: "text", syncMode: "textSearch", label: "Trace ID", description: "Trace identifier" },
+ { id: "name", aliases: [], kind: "text", syncMode: "textSearch", suggestObservedValues: true, label: "Name", description: "Observation name", nullable: true },
+ { id: "traceName", aliases: ["tracename", "trace_name"], kind: "text", syncMode: "exactOption", label: "Trace name", description: "Trace name", nullable: true },
+ { id: "type", aliases: [], kind: "text", syncMode: "exactOption", label: "Type", description: "Observation type" },
+ { id: "environment", aliases: ["env"], kind: "text", syncMode: "exactOption", label: "Environment", description: "Environment", nullable: true },
+ { id: "ingestionApiKey", aliases: ["ingestionapikey", "ingestion_api_key", "apikey", "api_key", "publickey", "public_key"], kind: "text", syncMode: "exactOption", label: "Ingestion API key", description: "Public ingestion API key" },
+ { id: "userId", aliases: ["userid", "user_id", "user"], kind: "text", syncMode: "exactOption", label: "User ID", description: "Trace user id", nullable: true },
+ { id: "sessionId", aliases: ["sessionid", "session_id", "session"], kind: "text", syncMode: "exactOption", label: "Session ID", description: "Trace session id", nullable: true },
+ { id: "level", aliases: [], kind: "text", syncMode: "exactOption", label: "Level", description: "Observation level" },
+ { id: "statusMessage", aliases: ["statusmessage", "status_message", "status"], kind: "text", syncMode: "textSearch", label: "Status message", description: "Status message", nullable: true },
+ { id: "modelId", aliases: ["modelid", "model_id"], kind: "text", syncMode: "exactOption", label: "Model ID", description: "Internal model id", nullable: true },
+ { id: "providedModelName", aliases: ["providedmodelname", "provided_model_name", "model"], kind: "text", syncMode: "exactOption", label: "Model name", description: "Provided model name", nullable: true },
+ { id: "promptName", aliases: ["promptname", "prompt_name", "prompt"], kind: "text", syncMode: "exactOption", label: "Prompt name", description: "Prompt name", nullable: true },
+ { id: "promptVersion", aliases: ["promptversion", "prompt_version"], kind: "number", syncMode: "textSearch", label: "Prompt version", description: "Prompt version", nullable: true },
+ { id: "startTime", aliases: ["starttime", "start_time"], kind: "datetime", syncMode: "textSearch", label: "Start time", description: "Observation start time" },
+ { id: "endTime", aliases: ["endtime", "end_time"], kind: "datetime", syncMode: "textSearch", label: "End time", description: "Observation end time", nullable: true },
+ { id: "latency", aliases: [], kind: "number", syncMode: "textSearch", label: "Latency", description: "Observation latency in seconds", unit: "s", nullable: true },
+ { id: "timeToFirstToken", aliases: ["timetofirsttoken", "time_to_first_token", "ttft"], kind: "number", syncMode: "textSearch", label: "Time to first token", description: "Time to first token in seconds", unit: "s", nullable: true },
+ { id: "tokensPerSecond", aliases: ["tokenspersecond", "tokens_per_second", "tps"], kind: "number", syncMode: "textSearch", label: "Tokens per second", description: "Output tokens per second", unit: "tok/s", nullable: true },
+ { id: "inputTokens", aliases: ["inputtokens", "input_tokens"], kind: "number", syncMode: "textSearch", label: "Input token count", description: "Input token count", nullable: true },
+ { id: "outputTokens", aliases: ["outputtokens", "output_tokens"], kind: "number", syncMode: "textSearch", label: "Output token count", description: "Output token count", nullable: true },
+ { id: "totalTokens", aliases: ["totaltokens", "total_tokens", "tokens"], kind: "number", syncMode: "textSearch", label: "Total token count", description: "Total token count", nullable: true },
+ { id: "inputCost", aliases: ["inputcost", "input_cost"], kind: "number", syncMode: "textSearch", label: "Input cost", description: "Input cost in USD", unit: "$", nullable: true },
+ { id: "outputCost", aliases: ["outputcost", "output_cost"], kind: "number", syncMode: "textSearch", label: "Output cost", description: "Output cost in USD", unit: "$", nullable: true },
+ { id: "totalCost", aliases: ["totalcost", "total_cost", "cost"], kind: "number", syncMode: "textSearch", label: "Total cost", description: "Total cost in USD", unit: "$", nullable: true },
+ { id: "version", aliases: [], kind: "text", syncMode: "exactOption", label: "Version", description: "Version tag", nullable: true },
+ { id: "release", aliases: [], kind: "text", syncMode: "exactOption", label: "Release", description: "Release tag", nullable: true },
+ { id: "traceTags", aliases: ["tracetags", "trace_tags", "tags", "tag"], kind: "text", syncMode: "arrayOption", label: "Trace tags", description: "Trace tags" },
+ { id: "isRootObservation", aliases: ["isrootobservation", "is_root_observation", "root"], kind: "boolean", syncMode: "textSearch", label: "Is root observation", negatedLabel: "Is not root observation", description: "Whether the observation is a trace root" },
+ { id: "hasParentObservation", aliases: ["hasparentobservation", "has_parent_observation"], kind: "boolean", syncMode: "textSearch", label: "Has a parent observation", negatedLabel: "Has no parent observation", description: "Whether the observation has a parent (inverse of root)" },
+ { id: "hasInput", aliases: ["hasinput", "has_input"], kind: "boolean", syncMode: "textSearch", label: "Has input", negatedLabel: "Has no input", description: "Whether the observation has input" },
+ { id: "hasOutput", aliases: ["hasoutput", "has_output"], kind: "boolean", syncMode: "textSearch", label: "Has output", negatedLabel: "Has no output", description: "Whether the observation has output" },
+ { id: "toolNames", aliases: ["toolnames", "tool_names"], kind: "text", syncMode: "arrayOption", label: "Available tools", description: "Available tool names", nullable: true },
+ { id: "calledToolNames", aliases: ["calledtoolnames", "called_tool_names", "calledtools", "called_tools"], kind: "text", syncMode: "arrayOption", label: "Called tools", description: "Called tool names", nullable: true },
+ { id: "toolDefinitions", aliases: ["tooldefinitions", "tool_definitions"], kind: "number", syncMode: "textSearch", label: "Available tool count", description: "Available tool count", nullable: true },
+ { id: "toolCalls", aliases: ["toolcalls", "tool_calls"], kind: "number", syncMode: "textSearch", label: "Tool call count", description: "Tool call count", nullable: true },
+ { id: "commentCount", aliases: ["commentcount", "comment_count"], kind: "number", syncMode: "textSearch", label: "Comment count", description: "Comment count" },
+ { id: "commentContent", aliases: ["commentcontent", "comment_content", "comment"], kind: "text", syncMode: "textSearch", label: "Comment text", description: "Comment text", nullable: true },
+ { id: "experimentDatasetId", aliases: ["experimentdatasetid", "experiment_dataset_id", "dataset"], kind: "text", syncMode: "exactOption", label: "Experiment dataset ID", description: "Experiment dataset identifier", nullable: true },
+ { id: "experimentId", aliases: ["experimentid", "experiment_id"], kind: "text", syncMode: "exactOption", label: "Experiment ID", description: "Experiment identifier", nullable: true },
+ { id: "experimentName", aliases: ["experimentname", "experiment_name", "experiment"], kind: "text", syncMode: "exactOption", label: "Experiment name", description: "Experiment name", nullable: true },
+ { id: "input", aliases: [], kind: "text", syncMode: "textSearch", label: "Input", description: "Observation input", nullable: true },
+ { id: "output", aliases: [], kind: "text", syncMode: "textSearch", label: "Output", description: "Observation output", nullable: true },
];
const byName = new Map<string, FieldDef>();