πͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
/* eslint-disable no-nested-ternary */
// Field registry β the single source of truth for autocomplete, validation,
// operator choice, and lowering into the flat Langfuse `FilterState`.
//
// Field ids/kinds mirror the v4 events table column definitions
// (packages/shared/src/eventsTable.ts) and the observations-events filter
// config (web/src/features/events/config/filter-config.ts). The registry only
// expresses what the existing events tRPC contract accepts today β the
// adapter never emits a filter shape the sidebar could not produce.
//
// Sync modes:
// exactOption β option-backed column; '=' lowers to stringOptions any-of
// arrayOption β array column (traceTags, toolNames); supports all-of
// textSearch β plain text/number/datetime column; '=' lowers to contains
//
// `syncMode` drives the LOWERING shape; `suggestObservedValues` drives the
// AUTOCOMPLETE picker independently β `id`/`name` are textSearch (so `id:abc`
// is a substring search) yet keep their observed-value picker.
import {
eventsTableCols,
type ColumnDefinition,
type FilterState,
type SingleValueOption,
type TracingSearchType,
} from "@langfuse/shared";
import type { CompareOp } from "./ast";
import { quoteIfNeeded, unquote } from "./quoting";
type FieldKind = "text" | "number" | "datetime" | "boolean";
type SyncMode = "exactOption" | "arrayOption" | "textSearch";
export type FieldDef = {
/** Canonical query field id; defaults to the FilterState column unless
* `filterColumn` maps a display-oriented field to canonical storage. */
id: string;
/** Lowercase aliases accepted by the grammar (canonical id always works too). */
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;
/** Column can be unset in the dataset β `has:`/`-has:` (null checks) apply. */
nullable?: boolean;
/**
* Offer the observed-value picker in autocomplete even when `syncMode` is
* `textSearch` (which otherwise has no value list). Lets `id`/`name` search
* as substring while still suggesting existing values. Implied for
* `exactOption`; only set this on `textSearch` fields that should suggest.
*/
suggestObservedValues?: boolean;
/** Preserve exact selections in the owning categorical facet's filter shape. */
exactMatchUsesOptions?: boolean;
/** Canonical FilterState column emitted for this display-oriented field. */
filterColumn?: string;
/** Display/query value β canonical FilterState value for labeled options. */
filterValueByDisplayValue?: ReadonlyMap<string, string>;
/** Canonical FilterState value β display/query value for labeled options. */
displayValueByFilterValue?: ReadonlyMap<string, string>;
/** Nullable-only columns participate in `has:` but are not direct filters. */
directFilter?: boolean;
};
export type SearchScope = {
searchType: readonly TracingSearchType[];
label: string;
description: string;
};
export type FilterTargeting = {
defaultTarget: string;
/** Meaning of targetless persisted filters, before target-aware editing. */
legacyDefaultTarget?: string;
targets: readonly {
id: string;
label: string;
displayLabel?: string;
keyword?: boolean;
textClassName?: string;
}[];
supports: (field: FieldRef) => boolean;
scoreTypesError?: string;
};
export type FieldRegistry = {
id:
| "events"
| "evaluationRules"
| "evaluatorSamples"
| "ruleSamples"
| "sessions"
| "sessionTraces"
| "scores"
| "experiments"
| "users"
| "traces"
| "observations"
| "evaluatorsList"
| "evaluationRulesList"
| "legacyEvaluators"
| "evalLogs"
| "prompts"
| "skills"
| "topics"
| "monitors"
| "gatewayModels"
| "experimentItems"
| "datasetItems";
defaultSearchType: readonly TracingSearchType[];
searchScopes: Readonly<Record<string, SearchScope>>;
fields: readonly FieldDef[];
columns: readonly ColumnDefinition[];
allowFreeText: boolean;
targeting?: FilterTargeting;
/** View-specific backend constraints beyond individual column operators. */
filterStateErrors?: (filters: FilterState) => readonly string[];
/** Whether this view exposes metadata.<key> filters. */
metadata: boolean;
/** Additional metadata roots mapped to their backend FilterState columns. */
metadataNamespaces?: Readonly<Record<string, string>>;
scores: boolean;
/** Trace-level `traceScores.<name>` paths. Views whose backend has no
* trace-score columns (sessions) keep observation scores without them. */
traceScores: boolean;
/** Field a bare word searches on a view with no full-text lane. Sessions has
* no searchQuery, but `id contains` is its most-applied filter by far, so a
* bare word means that instead of being rejected. Null = reject. */
defaultTextField: string | null;
/**
* What a bare word matches, phrased for the hint and the scope list
* ("ids, names, input & output"). Written per view because the registry
* cannot see it: `searchQuery` lowers to a column list the BACKEND picks,
* and the users query narrows that list to `user_id` while keeping the same
* field catalog. Null drops the clause rather than guessing β vague beats
* naming columns a view does not search.
*/
freeTextScopeLabel: string | null;
/** Placeholder examples. Written per view, never derived from field ids: the
* events examples advertise `latency:`/`level:` on a view that has neither. */
searchExamples: readonly string[];
searchPlaceholder?: string;
/**
* Field id used in the `has:` hint. Written per view like `searchExamples`:
* deriving it (e.g. "first nullable field") silently rewrites the hint
* whenever the field order changes. Null falls back to the first nullable.
*/
hasExample: string | null;
/**
* Offer the project's recent searches on the empty bar. Off by default: the
* store is per PROJECT, not per view, so a view opts in and only the recents
* that are valid against its own registry are offered.
*/
recentSearches: boolean;
/**
* Whether this view has its OWN branch in `buildFilterSystemPrompt`. False
* hides Ask AI: the fallback prompt is the events one β events prose, events
* worked examples β so a view without its own branch would be handed a
* correct field catalog wrapped in instructions steering the model at columns
* it does not have. Write the branch, then flip this.
*/
aiFilterPrompt: boolean;
aiContextFields: readonly AIContextField[];
resolveField: (name: string) => FieldRef | null;
nullableFields: () => readonly FieldDef[];
/** Ids of `nullableFields`, precomputed for per-keystroke validation. */
nullableFieldIds: ReadonlySet<string>;
isDanglingDotPrefix: (value: string) => boolean;
columnIdOf: (column: string) => string | null;
};
export type AIContextField = {
/** Key in the observed filter-options payload. */
observedOptionsKey: string;
/** Human-readable field description rendered into the AI prompt context. */
promptLabel: string;
};
export type FieldOverlay = Partial<
Omit<
FieldDef,
"id" | "kind" | "label" | "description" | "exactMatchUsesOptions"
>
> & {
label?: string;
description?: string;
};
export function fieldRegistryFromColumns(
columns: readonly ColumnDefinition[],
overlay: {
id: FieldRegistry["id"];
fields?: Readonly<Record<string, FieldOverlay>>;
metadata?: boolean;
metadataNamespaces?: Readonly<Record<string, string>>;
scores?: boolean;
/** Defaults to `scores`. */
traceScores?: boolean;
allowFreeText?: boolean;
defaultSearchType?: readonly TracingSearchType[];
searchScopes?: Readonly<Record<string, SearchScope>>;
filterStateErrors?: (filters: FilterState) => readonly string[];
defaultTextField?: string;
freeTextScopeLabel?: string;
searchExamples?: readonly string[];
searchPlaceholder?: string;
hasExample?: string;
recentSearches?: boolean;
aiFilterPrompt?: boolean;
aiContextFields?: readonly AIContextField[];
},
): FieldRegistry {
const scores = overlay.scores ?? false;
const fields = columns
// `*Object` columns and the categorical score column are keyed dot-paths
// (`metadata.<key>`, `scores.<name>`), never plain fields β a derived
// `score_categories` field would lower to a keyless categoryOptions filter
// the backend cannot answer. That holds whether or not this view exposes
// the `scores.` namespace: a view whose sidebar owns score filters still
// has the column in its facets, and it is sidebar-only, not a bare field.
// They stay in `columns` so the reverse adapter still resolves them.
.filter(
(column) =>
!column.type.endsWith("Object") && !isKeyedScoreColumn(column.id),
)
.map((column): FieldDef => {
const fieldOverlay = overlay.fields?.[column.id];
const kind: FieldKind =
column.type === "number" ||
column.type === "datetime" ||
column.type === "boolean"
? column.type
: "text";
const syncMode: SyncMode =
column.type === "stringOptions" || column.type === "categoryOptions"
? "exactOption"
: column.type === "arrayOptions"
? "arrayOption"
: "textSearch";
return {
id: column.id,
aliases: fieldOverlay?.aliases ?? column.aliases ?? [],
kind,
syncMode: fieldOverlay?.syncMode ?? syncMode,
exactMatchUsesOptions: column.type === "stringOptions",
label: fieldOverlay?.label ?? column.name,
description: fieldOverlay?.description ?? column.name,
nullable: column.nullable,
directFilter: column.type !== "null",
suggestObservedValues: fieldOverlay?.suggestObservedValues,
filterColumn: fieldOverlay?.filterColumn,
filterValueByDisplayValue: fieldOverlay?.filterValueByDisplayValue,
displayValueByFilterValue: fieldOverlay?.displayValueByFilterValue,
unit: fieldOverlay?.unit,
negatedLabel: fieldOverlay?.negatedLabel,
};
});
return createFieldRegistry({
id: overlay.id,
fields,
columns,
metadata: overlay.metadata ?? false,
metadataNamespaces: overlay.metadataNamespaces,
scores,
traceScores: overlay.traceScores ?? scores,
allowFreeText: overlay.allowFreeText ?? true,
defaultSearchType: overlay.defaultSearchType,
searchScopes: overlay.searchScopes,
filterStateErrors: overlay.filterStateErrors,
defaultTextField: overlay.defaultTextField ?? null,
freeTextScopeLabel: overlay.freeTextScopeLabel ?? null,
searchExamples: overlay.searchExamples ?? [],
searchPlaceholder: overlay.searchPlaceholder,
hasExample: overlay.hasExample ?? null,
recentSearches: overlay.recentSearches ?? false,
aiFilterPrompt: overlay.aiFilterPrompt ?? false,
aiContextFields: overlay.aiContextFields ?? [],
});
}
export function extendFieldRegistryWithColumns(
registry: FieldRegistry,
columns: readonly ColumnDefinition[],
fieldOverlays?: Readonly<Record<string, FieldOverlay>>,
): FieldRegistry {
const addedFields = fieldRegistryFromColumns(columns, {
id: registry.id,
fields: fieldOverlays,
}).fields;
return createFieldRegistry({
id: registry.id,
fields: [...registry.fields, ...addedFields],
columns: [...registry.columns, ...columns],
metadata: registry.metadata,
metadataNamespaces: registry.metadataNamespaces,
scores: registry.scores,
traceScores: registry.traceScores,
allowFreeText: registry.allowFreeText,
defaultSearchType: registry.defaultSearchType,
searchScopes: registry.searchScopes,
filterStateErrors: registry.filterStateErrors,
targeting: registry.targeting,
defaultTextField: registry.defaultTextField,
freeTextScopeLabel: registry.freeTextScopeLabel,
searchExamples: registry.searchExamples,
hasExample: registry.hasExample,
recentSearches: registry.recentSearches,
aiFilterPrompt: registry.aiFilterPrompt,
aiContextFields: registry.aiContextFields,
});
}
export function withFieldOptions(
registry: FieldRegistry,
fieldId: string,
options: readonly SingleValueOption[],
): FieldRegistry {
const filterValueByDisplayValue = new Map(
options.map((option) => [
option.displayValue ?? option.value,
option.value,
]),
);
const displayValueByFilterValue = new Map(
options.map((option) => [
option.value,
option.displayValue ?? option.value,
]),
);
return createFieldRegistry({
id: registry.id,
fields: registry.fields.map((field) =>
field.id === fieldId
? {
...field,
filterValueByDisplayValue,
displayValueByFilterValue,
}
: field,
),
columns: registry.columns,
metadata: registry.metadata,
metadataNamespaces: registry.metadataNamespaces,
scores: registry.scores,
traceScores: registry.traceScores,
allowFreeText: registry.allowFreeText,
defaultSearchType: registry.defaultSearchType,
searchScopes: registry.searchScopes,
filterStateErrors: registry.filterStateErrors,
targeting: registry.targeting,
defaultTextField: registry.defaultTextField,
freeTextScopeLabel: registry.freeTextScopeLabel,
searchExamples: registry.searchExamples,
hasExample: registry.hasExample,
recentSearches: registry.recentSearches,
aiFilterPrompt: registry.aiFilterPrompt,
aiContextFields: registry.aiContextFields,
});
}
// prettier-ignore
export const FIELDS: FieldDef[] = [
{ 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, exactMatchUsesOptions: 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: "ingestionSdkName", aliases: ["ingestionsdkname", "ingestion_sdk_name", "sdkname", "sdk_name"], kind: "text", syncMode: "exactOption", label: "Ingestion SDK name", description: "Ingestion SDK name" },
{ id: "ingestionSdkVersion", aliases: ["ingestionsdkversion", "ingestion_sdk_version", "sdkversion", "sdk_version"], kind: "text", syncMode: "exactOption", label: "Ingestion SDK version", description: "Ingestion SDK version" },
{ id: "ingestionSource", aliases: ["ingestionsource", "ingestion_source", "source"], kind: "text", syncMode: "exactOption", label: "Ingestion source", description: "Ingestion source (API or OTel path)" },
{ 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: "Status", description: "Observation status" },
{ 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: "cachedInputTokens", aliases: ["cachedinputtokens", "cached_input_tokens", "cachedtokens", "cached_tokens"], kind: "number", syncMode: "textSearch", label: "Cached input token count", description: "Cache-read 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: "cachedInputCost", aliases: ["cachedinputcost", "cached_input_cost", "cachedcost", "cached_cost"], kind: "number", syncMode: "textSearch", label: "Cached input cost", description: "Cache-read 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: "skillNamesAvailable", aliases: ["availableSkills", "available_skills"], kind: "text", syncMode: "arrayOption", label: "Available skills", description: "Available skill names" },
{ id: "skillsNamesLoaded", aliases: ["loadedSkills", "loaded_skills"], kind: "text", syncMode: "arrayOption", label: "Loaded skills", description: "Loaded skill names" },
{ 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: "isExperimentItemRootSpan", aliases: ["isexperimentitemrootspan", "is_experiment_item_root_span", "experimentroot"], kind: "boolean", syncMode: "textSearch", label: "Is experiment item root span", negatedLabel: "Is not experiment item root span", description: "Whether the observation is the root span for an experiment item" },
{ 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 METADATA_PREFIX = "metadata.";
// Score dot-paths. Lowercased prefixes accepted by the grammar; the
// canonical spellings are `scores.<name>` and `traceScores.<name>`.
const SCORE_PREFIXES = ["scores.", "score."];
const TRACE_SCORE_PREFIXES = ["tracescores.", "trace_scores.", "tracescore."];
// Presence checks lower to null filters. Compatibility `in:` and declared
// search scopes select the backend search lane without adding column filters.
const HAS_KEY = "has";
/** Langfuse score filter columns (filter by score NAME via key-value ops). */
export const SCORE_COLUMNS = {
observation: {
numeric: "scores_avg",
categorical: "score_categories",
boolean: "score_booleans",
},
trace: {
numeric: "trace_scores_avg",
categorical: "trace_score_categories",
boolean: "trace_score_booleans",
},
} as const;
const KEYED_SCORE_COLUMNS: ReadonlySet<string> = new Set([
...Object.values(SCORE_COLUMNS.observation),
...Object.values(SCORE_COLUMNS.trace),
]);
function isKeyedScoreColumn(column: string): boolean {
return KEYED_SCORE_COLUMNS.has(column);
}
export type FieldRef =
| { type: "field"; field: FieldDef }
| { type: "searchScope"; id: string; scope: SearchScope }
| { type: "metadata"; key: string; namespace?: string; column?: string }
| { type: "scores"; key: string; level: "observation" | "trace" }
| { type: "pseudo"; id: typeof HAS_KEY | "in" };
/**
* Assembles a registry from field defs that already exist. `fieldRegistryFromColumns`
* derives its defs from `ColumnDefinition.type`, which is right for a view with no
* grammar of its own β but a view that narrows ANOTHER view's grammar must reuse that
* view's defs verbatim. Deriving them again would silently re-decide `syncMode` from
* the column type and give the same field a different meaning on the two bars
* (`name:checkout` an exact match on one, a substring on the other).
*/
export function createFieldRegistry({
id,
fields,
columns,
metadata,
metadataNamespaces,
scores,
traceScores,
allowFreeText,
defaultSearchType = ["id", "content"],
searchScopes = {},
filterStateErrors,
targeting,
defaultTextField,
freeTextScopeLabel,
searchExamples,
searchPlaceholder,
hasExample,
recentSearches,
aiFilterPrompt,
aiContextFields,
}: {
id: FieldRegistry["id"];
fields: readonly FieldDef[];
columns: readonly ColumnDefinition[];
metadata: boolean;
metadataNamespaces?: Readonly<Record<string, string>>;
scores: boolean;
traceScores: boolean;
allowFreeText: boolean;
defaultSearchType?: readonly TracingSearchType[];
searchScopes?: Readonly<Record<string, SearchScope>>;
targeting?: FilterTargeting;
/** View-specific backend constraints beyond individual column operators. */
filterStateErrors?: (filters: FilterState) => readonly string[];
defaultTextField: string | null;
freeTextScopeLabel: string | null;
searchExamples: readonly string[];
searchPlaceholder?: string;
hasExample: string | null;
recentSearches: boolean;
aiFilterPrompt: boolean;
aiContextFields: readonly AIContextField[];
}): FieldRegistry {
const byName = new Map<string, FieldDef>();
for (const field of fields) {
byName.set(field.id.toLowerCase(), field);
for (const alias of field.aliases) byName.set(alias.toLowerCase(), field);
}
const nullable = fields.filter((field) => field.nullable === true);
const columnIds = new Map<string, string>();
for (const column of columns) {
columnIds.set(column.id.toLowerCase(), column.id);
columnIds.set(column.name.toLowerCase(), column.id);
for (const alias of column.aliases ?? []) {
columnIds.set(alias.toLowerCase(), column.id);
}
}
for (const field of fields) {
if (field.filterColumn) {
columnIds.set(field.filterColumn.toLowerCase(), field.id);
}
}
const registry: FieldRegistry = {
id,
fields,
columns,
allowFreeText,
defaultSearchType,
searchScopes,
filterStateErrors,
targeting,
metadata,
metadataNamespaces,
scores,
traceScores,
defaultTextField,
freeTextScopeLabel,
searchExamples,
searchPlaceholder,
hasExample,
recentSearches,
aiFilterPrompt,
aiContextFields,
resolveField: (name) => resolveFromRegistry(name, registry, byName),
nullableFields: () => nullable,
nullableFieldIds: new Set(nullable.map((field) => field.id)),
isDanglingDotPrefix: (value) => {
const lower = value.toLowerCase();
return (
(metadata && lower === METADATA_PREFIX) ||
Object.keys(metadataNamespaces ?? {}).some(
(name) => lower === `${name.toLowerCase()}.`,
) ||
(scores && SCORE_PREFIXES.includes(lower)) ||
(traceScores && TRACE_SCORE_PREFIXES.includes(lower))
);
},
columnIdOf: (column) => columnIds.get(column.toLowerCase()) ?? null,
};
return registry;
}
export const EVENTS_FIELD_REGISTRY = createFieldRegistry({
id: "events",
fields: FIELDS,
columns: eventsTableCols,
metadata: true,
scores: true,
traceScores: true,
allowFreeText: true,
searchScopes: {
content: {
searchType: ["content"],
label: "Content",
description: "search only input and output",
},
all: {
searchType: ["id", "content"],
label: "All fields",
description: "search IDs, names, input and output",
},
},
defaultTextField: null,
freeTextScopeLabel: "ids, names, input & output",
searchExamples: [
"level:ERROR",
"-env:dev",
"latency:>2",
"scores.accuracy:>0.8",
],
hasExample: "endTime",
recentSearches: true,
aiFilterPrompt: true,
aiContextFields: [
{ observedOptionsKey: "type", promptLabel: "type" },
{ observedOptionsKey: "level", promptLabel: "level" },
{ observedOptionsKey: "environment", promptLabel: "environment" },
{ observedOptionsKey: "traceName", promptLabel: "traceName" },
{ observedOptionsKey: "name", promptLabel: "name" },
{ observedOptionsKey: "traceTags", promptLabel: "traceTags (tags)" },
{
observedOptionsKey: "providedModelName",
promptLabel: "providedModelName (model)",
},
{ observedOptionsKey: "promptName", promptLabel: "promptName" },
{
observedOptionsKey: SCORE_COLUMNS.observation.numeric,
promptLabel: "scores.<name> (numeric)",
},
{
observedOptionsKey: SCORE_COLUMNS.observation.categorical,
promptLabel: "scores.<name> (categorical)",
},
{
observedOptionsKey: SCORE_COLUMNS.observation.boolean,
promptLabel: "scores.<name> (boolean)",
},
{
observedOptionsKey: SCORE_COLUMNS.trace.numeric,
promptLabel: "traceScores.<name> (numeric)",
},
{
observedOptionsKey: SCORE_COLUMNS.trace.categorical,
promptLabel: "traceScores.<name> (categorical)",
},
{
observedOptionsKey: SCORE_COLUMNS.trace.boolean,
promptLabel: "traceScores.<name> (boolean)",
},
],
});
function resolveFromRegistry(
name: string,
registry: FieldRegistry,
byName: ReadonlyMap<string, FieldDef>,
): FieldRef | null {
const lower = name.toLowerCase();
for (const [namespace, column] of Object.entries(
registry.metadataNamespaces ?? {},
)) {
const prefix = `${namespace}.`;
if (lower.startsWith(prefix.toLowerCase())) {
const key = unquote(name.slice(prefix.length)).value;
return key.length > 0
? { type: "metadata", key, namespace, column }
: null;
}
}
if (registry.metadata && lower.startsWith(METADATA_PREFIX)) {
const key = unquote(name.slice(METADATA_PREFIX.length)).value;
return key.length > 0 ? { type: "metadata", key } : null;
}
if (registry.traceScores) {
for (const prefix of TRACE_SCORE_PREFIXES) {
if (lower.startsWith(prefix)) {
const key = unquote(name.slice(prefix.length)).value;
return key.length > 0 ? { type: "scores", key, level: "trace" } : null;
}
}
}
if (registry.scores) {
for (const prefix of SCORE_PREFIXES) {
if (lower.startsWith(prefix)) {
const key = unquote(name.slice(prefix.length)).value;
return key.length > 0
? { type: "scores", key, level: "observation" }
: null;
}
}
}
if (lower === HAS_KEY) return { type: "pseudo", id: lower };
if (
registry.allowFreeText &&
Object.keys(registry.searchScopes).length > 0 &&
lower === "in"
)
return { type: "pseudo", id: "in" };
const scope = Object.hasOwn(registry.searchScopes, lower)
? registry.searchScopes[lower]
: undefined;
if (registry.allowFreeText && scope)
return { type: "searchScope", id: lower, scope };
const field = byName.get(lower);
return field ? { type: "field", field } : null;
}
/**
* Resolve a user-typed key (case-insensitive, alias-aware) to a field, a
* metadata/score dot path (the key keeps its case), or a pseudo-field.
* Null = unknown key.
*/
export function resolveField(
name: string,
registry: FieldRegistry = EVENTS_FIELD_REGISTRY,
): FieldRef | null {
return registry.resolveField(name);
}
/**
* A dot-path prefix typed/picked with no key after the dot (`metadata.`,
* `scores.`, `traceScores.` and accepted aliases). These parse as free text
* (no colon), so without this guard committing one would silently set the
* full-text searchQuery to the bare prefix.
*/
export function isDanglingDotPrefix(
value: string,
registry: FieldRegistry = EVENTS_FIELD_REGISTRY,
): boolean {
return registry.isDanglingDotPrefix(value);
}
// ---- operator validity ----
//
// One table consulted by the parser (span diagnostics), the validator (commit
// gate), and the adapter (lowering guard), so the three layers cannot drift.
// Everything allowed here lowers to a filter shape the events tRPC contract
// accepts today (filterTypeCompatibility.ts in @langfuse/shared).
const COMPARISONS: ReadonlySet<CompareOp> = new Set([">", "<", ">=", "<="]);
const STRING_OPS: ReadonlySet<CompareOp> = new Set(["exact", "~", "^", "$"]);
const OP_LABEL: Record<string, string> = {
"~": "contains (*term*)",
"^": "starts-with (term*)",
$: "ends-with (*term)",
exact: "exact match (=)",
};
function label(op: CompareOp): string {
return OP_LABEL[op] ?? op;
}
/**
* Is `op` (with `valueOp` grouping) usable on the field `ref` points at?
* Returns the error message, or null when valid. Value-level checks (numeric
* parse, ISO dates, true/false, has:/in: domains, flat-contract limits) live
* in validate.ts.
*/
export function operatorIssue(
ref: FieldRef,
op: CompareOp,
valueOp: "or" | "and" = "or",
): string | null {
if (valueOp === "and") {
const isArray =
ref.type === "field" && ref.field.syncMode === "arrayOption";
if (!isArray) {
const name = refName(ref);
return `AND grouping (all of) only applies to array fields like traceTags β "${name}" is not an array`;
}
if (op !== "=")
return `AND grouping only works with plain values, not ${label(op)}`;
}
switch (ref.type) {
case "searchScope":
return op === "="
? null
: `${ref.id}: searches one phrase β ${label(op)} is not supported`;
case "pseudo":
if (op !== "=") {
return `${ref.id}: lists ${ref.id === "has" ? "fields that have a value" : "search scopes"} β it does not support ${label(op)}`;
}
return null;
case "metadata":
// stringObject filters support string ops only; there is no numeric
// metadata filter in the current contract.
if (COMPARISONS.has(op)) {
return `metadata filters match text β ${op} comparisons are not supported`;
}
return null;
case "scores":
if (STRING_OPS.has(op) && op !== "exact") {
return `score filters compare numbers (${refName(ref)}:>0.8) or match categories (${refName(ref)}:positive) β ${label(op)} is not supported`;
}
return null;
case "field": {
const f = ref.field;
if (f.directFilter === false) {
return `"${f.id}" only supports presence checks (has:${f.id} or -has:${f.id})`;
}
if (f.filterColumn && (op === "~" || op === "^" || op === "$")) {
return `"${f.id}" maps labeled options to exact stored values and does not support ${label(op)}`;
}
if (f.kind === "number") {
if (op === "~" || op === "^" || op === "$") {
return `"${f.id}" is a number field and does not support ${label(op)}`;
}
return null;
}
if (f.kind === "datetime") {
if (op === "=" || op === "exact") {
return `"${f.id}" is a datetime field β use a comparison (e.g. ${f.id}:>2026-06-01)`;
}
if (!COMPARISONS.has(op)) {
return `"${f.id}" is a datetime field and does not support ${label(op)}`;
}
return null;
}
if (f.kind === "boolean") {
if (op !== "=" && op !== "exact") {
return `"${f.id}" is a boolean field and does not support ${label(op)}`;
}
return null;
}
// text
if (COMPARISONS.has(op)) {
return `"${f.id}" is a text field and does not support ${op}`;
}
if (f.syncMode === "arrayOption" && STRING_OPS.has(op)) {
return `"${f.id}" is an array field β use values (${f.id}:a), any-of groups (${f.id}:(a OR b)), or all-of groups (${f.id}:(a AND b))`;
}
return null;
}
}
}
/**
* Negation gaps: operations whose negative form has no counterpart in the
* flat Langfuse filter contract.
*/
export function negationIssue(
ref: FieldRef,
op: CompareOp,
valueOp: "or" | "and" = "or",
): string | null {
if (
ref.type === "searchScope" ||
(ref.type === "pseudo" && ref.id === "in")
) {
return `Search scopes cannot be negated β search text is global`;
}
if (valueOp === "and") {
// NOT(all of) would mean "missing at least one" β no such array operator.
return `negated all-of groups on "${refName(ref)}" are not representable β negate single values instead`;
}
if (ref.type === "pseudo") {
return null; // -has: is valid (missing value); in: was rejected above.
}
if (op === "^" || op === "$") {
return `negation of ${label(op)} is not representable in the Langfuse filter contract`;
}
if (op === "exact" || op === "=") {
if (ref.type === "metadata") {
// stringObject has no "does not equal" β only does-not-contain.
return op === "exact"
? `negated exact match on metadata is not representable β use -${refName(ref)}:*value* (does not contain)`
: null; // '=' on metadata negates via categoryOptions? No β handled below.
}
if (ref.type === "scores") {
// Numeric scores have no != ; categorical scores negate via none-of.
return null; // checked per-value in validate.ts (numeric vs categorical)
}
if (ref.type === "field") {
const f = ref.field;
if (f.kind === "number") {
return `negated equality on "${f.id}" is not representable β use comparisons (${f.id}:<n or ${f.id}:>n)`;
}
if (f.kind === "boolean") return null; // inverts the value
// Negated exact on a textSearch field (`-name:=abc`) IS representable: it
// is exact-inequality, which lowers to a stringOptions `none of` (there is
// no `string !=`, but the option-set form covers it β and it is the shape
// the facet emits when one value is unchecked). So no negation gap here.
return null;
}
}
return null;
}
function refName(ref: FieldRef): string {
switch (ref.type) {
case "field":
return ref.field.id;
case "metadata":
return `${ref.namespace ?? "metadata"}.${quoteIfNeeded(ref.key)}`;
case "scores":
return ref.level === "trace"
? `traceScores.${quoteIfNeeded(ref.key)}`
: `scores.${quoteIfNeeded(ref.key)}`;
case "pseudo":
case "searchScope":
return ref.id;
}
}
/** Canonical query-text key for a resolved field reference. */
export function canonicalKey(ref: FieldRef): string {
return refName(ref);
}