Skip to content

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

fix(query-ast): align registry column types with the ClickHouse DDL (#18793)

Niklas Semmlerd17f6b7fc8e0
diff --git a/packages/shared/src/server/query-ast/README.md b/packages/shared/src/server/query-ast/README.md
index 150800d36b..a6c1952437 100644
--- a/packages/shared/src/server/query-ast/README.md
+++ b/packages/shared/src/server/query-ast/README.md
@@ -90,7 +90,7 @@ suffix to run there. Promote it to a required check once it has proven stable.
explicit non-version LIMIT BY. Auto-lowering does not declare scores as
`{ strategy: "final" }`; callers opt in with `$call(useFinal(["scores"]))`.
- **Value binds take their ClickHouse type from the compared column** in the
- table registry (`total_cost > 1` emits `{p:Float64}`, not inferred
+ table registry (`scores.value > 1` emits `{p:Float64}`, not inferred
`{p:Int64}`). Same-value binds still intern to one placeholder.
- **ClickHouse-only clauses use `$call(helper())`** — not fluent builder
methods, so they compose inside CTEs, subqueries, and views. See the recipes
@@ -201,7 +201,7 @@ is where tenancy is enforced:
4. `ClickHouseQueryCompiler` refuses to emit SQL unless that identity stamp is
present, so `qb.compile()` without the plugin also fails. Value binds take
their ClickHouse type from the compared column's registry entry when one is
- in scope (`total_cost > 1` → `{p:Float64}`).
+ in scope (`scores.value > 1` → `{p:Float64}`).
5. Raw-SQL table sources (``selectFrom(sql`...`)``) and raw fragments embedding
a `SELECT`/`FROM`/`JOIN` in SELECT/WHERE throw `UnscopedRelationError`.
Kysely's own keyword fragments (`asc`/`desc`) are not relations.
diff --git a/packages/shared/src/server/query-ast/binds.test.ts b/packages/shared/src/server/query-ast/binds.test.ts
index 3a9f549a6b..63644fbcca 100644
--- a/packages/shared/src/server/query-ast/binds.test.ts
+++ b/packages/shared/src/server/query-ast/binds.test.ts
@@ -14,26 +14,36 @@ function compile(builder: Parameters<typeof compileClickhouseQuery>[0]) {
}
describe("typed params from the column registry", () => {
- it("binds an integer compared to total_cost as Float64, not Int64", () => {
+ it("binds an integer compared to a Float column as Float64, not Int64", () => {
const { sql, params } = compile(
getClickhouseKysely()
- .selectFrom("events_core")
- .select("span_id")
- .where("total_cost", ">", 1),
+ .selectFrom("scores")
+ .select("id")
+ .where("value", ">", 1),
);
- expect(sql).toMatch(/total_cost > \{p\d+:Float64\}/);
+ expect(sql).toMatch(/value > \{p\d+:Float64\}/);
expect(sql).not.toMatch(/\{p\d+:Int64\}/);
expect(Object.values(params)).toContain(1);
});
it("binds an IN list against a Float column as Array(Float64)", () => {
+ const { sql } = compile(
+ getClickhouseKysely()
+ .selectFrom("scores")
+ .select("id")
+ .where("value", "in", [1, 2]),
+ );
+ expect(sql).toMatch(/value in \(\{p\d+:Array\(Float64\)\}\)/);
+ });
+
+ it("binds a number compared to total_cost as Decimal(18, 12)", () => {
const { sql } = compile(
getClickhouseKysely()
.selectFrom("events_core")
.select("span_id")
- .where("total_cost", "in", [1, 2]),
+ .where("total_cost", ">", 1),
);
- expect(sql).toMatch(/total_cost in \(\{p\d+:Array\(Float64\)\}\)/);
+ expect(sql).toMatch(/total_cost > \{p\d+:Decimal\(18, 12\)\}/);
});
it("wraps an IN list against an Array column as Array(Array(...))", () => {
diff --git a/packages/shared/src/server/query-ast/catalog.golden.test.ts b/packages/shared/src/server/query-ast/catalog.golden.test.ts
index 8af77f40f8..22bb737d25 100644
--- a/packages/shared/src/server/query-ast/catalog.golden.test.ts
+++ b/packages/shared/src/server/query-ast/catalog.golden.test.ts
@@ -55,8 +55,8 @@ const JOIN_MEMORY_DDL = `
project_id String,
start_time DateTime64(3),
trace_id String,
- cost_details Map(String, Float64),
- usage_details Map(String, Float64)
+ cost_details Map(String, Decimal(18, 12)),
+ usage_details Map(String, UInt64)
) ENGINE = Memory;
CREATE TABLE traces (
environment String,
@@ -105,12 +105,12 @@ const CATALOG_MEMORY_DDL = `
CREATE TABLE events_core (
environment String,
project_id String,
- start_time DateTime64(3),
+ start_time DateTime64(6),
span_id String,
trace_id String,
- event_ts DateTime64(3),
+ event_ts DateTime64(6),
type String,
- total_cost Float64,
+ total_cost Decimal(18, 12),
metadata_names Array(String),
metadata_values Array(String)
) ENGINE = Memory;
@@ -119,8 +119,8 @@ const CATALOG_MEMORY_DDL = `
project_id String,
start_time DateTime64(3),
trace_id String,
- cost_details Map(String, Float64),
- usage_details Map(String, Float64)
+ cost_details Map(String, Decimal(18, 12)),
+ usage_details Map(String, UInt64)
) ENGINE = Memory;
CREATE TABLE traces (
environment String,
diff --git a/packages/shared/src/server/query-ast/schema.test.ts b/packages/shared/src/server/query-ast/schema.test.ts
index ed6bbc0cda..000e7b9a72 100644
--- a/packages/shared/src/server/query-ast/schema.test.ts
+++ b/packages/shared/src/server/query-ast/schema.test.ts
@@ -39,7 +39,9 @@ describe("table registry derivation", () => {
});
it("derives ClickHouse bind types from the same column declarations", () => {
- expect(COLUMN_BIND_TYPES.total_cost).toBe("Float64");
+ expect(COLUMN_BIND_TYPES.total_cost).toBe("Decimal(18, 12)");
+ expect(COLUMN_BIND_TYPES.value).toBe("Float64");
+ expect(TABLE_BIND_TYPES.scores.trace_id).toBe("String");
expect(TABLE_BIND_TYPES.events_core.start_time).toBe("DateTime64(6)");
expect(TABLE_BIND_TYPES.observations.start_time).toBe("DateTime64(3)");
expect(COLUMN_BIND_TYPES.start_time).toBeUndefined();
@@ -47,6 +49,7 @@ describe("table registry derivation", () => {
expect(COLUMN_BIND_TYPES.metadata_names).toBe("Array(String)");
expect(COLUMN_BIND_TYPES.is_deleted).toBe("UInt8");
expect(COLUMN_BIND_TYPES.metadata).toBe("Map(String, String)");
+ expect(COLUMN_BIND_TYPES.cost_details).toBe("Map(String, Decimal(18, 12))");
});
// The assertions themselves are compile-time (`tsc` is the test); this only
diff --git a/packages/shared/src/server/query-ast/schema.ts b/packages/shared/src/server/query-ast/schema.ts
index d064061b7a..2a1df2ae47 100644
--- a/packages/shared/src/server/query-ast/schema.ts
+++ b/packages/shared/src/server/query-ast/schema.ts
@@ -26,7 +26,9 @@
*/
export type ChColumnType =
| "String"
+ | "Nullable(String)"
| "Float"
+ | "Decimal(18,12)"
| "DateTime"
| "DateTime64(6)"
| "UInt8"
@@ -34,40 +36,42 @@ export type ChColumnType =
| "Nullable(UInt16)"
| "Nullable(DateTime64(6))"
| "Array(String)"
- | "Map(String, Float)"
| "Map(String, UInt64)"
| "Map(String, Decimal(18,12))"
| "Map(String, String)";
type TsTypeOfColumn<T extends ChColumnType> = T extends "String"
? string
- : T extends "Float"
- ? number
- : T extends "UInt8" | "UInt16"
+ : T extends "Nullable(String)"
+ ? string | null
+ : T extends "Float" | "Decimal(18,12)"
? number
- : T extends "Nullable(UInt16)"
- ? number | null
- : T extends "DateTime" | "DateTime64(6)"
- ? Date
- : T extends "Nullable(DateTime64(6))"
- ? Date | null
- : T extends "Array(String)"
- ? string[]
- : T extends
- | "Map(String, Float)"
- | "Map(String, UInt64)"
- | "Map(String, Decimal(18,12))"
- ? Record<string, number>
- : T extends "Map(String, String)"
- ? Record<string, string>
- : never;
+ : T extends "UInt8" | "UInt16"
+ ? number
+ : T extends "Nullable(UInt16)"
+ ? number | null
+ : T extends "DateTime" | "DateTime64(6)"
+ ? Date
+ : T extends "Nullable(DateTime64(6))"
+ ? Date | null
+ : T extends "Array(String)"
+ ? string[]
+ : T extends
+ | "Map(String, UInt64)"
+ | "Map(String, Decimal(18,12))"
+ ? Record<string, number>
+ : T extends "Map(String, String)"
+ ? Record<string, string>
+ : never;
/** Coarse runtime category the aggregate type-check pass reasons about. */
export type ColumnDataType = "string" | "number" | "date" | "array" | "map";
const RUNTIME_TYPE: Record<ChColumnType, ColumnDataType> = {
String: "string",
+ "Nullable(String)": "string",
Float: "number",
+ "Decimal(18,12)": "number",
UInt8: "number",
UInt16: "number",
"Nullable(UInt16)": "number",
@@ -75,7 +79,6 @@ const RUNTIME_TYPE: Record<ChColumnType, ColumnDataType> = {
"DateTime64(6)": "date",
"Nullable(DateTime64(6))": "date",
"Array(String)": "array",
- "Map(String, Float)": "map",
"Map(String, UInt64)": "map",
"Map(String, Decimal(18,12))": "map",
"Map(String, String)": "map",
@@ -129,7 +132,7 @@ const EVENTS_COLUMNS = {
trace_id: "String",
event_ts: "DateTime64(6)",
type: "String",
- total_cost: "Float",
+ total_cost: "Decimal(18,12)",
experiment_id: "String",
prompt_id: "String",
prompt_name: "String",
@@ -173,8 +176,8 @@ const TABLE_REGISTRY = {
project_id: "String",
start_time: "DateTime",
trace_id: "String",
- cost_details: "Map(String, Float)",
- usage_details: "Map(String, Float)",
+ cost_details: "Map(String, Decimal(18,12))",
+ usage_details: "Map(String, UInt64)",
},
}),
events_core: defineTable({
@@ -199,19 +202,19 @@ const TABLE_REGISTRY = {
created_at: "DateTime",
updated_at: "DateTime",
data_type: "String",
- trace_id: "String",
- session_id: "String",
- observation_id: "String",
- dataset_run_id: "String",
+ trace_id: "Nullable(String)",
+ session_id: "Nullable(String)",
+ observation_id: "Nullable(String)",
+ dataset_run_id: "Nullable(String)",
name: "String",
value: "Float",
source: "String",
- comment: "String",
- author_user_id: "String",
- config_id: "String",
- string_value: "String",
- queue_id: "String",
- execution_trace_id: "String",
+ comment: "Nullable(String)",
+ author_user_id: "Nullable(String)",
+ config_id: "Nullable(String)",
+ string_value: "Nullable(String)",
+ queue_id: "Nullable(String)",
+ execution_trace_id: "Nullable(String)",
is_deleted: "UInt8",
metadata: "Map(String, String)",
},
@@ -262,20 +265,21 @@ export const DEDUP_SPECS: Record<string, DedupSpec> = Object.fromEntries(
* ClickHouse bind type for a JS value compared against this column. Wider than
* the coarse {@link COLUMN_DATA_TYPES} category: `DateTime` columns bind as
* `DateTime64(3)`, `Float` as `Float64`, so an integer literal compared to
- * `total_cost` still becomes `{p:Float64}`.
+ * `value` still becomes `{p:Float64}`.
*/
const BIND_TYPE: Record<ChColumnType, string> = {
String: "String",
Float: "Float64",
+ "Decimal(18,12)": "Decimal(18, 12)",
UInt8: "UInt8",
UInt16: "UInt16",
// A bound value is never NULL; NULL checks compile to `IS NULL`.
+ "Nullable(String)": "String",
"Nullable(UInt16)": "UInt16",
DateTime: "DateTime64(3)",
"DateTime64(6)": "DateTime64(6)",
"Nullable(DateTime64(6))": "DateTime64(6)",
"Array(String)": "Array(String)",
- "Map(String, Float)": "Map(String, Float64)",
"Map(String, UInt64)": "Map(String, UInt64)",
"Map(String, Decimal(18,12))": "Map(String, Decimal(18, 12))",
"Map(String, String)": "Map(String, String)",