Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

refactor(query-ast): reuse the row field map for by-id selects and type the skills columns (#19081)

Niklas Semmlerf384f91e0ca9
diff --git a/packages/shared/src/server/query-ast/schema.ts b/packages/shared/src/server/query-ast/schema.ts
index 0679474407..ac90b7ba0a 100644
--- a/packages/shared/src/server/query-ast/schema.ts
+++ b/packages/shared/src/server/query-ast/schema.ts
@@ -42,7 +42,16 @@ export type ChColumnType =
| "Array(String)"
| "Map(String, UInt64)"
| "Map(String, Decimal(18,12))"
- | "Map(String, String)";
+ | "Map(String, String)"
+ | "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String))"
+ | "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String, filePath String))";
+
+/** One `skills_available` element, read as an object keyed by tuple name. */
+type SkillRef = {
+ langfuseSkillId: string | null;
+ skillVersion: number | null;
+ skillName: string;
+};
/**
* Logical TS type of a column: the value a caller binds, and what a result
@@ -76,7 +85,11 @@ type TsTypeOfColumn<T extends ChColumnType> = T extends "String"
? Record<string, number>
: T extends "Map(String, String)"
? Record<string, string>
- : never;
+ : T extends "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String))"
+ ? SkillRef[]
+ : T extends "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String, filePath String))"
+ ? (SkillRef & { filePath: string })[]
+ : never;
/** Coarse runtime category the aggregate type-check pass reasons about. */
export type ColumnDataType = "string" | "number" | "date" | "array" | "map";
@@ -99,6 +112,10 @@ const RUNTIME_TYPE: Record<ChColumnType, ColumnDataType> = {
"Map(String, UInt64)": "map",
"Map(String, Decimal(18,12))": "map",
"Map(String, String)": "map",
+ "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String))":
+ "array",
+ "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String, filePath String))":
+ "array",
};
/**
@@ -227,6 +244,10 @@ const EVENTS_COLUMNS = {
created_at: "DateTime64(6)",
updated_at: "DateTime64(6)",
ingestion_api_key: "String",
+ skills_available:
+ "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String))",
+ skills_resource_loaded:
+ "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String, filePath String))",
} as const satisfies Record<string, ChColumnType>;
/**
@@ -405,6 +426,10 @@ const BIND_TYPE: Record<ChColumnType, string> = {
"Map(String, UInt64)": "Map(String, UInt64)",
"Map(String, Decimal(18,12))": "Map(String, Decimal(18, 12))",
"Map(String, String)": "Map(String, String)",
+ "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String))":
+ "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String))",
+ "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String, filePath String))":
+ "Array(Tuple(langfuseSkillId Nullable(String), skillVersion Nullable(UInt32), skillName String, filePath String))",
};
/** Bind type per column, per registry table. */
diff --git a/packages/shared/src/server/query-ast/types.assert.ts b/packages/shared/src/server/query-ast/types.assert.ts
index af4c80c2ef..81832ede8c 100644
--- a/packages/shared/src/server/query-ast/types.assert.ts
+++ b/packages/shared/src/server/query-ast/types.assert.ts
@@ -46,6 +46,27 @@ export function schemaTypeAssertions(): void {
fromView(view)
// @ts-expect-error view is a black box: inner columns are not exposed
.select("span_id");
+
+ // Named-tuple arrays read as arrays of objects keyed by tuple name; a typo
+ // in the column type would make the row field `never` and reject these.
+ const _skills = db
+ .selectFrom("events_core")
+ .select(["skills_available", "skills_resource_loaded"]);
+ type SkillsRow = InferResult<typeof _skills>[number];
+ const _available: SkillsRow["skills_available"] = [
+ { langfuseSkillId: null, skillVersion: null, skillName: "s" },
+ { langfuseSkillId: "id", skillVersion: 1, skillName: "s" },
+ ];
+ const _loaded: SkillsRow["skills_resource_loaded"] = [
+ {
+ langfuseSkillId: null,
+ skillVersion: null,
+ skillName: "s",
+ filePath: "f",
+ },
+ ];
+ // @ts-expect-error skills_available elements have no filePath
+ type _NoFilePath = SkillsRow["skills_available"][number]["filePath"];
}
/**
diff --git a/packages/shared/src/server/repositories/events-selects.ts b/packages/shared/src/server/repositories/events-selects.ts
index 633c077fc3..e691d28ee2 100644
--- a/packages/shared/src/server/repositories/events-selects.ts
+++ b/packages/shared/src/server/repositories/events-selects.ts
@@ -1,14 +1,4 @@
-import {
- sql,
- type Expression,
- type ExpressionBuilder,
- type SelectExpression,
-} from "kysely";
-
-import type {
- SkillsAvailable,
- SkillsResourceLoaded,
-} from "../../features/skills/trace";
+import type { Expression, ExpressionBuilder, SelectExpression } from "kysely";
import {
argMaxIf,
@@ -41,7 +31,11 @@ import {
uniqIf,
} from "../query-ast/extensions";
import type { ClickHouseDatabase } from "../query-ast/schema";
-import type { FieldSetFieldKey } from "./events-field-sets";
+import {
+ orderedFieldKeys,
+ type EventsFieldKey,
+ type FieldSetFieldKey,
+} from "./events-field-sets";
/** One row of the session aggregation (`sessionAggregationSelects`). */
export type SessionEventsMetricsRow = {
@@ -77,6 +71,51 @@ type EventsSelection = SelectExpression<EventsDb, "e">;
type EventsExpressionBuilder = ExpressionBuilder<EventsDb, "e">;
+const OBSERVATION_BY_ID_FIELDS = orderedFieldKeys([
+ "id",
+ "traceId",
+ "projectId",
+ "environment",
+ "type",
+ "parentObservationId",
+ "name",
+ "level",
+ "statusMessage",
+ "version",
+ "bookmarked",
+ "public",
+ "userId",
+ "sessionId",
+ "traceName",
+ "startTime",
+ "endTime",
+ "completionStartTime",
+ "createdAt",
+ "updatedAt",
+ "eventTs",
+ "providedModelName",
+ "internalModelId",
+ "modelParameters",
+ "providedUsageDetails",
+ "usageDetails",
+ "providedCostDetails",
+ "costDetails",
+ "totalCost",
+ "promptId",
+ "promptName",
+ "promptVersion",
+ "skillsAvailable",
+ "skillsResourceLoaded",
+ "toolDefinitions",
+ "toolCalls",
+ "toolCallNames",
+ "usagePricingTierId",
+ "usagePricingTierName",
+ "metadata",
+ "tags",
+ "release",
+] as const satisfies readonly EventsFieldKey[]);
+
const eventsMetadataMap = (eb: EventsExpressionBuilder) =>
metadataMap(eb.ref("e.metadata_names"), eb.ref("e.metadata_values"));
@@ -321,57 +360,6 @@ function sessionAggregationSelectMap(eb: EventsExpressionBuilder) {
} satisfies Record<SessionEventsField, EventsSelection>;
}
-/** One observation's fields, without input/output. */
-export const observationByIdSelects = scopedToEvents(
- (eb) =>
- [
- "e.span_id as id",
- "e.trace_id as trace_id",
- "e.project_id as project_id",
- "e.environment as environment",
- "e.type as type",
- "e.parent_span_id as parent_observation_id",
- "e.name as name",
- "e.level as level",
- "e.status_message as status_message",
- "e.version as version",
- "e.bookmarked as bookmarked",
- "e.public as public",
- "e.user_id as user_id",
- "e.session_id as session_id",
- traceNameSelect(eb),
- "e.start_time as start_time",
- "e.end_time as end_time",
- "e.completion_start_time as completion_start_time",
- "e.created_at as created_at",
- "e.updated_at as updated_at",
- "e.event_ts",
- "e.provided_model_name as provided_model_name",
- "e.model_id as internal_model_id",
- "e.model_parameters as model_parameters",
- "e.provided_usage_details as provided_usage_details",
- "e.usage_details as usage_details",
- "e.provided_cost_details as provided_cost_details",
- "e.cost_details as cost_details",
- "e.total_cost as total_cost",
- "e.prompt_id as prompt_id",
- "e.prompt_name as prompt_name",
- "e.prompt_version as prompt_version",
- sql.ref<SkillsAvailable>("e.skills_available").as("skills_available"),
- sql
- .ref<SkillsResourceLoaded>("e.skills_resource_loaded")
- .as("skills_resource_loaded"),
- "e.tool_definitions as tool_definitions",
- "e.tool_calls as tool_calls",
- "e.tool_call_names as tool_call_names",
- "e.usage_pricing_tier_id as usage_pricing_tier_id",
- "e.usage_pricing_tier_name as usage_pricing_tier_name",
- eventsMetadataMap(eb).as("metadata"),
- "e.tags as tags",
- "e.release as release",
- ] satisfies EventsSelection[],
-);
-
/** Milliseconds from an event's start to `end`, NULL while `end` is unset. */
export const millisecondsSinceStart = scopedToEvents(
(
@@ -413,6 +401,10 @@ type RowFieldSet =
| "tools"
| "export";
+type RowFieldKey =
+ | FieldSetFieldKey<RowFieldSet>
+ | (typeof OBSERVATION_BY_ID_FIELDS)[number];
+
/**
* Row-level event fields for `keys`, in that order. Pass keys in
* `eventsFieldSetKeys` order: clustered reads align result blocks by column
@@ -420,6 +412,11 @@ type RowFieldSet =
*/
export const eventsRowFieldSelects = pickSelects(rowFieldSelectMap);
+/** One observation's fields, without input/output. */
+export const observationByIdSelects = eventsRowFieldSelects(
+ OBSERVATION_BY_ID_FIELDS,
+);
+
/**
* Row-level event fields, keyed like the legacy builder's field sets. Select
* them in `eventsFieldSetKeys` order: clustered reads align result blocks by
@@ -450,14 +447,20 @@ function rowFieldSelectMap(eb: EventsExpressionBuilder) {
completionStartTime: "e.completion_start_time as completion_start_time",
createdAt: "e.created_at as created_at",
updatedAt: "e.updated_at as updated_at",
+ eventTs: "e.event_ts",
providedModelName: "e.provided_model_name as provided_model_name",
+ internalModelId: "e.model_id as internal_model_id",
modelParameters: "e.model_parameters as model_parameters",
+ providedUsageDetails: "e.provided_usage_details as provided_usage_details",
usageDetails: "e.usage_details as usage_details",
+ providedCostDetails: "e.provided_cost_details as provided_cost_details",
costDetails: "e.cost_details as cost_details",
totalCost: "e.total_cost as total_cost",
promptId: "e.prompt_id as prompt_id",
promptName: "e.prompt_name as prompt_name",
promptVersion: "e.prompt_version as prompt_version",
+ skillsAvailable: "e.skills_available as skills_available",
+ skillsResourceLoaded: "e.skills_resource_loaded as skills_resource_loaded",
toolDefinitions: "e.tool_definitions as tool_definitions",
toolCalls: "e.tool_calls as tool_calls",
toolCallNames: "e.tool_call_names as tool_call_names",
@@ -472,7 +475,7 @@ function rowFieldSelectMap(eb: EventsExpressionBuilder) {
timeToFirstToken: millisecondsSinceStart(eb, "e.completion_start_time").as(
"time_to_first_token",
),
- } satisfies Record<FieldSetFieldKey<RowFieldSet>, EventsSelection>;
+ } satisfies Record<RowFieldKey, EventsSelection>;
}
/** The `metrics` field set with latencies in seconds instead of milliseconds. */
diff --git a/packages/shared/src/server/repositories/events.ts b/packages/shared/src/server/repositories/events.ts
index edf4e72c55..9f54faedfa 100644
--- a/packages/shared/src/server/repositories/events.ts
+++ b/packages/shared/src/server/repositories/events.ts
@@ -2830,10 +2830,8 @@ export const getObservationsBatchIOFromEventsTable = async <
)
.$if(opts.includeSkillFields === true, (qb) =>
qb.select([
- sql.ref<SkillsAvailable>("e.skills_available").as("skills_available"),
- sql
- .ref<SkillsResourceLoaded>("e.skills_resource_loaded")
- .as("skills_resource_loaded"),
+ "e.skills_available as skills_available",
+ "e.skills_resource_loaded as skills_resource_loaded",
]),
)
.$if(opts.includeToolCallFields === true, (qb) =>