@mastra/clickhouse 1.26.0-alpha.3 → 1.26.0-alpha.4

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-clickhouse
 description: Documentation for @mastra/clickhouse. Use when working with @mastra/clickhouse APIs, configuration, or implementation.
 metadata:
   package: "@mastra/clickhouse"
-  version: "1.26.0-alpha.3"
+  version: "1.26.0-alpha.4"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.26.0-alpha.3",
+  "version": "1.26.0-alpha.4",
   "package": "@mastra/clickhouse",
   "exports": {},
   "modules": {}

package/dist/docs/references/integrations-databases-clickhouse.md

@@ -290,7 +290,7 @@ Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `Shar
 
 ### Observability domain options
 
-`ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`). `ObservabilityStorageClickhouseVNext` also accepts `retention`, the per-signal TTL in days described in [ClickHouse native TTL](https://mastra.ai/reference/storage/retention), and `traceQuery`, the execution limits for [trace queries](https://mastra.ai/reference/observability/tracing/trace-query).
+`ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`). `ObservabilityStorageClickhouseVNext` also accepts `retention`, the per-signal TTL in days described in [ClickHouse native TTL](https://mastra.ai/reference/storage/retention), and `traceQuery`, the execution limits for [trace queries](https://mastra.ai/reference/observability/tracing/advanced-queries).
 
 ## Hosting options
 

package/dist/index.cjs

@@ -6869,7 +6869,9 @@ const TRACE_STATUS_SQL = `if(isNotNull(r.error), 'error', 'success')`;
 * Core before 1.68 has no field registry at all.
 */
 const timeToFirstChunkSupported = "timeToFirstChunkMs" in (_mastra_core_storage.TRACE_QUERY_FIELD_REGISTRY?.trace ?? {});
-const timeToFirstChunkFeatures = timeToFirstChunkSupported ? ["trace-query-time-to-first-chunk"] : [];
+/** Core before the sort rejects `orderBy` on the field, so the sort is only declared when core plans it. */
+const timeToFirstChunkSortSupported = _mastra_core_storage.TRACE_QUERY_ORDER_FIELDS?.includes("timeToFirstChunkMs") === true;
+const timeToFirstChunkFeatures = timeToFirstChunkSupported ? timeToFirstChunkSortSupported ? ["trace-query-time-to-first-chunk", "trace-query-time-to-first-chunk-sort"] : ["trace-query-time-to-first-chunk"] : [];
 function durationMsSql(startedAt, endedAt) {
 	return `dateDiff('millisecond', ${startedAt}, ${endedAt})`;
 }
@@ -7212,7 +7214,7 @@ function fieldDefinition(registry, field) {
 	return definition;
 }
 function resolveOrderField(field) {
-	if (field === "startedAt" || field === "endedAt") return field;
+	if (field === "startedAt" || field === "endedAt" || field === "timeToFirstChunkMs") return field;
 	throw new Error(`Unsupported trusted trace-query field: ${field}`);
 }
 function isMetadataField(field) {
@@ -7490,9 +7492,11 @@ function traceOrder(plan) {
 */
 function keysetCursorCondition(plan, order, parameters) {
 	if (plan.paginationMode !== "keyset" || !plan.cursor) return "";
+	if (plan.cursor.sortValue === null) return `(isNull(sortValue) AND traceId > ${parameters.add(plan.cursor.traceId, "String")})`;
+	const numeric = order.field === "timeToFirstChunkMs";
 	const comparison = order.direction === "ASC" ? ">" : "<";
-	const sortValue = parameters.add(plan.cursor.sortValue, "DateTime64(3, 'UTC')");
-	return `(sortValue ${comparison} ${sortValue} OR (sortValue = ${sortValue} AND traceId > ${parameters.add(plan.cursor.traceId, "String")}))`;
+	const sortValue = parameters.add(plan.cursor.sortValue, numeric ? "Float64" : "DateTime64(3, 'UTC')");
+	return `(sortValue ${comparison} ${sortValue} OR (sortValue = ${sortValue} AND traceId > ${parameters.add(plan.cursor.traceId, "String")})${numeric ? " OR isNull(sortValue)" : ""})`;
 }
 /**
 * First statement of keyset and page mode: the page's traces (after the keyset cursor, `limit + 1`
@@ -7504,21 +7508,22 @@ function compileClickHouseTraceQueryKeys(plan) {
 	if (plan.paginationMode === "delta") throw new Error("Delta trace queries have no keys statement");
 	const parameters = new ParameterBuilder();
 	const order = traceOrder(plan);
-	const ctes = compileClickHouseTraceCandidates(plan, "r.traceId AS traceId, r.dedupeKey AS dedupeKey, r.startedAt AS startedAt, r.endedAt AS endedAt", parameters, QUERY_TRACES_SCOPE);
+	const ctes = compileClickHouseTraceCandidates(plan, "r.traceId AS traceId, r.dedupeKey AS dedupeKey, r.startedAt AS startedAt, r.endedAt AS endedAt, r.timeToFirstChunkMs AS timeToFirstChunkMs", parameters, QUERY_TRACES_SCOPE);
 	const cursor = keysetCursorCondition(plan, order, parameters);
 	const pick = order.direction === "DESC" ? "max" : "min";
+	const rootOrder = order.field === "timeToFirstChunkMs" ? `ifNull(${order.field}, ${pick === "max" ? "-inf" : "inf"})` : order.field;
 	const limit = plan.paginationMode === "page" ? `LIMIT ${parameters.add(plan.perPage, "UInt64")} OFFSET ${parameters.add(plan.page * plan.perPage, "UInt64")}` : `LIMIT ${parameters.add(plan.limit + 1, "UInt64")}`;
 	return {
 		query: `WITH ${ctes.join(",\n")},
 per_trace AS (
   SELECT traceId, ${pick}(${order.field}) AS sortValue,
-    ${pick === "max" ? "argMax" : "argMin"}((dedupeKey, startedAt), ${order.field}) AS root
+    ${pick === "max" ? "argMax" : "argMin"}((dedupeKey, startedAt), ${rootOrder}) AS root
   FROM candidates
   GROUP BY traceId${cursor ? `\n  HAVING ${cursor}` : ""}
 )
 SELECT traceId, root.1 AS dedupeKey, sortValue, root.2 AS rootStartedAt, count() OVER () AS __total
 FROM per_trace
-ORDER BY sortValue ${order.direction}, traceId ASC
+ORDER BY sortValue ${order.direction} NULLS LAST, traceId ASC
 ${limit}`,
 		query_params: parameters.params,
 		sharedSnapshot: true
@@ -7536,16 +7541,16 @@ function compileClickHouseTraceRowsByKey(plan, keys) {
 	const ts = (value) => parameters.add(value, "DateTime64(3, 'UTC')");
 	const byEnd = order.field === "endedAt";
 	const tuples = keys.map((key) => {
-		const started = ts(byEnd ? key.rootStartedAt : key.sortValue);
+		const started = ts(key.rootStartedAt);
 		const id = `${parameters.add(key.traceId, "String")}, ${parameters.add(key.dedupeKey, "String")}`;
-		return byEnd ? `(${started}, ${id}, ${ts(key.sortValue)})` : `(${started}, ${id})`;
+		return byEnd ? `(${started}, ${id}, ${ts(String(key.sortValue))})` : `(${started}, ${id})`;
 	});
 	const predicate = (plan.where ? (plan.where.type === "boolean" && plan.where.operator === "and" ? plan.where.args : [plan.where]).filter((conjunct) => collectRelationCollections(conjunct).size === 0) : []).map((conjunct) => `\n  AND (${compilePredicate(conjunct, parameters)})`).join("");
 	return {
 		query: `SELECT ${TRACE_SELECT}
 FROM ${TABLE_TRACE_ROOTS} r
 WHERE (r.startedAt, r.traceId, r.dedupeKey${byEnd ? ", r.endedAt" : ""}) IN (${tuples.join(", ")})${compileTenantScope(plan.scope, parameters)}${predicate}
-ORDER BY ${order.field} ${order.direction}, traceId ASC
+ORDER BY ${order.field} ${order.direction} NULLS LAST, traceId ASC
 LIMIT 1 BY traceId`,
 		query_params: parameters.params
 	};
@@ -7936,6 +7941,7 @@ async function queryTraces(client, plan, timeoutMs, strategy = null) {
 		});
 	}
 	const keys = await run(compileClickHouseTraceQueryKeys(plan));
+	const sortValue = (value) => plan.orderBy.field !== "timeToFirstChunkMs" ? asIsoTimestamp(value) : value == null ? null : Number(value);
 	let total = Number(keys[0]?.__total ?? 0);
 	if (plan.paginationMode === "page" && keys.length === 0 && plan.page > 0) {
 		const [stats] = await run(compileClickHouseTraceQueryTotal(plan));
@@ -7945,7 +7951,7 @@ async function queryTraces(client, plan, timeoutMs, strategy = null) {
 	const rows = visible.length > 0 ? await run(compileClickHouseTraceRowsByKey(plan, visible.map((key) => ({
 		traceId: String(key.traceId),
 		dedupeKey: String(key.dedupeKey),
-		sortValue: asIsoTimestamp(key.sortValue),
+		sortValue: sortValue(key.sortValue),
 		rootStartedAt: asIsoTimestamp(key.rootStartedAt)
 	})))) : [];
 	if (plan.paginationMode === "page") return _mastra_core_storage.traceQueryResponseSchema.parse({
@@ -7963,7 +7969,7 @@ async function queryTraces(client, plan, timeoutMs, strategy = null) {
 		traces: await toTraceRecords(rows),
 		page: { next: keys.length > plan.limit && lastKey ? _mastra_core_storage.encodeTraceQueryCursor(plan, {
 			result: "traces",
-			sortValue: asIsoTimestamp(lastKey.sortValue),
+			sortValue: sortValue(lastKey.sortValue),
 			traceId: String(lastKey.traceId)
 		}) : null }
 	});
@@ -8043,10 +8049,10 @@ const displayFields = [
 ];
 var Parameters = class {
 	values = {};
-	add(value, timestamp = false) {
+	add(value, type = typeof value === "number" ? "UInt64" : "String") {
 		const name = `span_${Object.keys(this.values).length}`;
-		this.values[name] = timestamp ? new Date(value).toISOString().replace("T", " ").replace(/Z$/, "") : value;
-		return `{${name}:${timestamp ? "DateTime64(3, 'UTC')" : typeof value === "number" ? "UInt64" : "String"}}`;
+		this.values[name] = type === "DateTime64(3, 'UTC')" ? new Date(value).toISOString().replace("T", " ").replace(/Z$/, "") : value;
+		return `{${name}:${type}}`;
 	}
 };
 function identityValues(row) {
@@ -8062,10 +8068,17 @@ function identityValues(row) {
 function afterCursor$1(plan, parameters) {
 	if (!plan.cursor) return "1";
 	const cursor = plan.cursor;
-	const timestamp = parameters.add(cursor.sortValue, true);
 	const field = `s.${plan.orderBy.field}`;
-	const terms = [`${field} ${plan.orderBy.direction === "asc" ? ">" : "<"} ${timestamp}`];
-	const equal = [`${field} = ${timestamp}`];
+	const terms = [];
+	const equal = [];
+	if (cursor.sortValue === null) equal.push(`isNull(${field})`);
+	else {
+		const numeric = plan.orderBy.field === "timeToFirstChunkMs";
+		const value = parameters.add(cursor.sortValue, numeric ? "Float64" : "DateTime64(3, 'UTC')");
+		terms.push(`${field} ${plan.orderBy.direction === "asc" ? ">" : "<"} ${value}`);
+		if (numeric) terms.push(`isNull(${field})`);
+		equal.push(`${field} = ${value}`);
+	}
 	for (const key of identityFields) {
 		const value = cursor[key];
 		if (value === null) equal.push(`isNull(s.${key})`);
@@ -8093,8 +8106,8 @@ function fieldExpression(field) {
 }
 function compileClickHouseSpanQuery(plan) {
 	const parameters = new Parameters();
-	const from = parameters.add(plan.timeRange.from, true);
-	const to = parameters.add(plan.timeRange.to, true);
+	const from = parameters.add(plan.timeRange.from, "DateTime64(3, 'UTC')");
+	const to = parameters.add(plan.timeRange.to, "DateTime64(3, 'UTC')");
 	const scope = [];
 	if (plan.scope) {
 		scope.push(`organizationId = ${parameters.add(plan.scope.organizationId)}`);
@@ -8107,6 +8120,7 @@ function compileClickHouseSpanQuery(plan) {
 	const selectionFields = [.../* @__PURE__ */ new Set([
 		"startedAt",
 		"endedAt",
+		plan.orderBy.field,
 		...predicateFields$1(plan.where)
 	])].filter((field) => !new Set(identityFields).has(field));
 	const expressions = selectionFields.map(fieldExpression);
@@ -8120,13 +8134,14 @@ function compileClickHouseSpanQuery(plan) {
     ORDER BY ${identities}, e.endedAt DESC
     LIMIT 1 BY ${identities}
   )
-  SELECT ${[
+  SELECT ${[.../* @__PURE__ */ new Set([
 			...identityFields,
 			"startedAt",
-			"endedAt"
-		].map((field) => `s.${field}`).join(", ")}
+			"endedAt",
+			plan.orderBy.field
+		])].map((field) => `s.${field}`).join(", ")}
   FROM candidates s WHERE s.startedAt >= ${from} AND s.startedAt < ${to} AND (${predicate.sql}) AND ${after}
-  ORDER BY s.${plan.orderBy.field} ${plan.orderBy.direction === "asc" ? "ASC" : "DESC"}, ${identityFields.map((field) => `s.${field} ASC NULLS LAST`).join(", ")}
+  ORDER BY s.${plan.orderBy.field} ${plan.orderBy.direction === "asc" ? "ASC" : "DESC"} NULLS LAST, ${identityFields.map((field) => `s.${field} ASC NULLS LAST`).join(", ")}
   LIMIT ${parameters.add(plan.limit + 1)}`,
 		query_params: {
 			...parameters.values,
@@ -8218,7 +8233,7 @@ async function querySpans(client, plan, timeoutMs) {
 		resourceId: last.resourceId,
 		traceId: last.traceId,
 		spanId: last.spanId,
-		sortValue: last[plan.orderBy.field]
+		sortValue: last[plan.orderBy.field] ?? null
 	}) : null;
 	return result;
 }