@mastra/clickhouse 1.27.0 → 1.28.0-alpha.0

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.27.0"
+  version: "1.28.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.27.0",
+  "version": "1.28.0-alpha.0",
   "package": "@mastra/clickhouse",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -6928,7 +6928,17 @@ const TRACE_STATUS_SQL = `if(isNotNull(r.error), 'error', 'success')`;
 const timeToFirstChunkSupported = "timeToFirstChunkMs" in (_mastra_core_storage.TRACE_QUERY_FIELD_REGISTRY?.trace ?? {});
 /** 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"] : [];
+/** Same rule for time to first token: returned and sorted only when core knows the field. */
+const timeToFirstTokenSupported = "timeToFirstTokenMs" in (_mastra_core_storage.TRACE_QUERY_FIELD_REGISTRY?.trace ?? {});
+const timeToFirstTokenSortSupported = _mastra_core_storage.TRACE_QUERY_ORDER_FIELDS?.includes("timeToFirstTokenMs") === true;
+const timingFeatures = [
+	...timeToFirstChunkSupported ? ["trace-query-time-to-first-chunk"] : [],
+	...timeToFirstChunkSupported && timeToFirstChunkSortSupported ? ["trace-query-time-to-first-chunk-sort"] : [],
+	...timeToFirstTokenSupported ? ["trace-query-time-to-first-token"] : [],
+	...timeToFirstTokenSupported && timeToFirstTokenSortSupported ? ["trace-query-time-to-first-token-sort"] : []
+];
+/** Order fields holding numbers that can be empty; the rest are timestamps. */
+const NUMERIC_ORDER_FIELDS = /* @__PURE__ */ new Set(["timeToFirstChunkMs", "timeToFirstTokenMs"]);
 function durationMsSql(startedAt, endedAt) {
 	return `dateDiff('millisecond', ${startedAt}, ${endedAt})`;
 }
@@ -6981,6 +6991,10 @@ const TRACE_FIELDS = {
 		sql: "r.timeToFirstChunkMs",
 		parameterType: "Float64"
 	},
+	timeToFirstTokenMs: {
+		sql: "r.timeToFirstTokenMs",
+		parameterType: "Float64"
+	},
 	entityId: {
 		sql: "r.entityId",
 		parameterType: "String"
@@ -7047,6 +7061,10 @@ const SPAN_FIELDS = {
 		sql: "s.timeToFirstChunkMs",
 		parameterType: "Float64"
 	},
+	timeToFirstTokenMs: {
+		sql: "s.timeToFirstTokenMs",
+		parameterType: "Float64"
+	},
 	status: {
 		sql: "s.status",
 		parameterType: "String"
@@ -7259,6 +7277,7 @@ const TRACE_SELECT = `
   r.entityType AS entityType,
   r.environment AS environment,
   r.timeToFirstChunkMs AS timeToFirstChunkMs,
+  r.timeToFirstTokenMs AS timeToFirstTokenMs,
   ${TRACE_STATUS_SQL} AS status`;
 var ParameterBuilder = class {
 	params = {};
@@ -7275,7 +7294,7 @@ function fieldDefinition(registry, field) {
 	return definition;
 }
 function resolveOrderField(field) {
-	if (field === "startedAt" || field === "endedAt" || field === "timeToFirstChunkMs") return field;
+	if (field === "startedAt" || field === "endedAt" || NUMERIC_ORDER_FIELDS.has(field)) return field;
 	throw new Error(`Unsupported trusted trace-query field: ${field}`);
 }
 function isMetadataField(field) {
@@ -7465,6 +7484,7 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters,
       endedAt,
       ${durationMsSql("startedAt", "endedAt")} AS durationMs,
       timeToFirstChunkMs,
+      timeToFirstTokenMs,
       if(isNotNull(error), 'error', 'success') AS status,
       error,
       entityType,
@@ -7580,7 +7600,7 @@ 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 numeric = NUMERIC_ORDER_FIELDS.has(order.field);
 	const comparison = order.direction === "ASC" ? ">" : "<";
 	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)" : ""})`;
@@ -7594,7 +7614,7 @@ 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, r.timeToFirstChunkMs AS timeToFirstChunkMs", 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, r.timeToFirstTokenMs AS timeToFirstTokenMs", parameters, QUERY_TRACES_SCOPE);
 	const cursor = keysetCursorCondition(plan, order, parameters);
 	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 {
@@ -7995,7 +8015,8 @@ async function queryTraces(client, plan, timeoutMs, strategy = null) {
 		entityType: row.entityType == null ? null : String(row.entityType),
 		environment: row.environment == null ? null : String(row.environment),
 		status: row.status,
-		...timeToFirstChunkSupported && { timeToFirstChunkMs: row.timeToFirstChunkMs == null ? null : Number(row.timeToFirstChunkMs) }
+		...timeToFirstChunkSupported && { timeToFirstChunkMs: row.timeToFirstChunkMs == null ? null : Number(row.timeToFirstChunkMs) },
+		...timeToFirstTokenSupported && { timeToFirstTokenMs: row.timeToFirstTokenMs == null ? null : Number(row.timeToFirstTokenMs) }
 	});
 	if (plan.paginationMode === "delta") {
 		const rows = await run(compileClickHouseTraceQuery(plan, deltaHead));
@@ -8018,7 +8039,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);
+	const sortValue = (value) => !NUMERIC_ORDER_FIELDS.has(plan.orderBy.field) ? 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));
@@ -8121,6 +8142,7 @@ const displayFields = [
 	"provider",
 	"durationMs",
 	"timeToFirstChunkMs",
+	"timeToFirstTokenMs",
 	"status"
 ];
 var Parameters = class {
@@ -8149,7 +8171,7 @@ function afterCursor$1(plan, parameters) {
 	const equal = [];
 	if (cursor.sortValue === null) equal.push(`isNull(${field})`);
 	else {
-		const numeric = plan.orderBy.field === "timeToFirstChunkMs";
+		const numeric = plan.orderBy.field === "timeToFirstChunkMs" || plan.orderBy.field === "timeToFirstTokenMs";
 		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})`);
@@ -8245,6 +8267,7 @@ const TRACE_BRANCHES_SPAN_FIELD_COLUMNS = {
 		"startedAt",
 		"endedAt",
 		"timeToFirstChunkMs",
+		"timeToFirstTokenMs",
 		"threadId",
 		"runId",
 		"sessionId",
@@ -8405,12 +8428,13 @@ async function querySpans(client, plan, timeoutMs) {
 	const hydrated = page.flatMap((identity) => {
 		const row = byIdentity.get(_mastra_core_storage.spanQueryIdentityKey(identity));
 		if (!row) return [];
-		const { inputPreview: _input, outputPreview: _output, errorPreview: _error, timeToFirstChunkMs, ...metadata } = row;
+		const { inputPreview: _input, outputPreview: _output, errorPreview: _error, timeToFirstChunkMs, timeToFirstTokenMs, ...metadata } = row;
 		return [{
 			...metadata,
 			...identity,
 			durationMs: Number(row.durationMs),
-			...timeToFirstChunkSupported && { timeToFirstChunkMs: timeToFirstChunkMs == null ? null : Number(timeToFirstChunkMs) }
+			...timeToFirstChunkSupported && { timeToFirstChunkMs: timeToFirstChunkMs == null ? null : Number(timeToFirstChunkMs) },
+			...timeToFirstTokenSupported && { timeToFirstTokenMs: timeToFirstTokenMs == null ? null : Number(timeToFirstTokenMs) }
 		}];
 	});
 	let metrics = [];
@@ -8533,7 +8557,11 @@ function compileClickHouseThreadRowsQuery(plan, strategy = "full") {
 	const after = afterCursor(plan, parameters);
 	const qualify = plan.timeRange.mode === "traces" ? "s.inWindow > 0" : `s.${plan.timeRange.field} >= ${from} AND s.${plan.timeRange.field} < ${to}`;
 	const filtered = predicateFields(plan.where);
-	const firstContext = [...contextFields, "timeToFirstChunkMs"].filter((field) => field === "resourceId" || filtered.has(field));
+	const firstContext = [
+		...contextFields,
+		"timeToFirstChunkMs",
+		"timeToFirstTokenMs"
+	].filter((field) => field === "resourceId" || filtered.has(field));
 	const firstFields = [
 		"startedAt",
 		"traceId",
@@ -8557,7 +8585,7 @@ function compileClickHouseThreadRowsQuery(plan, strategy = "full") {
 		...firstContext,
 		...filtered.has("status") ? ["status"] : []
 	];
-	const rootExpression = (field) => field === "timeToFirstChunkMs" ? "if(spanType = 'agent_run', timeToFirstChunkMs, NULL)" : field === "status" ? "if(isNull(error), 'success', 'error')" : field;
+	const rootExpression = (field) => field === "timeToFirstChunkMs" || field === "timeToFirstTokenMs" ? `if(spanType = 'agent_run', ${field}, NULL)` : field === "status" ? "if(isNull(error), 'success', 'error')" : field;
 	const sortedRoots = `roots AS (
     SELECT organizationId, traceId, ${rootDataFields.map((field) => `${rootExpression(field)} AS ${field}`).join(", ")}
     FROM ${TABLE_TRACE_ROOTS} ${scope.length || strategy === "candidates" ? `WHERE ${[...scope, ...strategy === "candidates" ? [candidateTracesFilter] : []].join(" AND ")}` : ""}
@@ -8661,6 +8689,7 @@ async function queryThreadRows(client, plan, timeoutMs, strategy = "auto") {
 	for (const batch of batches([...roots.values()])) stored.push(...await run({
 		query: `SELECT organizationId, traceId, spanId, startedAt, endedAt,
       ${contextFields.join(", ")}, if(spanType = 'agent_run', timeToFirstChunkMs, NULL) AS timeToFirstChunkMs,
+      if(spanType = 'agent_run', timeToFirstTokenMs, NULL) AS timeToFirstTokenMs,
       if(isNull(error), 'success', 'error') AS status, ${PREVIEW_COLUMNS.join(", ")}
       FROM ${TABLE_TRACE_ROOTS} WHERE ${rootWhere}
       ORDER BY ${ROOT_VERSION_ORDER} LIMIT 1 BY organizationId, traceId, spanId`,
@@ -8694,6 +8723,7 @@ async function queryThreadRows(client, plan, timeoutMs, strategy = "auto") {
 			endedAt: iso(row.endedAt),
 			traceCount: Number(row.traceCount),
 			timeToFirstChunkMs: first.timeToFirstChunkMs,
+			...timeToFirstTokenSupported && { timeToFirstTokenMs: first.timeToFirstTokenMs },
 			inputPreview: resolveStoredPreviews(first).inputPreview,
 			outputPreview: resolveStoredPreviews(last).outputPreview,
 			errorPreview: resolveStoredPreviews(last).errorPreview
@@ -10350,7 +10380,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"trace-query-tenant-scope",
 			"feedback",
 			"trace-query-context-ids",
-			...timeToFirstChunkFeatures,
+			...timingFeatures,
 			"trace-query-root-span-fields",
 			"trace-query-root-entity-id",
 			"trace-aggregate",
@@ -10375,7 +10405,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"trace-query-tenant-scope",
 			"feedback",
 			"trace-query-context-ids",
-			...timeToFirstChunkFeatures,
+			...timingFeatures,
 			"trace-query-root-span-fields",
 			"trace-query-root-entity-id",
 			"trace-aggregate",