Skip to content

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

test(query-ast): check the table registry against the migrated ClickHouse schema (#18866)

Niklas Semmler170b24b83cdc
diff --git a/packages/shared/package.json b/packages/shared/package.json
index b0d8afdefb..ec91a617e6 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -31,6 +31,10 @@
"import": "./dist/src/server/index.js",
"require": "./dist/src/server/index.js"
},
+ "./src/server/query-ast/schema": {
+ "import": "./dist/src/server/query-ast/schema.js",
+ "require": "./dist/src/server/query-ast/schema.js"
+ },
"./src/server/transcript/ordering": {
"import": "./dist/src/server/transcript/ordering.js",
"require": "./dist/src/server/transcript/ordering.js"
diff --git a/packages/shared/src/server/query-ast/schema.ts b/packages/shared/src/server/query-ast/schema.ts
index 04ad9003e1..a21eba2748 100644
--- a/packages/shared/src/server/query-ast/schema.ts
+++ b/packages/shared/src/server/query-ast/schema.ts
@@ -29,9 +29,9 @@
export type ChColumnType =
| "String"
| "Nullable(String)"
- | "Float"
+ | "Float64"
| "Decimal(18,12)"
- | "DateTime"
+ | "DateTime64(3)"
| "DateTime64(6)"
| "UInt8"
| "UInt16"
@@ -48,7 +48,7 @@ type TsTypeOfColumn<T extends ChColumnType> = T extends "String"
? string
: T extends "Nullable(String)"
? string | null
- : T extends "Float" | "Decimal(18,12)"
+ : T extends "Float64" | "Decimal(18,12)"
? number
: T extends "UInt8" | "UInt16" | "UInt64"
? number
@@ -56,7 +56,7 @@ type TsTypeOfColumn<T extends ChColumnType> = T extends "String"
? boolean
: T extends "Nullable(UInt16)"
? number | null
- : T extends "DateTime" | "DateTime64(6)"
+ : T extends "DateTime64(3)" | "DateTime64(6)"
? Date
: T extends "Nullable(DateTime64(6))"
? Date | null
@@ -76,7 +76,7 @@ export type ColumnDataType = "string" | "number" | "date" | "array" | "map";
const RUNTIME_TYPE: Record<ChColumnType, ColumnDataType> = {
String: "string",
"Nullable(String)": "string",
- Float: "number",
+ Float64: "number",
"Decimal(18,12)": "number",
UInt8: "number",
UInt16: "number",
@@ -84,7 +84,7 @@ const RUNTIME_TYPE: Record<ChColumnType, ColumnDataType> = {
// ClickHouse stores Bool as UInt8, so numeric aggregates accept it.
Bool: "number",
"Nullable(UInt16)": "number",
- DateTime: "date",
+ "DateTime64(3)": "date",
"DateTime64(6)": "date",
"Nullable(DateTime64(6))": "date",
"Array(String)": "array",
@@ -226,7 +226,7 @@ const TABLE_REGISTRY = {
columns: {
environment: "String",
project_id: "String",
- timestamp: "DateTime",
+ timestamp: "DateTime64(3)",
id: "String",
},
}),
@@ -234,7 +234,7 @@ const TABLE_REGISTRY = {
columns: {
environment: "String",
project_id: "String",
- start_time: "DateTime",
+ start_time: "DateTime64(3)",
trace_id: "String",
cost_details: "Map(String, Decimal(18,12))",
usage_details: "Map(String, UInt64)",
@@ -259,17 +259,17 @@ const TABLE_REGISTRY = {
id: "String",
environment: "String",
project_id: "String",
- timestamp: "DateTime",
- event_ts: "DateTime",
- created_at: "DateTime",
- updated_at: "DateTime",
+ timestamp: "DateTime64(3)",
+ event_ts: "DateTime64(3)",
+ created_at: "DateTime64(3)",
+ updated_at: "DateTime64(3)",
data_type: "String",
trace_id: "Nullable(String)",
session_id: "Nullable(String)",
observation_id: "Nullable(String)",
dataset_run_id: "Nullable(String)",
name: "String",
- value: "Float",
+ value: "Float64",
source: "String",
comment: "Nullable(String)",
author_user_id: "Nullable(String)",
@@ -294,6 +294,17 @@ export type ClickHouseDatabase = {
>;
};
+/**
+ * Declared ClickHouse type per column, per registry table. A servertest checks
+ * it against `system.columns` of the migrated database.
+ */
+export const TABLE_COLUMN_TYPES: Record<
+ string,
+ Record<string, ChColumnType>
+> = Object.fromEntries(
+ Object.entries(TABLE_REGISTRY).map(([table, spec]) => [table, spec.columns]),
+);
+
/**
* Derived coarse runtime column-type map (column name -> category), consumed by
* the aggregate type-check pass. Column names are consistent across tables in
@@ -332,13 +343,12 @@ export const SOFT_DELETE_COLUMNS: Record<string, string> = 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
- * `value` still becomes `{p:Float64}`.
+ * the coarse {@link COLUMN_DATA_TYPES} category, so an integer literal compared
+ * to `value` still becomes `{p:Float64}`.
*/
const BIND_TYPE: Record<ChColumnType, string> = {
String: "String",
- Float: "Float64",
+ Float64: "Float64",
"Decimal(18,12)": "Decimal(18, 12)",
UInt8: "UInt8",
UInt16: "UInt16",
@@ -347,7 +357,7 @@ const BIND_TYPE: Record<ChColumnType, string> = {
// A bound value is never NULL; NULL checks compile to `IS NULL`.
"Nullable(String)": "String",
"Nullable(UInt16)": "UInt16",
- DateTime: "DateTime64(3)",
+ "DateTime64(3)": "DateTime64(3)",
"DateTime64(6)": "DateTime64(6)",
"Nullable(DateTime64(6))": "DateTime64(6)",
"Array(String)": "Array(String)",
diff --git a/web/src/__tests__/server/query-ast-registry-ddl.servertest.ts b/web/src/__tests__/server/query-ast-registry-ddl.servertest.ts
new file mode 100644
index 0000000000..b1b349d6a4
--- /dev/null
+++ b/web/src/__tests__/server/query-ast-registry-ddl.servertest.ts
@@ -0,0 +1,55 @@
+import { clickhouseClient } from "@langfuse/shared/src/server";
+import { TABLE_COLUMN_TYPES } from "@langfuse/shared/src/server/query-ast/schema";
+
+// `LowCardinality` is a storage encoding the registry does not model, and
+// ClickHouse prints `Decimal(18, 12)` where the registry writes
+// `Decimal(18,12)`. Both are normalized away; every other difference fails.
+// Example: `Map(LowCardinality(String), Decimal(18, 12))` →
+// `Map(String,Decimal(18,12))`.
+const normalizeType = (type: string) =>
+ type
+ .replace(/\s+/g, "")
+ .replace(/LowCardinality\(((?:[^()]|\([^()]*\))*)\)/g, "$1");
+
+describe("query-AST table registry", () => {
+ it("declares every column with the type of the migrated ClickHouse schema", async () => {
+ const result = await clickhouseClient().query({
+ query: `
+ SELECT table, name, type
+ FROM system.columns
+ WHERE database = currentDatabase() AND table IN {tables: Array(String)}
+ `,
+ query_params: { tables: Object.keys(TABLE_COLUMN_TYPES) },
+ format: "JSONEachRow",
+ });
+ const rows = await result.json<{
+ table: string;
+ name: string;
+ type: string;
+ }>();
+ const physical = new Map(
+ rows.map((row) => [`${row.table}.${row.name}`, row.type]),
+ );
+
+ const declared = Object.entries(TABLE_COLUMN_TYPES).flatMap(
+ ([table, columns]) =>
+ Object.entries(columns).map(([name, type]) => ({
+ column: `${table}.${name}`,
+ type,
+ })),
+ );
+ const mismatches = declared
+ .map(({ column, type }) => ({
+ column,
+ registry: type,
+ clickhouse: physical.get(column) ?? "missing",
+ }))
+ .filter(
+ ({ registry, clickhouse }) =>
+ normalizeType(registry) !== normalizeType(clickhouse),
+ );
+
+ expect(declared.length).toBeGreaterThan(0);
+ expect(mismatches).toEqual([]);
+ });
+});