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

package/dist/index.cjs

@@ -6864,6 +6864,14 @@ 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 ?? {});
+/** 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})`;
 }
@@ -6912,6 +6920,10 @@ const TRACE_FIELDS = {
 		sql: durationMsSql("r.startedAt", "r.endedAt"),
 		parameterType: "Float64"
 	},
+	timeToFirstChunkMs: {
+		sql: "r.timeToFirstChunkMs",
+		parameterType: "Float64"
+	},
 	entityName: {
 		sql: "r.entityName",
 		parameterType: "String"
@@ -6920,6 +6932,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"
@@ -6962,6 +6982,10 @@ const SPAN_FIELDS = {
 		sql: "s.durationMs",
 		parameterType: "Float64"
 	},
+	timeToFirstChunkMs: {
+		sql: "s.timeToFirstChunkMs",
+		parameterType: "Float64"
+	},
 	status: {
 		sql: "s.status",
 		parameterType: "String"
@@ -7173,6 +7197,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 = {};
@@ -7189,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) {
@@ -7348,6 +7373,7 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters,
       startedAt,
       endedAt,
       ${durationMsSql("startedAt", "endedAt")} AS durationMs,
+      timeToFirstChunkMs,
       if(isNotNull(error), 'error', 'success') AS status,
       error,
       entityType,
@@ -7466,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`
@@ -7480,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
@@ -7512,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
 	};
@@ -7760,6 +7789,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();
@@ -7882,7 +7917,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));
@@ -7905,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));
@@ -7914,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({
@@ -7932,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 }
 	});
@@ -7957,6 +7994,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 = [
@@ -7997,14 +8044,15 @@ const displayFields = [
 	"model",
 	"provider",
 	"durationMs",
+	"timeToFirstChunkMs",
 	"status"
 ];
 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) {
@@ -8017,13 +8065,20 @@ 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);
 	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})`);
@@ -8035,10 +8090,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;
 }
@@ -8051,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)}`);
@@ -8065,10 +8120,11 @@ function compileClickHouseSpanQuery(plan) {
 	const selectionFields = [.../* @__PURE__ */ new Set([
 		"startedAt",
 		"endedAt",
-		...predicateFields(plan.where)
+		plan.orderBy.field,
+		...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(", ")}
@@ -8078,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,
@@ -8093,7 +8150,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) {
@@ -8108,8 +8165,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 {
@@ -8147,11 +8204,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 = [];
@@ -8175,16 +8233,313 @@ 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;
 }
 //#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",
@@ -9328,6 +9683,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 `
@@ -9765,8 +10121,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",
@@ -9785,8 +10144,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) {
@@ -9963,6 +10325,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;