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

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.1"
+  version: "1.26.0-alpha.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.26.0-alpha.1",
+  "version": "1.26.0-alpha.3",
   "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,
@@ -4155,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),
@@ -6857,6 +6864,12 @@ async function getScorePercentiles(client, args) {
 //#endregion
 //#region src/storage/domains/observability/v-next/trace-query.ts
 const TRACE_STATUS_SQL = `if(isNotNull(r.error), 'error', 'success')`;
+/**
+* Core versions without the field reject it in strict query results, so it is only returned when core knows it.
+* 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"] : [];
 function durationMsSql(startedAt, endedAt) {
 	return `dateDiff('millisecond', ${startedAt}, ${endedAt})`;
 }
@@ -6905,6 +6918,10 @@ const TRACE_FIELDS = {
 		sql: durationMsSql("r.startedAt", "r.endedAt"),
 		parameterType: "Float64"
 	},
+	timeToFirstChunkMs: {
+		sql: "r.timeToFirstChunkMs",
+		parameterType: "Float64"
+	},
 	entityName: {
 		sql: "r.entityName",
 		parameterType: "String"
@@ -6913,6 +6930,14 @@ const TRACE_FIELDS = {
 		sql: "r.entityType",
 		parameterType: "String"
 	},
+	name: {
+		sql: "r.name",
+		parameterType: "String"
+	},
+	spanType: {
+		sql: "r.spanType",
+		parameterType: "String"
+	},
 	environment: {
 		sql: "r.environment",
 		parameterType: "String"
@@ -6955,6 +6980,10 @@ const SPAN_FIELDS = {
 		sql: "s.durationMs",
 		parameterType: "Float64"
 	},
+	timeToFirstChunkMs: {
+		sql: "s.timeToFirstChunkMs",
+		parameterType: "Float64"
+	},
 	status: {
 		sql: "s.status",
 		parameterType: "String"
@@ -7166,6 +7195,7 @@ const TRACE_SELECT = `
   r.entityName AS entityName,
   r.entityType AS entityType,
   r.environment AS environment,
+  r.timeToFirstChunkMs AS timeToFirstChunkMs,
   ${TRACE_STATUS_SQL} AS status`;
 var ParameterBuilder = class {
 	params = {};
@@ -7341,6 +7371,7 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters,
       startedAt,
       endedAt,
       ${durationMsSql("startedAt", "endedAt")} AS durationMs,
+      timeToFirstChunkMs,
       if(isNotNull(error), 'error', 'success') AS status,
       error,
       entityType,
@@ -7753,6 +7784,12 @@ async function runWithClickHouseTraceQueryTimeout(client, limits, compiled, quer
 				...CH_SETTINGS,
 				max_execution_time: resolvedTimeoutMs / 1e3,
 				...limits.memoryLimitBytes === void 0 ? {} : { max_memory_usage: String(limits.memoryLimitBytes) },
+				...limits.maxThreads === void 0 ? {} : { max_threads: limits.maxThreads },
+				...limits.maxBlockSize === void 0 ? {} : { max_block_size: String(limits.maxBlockSize) },
+				...limits.spillThresholdBytes === void 0 ? {} : {
+					max_bytes_before_external_sort: String(limits.spillThresholdBytes),
+					max_bytes_before_external_group_by: String(limits.spillThresholdBytes)
+				},
 				...compiled.sharedSnapshot ? { enable_shared_storage_snapshot_in_query: 1 } : {}
 			}
 		})).json();
@@ -7875,7 +7912,8 @@ async function queryTraces(client, plan, timeoutMs, strategy = null) {
 		entityName: row.entityName == null ? null : String(row.entityName),
 		entityType: row.entityType == null ? null : String(row.entityType),
 		environment: row.environment == null ? null : String(row.environment),
-		status: row.status
+		status: row.status,
+		...timeToFirstChunkSupported && { timeToFirstChunkMs: row.timeToFirstChunkMs == null ? null : Number(row.timeToFirstChunkMs) }
 	});
 	if (plan.paginationMode === "delta") {
 		const rows = await run(compileClickHouseTraceQuery(plan, deltaHead));
@@ -7950,6 +7988,16 @@ function compileSpanQueryPredicate(predicate) {
 		params: parameters.params
 	};
 }
+/** Thread filters see full-history representative values, never individual member traces. */
+function compileThreadQueryPredicate(predicate, parameters = new ParameterBuilder()) {
+	return {
+		sql: compileScalarPredicate(predicate, Object.fromEntries(Object.entries(_mastra_core_storage.THREAD_QUERY_FIELD_REGISTRY).map(([field, rule]) => [field, {
+			sql: `s.${field}`,
+			parameterType: rule.valueKind === "timestamp" ? "DateTime64(3, 'UTC')" : rule.valueKind === "number" ? "Float64" : "String"
+		}])), parameters),
+		params: parameters.params
+	};
+}
 //#endregion
 //#region src/storage/domains/observability/v-next/span-query.ts
 const identityFields = [
@@ -7990,6 +8038,7 @@ const displayFields = [
 	"model",
 	"provider",
 	"durationMs",
+	"timeToFirstChunkMs",
 	"status"
 ];
 var Parameters = class {
@@ -8010,7 +8059,7 @@ function identityValues(row) {
 		row.spanId
 	];
 }
-function afterCursor(plan, parameters) {
+function afterCursor$1(plan, parameters) {
 	if (!plan.cursor) return "1";
 	const cursor = plan.cursor;
 	const timestamp = parameters.add(cursor.sortValue, true);
@@ -8028,10 +8077,10 @@ function afterCursor(plan, parameters) {
 	}
 	return `(${terms.join(" OR ")})`;
 }
-function predicateFields(predicate, fields = /* @__PURE__ */ new Set()) {
+function predicateFields$1(predicate, fields = /* @__PURE__ */ new Set()) {
 	if (!predicate) return fields;
-	if (predicate.type === "boolean") for (const arg of predicate.args) predicateFields(arg, fields);
-	else if (predicate.type === "not") predicateFields(predicate.arg, fields);
+	if (predicate.type === "boolean") for (const arg of predicate.args) predicateFields$1(arg, fields);
+	else if (predicate.type === "not") predicateFields$1(predicate.arg, fields);
 	else fields.add(predicate.field);
 	return fields;
 }
@@ -8058,10 +8107,10 @@ function compileClickHouseSpanQuery(plan) {
 	const selectionFields = [.../* @__PURE__ */ new Set([
 		"startedAt",
 		"endedAt",
-		...predicateFields(plan.where)
+		...predicateFields$1(plan.where)
 	])].filter((field) => !new Set(identityFields).has(field));
 	const expressions = selectionFields.map(fieldExpression);
-	const after = afterCursor(plan, parameters);
+	const after = afterCursor$1(plan, parameters);
 	return {
 		query: `WITH candidates AS (
     SELECT ${identities}, ${selectionFields.map((field, index) => `${expressions[index]} AS ${field}`).join(", ")}
@@ -8086,7 +8135,7 @@ function compileClickHouseSpanQuery(plan) {
 	};
 }
 const LEGACY_PAYLOAD_BATCH_ROWS = 32;
-function iso(value) {
+function iso$1(value) {
 	return new Date(value.includes("T") ? value : `${value.replace(" ", "T")}Z`).toISOString();
 }
 async function querySpans(client, plan, timeoutMs) {
@@ -8101,8 +8150,8 @@ async function querySpans(client, plan, timeoutMs) {
 	};
 	const selected = (await run(compileClickHouseSpanQuery(plan))).map((row) => ({
 		...row,
-		startedAt: iso(row.startedAt),
-		endedAt: iso(row.endedAt)
+		startedAt: iso$1(row.startedAt),
+		endedAt: iso$1(row.endedAt)
 	}));
 	const page = selected.slice(0, plan.limit);
 	if (!page.length) return {
@@ -8140,11 +8189,12 @@ 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, ...metadata } = row;
+		const { inputPreview: _input, outputPreview: _output, errorPreview: _error, timeToFirstChunkMs, ...metadata } = row;
 		return [{
 			...metadata,
 			...identity,
-			durationMs: Number(row.durationMs)
+			durationMs: Number(row.durationMs),
+			...timeToFirstChunkSupported && { timeToFirstChunkMs: timeToFirstChunkMs == null ? null : Number(timeToFirstChunkMs) }
 		}];
 	});
 	let metrics = [];
@@ -8173,11 +8223,308 @@ async function querySpans(client, plan, timeoutMs) {
 	return result;
 }
 //#endregion
+//#region src/storage/domains/observability/v-next/thread-query.ts
+const contextFields = [
+	"resourceId",
+	"userId",
+	"entityType",
+	"entityId",
+	"entityName",
+	"entityVersionId",
+	"runId",
+	"sessionId",
+	"requestId",
+	"serviceName",
+	"experimentId",
+	"environment",
+	"executionSource"
+];
+function predicateFields(predicate, fields = /* @__PURE__ */ new Set()) {
+	if (!predicate) return fields;
+	if (predicate.type === "boolean") for (const arg of predicate.args) predicateFields(arg, fields);
+	else if (predicate.type === "not") predicateFields(predicate.arg, fields);
+	else fields.add(predicate.field);
+	return fields;
+}
+function afterCursor(plan, parameters) {
+	if (!plan.cursor) return "1";
+	const { cursor } = plan;
+	const stamp = parameters.add(cursor.sortValue, "DateTime64(3, 'UTC')");
+	const field = `s.${plan.orderBy.field}`;
+	const terms = [`${field} ${plan.orderBy.direction === "asc" ? ">" : "<"} ${stamp}`];
+	const equal = [`${field} = ${stamp}`];
+	for (const key of ["organizationId", "threadId"]) if (cursor[key] === null) equal.push(`isNull(s.${key})`);
+	else {
+		const value = parameters.add(cursor[key], "String");
+		terms.push(`(${equal.join(" AND ")} AND (s.${key} > ${value} OR isNull(s.${key})))`);
+		equal.push(`s.${key} = ${value}`);
+	}
+	return `(${terms.join(" OR ")})`;
+}
+const THREAD_QUERY_EXECUTION_LIMITS = {
+	memoryLimitBytes: 512 * 1024 * 1024,
+	maxThreads: 2,
+	maxBlockSize: 4096,
+	spillThresholdBytes: 32 * 1024 * 1024
+};
+const MAX_CANDIDATE_THREADS = 16384;
+const MAX_CANDIDATE_TRACES = 1e5;
+const MAX_CANDIDATE_ID_BYTES = 4 * 1024 * 1024;
+const MAX_FULL_HISTORY_ROOTS = 25e4;
+function canUseThreadCandidates(probe) {
+	return Number(probe.threadCount) <= MAX_CANDIDATE_THREADS && Number(probe.traceCount) <= MAX_CANDIDATE_TRACES && Number(probe.threadBytes) + Number(probe.traceBytes) <= MAX_CANDIDATE_ID_BYTES;
+}
+const identity = (field) => `tuple(isNull(organizationId), ifNull(organizationId, ''), ${field})`;
+const candidateThreadsFilter = `${identity("threadId")} IN (SELECT ${identity("threadId")} FROM candidate_threads)`;
+const candidateTracesFilter = `${identity("traceId")} IN (SELECT ${identity("traceId")} FROM candidate_traces)`;
+function candidateCtes(scope, from, to, plan, probe = false) {
+	const timestamp = plan.timeRange.mode === "threads" ? plan.timeRange.field : "startedAt";
+	const scoped = scope.length ? `${scope.join(" AND ")} AND ` : "";
+	return `candidate_threads AS (
+    SELECT DISTINCT organizationId, threadId FROM ${TABLE_TRACE_ROOTS}
+    WHERE ${scoped}threadId IS NOT NULL AND ${timestamp} >= ${from} AND ${timestamp} < ${to}
+    ${probe ? `LIMIT 16385` : ""}
+  ), candidate_traces AS (
+    SELECT DISTINCT organizationId, traceId FROM ${TABLE_TRACE_ROOTS}
+    WHERE ${scoped}${candidateThreadsFilter}
+    ${probe ? `LIMIT 100001` : ""}
+  )`;
+}
+function compileClickHouseThreadRowsQuery(plan, strategy = "full") {
+	const parameters = new ParameterBuilder();
+	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, "String")}`);
+		if (plan.scope.resourceId !== void 0) scope.push(`resourceId = ${parameters.add(plan.scope.resourceId, "String")}`);
+	}
+	if (strategy === "historyBudget") return {
+		query: `SELECT count() AS rootCount FROM (
+        SELECT 1 FROM ${TABLE_TRACE_ROOTS} ${scope.length ? `WHERE ${scope.join(" AND ")}` : ""}
+        LIMIT 250001
+      )`,
+		query_params: parameters.params
+	};
+	if (strategy === "probe") return {
+		query: `WITH ${candidateCtes(scope, from, to, plan, true)}
+        SELECT (SELECT count() FROM candidate_threads) AS threadCount,
+          (SELECT sum(length(ifNull(organizationId, '')) + length(threadId)) FROM candidate_threads) AS threadBytes,
+          count() AS traceCount, sum(length(ifNull(organizationId, '')) + length(traceId)) AS traceBytes
+        FROM candidate_traces`,
+		query_params: parameters.params
+	};
+	const predicate = plan.where ? compileThreadQueryPredicate(plan.where, parameters).sql : "1";
+	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 firstFields = [
+		"startedAt",
+		"traceId",
+		"spanId",
+		"endedAt",
+		...firstContext
+	];
+	const lastFields = [
+		"startedAt",
+		"traceId",
+		"spanId",
+		"endedAt",
+		"resourceId",
+		...filtered.has("status") ? ["status"] : []
+	];
+	const rootDataFields = [
+		"threadId",
+		"spanId",
+		"startedAt",
+		"endedAt",
+		...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 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 ")}` : ""}
+    ORDER BY organizationId, traceId, startedAt ASC, spanId, endedAt DESC, isNotNull(threadId) DESC, dedupeKey
+    LIMIT 1 BY organizationId, traceId
+  )`;
+	return {
+		query: `WITH ${strategy === "candidates" ? `${candidateCtes(scope, from, to, plan)}, ` : ""}${sortedRoots}, grouped AS (
+    SELECT organizationId, threadId, min(startedAt) AS firstActivity, max(endedAt) AS lastActivity,
+      count() AS traceCount, countIf(startedAt >= ${from} AND startedAt < ${to}) AS inWindow,
+      min(tuple(${firstFields.join(", ")})) AS first,
+      max(tuple(${lastFields.join(", ")})) AS last
+    FROM roots WHERE threadId IS NOT NULL ${strategy === "candidates" ? `AND ${candidateThreadsFilter}` : ""} GROUP BY organizationId, threadId
+  ), rows AS (
+    SELECT organizationId, threadId, firstActivity AS startedAt, lastActivity AS endedAt, traceCount, inWindow,
+      ${firstFields.map((field, i) => `first.${i + 1} AS ${i < 4 ? `first${field[0].toUpperCase()}${field.slice(1)}` : field}`).join(", ")},
+      ${lastFields.map((field, i) => `last.${i + 1} AS ${field === "status" ? "status" : `last${field[0].toUpperCase()}${field.slice(1)}`}`).join(", ")}
+    FROM grouped
+  ) SELECT * FROM rows s WHERE ${qualify} AND (${predicate}) AND ${after}
+  ORDER BY s.${plan.orderBy.field} ${plan.orderBy.direction === "asc" ? "ASC" : "DESC"}, s.organizationId ASC NULLS LAST, s.threadId ASC
+  LIMIT ${parameters.add(plan.limit + 1, "UInt64")}`,
+		query_params: parameters.params
+	};
+}
+const rootKey = (row) => JSON.stringify([
+	row.organizationId,
+	row.traceId,
+	row.spanId
+]);
+const iso = (value) => new Date(value.includes("T") ? value : `${value.replace(" ", "T")}Z`).toISOString();
+/** Bound HTTP form parameter size as well as payload rows. Long IDs must not break large pages. */
+function* batches(rows, maxRows = 256) {
+	let batch = [];
+	let bytes = 0;
+	for (const row of rows) {
+		const size = Buffer.byteLength(JSON.stringify(row), "utf8") * 2;
+		if (batch.length && (batch.length >= maxRows || bytes + size > 48 * 1024)) {
+			yield batch;
+			batch = [];
+			bytes = 0;
+		}
+		batch.push(row);
+		bytes += size;
+	}
+	if (batch.length) yield batch;
+}
+async function queryThreadRows(client, plan, timeoutMs, strategy = "auto") {
+	const deadline = performance.now() + _mastra_core_storage.resolveTraceQueryTimeoutMs(timeoutMs);
+	const run = async (compiled) => {
+		const remaining = Math.floor(deadline - performance.now());
+		if (remaining <= 0) throw new _mastra_core_storage.TraceQueryExecutionError();
+		return await runWithClickHouseTraceQueryTimeout(client, {
+			timeoutMs: remaining,
+			...THREAD_QUERY_EXECUTION_LIMITS
+		}, compiled);
+	};
+	if (strategy === "auto") {
+		const [probe] = await run(compileClickHouseThreadRowsQuery(plan, "probe"));
+		if (Number(probe.threadCount) === 0) return {
+			threads: [],
+			page: { next: null }
+		};
+		strategy = canUseThreadCandidates(probe) ? "candidates" : "full";
+	}
+	if (strategy === "full") {
+		const [budget] = await run(compileClickHouseThreadRowsQuery(plan, "historyBudget"));
+		if (Number(budget.rootCount) > MAX_FULL_HISTORY_ROOTS) throw new _mastra_core_storage.TraceQueryResourceLimitError();
+	}
+	const selected = await run(compileClickHouseThreadRowsQuery(plan, strategy));
+	const page = selected.slice(0, plan.limit);
+	if (!page.length) return {
+		threads: [],
+		page: { next: null }
+	};
+	const roots = /* @__PURE__ */ new Map();
+	const representative = (row, which) => ({
+		organizationId: row.organizationId,
+		resourceId: which === "first" ? row.resourceId : row.lastResourceId,
+		traceId: row[`${which}TraceId`],
+		spanId: row[`${which}SpanId`],
+		startedAt: row[`${which}StartedAt`],
+		endedAt: row[`${which}EndedAt`]
+	});
+	for (const row of page) for (const which of ["first", "last"]) {
+		const root = representative(row, which);
+		roots.set(rootKey(root), root);
+	}
+	const keys = (batch) => batch.map((root) => new _clickhouse_client.TupleParam([
+		root.organizationId === null ? 1 : 0,
+		root.organizationId ?? "",
+		root.resourceId === null ? 1 : 0,
+		root.resourceId ?? "",
+		root.traceId,
+		root.spanId,
+		iso(root.startedAt).replace("T", " ").replace(/Z$/, ""),
+		iso(root.endedAt).replace("T", " ").replace(/Z$/, "")
+	]));
+	const rootWhere = `tuple(isNull(organizationId), ifNull(organizationId, ''), isNull(resourceId), ifNull(resourceId, ''),
+    traceId, spanId, startedAt, endedAt) IN {roots:Array(Tuple(UInt8, String, UInt8, String, String, String, DateTime64(3, 'UTC'), DateTime64(3, 'UTC')))}`;
+	const stored = [];
+	for (const batch of batches([...roots.values()])) stored.push(...await run({
+		query: `SELECT organizationId, traceId, spanId, startedAt, endedAt, spanType,
+      ${contextFields.join(", ")}, if(spanType = 'agent_run', timeToFirstChunkMs, NULL) AS timeToFirstChunkMs,
+      if(isNull(error), 'success', 'error') AS status, ${PREVIEW_COLUMNS.join(", ")}
+      FROM ${TABLE_TRACE_ROOTS} WHERE ${rootWhere}
+      ORDER BY isNotNull(threadId) DESC LIMIT 1 BY organizationId, traceId, spanId`,
+		query_params: { roots: keys(batch) }
+	}));
+	const byRoot = new Map(stored.map((row) => [rootKey(row), row]));
+	const missing = stored.filter(needsPreviewPayloads);
+	for (const batch of batches(missing, 32)) {
+		const payloads = await run({
+			query: `SELECT organizationId, traceId, spanId, input, output, error FROM ${TABLE_TRACE_ROOTS}
+        WHERE ${rootWhere} ORDER BY isNotNull(threadId) DESC LIMIT 1 BY organizationId, traceId, spanId`,
+			query_params: { roots: keys(batch) }
+		});
+		for (const payload of payloads) {
+			const row = byRoot.get(rootKey(payload));
+			if (row) Object.assign(row, resolveStoredPreviews(row, payload));
+		}
+	}
+	const firstRoots = page.map((row) => representative(row, "first")).filter((root) => byRoot.get(rootKey(root))?.spanType === "agent_run");
+	const models = [];
+	for (const batch of batches(firstRoots)) models.push(...await run({
+		query: `SELECT organizationId, traceId,
+      if(JSONType(attributes, 'model') = 'String', JSONExtractString(attributes, 'model'), NULL) AS model,
+      if(JSONType(attributes, 'provider') = 'String', JSONExtractString(attributes, 'provider'), NULL) AS provider
+      FROM ${TABLE_SPAN_EVENTS} WHERE spanType = 'model_generation' AND
+      tuple(isNull(organizationId), ifNull(organizationId, ''), isNull(resourceId), ifNull(resourceId, ''), traceId, parentSpanId)
+        IN {agents:Array(Tuple(UInt8, String, UInt8, String, String, String))}
+      ORDER BY organizationId, traceId, startedAt, spanId LIMIT 1 BY organizationId, traceId`,
+		query_params: { agents: batch.map((root) => new _clickhouse_client.TupleParam([
+			root.organizationId === null ? 1 : 0,
+			root.organizationId ?? "",
+			root.resourceId === null ? 1 : 0,
+			root.resourceId ?? "",
+			root.traceId,
+			root.spanId
+		])) }
+	}));
+	const byTrace = new Map(models.map((row) => [JSON.stringify([row.organizationId, row.traceId]), row]));
+	const threads = page.flatMap((row) => {
+		const first = byRoot.get(rootKey(representative(row, "first")));
+		const last = byRoot.get(rootKey(representative(row, "last")));
+		if (!first || !last) return [];
+		const model = byTrace.get(JSON.stringify([row.organizationId, row.firstTraceId]));
+		return [_mastra_core_storage.threadQueryRowSchema.parse({
+			organizationId: row.organizationId,
+			threadId: row.threadId,
+			firstTraceId: row.firstTraceId,
+			lastTraceId: row.lastTraceId,
+			...Object.fromEntries(contextFields.map((field) => [field, first[field]])),
+			status: last.status,
+			startedAt: iso(row.startedAt),
+			endedAt: iso(row.endedAt),
+			traceCount: Number(row.traceCount),
+			timeToFirstChunkMs: first.timeToFirstChunkMs,
+			model: model?.model ?? null,
+			provider: model?.provider ?? null,
+			inputPreview: resolveStoredPreviews(first).inputPreview,
+			outputPreview: resolveStoredPreviews(last).outputPreview,
+			errorPreview: resolveStoredPreviews(last).errorPreview
+		})];
+	});
+	const last = page.at(-1);
+	return {
+		threads,
+		page: { next: selected.length > plan.limit ? _mastra_core_storage.encodeThreadQueryCursor(plan, {
+			organizationId: last.organizationId,
+			threadId: last.threadId,
+			sortValue: iso(last[plan.orderBy.field])
+		}) : null }
+	};
+}
+//#endregion
 //#region src/storage/domains/observability/v-next/trace-aggregate.ts
 /** Trace-root column expressions (alias `r`) for each groupable dimension; same values `where` sees. */
 const DIMENSION_SQL = {
 	entityType: "r.entityType",
 	entityName: "r.entityName",
+	name: "r.name",
+	spanType: "r.spanType",
 	environment: "r.environment",
 	status: TRACE_STATUS_SQL,
 	serviceName: "r.serviceName",
@@ -9321,6 +9668,7 @@ function buildBranchCursor(row) {
 //#endregion
 //#region src/storage/domains/observability/v-next/index.ts
 const spanQueryFeatures = typeof _mastra_core_storage.planSpanQuery === "function" ? ["span-query", "span-query-context-fields"] : [];
+const threadQueryFeatures = typeof _mastra_core_storage.planThreadRowsQuery === "function" ? ["thread-query-rows"] : [];
 function buildSignalMigrationRequiredMessage(args) {
 	const tableList = args.tables.map((table) => `  - ${table.table} (${table.engine})`).join("\n");
 	return `
@@ -9758,8 +10106,11 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"trace-query-tenant-scope",
 			"feedback",
 			"trace-query-context-ids",
+			...timeToFirstChunkFeatures,
+			"trace-query-root-span-fields",
 			"trace-aggregate",
-			...spanQueryFeatures
+			...spanQueryFeatures,
+			...threadQueryFeatures
 		];
 		return [
 			"metrics",
@@ -9778,8 +10129,11 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"trace-query-tenant-scope",
 			"feedback",
 			"trace-query-context-ids",
+			...timeToFirstChunkFeatures,
+			"trace-query-root-span-fields",
 			"trace-aggregate",
-			...spanQueryFeatures
+			...spanQueryFeatures,
+			...threadQueryFeatures
 		];
 	}
 	async createSpan(args) {
@@ -9956,6 +10310,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 	}
 	async queryThreads(plan) {
 		try {
+			if (plan.result === "threadRows") return await queryThreadRows(this.#client, plan, this.#traceQueryTimeoutMs);
 			return await queryThreads(this.#client, plan, this.#traceQueryTimeoutMs);
 		} catch (error) {
 			if (error instanceof _mastra_core_error.MastraError || error instanceof _mastra_core_storage.TraceQueryExecutionError || error instanceof _mastra_core_storage.TraceQueryResourceLimitError) throw error;