Skip to content

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

docs(query-ast): document registry column types as logical, not wire types (#18860)

Niklas Semmler857186a4cc6f
diff --git a/packages/shared/src/server/query-ast/README.md b/packages/shared/src/server/query-ast/README.md
index 7ff7192d6e..f61fef3535 100644
--- a/packages/shared/src/server/query-ast/README.md
+++ b/packages/shared/src/server/query-ast/README.md
@@ -109,6 +109,10 @@ suffix to run there. Promote it to a required check once it has proven stable.
`eb("level", "=", literal("ERROR"))` renders `level = 'ERROR'`; a value that
comes from a caller is a plain bind, `eb("level", "=", level)`. `literal`
rejects backslashes and must never receive user input.
+- **Registry types are logical, not wire types.** `DateTime64` is `Date` and
+ `UInt64` is `number` so binds type-check, but query results arrive as raw
+ JSON (dates as strings). Type rows with a read schema and convert them; do
+ not type results with the builder's `InferResult`.
- **ClickHouse-only clauses use `$call(helper())`** — not fluent builder
methods, so they compose inside CTEs, subqueries, and views. See the recipes
below.
diff --git a/packages/shared/src/server/query-ast/schema.ts b/packages/shared/src/server/query-ast/schema.ts
index a21eba2748..274f64cf6f 100644
--- a/packages/shared/src/server/query-ast/schema.ts
+++ b/packages/shared/src/server/query-ast/schema.ts
@@ -44,6 +44,14 @@ export type ChColumnType =
| "Map(String, Decimal(18,12))"
| "Map(String, String)";
+/**
+ * Logical TS type of a column: the value a caller binds, and what a result
+ * value means once parsed. Not the wire type — `JSONEachRow` returns
+ * `DateTime64` as a `YYYY-MM-DD hh:mm:ss.ffffff` string, and `UInt64` as a
+ * string on servers that quote 64-bit integers. Rows inferred from a builder
+ * (`InferResult`) therefore do not describe raw query results; read those
+ * through a read schema and converter.
+ */
type TsTypeOfColumn<T extends ChColumnType> = T extends "String"
? string
: T extends "Nullable(String)"