@mastra/clickhouse 1.25.2-alpha.0 → 1.26.0-alpha.2

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.25.2-alpha.0"
+  version: "1.26.0-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/index.cjs

@@ -2743,6 +2743,7 @@ CREATE TABLE IF NOT EXISTS ${TABLE_SPAN_EVENTS} (
   isEvent            Bool DEFAULT false,
   startedAt          DateTime64(3, 'UTC'),
   endedAt            DateTime64(3, 'UTC'),
+  timeToFirstChunkMs Nullable(Float64),
 
   -- Query-relevant flexible fields
   tags               Array(LowCardinality(String)) DEFAULT [],
@@ -2816,6 +2817,7 @@ CREATE TABLE IF NOT EXISTS ${TABLE_TRACE_ROOTS} (
   isEvent            Bool DEFAULT false,
   startedAt          DateTime64(3, 'UTC'),
   endedAt            DateTime64(3, 'UTC'),
+  timeToFirstChunkMs Nullable(Float64),
 
   -- Query-relevant flexible fields
   tags               Array(LowCardinality(String)) DEFAULT [],
@@ -2901,6 +2903,7 @@ CREATE TABLE IF NOT EXISTS ${TABLE_TRACE_BRANCHES} (
   isEvent            Bool DEFAULT false,
   startedAt          DateTime64(3, 'UTC'),
   endedAt            DateTime64(3, 'UTC'),
+  timeToFirstChunkMs Nullable(Float64),
 
   -- Query-relevant flexible fields
   tags               Array(LowCardinality(String)) DEFAULT [],
@@ -3706,7 +3709,10 @@ const ALL_MIGRATIONS = [
 	addBloomIndex(TABLE_METRIC_EVENTS, "idx_sessionId", "sessionId"),
 	addBloomIndex(TABLE_METRIC_EVENTS, "idx_requestId", "requestId"),
 	...LOG_SKIP_INDEX_COLUMNS.map((column) => addBloomIndex(TABLE_LOG_EVENTS, `idx_${column}`, column)),
-	addBloomIndex(TABLE_DELETION_REQUESTS, "idx_predicateValues", "predicateValues")
+	addBloomIndex(TABLE_DELETION_REQUESTS, "idx_predicateValues", "predicateValues"),
+	addColumn(TABLE_TRACE_ROOTS, "timeToFirstChunkMs", "Nullable(Float64)"),
+	addColumn(TABLE_TRACE_BRANCHES, "timeToFirstChunkMs", "Nullable(Float64)"),
+	addColumn(TABLE_SPAN_EVENTS, "timeToFirstChunkMs", "Nullable(Float64)")
 ];
 const ALL_TABLE_NAMES = [
 	TABLE_SPAN_EVENTS,
@@ -3838,9 +3844,27 @@ function readPreview(preview, payload, jsonEncoded = false) {
 }
 /** Older response builders may shorten previews or turn empty strings into null. */
 function buildSpanQueryResponse(...args) {
-	if (canGeneratePreviews) return _mastra_core_storage.buildSpanQueryResponse(...args);
-	const [plan, selected, payloads, metrics] = args;
-	const response = _mastra_core_storage.buildSpanQueryResponse(plan, selected, [], metrics);
+	const [plan, selected, payloads, metrics = []] = args;
+	const compatibleSelected = _mastra_core_storage.SPAN_QUERY_FIELD_REGISTRY ? selected : selected.map((row) => ({
+		organizationId: row.organizationId,
+		resourceId: row.resourceId,
+		traceId: row.traceId,
+		spanId: row.spanId,
+		parentSpanId: row.parentSpanId,
+		name: row.name,
+		spanType: row.spanType,
+		status: row.status,
+		startedAt: row.startedAt,
+		endedAt: row.endedAt,
+		durationMs: row.durationMs,
+		entityType: row.entityType,
+		entityId: row.entityId,
+		entityName: row.entityName,
+		model: row.model,
+		provider: row.provider
+	}));
+	if (canGeneratePreviews) return _mastra_core_storage.buildSpanQueryResponse(plan, compatibleSelected, payloads, metrics);
+	const response = _mastra_core_storage.buildSpanQueryResponse(plan, compatibleSelected, [], metrics);
 	const byIdentity = new Map(payloads.map((payload) => [_mastra_core_storage.spanQueryIdentityKey(payload), payload]));
 	for (const span of response.spans) {
 		const payload = byIdentity.get(_mastra_core_storage.spanQueryIdentityKey(span));
@@ -4137,6 +4161,7 @@ function spanRecordToRow(span) {
 		isEvent: span.isEvent,
 		startedAt: toISOString(span.startedAt),
 		endedAt: toISOString(endedAt),
+		timeToFirstChunkMs: span.timeToFirstChunkMs ?? null,
 		tags: normalizeTags(span.tags),
 		metadataSearch: buildMetadataSearch(metadata),
 		metadataRaw: jsonEncode(metadata),
@@ -4792,6 +4817,7 @@ function buildMetricsFilterConditions(filters, tableAlias) {
 	assertNoDeprecatedSourceFilter(filters.source, "executionSource", "metrics");
 	addCommonFilterFields(filters, tableAlias, out);
 	addIn(col("traceId"), filters.traceIds, "traceIds", out);
+	addIn(col("experimentId"), filters.experimentIds, "experimentIds", out);
 	addIn(col("name"), filters.name, "metricNames", out);
 	addEq(col("provider"), filters.provider, "provider", "String", out);
 	addEq(col("model"), filters.model, "model", "String", out);
@@ -6985,6 +7011,73 @@ const SPAN_FIELDS = {
 		parameterType: "String"
 	}
 };
+const SPAN_QUERY_FIELDS = {
+	...SPAN_FIELDS,
+	traceId: {
+		sql: "s.traceId",
+		parameterType: "String"
+	},
+	spanId: {
+		sql: "s.spanId",
+		parameterType: "String"
+	},
+	parentSpanId: {
+		sql: "s.parentSpanId",
+		parameterType: "String"
+	},
+	threadId: {
+		sql: "s.threadId",
+		parameterType: "String"
+	},
+	resourceId: {
+		sql: "s.resourceId",
+		parameterType: "String"
+	},
+	requestId: {
+		sql: "s.requestId",
+		parameterType: "String"
+	},
+	serviceName: {
+		sql: "s.serviceName",
+		parameterType: "String"
+	},
+	experimentId: {
+		sql: "s.experimentId",
+		parameterType: "String"
+	},
+	environment: {
+		sql: "s.environment",
+		parameterType: "String"
+	},
+	executionSource: {
+		sql: "s.executionSource",
+		parameterType: "String"
+	},
+	parentEntityType: {
+		sql: "s.parentEntityType",
+		parameterType: "String"
+	},
+	parentEntityId: {
+		sql: "s.parentEntityId",
+		parameterType: "String"
+	},
+	parentEntityName: {
+		sql: "s.parentEntityName",
+		parameterType: "String"
+	},
+	rootEntityType: {
+		sql: "s.rootEntityType",
+		parameterType: "String"
+	},
+	rootEntityId: {
+		sql: "s.rootEntityId",
+		parameterType: "String"
+	},
+	rootEntityName: {
+		sql: "s.rootEntityName",
+		parameterType: "String"
+	}
+};
 const SCORE_FIELDS = {
 	scorerId: {
 		sql: "s.scorerId",
@@ -7856,11 +7949,11 @@ async function queryThreads(client, plan, timeoutMs) {
 		}) : null }
 	});
 }
-/** Compile a span-row filter with exactly the same rules as trace span predicates. */
+/** Compile a direct span-query filter using its dedicated field mapping. */
 function compileSpanQueryPredicate(predicate) {
 	const parameters = new ParameterBuilder();
 	return {
-		sql: compileScalarPredicate(predicate, SPAN_FIELDS, parameters),
+		sql: compileScalarPredicate(predicate, SPAN_QUERY_FIELDS, parameters),
 		params: parameters.params
 	};
 }
@@ -7874,7 +7967,6 @@ const identityFields = [
 ];
 const identities = identityFields.join(", ");
 const identitySetColumns = "isNull(organizationId), ifNull(organizationId, ''), isNull(resourceId), ifNull(resourceId, ''), traceId, spanId";
-const identitySetKey = `tuple(${identitySetColumns})`;
 const displayFields = [
 	"parentSpanId",
 	"name",
@@ -7882,6 +7974,24 @@ const displayFields = [
 	"entityType",
 	"entityId",
 	"entityName",
+	"entityVersionId",
+	"parentEntityType",
+	"parentEntityId",
+	"parentEntityName",
+	"parentEntityVersionId",
+	"rootEntityType",
+	"rootEntityId",
+	"rootEntityName",
+	"rootEntityVersionId",
+	"threadId",
+	"runId",
+	"sessionId",
+	"userId",
+	"requestId",
+	"serviceName",
+	"experimentId",
+	"environment",
+	"executionSource",
 	"startedAt",
 	"endedAt",
 	"model",
@@ -7960,15 +8070,11 @@ function compileClickHouseSpanQuery(plan) {
 	const expressions = selectionFields.map(fieldExpression);
 	const after = afterCursor(plan, parameters);
 	return {
-		query: `WITH candidate_ids AS (
-    SELECT ${identitySetKey} AS identity FROM ${TABLE_SPAN_EVENTS}
-    PREWHERE endedAt >= ${from}
-    WHERE startedAt >= ${from} AND startedAt < ${to} ${scope.length ? `AND ${scope.join(" AND ")}` : ""}
-  ), candidates AS (
+		query: `WITH candidates AS (
     SELECT ${identities}, ${selectionFields.map((field, index) => `${expressions[index]} AS ${field}`).join(", ")}
     FROM ${TABLE_SPAN_EVENTS} e
     PREWHERE e.endedAt >= ${from}
-    WHERE ${identitySetKey} IN (SELECT identity FROM candidate_ids) ${scope.length ? `AND ${scope.join(" AND ")}` : ""}
+    WHERE e.startedAt >= ${from} AND e.startedAt < ${to} ${scope.length ? `AND ${scope.join(" AND ")}` : ""}
     ORDER BY ${identities}, e.endedAt DESC
     LIMIT 1 BY ${identities}
   )
@@ -7986,6 +8092,7 @@ function compileClickHouseSpanQuery(plan) {
 		}
 	};
 }
+const LEGACY_PAYLOAD_BATCH_ROWS = 32;
 function iso(value) {
 	return new Date(value.includes("T") ? value : `${value.replace(" ", "T")}Z`).toISOString();
 }
@@ -8019,34 +8126,25 @@ async function querySpans(client, plan, timeoutMs) {
 	});
 	const missingKeys = new Set(rowsWithPreviews.filter(needsPreviewPayloads).map(_mastra_core_storage.spanQueryIdentityKey));
 	const missing = page.filter((row) => missingKeys.has(_mastra_core_storage.spanQueryIdentityKey(row)));
-	const previewPayloads = /* @__PURE__ */ new Map();
-	if (missing.length) {
+	const storedByIdentity = new Map(rowsWithPreviews.map((row) => [_mastra_core_storage.spanQueryIdentityKey(row), row]));
+	for (let start = 0; start < missing.length; start += LEGACY_PAYLOAD_BATCH_ROWS) {
 		const rows = await run({
 			query: `SELECT ${identities}, data.1 AS input, data.2 AS output, data.3 AS error
       FROM (SELECT ${identities}, any(tuple(input, output, error)) AS data
         FROM ${TABLE_SPAN_EVENTS} e WHERE ${payloadWhere} GROUP BY ${identities})`,
-			query_params: { page: pageParameter(missing) }
+			query_params: { page: pageParameter(missing.slice(start, start + LEGACY_PAYLOAD_BATCH_ROWS)) }
 		});
-		for (const row of rows) previewPayloads.set(_mastra_core_storage.spanQueryIdentityKey(row), row);
+		for (const row of rows) {
+			const stored = storedByIdentity.get(_mastra_core_storage.spanQueryIdentityKey(row));
+			if (stored) Object.assign(stored, resolveStoredPreviews(stored, row));
+		}
 	}
 	const payloads = rowsWithPreviews.map((row) => ({
 		...row,
-		...resolveStoredPreviews(row, previewPayloads.get(_mastra_core_storage.spanQueryIdentityKey(row)))
+		...resolveStoredPreviews(row)
 	}));
-	const metricWhere = `${identitySetKey} IN {page:Array(Tuple(UInt8, String, UInt8, String, String, String))}`;
-	const metrics = await run({
-		query: `SELECT ${identities}, data.1 AS name, data.2 AS estimatedCost,
-      data.3 AS costUnit, data.4 AS allocation, data.5 AS costError
-    FROM (SELECT ${identities}, metricId, argMax(tuple(name, estimatedCost, costUnit,
-        JSONExtractString(costMetadata, 'allocation'), JSONHas(costMetadata, 'error')), timestamp) AS data
-      FROM ${TABLE_METRIC_EVENTS} WHERE (${metricWhere}) AND name LIKE 'mastra_model_%'
-      GROUP BY ${identities}, metricId)
-    LIMIT ${_mastra_core_storage.SPAN_QUERY_MAX_COST_METRICS + 1}`,
-		query_params: { page: page.map((row) => new _clickhouse_client.TupleParam(identityValues(row))) }
-	});
-	if (metrics.length > _mastra_core_storage.SPAN_QUERY_MAX_COST_METRICS) throw new _mastra_core_storage.TraceQueryResourceLimitError();
 	const byIdentity = new Map(payloads.map((row) => [_mastra_core_storage.spanQueryIdentityKey(row), row]));
-	const result = buildSpanQueryResponse(plan, page.flatMap((identity) => {
+	const hydrated = page.flatMap((identity) => {
 		const row = byIdentity.get(_mastra_core_storage.spanQueryIdentityKey(identity));
 		if (!row) return [];
 		const { inputPreview: _input, outputPreview: _output, errorPreview: _error, ...metadata } = row;
@@ -8055,7 +8153,22 @@ async function querySpans(client, plan, timeoutMs) {
 			...identity,
 			durationMs: Number(row.durationMs)
 		}];
-	}), payloads, metrics);
+	});
+	let metrics = [];
+	if (!_mastra_core_storage.SPAN_QUERY_FIELD_REGISTRY) {
+		metrics = await run({
+			query: `SELECT ${identities}, data.1 AS name, data.2 AS estimatedCost,
+        data.3 AS costUnit, data.4 AS allocation, data.5 AS costError
+      FROM (SELECT ${identities}, metricId, argMax(tuple(name, estimatedCost, costUnit,
+          JSONExtractString(costMetadata, 'allocation'), JSONHas(costMetadata, 'error')), timestamp) AS data
+        FROM ${TABLE_METRIC_EVENTS} WHERE (${`tuple(${identitySetColumns}) IN {page:Array(Tuple(UInt8, String, UInt8, String, String, String))}`}) AND name LIKE 'mastra_model_%'
+        GROUP BY ${identities}, metricId)
+      LIMIT ${_mastra_core_storage.SPAN_QUERY_MAX_COST_METRICS + 1}`,
+			query_params: { page: page.map((row) => new _clickhouse_client.TupleParam(identityValues(row))) }
+		});
+		if (metrics.length > _mastra_core_storage.SPAN_QUERY_MAX_COST_METRICS) throw new _mastra_core_storage.TraceQueryResourceLimitError();
+	}
+	const result = buildSpanQueryResponse(plan, hydrated, payloads, metrics);
 	const last = page.at(-1);
 	result.page.next = selected.length > plan.limit ? _mastra_core_storage.encodeSpanQueryCursor(plan, {
 		organizationId: last.organizationId,
@@ -9214,7 +9327,7 @@ function buildBranchCursor(row) {
 }
 //#endregion
 //#region src/storage/domains/observability/v-next/index.ts
-const spanQueryFeatures = typeof _mastra_core_storage.planSpanQuery === "function" ? ["span-query"] : [];
+const spanQueryFeatures = typeof _mastra_core_storage.planSpanQuery === "function" ? ["span-query", "span-query-context-fields"] : [];
 function buildSignalMigrationRequiredMessage(args) {
 	const tableList = args.tables.map((table) => `  - ${table.table} (${table.engine})`).join("\n");
 	return `