@mastra/clickhouse 1.22.1 → 1.23.0-alpha.1

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.22.1",
+  "version": "1.23.0-alpha.1",
   "package": "@mastra/clickhouse",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -6580,6 +6580,10 @@ const TRACE_STATUS_SQL = `if(isNotNull(r.error), 'error', 'success')`;
 function durationMsSql(startedAt, endedAt) {
 	return `dateDiff('millisecond', ${startedAt}, ${endedAt})`;
 }
+/** Top-level metadata string value on a trace root (alias `r`); `key` is a bound parameter placeholder. */
+function traceMetadataValueSql(key) {
+	return `coalesce(if(mapContains(r.metadataSearch, ${key}), r.metadataSearch[${key}], NULL), nullIf(trim(JSONExtractString(r.metadataRaw, ${key})), ''))`;
+}
 const TRACE_FIELDS = {
 	traceId: {
 		sql: "r.traceId",
@@ -6838,9 +6842,8 @@ function compileScalarPredicate(predicate, registry, parameters, allowMetadata =
 	if (predicate.type === "not") return `NOT (${compileScalarPredicate(predicate.arg, registry, parameters, allowMetadata)})`;
 	const field = isMetadataField(predicate.field) ? (() => {
 		if (!allowMetadata) throw new Error(`Unsupported trusted trace-query field: ${predicate.field}`);
-		const key = parameters.add(predicate.field.slice(9), "String");
 		return {
-			sql: `coalesce(if(mapContains(r.metadataSearch, ${key}), r.metadataSearch[${key}], NULL), nullIf(trim(JSONExtractString(r.metadataRaw, ${key})), ''))`,
+			sql: traceMetadataValueSql(parameters.add(predicate.field.slice(9), "String")),
 			parameterType: "String"
 		};
 	})() : fieldDefinition(registry, predicate.field);
@@ -6933,7 +6936,7 @@ function compileTenantScope(scope, parameters) {
 	if (scope.resourceId !== void 0) sql += `\n      AND resourceId = ${parameters.add(scope.resourceId, "String")}`;
 	return sql;
 }
-function compileClickHouseTraceScope(selection, relationCollections, parameters, scope) {
+function compileClickHouseTraceScope(selection, relationCollections, parameters, scope, seedConjuncts = []) {
 	const from = parameters.add(selection.timeRange.from, "DateTime64(3, 'UTC')");
 	const to = parameters.add(selection.timeRange.to, "DateTime64(3, 'UTC')");
 	const tenant = compileTenantScope(scope, parameters);
@@ -6943,9 +6946,9 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters,
       FROM ${TABLE_TRACE_ROOTS}
       WHERE traceId IN (
         SELECT traceId
-        FROM ${TABLE_TRACE_ROOTS}
+        FROM ${TABLE_TRACE_ROOTS} r
         WHERE startedAt >= ${from}
-          AND startedAt < ${to}${tenant}
+          AND startedAt < ${to}${tenant}${seedConjuncts.map((conjunct) => `\n          AND (${compilePredicate(conjunct, parameters)})`).join("")}
       )
       ORDER BY dedupeKey
       LIMIT 1 BY dedupeKey
@@ -7038,16 +7041,25 @@ function parseDeltaWatermark(value) {
 		throw new _mastra_core_storage.TraceQueryCursorError("TRACE_QUERY_CURSOR_MALFORMED");
 	}
 }
-function compileClickHouseTraceQuery(plan, deltaHead) {
-	const parameters = new ParameterBuilder();
-	const ctes = compileClickHouseTraceScope(plan, collectRelationCollections(plan.where), parameters, plan.scope);
-	const predicate = plan.where ? compilePredicate(plan.where, parameters) : "1";
+/**
+* Builds the CTE chain ending in `candidates`: the completed, current trace roots in the
+* selection's time range and tenant scope that match its `where` predicate. Trace queries and
+* trace aggregates both select from this CTE so they always see the same population.
+*/
+function compileClickHouseTraceCandidates(selection, columns, parameters) {
+	const rootConjuncts = selection.where ? (selection.where.type === "boolean" && selection.where.operator === "and" ? selection.where.args : [selection.where]).filter((conjunct) => collectRelationCollections(conjunct).size === 0) : [];
+	const ctes = compileClickHouseTraceScope(selection, collectRelationCollections(selection.where), parameters, selection.scope, rootConjuncts);
+	const predicate = selection.where ? compilePredicate(selection.where, parameters) : "1";
 	ctes.push(`candidates AS (
-    SELECT ${TRACE_SELECT}
+    SELECT ${columns}
     FROM root_scope r
     WHERE ${predicate}
   )`);
-	const candidates = `WITH ${ctes.join(",\n")}`;
+	return ctes;
+}
+function compileClickHouseTraceQuery(plan, deltaHead) {
+	const parameters = new ParameterBuilder();
+	const candidates = `WITH ${compileClickHouseTraceCandidates(plan, TRACE_SELECT, parameters).join(",\n")}`;
 	if (plan.result === "groups") return {
 		query: `${candidates}
 SELECT threadId
@@ -7223,10 +7235,8 @@ function compileClickHouseTraceQueryValues(plan) {
 	const parameters = new ParameterBuilder();
 	const ctes = compileClickHouseTraceScope(plan, discoveryCollections(plan.predicateScope), parameters, plan.scope);
 	let field;
-	if (plan.predicateScope === "trace" && plan.path.startsWith("metadata.")) {
-		const key = parameters.add(plan.path.slice(9), "String");
-		field = `coalesce(if(mapContains(r.metadataSearch, ${key}), r.metadataSearch[${key}], NULL), nullIf(trim(JSONExtractString(r.metadataRaw, ${key})), ''))`;
-	} else if (plan.predicateScope === "trace" && plan.path === "tags") field = `arrayJoin(arrayDistinct(${TRACE_FIELDS.tags.sql}))`;
+	if (plan.predicateScope === "trace" && plan.path.startsWith("metadata.")) field = traceMetadataValueSql(parameters.add(plan.path.slice(9), "String"));
+	else if (plan.predicateScope === "trace" && plan.path === "tags") field = `arrayJoin(arrayDistinct(${TRACE_FIELDS.tags.sql}))`;
 	else field = fieldDefinition(discoveryRegistry(plan.predicateScope), plan.path).sql;
 	const search = plan.search ? `AND positionCaseInsensitiveUTF8(value, ${parameters.add(plan.search, "String")}) > 0` : "";
 	const limit = parameters.add(plan.limit + 1, "UInt64");
@@ -7433,6 +7443,380 @@ async function queryThreads(client, plan, timeoutMs) {
 		}) : null }
 	});
 }
+/** Compile a span-row filter with exactly the same rules as trace span predicates. */
+function compileSpanQueryPredicate(predicate) {
+	const parameters = new ParameterBuilder();
+	return {
+		sql: compileScalarPredicate(predicate, SPAN_FIELDS, parameters),
+		params: parameters.params
+	};
+}
+//#endregion
+//#region src/storage/domains/observability/v-next/span-query.ts
+const identityFields = [
+	"organizationId",
+	"resourceId",
+	"traceId",
+	"spanId"
+];
+const identities = identityFields.join(", ");
+const identitySetColumns = "isNull(organizationId), ifNull(organizationId, ''), isNull(resourceId), ifNull(resourceId, ''), traceId, spanId";
+const identitySetKey = `tuple(${identitySetColumns})`;
+const displayFields = [
+	"parentSpanId",
+	"name",
+	"spanType",
+	"entityType",
+	"entityId",
+	"entityName",
+	"startedAt",
+	"endedAt",
+	"model",
+	"provider",
+	"durationMs",
+	"status"
+];
+var Parameters = class {
+	values = {};
+	add(value, timestamp = false) {
+		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"}}`;
+	}
+};
+function identityValues(row) {
+	return [
+		row.organizationId === null ? 1 : 0,
+		row.organizationId ?? "",
+		row.resourceId === null ? 1 : 0,
+		row.resourceId ?? "",
+		row.traceId,
+		row.spanId
+	];
+}
+function afterCursor(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}`];
+	for (const key of identityFields) {
+		const value = cursor[key];
+		if (value === null) equal.push(`isNull(s.${key})`);
+		else {
+			const parameter = parameters.add(value);
+			terms.push(`(${equal.join(" AND ")} AND (s.${key} > ${parameter} OR isNull(s.${key})))`);
+			equal.push(`s.${key} = ${parameter}`);
+		}
+	}
+	return `(${terms.join(" OR ")})`;
+}
+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 fieldExpression(field) {
+	if (field === "model" || field === "provider") return `if(JSONType(e.attributes, '${field}') = 'String', JSONExtractString(e.attributes, '${field}'), NULL)`;
+	if (field === "durationMs") return "dateDiff('millisecond', e.startedAt, e.endedAt)";
+	if (field === "status") return "if(isNull(e.error), 'success', 'error')";
+	if (field === "error") return "if(isNull(e.error), NULL, 'error')";
+	return `e.${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 scope = [];
+	if (plan.scope) {
+		scope.push(`organizationId = ${parameters.add(plan.scope.organizationId)}`);
+		if (plan.scope.resourceId !== void 0) scope.push(`resourceId = ${parameters.add(plan.scope.resourceId)}`);
+	}
+	const predicate = plan.where ? compileSpanQueryPredicate(plan.where) : {
+		sql: "1",
+		params: {}
+	};
+	const selectionFields = [.../* @__PURE__ */ new Set([
+		"startedAt",
+		"endedAt",
+		...predicateFields(plan.where)
+	])].filter((field) => !new Set(identityFields).has(field));
+	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 (
+    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 ")}` : ""}
+    ORDER BY ${identities}, e.endedAt DESC
+    LIMIT 1 BY ${identities}
+  )
+  SELECT ${[
+			...identityFields,
+			"startedAt",
+			"endedAt"
+		].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(", ")}
+  LIMIT ${parameters.add(plan.limit + 1)}`,
+		query_params: {
+			...parameters.values,
+			...predicate.params
+		}
+	};
+}
+function iso(value) {
+	return new Date(value.includes("T") ? value : `${value.replace(" ", "T")}Z`).toISOString();
+}
+async function querySpans(client, plan, timeoutMs) {
+	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,
+			memoryLimitBytes: 512 * 1024 * 1024
+		}, compiled);
+	};
+	const selected = (await run(compileClickHouseSpanQuery(plan))).map((row) => ({
+		...row,
+		startedAt: iso(row.startedAt),
+		endedAt: iso(row.endedAt)
+	}));
+	const page = selected.slice(0, plan.limit);
+	if (!page.length) return {
+		spans: [],
+		page: { next: null }
+	};
+	const payloadWhere = `tuple(${identitySetColumns}, endedAt) IN {page:Array(Tuple(UInt8, String, UInt8, String, String, String, DateTime64(3, 'UTC')))}`;
+	const payloads = await run({
+		query: `SELECT ${identities}, ${displayFields.map((field, index) => `data.${index + 1} AS ${field}`).join(", ")},
+      data.${displayFields.length + 1} AS inputPreview, data.${displayFields.length + 2} AS outputPreview
+    FROM (SELECT ${identities}, any(tuple(${displayFields.map(fieldExpression).join(", ")}, substringUTF8(input, 1, ${_mastra_core_storage.SPAN_QUERY_MAX_PREVIEW_CHARACTERS + 1}), substringUTF8(output, 1, ${_mastra_core_storage.SPAN_QUERY_MAX_PREVIEW_CHARACTERS + 1}))) AS data
+      FROM ${TABLE_SPAN_EVENTS} e WHERE ${payloadWhere} GROUP BY ${identities})`,
+		query_params: { page: page.map((row) => new _clickhouse_client.TupleParam([...identityValues(row), row.endedAt.replace("T", " ").replace(/Z$/, "")])) }
+	});
+	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 hydrated = page.flatMap((identity) => {
+		const row = byIdentity.get(_mastra_core_storage.spanQueryIdentityKey(identity));
+		if (!row) return [];
+		const { inputPreview: _input, outputPreview: _output, ...metadata } = row;
+		return [{
+			...metadata,
+			...identity,
+			durationMs: Number(row.durationMs)
+		}];
+	});
+	const result = _mastra_core_storage.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,
+		resourceId: last.resourceId,
+		traceId: last.traceId,
+		spanId: last.spanId,
+		sortValue: last[plan.orderBy.field]
+	}) : null;
+	return result;
+}
+//#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",
+	environment: "r.environment",
+	status: TRACE_STATUS_SQL,
+	serviceName: "r.serviceName",
+	executionSource: "r.executionSource",
+	threadId: "r.threadId",
+	resourceId: "r.resourceId",
+	userId: "r.userId",
+	sessionId: "r.sessionId",
+	organizationId: "r.organizationId",
+	experimentId: "r.experimentId"
+};
+const PERCENTILES = {
+	"duration.p50": .5,
+	"duration.p90": .9,
+	"duration.p95": .95,
+	"duration.p99": .99
+};
+const COMPARISON_SQL = {
+	eq: "=",
+	ne: "!=",
+	lt: "<",
+	lte: "<=",
+	gt: ">",
+	gte: ">="
+};
+/**
+* Compiles a trusted aggregate plan. The plan's caps are enforced by the planner and trusted here.
+*
+* Every candidate root is first reduced to a `facts` row (dimension values, duration, error flag,
+* countDistinct inputs, bucket). Without `interval`, groups are filtered, ordered, and limited in
+* one grouped select. With `interval`, one `GROUPING SETS` pass computes both the whole-window
+* group rows and the per-bucket rows: group rows are ranked (having → orderBy), and each bucket
+* row inherits its group's rank. ClickHouse re-executes a CTE at every reference, so this keeps
+* the candidate scan to a single pass instead of joining bucket rows back to a ranked CTE.
+*/
+function compileClickHouseTraceAggregate(plan) {
+	const parameters = new ParameterBuilder();
+	const ctes = compileClickHouseTraceCandidates(plan, "*", parameters);
+	const dimensionSql = (field) => {
+		if (field.startsWith("metadata.")) return traceMetadataValueSql(parameters.add(field.slice(9), "String"));
+		const sql = Object.hasOwn(DIMENSION_SQL, field) ? DIMENSION_SQL[field] : void 0;
+		if (sql === void 0) throw new Error(`Unsupported trusted trace-aggregate field: ${field}`);
+		return sql;
+	};
+	const distinctSql = (field) => field === "traceId" ? "r.traceId" : dimensionSql(field);
+	const dimensionColumns = plan.dimensions.map((_, index) => `d${index}`);
+	const distinctColumns = /* @__PURE__ */ new Map();
+	const factColumns = plan.dimensions.map((dimension, index) => `CAST(${dimensionSql(dimension)} AS Nullable(String)) AS d${index}`);
+	for (const measure of plan.measures) {
+		if (measure.type !== "countDistinct" || distinctColumns.has(measure.field)) continue;
+		const column = `cd${distinctColumns.size}`;
+		distinctColumns.set(measure.field, column);
+		factColumns.push(`CAST(${distinctSql(measure.field)} AS Nullable(String)) AS ${column}`);
+	}
+	factColumns.push(`toFloat64(${durationMsSql("r.startedAt", "r.endedAt")}) AS durationMs`, `isNotNull(r.error) AS isError`, `cityHash64(r.traceId) AS traceSeed`);
+	if (plan.interval !== void 0) {
+		const intervalMs = _mastra_core_storage.TRACE_AGGREGATE_INTERVAL_MS[plan.interval];
+		if (intervalMs === void 0) throw new Error(`Unsupported trusted trace-aggregate interval: ${plan.interval}`);
+		factColumns.push(`fromUnixTimestamp64Milli(intDiv(toUnixTimestamp64Milli(r.startedAt), ${intervalMs}) * ${intervalMs}, 'UTC') AS bucket`);
+	}
+	ctes.push(`facts AS (
+    SELECT ${factColumns.join(",\n      ")}
+    FROM candidates r
+  )`);
+	const measureSql = (name) => {
+		if (name === "count") return "toFloat64(count())";
+		if (name === "errorCount") return "toFloat64(countIf(isError))";
+		if (name === "errorRate") return "countIf(isError) / count()";
+		if (name === "duration.avg") return "avg(durationMs)";
+		if (name === "duration.min") return "min(durationMs)";
+		if (name === "duration.max") return "max(durationMs)";
+		const percentile = PERCENTILES[name];
+		if (percentile !== void 0) return `quantileDeterministic(${percentile})(durationMs, traceSeed)`;
+		const measure = plan.measures.find((candidate) => candidate.type === "countDistinct" && candidate.name === name);
+		const distinctColumn = measure && distinctColumns.get(measure.field);
+		if (distinctColumn === void 0) throw new Error(`Unsupported trusted trace-aggregate measure: ${name}`);
+		return `toFloat64(uniqExact(${distinctColumn}))`;
+	};
+	const compileHaving = (predicate) => {
+		if (predicate.type === "boolean") return predicate.args.map((arg) => `(${compileHaving(arg)})`).join(predicate.operator === "and" ? " AND " : " OR ");
+		if (predicate.type === "not") return `NOT (${compileHaving(predicate.arg)})`;
+		const measure = measureSql(predicate.measure);
+		if (predicate.type === "membership") {
+			if (predicate.values.length === 0) return predicate.operator === "in" ? "0" : "1";
+			const list = predicate.values.map((value) => parameters.add(value, "Float64")).join(", ");
+			return `${measure} ${predicate.operator === "in" ? "IN" : "NOT IN"} (${list})`;
+		}
+		const operator = COMPARISON_SQL[predicate.operator];
+		if (operator === void 0) throw new Error(`Unsupported trusted trace-aggregate operator: ${predicate.operator}`);
+		return `${measure} ${operator} ${parameters.add(predicate.value, "Float64")}`;
+	};
+	const havingSql = ["count() > 0", ...plan.having ? [`(${compileHaving(plan.having)})`] : []].join(" AND ");
+	const direction = plan.orderBy.direction === "asc" ? "ASC" : "DESC";
+	let orderTarget;
+	if (plan.orderBy.target === "measure") orderTarget = measureSql(plan.orderBy.measure);
+	else {
+		const index = plan.dimensions.indexOf(plan.orderBy.dimension);
+		if (index === -1) throw new Error(`Unsupported trusted trace-aggregate order dimension: ${plan.orderBy.dimension}`);
+		orderTarget = dimensionColumns[index];
+	}
+	const tiebreakSql = dimensionColumns.map((column) => `${column} ASC NULLS LAST`);
+	const measureColumns = plan.measures.map((measure, index) => `${measureSql(measure.name)} AS m${index}`);
+	const measureNames = plan.measures.map((_, index) => `m${index}`);
+	if (plan.interval === void 0) {
+		const limit = parameters.add(plan.limit + 1, "UInt64");
+		return {
+			query: `WITH ${ctes.join(",\n")}
+SELECT ${[...dimensionColumns, ...measureColumns].join(", ")}
+FROM facts
+${dimensionColumns.length > 0 ? `GROUP BY ${dimensionColumns.join(", ")}\n` : ""}HAVING ${havingSql}
+ORDER BY ${[`${orderTarget} ${direction} NULLS LAST`, ...tiebreakSql].join(", ")}
+LIMIT ${limit}`,
+			query_params: parameters.params
+		};
+	}
+	const maxRank = parameters.add(plan.limit, "UInt64");
+	const groupOrderSql = [`__order ${direction} NULLS LAST`, ...tiebreakSql].join(", ");
+	const groupPartition = dimensionColumns.length > 0 ? `PARTITION BY ${dimensionColumns.join(", ")}` : "";
+	ctes.push(`grouped AS (
+    SELECT ${[
+		...dimensionColumns,
+		"bucket",
+		"grouping(bucket) = 1 AS __isGroup",
+		...measureColumns,
+		`(${havingSql}) AS __keep`,
+		`${orderTarget} AS __order`
+	].join(", ")}
+    FROM facts
+    GROUP BY GROUPING SETS ((${[...dimensionColumns, "bucket"].join(", ")}), (${dimensionColumns.join(", ")}))
+  )`, `ranked AS (
+    SELECT *,
+      if(__isGroup AND __keep, row_number() OVER (PARTITION BY __isGroup, __keep ORDER BY ${groupOrderSql}), 0) AS __groupRank,
+      countIf(__isGroup AND __keep) OVER () AS __survivingGroups
+    FROM grouped
+  )`, `expanded AS (
+    SELECT *, maxIf(__groupRank, __isGroup) OVER (${groupPartition}) AS __rank
+    FROM ranked
+  )`);
+	return {
+		query: `WITH ${ctes.join(",\n")}
+SELECT ${[
+			...dimensionColumns,
+			"bucket",
+			...measureNames,
+			`toUInt8(__survivingGroups > ${maxRank}) AS truncated`
+		].join(", ")}
+FROM expanded
+WHERE NOT __isGroup AND __rank BETWEEN 1 AND ${maxRank}
+ORDER BY __rank ASC, bucket ASC`,
+		query_params: parameters.params
+	};
+}
+async function aggregateTraces(client, plan, timeoutMs) {
+	const result = await runWithClickHouseTraceQueryTimeout(client, { timeoutMs }, compileClickHouseTraceAggregate(plan));
+	let truncated;
+	let resultRows;
+	if (plan.interval === void 0) {
+		truncated = result.length > plan.limit;
+		resultRows = result.slice(0, plan.limit);
+	} else {
+		truncated = Number(result[0]?.truncated ?? 0) === 1;
+		resultRows = result;
+	}
+	return {
+		rows: resultRows.map((row) => {
+			const shaped = { measures: Object.fromEntries(plan.measures.map((measure, index) => [measure.name, Number(row[`m${index}`])])) };
+			if (plan.dimensions.length > 0) shaped.dimensions = Object.fromEntries(plan.dimensions.map((dimension, index) => [dimension, row[`d${index}`] ?? null]));
+			if (plan.interval !== void 0) shaped.bucket = new Date(row.bucket).toISOString();
+			return shaped;
+		}),
+		truncated
+	};
+}
 //#endregion
 //#region src/storage/domains/observability/v-next/trace-roots.ts
 /**
@@ -8245,6 +8629,7 @@ function buildBranchCursor(row) {
 }
 //#endregion
 //#region src/storage/domains/observability/v-next/index.ts
+const spanQueryFeatures = typeof _mastra_core_storage.planSpanQuery === "function" ? ["span-query"] : [];
 function buildSignalMigrationRequiredMessage(args) {
 	const tableList = args.tables.map((table) => `  - ${table.table} (${table.engine})`).join("\n");
 	return `
@@ -8676,12 +9061,14 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"tag-discovery",
 			"metric-discovery",
 			"trace-query",
+			...spanQueryFeatures,
 			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
 			"trace-query-tenant-scope",
 			"feedback",
-			"trace-query-context-ids"
+			"trace-query-context-ids",
+			"trace-aggregate"
 		];
 		return [
 			"metrics",
@@ -8694,12 +9081,14 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"metric-discovery",
 			"delta-polling",
 			"trace-query",
+			...spanQueryFeatures,
 			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
 			"trace-query-tenant-scope",
 			"feedback",
-			"trace-query-context-ids"
+			"trace-query-context-ids",
+			"trace-aggregate"
 		];
 	}
 	async createSpan(args) {
@@ -8814,6 +9203,18 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			}, error);
 		}
 	}
+	async querySpans(plan) {
+		try {
+			return await querySpans(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.TraceQueryCursorError || error instanceof _mastra_core_storage.TraceQueryResourceLimitError) throw error;
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("CLICKHOUSE", "QUERY_SPANS", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY
+			}, error);
+		}
+	}
 	async queryTraces(plan) {
 		try {
 			return await queryTraces(this.#client, plan, this.#traceQueryTimeoutMs, this.#deltaCursorStrategy);
@@ -8826,6 +9227,18 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			}, error);
 		}
 	}
+	async aggregateTraces(plan) {
+		try {
+			return await aggregateTraces(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;
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("CLICKHOUSE", "AGGREGATE_TRACES", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY
+			}, error);
+		}
+	}
 	async getTraceQueryObservedFields(plan) {
 		try {
 			return await getTraceQueryObservedFields(this.#client, plan, this.#traceQueryDiscoveryLimits);