@mastra/clickhouse 1.26.0-alpha.5 → 1.27.0-alpha.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-clickhouse
 description: Documentation for @mastra/clickhouse. Use when working with @mastra/clickhouse APIs, configuration, or implementation.
 metadata:
   package: "@mastra/clickhouse"
-  version: "1.26.0-alpha.5"
+  version: "1.27.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/index.cjs

@@ -16,7 +16,7 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
@@ -1610,6 +1610,7 @@ var MemoryStorageClickhouse = class extends _mastra_core_storage.MemoryStorage {
 					metadataIndex++;
 				}
 			}
+			const idScope = filter?.resourceId ? `WHERE id IN (SELECT id FROM ${_mastra_core_storage.TABLE_THREADS} WHERE resourceId = {resourceId:String})` : "";
 			const latestThreads = `
         latest_threads AS (
           SELECT
@@ -1620,7 +1621,7 @@ var MemoryStorageClickhouse = class extends _mastra_core_storage.MemoryStorage {
             toDateTime64(createdAt, 3) as createdAt,
             toDateTime64(updatedAt, 3) as updatedAt
           FROM ${_mastra_core_storage.TABLE_THREADS}
-          ${filter?.resourceId ? `WHERE id IN (SELECT id FROM ${_mastra_core_storage.TABLE_THREADS} WHERE resourceId = {resourceId:String})` : ""}
+          ${idScope}
           ORDER BY updatedAt DESC
           LIMIT 1 BY id
         )`;
@@ -2441,9 +2442,7 @@ var ObservabilityStorageClickhouse = class extends _mastra_core_storage.Observab
 					case _mastra_core_storage.TraceStatus.RUNNING:
 						conditions.push(`endedAt IS NULL AND (error IS NULL OR error = '')`);
 						break;
-					case _mastra_core_storage.TraceStatus.SUCCESS:
-						conditions.push(`endedAt IS NOT NULL AND (error IS NULL OR error = '')`);
-						break;
+					case _mastra_core_storage.TraceStatus.SUCCESS: conditions.push(`endedAt IS NOT NULL AND (error IS NULL OR error = '')`);
 				}
 				if (filters.hasChildError !== void 0) {
 					const finalClause = (TABLE_ENGINES[_mastra_core_storage.TABLE_SPANS] ?? "MergeTree()").startsWith("ReplacingMergeTree") ? "FINAL" : "";
@@ -3672,6 +3671,9 @@ const ALL_MIGRATIONS = [
 	addColumn(TABLE_SPAN_EVENTS, "inputPreview", "Nullable(String)"),
 	addColumn(TABLE_SPAN_EVENTS, "outputPreview", "Nullable(String)"),
 	addColumn(TABLE_SPAN_EVENTS, "errorPreview", "Nullable(String)"),
+	addColumn(TABLE_TRACE_BRANCHES, "entityVersionId", "Nullable(String)"),
+	addColumn(TABLE_TRACE_BRANCHES, "parentEntityVersionId", "Nullable(String)"),
+	addColumn(TABLE_TRACE_BRANCHES, "rootEntityVersionId", "Nullable(String)"),
 	addColumn(TABLE_SPAN_EVENTS, "entityVersionId", "Nullable(String)"),
 	addColumn(TABLE_SPAN_EVENTS, "parentEntityVersionId", "Nullable(String)"),
 	addColumn(TABLE_SPAN_EVENTS, "rootEntityVersionId", "Nullable(String)"),
@@ -5284,7 +5286,8 @@ async function getFeedbackAggregate(client, args) {
 	const aggSql = getAggregationSql$2(args.aggregation);
 	const identity = buildFeedbackIdentityFilter(args);
 	const combined = mergeFilters$2(identity, buildFeedbackFilterConditions(args.filters));
-	const result = await queryJson$2(client, `SELECT ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} FINAL ${toWhereClause$2(combined)}`, combined.params);
+	const whereClause = toWhereClause$2(combined);
+	const result = await queryJson$2(client, `SELECT ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} FINAL ${whereClause}`, combined.params);
 	const value = result[0]?.value == null ? null : Number(result[0]?.value);
 	if (args.comparePeriod && args.filters?.timestamp) {
 		const ts = args.filters.timestamp;
@@ -5318,7 +5321,8 @@ async function getFeedbackAggregate(client, args) {
 					endExclusive: ts.endExclusive
 				}
 			}));
-			const prevResult = await queryJson$2(client, `SELECT ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} FINAL ${toWhereClause$2(prevCombined)}`, prevCombined.params);
+			const prevWhereClause = toWhereClause$2(prevCombined);
+			const prevResult = await queryJson$2(client, `SELECT ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} FINAL ${prevWhereClause}`, prevCombined.params);
 			const previousValue = prevResult[0]?.value == null ? null : Number(prevResult[0]?.value);
 			let changePercent = null;
 			if (previousValue !== null && previousValue !== 0 && value !== null) changePercent = (value - previousValue) / Math.abs(previousValue) * 100;
@@ -6225,8 +6229,10 @@ function buildLegacySpanSelectExprs(legacyColumnTypes) {
 	const promotedIn = PROMOTED_METADATA_KEYS.map((k) => `'${k}'`).join(", ");
 	const metadataSearchExpr = has("metadata") ? `CAST(arrayFilter(x -> x.1 NOT IN (${promotedIn}) AND trim(BOTH ' ' FROM x.2) != '', arrayMap(x -> (x.1, trim(BOTH ' ' FROM x.2)), JSONExtractKeysAndValues(COALESCE("metadata", '{}'), 'String'))), 'Map(String, String)')` : `CAST(map(), 'Map(String, String)')`;
 	let tagsExpr = "[]";
-	if (has("tags")) if (legacyColumnTypes.get("tags").includes("Array")) tagsExpr = `arrayFilter(x -> x != '', arrayDistinct(arrayMap(x -> trim(BOTH ' ' FROM x), "tags")))`;
-	else tagsExpr = `arrayFilter(x -> x != '', arrayDistinct(arrayMap(x -> trim(BOTH ' ' FROM x), JSONExtract(COALESCE("tags", '[]'), 'Array(String)'))))`;
+	if (has("tags")) {
+		if (legacyColumnTypes.get("tags").includes("Array")) tagsExpr = `arrayFilter(x -> x != '', arrayDistinct(arrayMap(x -> trim(BOTH ' ' FROM x), "tags")))`;
+		else tagsExpr = `arrayFilter(x -> x != '', arrayDistinct(arrayMap(x -> trim(BOTH ' ' FROM x), JSONExtract(COALESCE("tags", '[]'), 'Array(String)'))))`;
+	}
 	const exprs = {
 		dedupeKey: `concat("traceId", ':', "spanId")`,
 		traceId: `"traceId"`,
@@ -6473,10 +6479,11 @@ function toWhereClause(filter) {
 	return filter.conditions.length ? `WHERE ${filter.conditions.join(" AND ")}` : "";
 }
 function currentScoresRelation(sourcePredicate) {
+	const whereClause = sourcePredicate ? `WHERE ${sourcePredicate}` : "";
 	return `(
     SELECT *
     FROM ${TABLE_SCORE_EVENTS_CURRENT} FINAL
-    ${sourcePredicate ? `WHERE ${sourcePredicate}` : ""}
+    ${whereClause}
   )`;
 }
 /**
@@ -8008,8 +8015,7 @@ async function queryThreads(client, plan, timeoutMs) {
 	});
 }
 /** Compile a direct span-query filter using its dedicated field mapping. */
-function compileSpanQueryPredicate(predicate) {
-	const parameters = new ParameterBuilder();
+function compileSpanQueryPredicate(predicate, parameters = new ParameterBuilder()) {
 	return {
 		sql: compileScalarPredicate(predicate, SPAN_QUERY_FIELDS, parameters),
 		params: parameters.params
@@ -8170,6 +8176,131 @@ function compileClickHouseSpanQuery(plan) {
 		}
 	};
 }
+const branchSpanTypes = new Set(BRANCH_SPAN_TYPE_VALUES);
+const sameColumn = (field) => [field];
+/**
+* Span fields `trace_branches` can serve, as the `trace_branches` columns each one reads. The two
+* tables are expected to diverge, so this list is explicit: a selection whose fields are not all
+* listed reads `span_events`. A new span-query field has to be classified here deliberately, and a
+* missing column then costs speed, not correctness.
+*/
+const TRACE_BRANCHES_SPAN_FIELD_COLUMNS = {
+	...Object.fromEntries([
+		"organizationId",
+		"resourceId",
+		"traceId",
+		"spanId",
+		"parentSpanId",
+		"name",
+		"spanType",
+		"startedAt",
+		"endedAt",
+		"timeToFirstChunkMs",
+		"threadId",
+		"runId",
+		"sessionId",
+		"userId",
+		"requestId",
+		"serviceName",
+		"experimentId",
+		"environment",
+		"executionSource",
+		"entityType",
+		"entityId",
+		"entityName",
+		"entityVersionId",
+		"parentEntityType",
+		"parentEntityId",
+		"parentEntityName",
+		"parentEntityVersionId",
+		"rootEntityType",
+		"rootEntityId",
+		"rootEntityName",
+		"rootEntityVersionId"
+	].map((field) => [field, sameColumn(field)])),
+	status: ["error"],
+	error: ["error"],
+	durationMs: ["startedAt", "endedAt"]
+};
+/**
+* Whether a span selection reads `trace_branches`: `where` must restrict `spanType` to branch
+* types, and `trace_branches` must serve every selected field (`served`, for tests).
+*/
+function readsTraceBranches(where, fields, served = TRACE_BRANCHES_SPAN_FIELD_COLUMNS) {
+	return positiveSpanConjuncts(where).some(({ field, values }) => field === "spanType" && values.length > 0 && values.every((value) => branchSpanTypes.has(String(value)))) && [...fields].every((field) => Object.hasOwn(served, field));
+}
+/**
+* Top-level `spanType` / `name` equality or `in` conditions. Every span the predicate can match
+* satisfies them, and copies of a span never differ in either field, so they can be applied
+* before collapsing copies.
+*/
+function positiveSpanConjuncts(where) {
+	return (where?.type === "boolean" && where.operator === "and" ? where.args : where ? [where] : []).flatMap((conjunct) => {
+		if (conjunct.type !== "comparison" && conjunct.type !== "membership") return [];
+		if (conjunct.field !== "spanType" && conjunct.field !== "name") return [];
+		if (conjunct.type === "comparison" && conjunct.operator === "eq") return [{
+			field: conjunct.field,
+			values: [conjunct.value]
+		}];
+		if (conjunct.type === "membership" && conjunct.operator === "in") return [{
+			field: conjunct.field,
+			values: conjunct.values
+		}];
+		return [];
+	});
+}
+/**
+* The spans `querySpans()` selects, as CTEs ending in `selected` (alias each row as you like):
+* one row per current completed span with `startedAt` in the window, matching `where`, carrying
+* the identity, `startedAt`, `endedAt`, `status`, and `fields`.
+*
+* Copies of a span collapse to the copy with the latest `endedAt`. When `where` requires branch
+* span types (agent and workflow runs, tool calls, …) and `trace_branches` serves every selected
+* field, the spans are read from `trace_branches`, whose sort key starts with `spanType`, instead of
+* every span in the window. That path can differ from `querySpans()` in two ways:
+* - `trace_branches` is filled only by its materialized view, with no backfill, so an install that
+*   upgraded from @mastra/clickhouse 1.4–1.6 has no branch rows for spans written before then.
+* - It is a `ReplacingMergeTree` without a version column, so once a background merge collapses a
+*   retried span's copies it keeps the last-inserted copy, not the one with the latest `endedAt`.
+*   Counts are unaffected; `status` and duration of an out-of-order retry can differ.
+*
+* Like `querySpans()`, the read has no upper bound on `endedAt` (`PREWHERE endedAt >= from` only,
+* since a span that starts in the window can end any time later), so a historical window reads
+* every span that ended since `from`.
+*/
+function compileClickHouseSpanSelection(plan, fields, parameters) {
+	const from = parameters.add(plan.timeRange.from, "DateTime64(3, 'UTC')");
+	const to = parameters.add(plan.timeRange.to, "DateTime64(3, 'UTC')");
+	const prefilter = positiveSpanConjuncts(plan.where).map(({ field, values }) => values.length ? `\n      AND e.${field} IN (${values.map((value) => parameters.add(String(value), "String")).join(", ")})` : "\n      AND 0").join("");
+	const predicate = plan.where ? compileSpanQueryPredicate(plan.where, parameters).sql : "1";
+	let tenant = "";
+	if (plan.scope) {
+		tenant += `\n      AND e.organizationId = ${parameters.add(plan.scope.organizationId, "String")}`;
+		if (plan.scope.resourceId !== void 0) tenant += `\n      AND e.resourceId = ${parameters.add(plan.scope.resourceId, "String")}`;
+	}
+	const selectionFields = [.../* @__PURE__ */ new Set([
+		"startedAt",
+		"endedAt",
+		"status",
+		...fields,
+		...predicateFields$1(plan.where)
+	])].filter((field) => !new Set(identityFields).has(field));
+	const branches = readsTraceBranches(plan.where, selectionFields);
+	const scan = `FROM ${branches ? TABLE_TRACE_BRANCHES : TABLE_SPAN_EVENTS} e
+    PREWHERE e.endedAt >= ${from}
+    WHERE e.startedAt >= ${from} AND e.startedAt < ${to}${tenant}${prefilter}`;
+	return [`span_candidates AS (
+    ${branches ? `SELECT ${identityFields.map((field) => `e.${field} AS ${field}`).join(", ")}, ${selectionFields.map((field) => field === "endedAt" ? "max(e.endedAt) AS endedAt" : `argMax(tuple(${fieldExpression(field)}), e.endedAt).1 AS ${field}`).join(", ")}
+    ${scan}
+    GROUP BY ${identityFields.map((field) => `e.${field}`).join(", ")}` : `SELECT ${identities}, ${selectionFields.map((field) => `${fieldExpression(field)} AS ${field}`).join(", ")}
+    ${scan}
+    ORDER BY ${identities}, e.endedAt DESC
+    LIMIT 1 BY ${identities}`}
+  )`, `selected AS (
+    SELECT * FROM span_candidates s
+    WHERE s.startedAt >= ${from} AND s.startedAt < ${to} AND (${predicate})
+  )`];
+}
 const LEGACY_PAYLOAD_BATCH_ROWS = 32;
 function iso$1(value) {
 	return new Date(value.includes("T") ? value : `${value.replace(" ", "T")}Z`).toISOString();
@@ -8181,7 +8312,7 @@ async function querySpans(client, plan, timeoutMs) {
 		if (remaining <= 0) throw new _mastra_core_storage.TraceQueryExecutionError();
 		return await runWithClickHouseTraceQueryTimeout(client, {
 			timeoutMs: remaining,
-			memoryLimitBytes: 512 * 1024 * 1024
+			memoryLimitBytes: 536870912
 		}, compiled);
 	};
 	const selected = (await run(compileClickHouseSpanQuery(plan))).map((row) => ({
@@ -8298,14 +8429,14 @@ function afterCursor(plan, parameters) {
 	return `(${terms.join(" OR ")})`;
 }
 const THREAD_QUERY_EXECUTION_LIMITS = {
-	memoryLimitBytes: 512 * 1024 * 1024,
+	memoryLimitBytes: 536870912,
 	maxThreads: 2,
 	maxBlockSize: 4096,
-	spillThresholdBytes: 32 * 1024 * 1024
+	spillThresholdBytes: 33554432
 };
 const MAX_CANDIDATE_THREADS = 16384;
 const MAX_CANDIDATE_TRACES = 1e5;
-const MAX_CANDIDATE_ID_BYTES = 4 * 1024 * 1024;
+const MAX_CANDIDATE_ID_BYTES = 4194304;
 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;
@@ -8415,7 +8546,7 @@ function* batches(rows, maxRows = 256) {
 	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)) {
+		if (batch.length && (batch.length >= maxRows || bytes + size > 49152)) {
 			yield batch;
 			batch = [];
 			bytes = 0;
@@ -8573,6 +8704,28 @@ const DIMENSION_SQL = {
 	organizationId: "r.organizationId",
 	experimentId: "r.experimentId"
 };
+/** Span column expressions (alias `r`, a `selected` span row) for each groupable span dimension. */
+const SPAN_DIMENSION_SQL = Object.fromEntries([
+	"name",
+	"spanType",
+	"entityType",
+	"entityId",
+	"entityName",
+	"parentEntityType",
+	"parentEntityName",
+	"rootEntityType",
+	"rootEntityName",
+	"environment",
+	"status",
+	"serviceName",
+	"executionSource",
+	"threadId",
+	"resourceId",
+	"userId",
+	"sessionId",
+	"organizationId",
+	"experimentId"
+].map((field) => [field, `r.${field}`]));
 const PERCENTILES = {
 	"duration.p50": .5,
 	"duration.p90": .9,
@@ -8599,13 +8752,41 @@ const COMPARISON_SQL = {
 */
 function compileClickHouseTraceAggregate(plan) {
 	const parameters = new ParameterBuilder();
-	const ctes = compileClickHouseTraceCandidates(plan, "*", parameters, { oneRootPerTrace: true });
-	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;
-	};
+	return compileClickHouseAggregate(plan, parameters, {
+		ctes: compileClickHouseTraceCandidates(plan, "*", parameters, { oneRootPerTrace: true }),
+		from: "candidates",
+		dimensionSql: (field) => {
+			if (field.startsWith("metadata.")) return traceMetadataValueSql(parameters.add(field.slice(9), "String"));
+			return lookupDimensionSql(DIMENSION_SQL, field);
+		},
+		isErrorSql: "isNotNull(r.error)",
+		usageKey: ["traceId"],
+		usageBound: "traceId IN (SELECT traceId FROM candidates)"
+	});
+}
+/**
+* Compiles a trusted span aggregate plan over the spans `querySpans()` selects. Usage is
+* attributed by `(traceId, spanId)`, so only the span that recorded a metric row carries it.
+*/
+function compileClickHouseSpanAggregate(plan) {
+	const parameters = new ParameterBuilder();
+	return compileClickHouseAggregate(plan, parameters, {
+		ctes: compileClickHouseSpanSelection(plan, [...plan.dimensions, ...plan.measures.flatMap((measure) => measure.type === "countDistinct" && measure.field !== "traceId" ? [measure.field] : [])], parameters),
+		from: "selected",
+		dimensionSql: (field) => lookupDimensionSql(SPAN_DIMENSION_SQL, field),
+		isErrorSql: "r.status = 'error'",
+		usageKey: ["traceId", "spanId"],
+		usageBound: "isNotNull(spanId)"
+	});
+}
+function lookupDimensionSql(columns, field) {
+	const sql = Object.hasOwn(columns, field) ? columns[field] : void 0;
+	if (sql === void 0) throw new Error(`Unsupported trusted aggregate field: ${field}`);
+	return sql;
+}
+function compileClickHouseAggregate(plan, parameters, source) {
+	const { ctes } = source;
+	const dimensionSql = source.dimensionSql;
 	const distinctSql = (field) => field === "traceId" ? "r.traceId" : dimensionSql(field);
 	const dimensionColumns = plan.dimensions.map((_, index) => `d${index}`);
 	const distinctColumns = /* @__PURE__ */ new Map();
@@ -8616,7 +8797,7 @@ function compileClickHouseTraceAggregate(plan) {
 		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`);
+	factColumns.push(`toFloat64(${durationMsSql("r.startedAt", "r.endedAt")}) AS durationMs`, `${source.isErrorSql} AS isError`, `cityHash64(${source.usageKey.map((column) => `r.${column}`).join(", ")}) 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}`);
@@ -8626,14 +8807,14 @@ function compileClickHouseTraceAggregate(plan) {
 	const hasCost = measureKinds.has("cost");
 	let usageJoin = "";
 	if (hasCost || measureKinds.has("tokens")) {
-		ctes.push(compileUsageCte(plan, parameters));
-		usageJoin = "\n    LEFT JOIN usage u ON u.traceId = r.traceId";
+		ctes.push(compileUsageCte(plan, parameters, source));
+		usageJoin = `\n    LEFT JOIN usage u ON ${source.usageKey.map((column) => `u.${column} = r.${column}`).join(" AND ")}`;
 		USAGE_METRIC_NAMES.forEach((_, index) => factColumns.push(`if(u.hasUsage = 1, u.t${index}, NULL) AS t${index}`));
 		factColumns.push(`u.hasUsage = 1 AS usageBearing`, `if(u.hasUsage = 1 AND u.priced = 1, u.cost, NULL) AS traceCost`, `u.hasUsage = 1 AND u.priced = 1 AND u.pricingFailure = 0 AS covered`, `if(u.hasUsage = 1 AND u.priced = 1, u.unitMin, NULL) AS unitMin`, `if(u.hasUsage = 1 AND u.priced = 1, u.unitMax, NULL) AS unitMax`);
 	}
 	ctes.push(`facts AS (
     SELECT ${factColumns.join(",\n      ")}
-    FROM candidates r${usageJoin}
+    FROM ${source.from} r${usageJoin}
   )`);
 	const mixedUnitsSql = "minOrNull(unitMin) != maxOrNull(unitMax)";
 	const measureSql = (name) => {
@@ -8748,26 +8929,28 @@ function usageMetricIndex(name) {
 	return index;
 }
 /**
-* Builds `usage`: one row per candidate trace that has at least one token metric row, holding
-* per-name token sums (`t<i>`, indexed by `TRACE_AGGREGATE_USAGE_METRIC_NAMES`) and the trace's
-* pricing state. Metric rows are matched by traceId, usage metric name, tenant scope, and
-* `timestamp >= from` only: a trace that starts in the window can emit metrics after `to`, and
-* the candidates semi-join already bounds the scan.
+* Builds `usage`: one row per usage key (a trace, or a span) that has at least one token metric
+* row, holding per-name token sums (`t<i>`, indexed by `TRACE_AGGREGATE_USAGE_METRIC_NAMES`) and
+* its pricing state. Metric rows are matched by the source's usage bound, usage metric name,
+* tenant scope, and `timestamp >= from` only: a trace or span that starts in the window can emit
+* metrics after `to`. For spans that makes the read cost grow with the age of `from` (see
+* `usageBound`).
 *
 * Rows are deduplicated with `LIMIT 1 BY metricId` at query time. `ReplacingMergeTree` only
 * collapses rows with equal sort keys `(name, timestamp, metricId)`, so retried copies with
 * different timestamps never merge, and copies with equal keys stay separate until a background
 * merge runs.
 */
-function compileUsageCte(plan, parameters) {
+function compileUsageCte(plan, parameters, source) {
+	const key = source.usageKey.join(", ");
 	const names = USAGE_METRIC_NAMES.map((name) => parameters.add(name, "String"));
 	const costRow = `name IN (${_mastra_core_storage.TRACE_AGGREGATE_COST_METRIC_NAMES.map((name) => names[usageMetricIndex(name)]).join(", ")})`;
 	const from = parameters.add(plan.timeRange.from, "DateTime64(3, 'UTC')");
 	const tenant = compileTenantScope(plan.scope, parameters);
-	const priced = `${costRow} AND isNotNull(estimatedCost) AND isNotNull(costUnit) AND NOT hasError`;
+	const priced = `${costRow} AND isNotNull(estimatedCost) AND isNotNull(costUnit) AND (NOT hasError OR partialCost)`;
 	const failed = `${costRow} AND (hasError OR (isNotNull(estimatedCost) AND isNull(costUnit)))`;
 	return `usage AS (
-    SELECT traceId,
+    SELECT ${key},
       toUInt8(1) AS hasUsage,
       ${names.map((name, index) => `sumIf(value, name = ${name}) AS t${index}`).join(",\n      ")},
       sumIf(assumeNotNull(estimatedCost), ${priced}) AS cost,
@@ -8776,34 +8959,42 @@ function compileUsageCte(plan, parameters) {
       minIf(assumeNotNull(costUnit), ${priced}) AS unitMin,
       maxIf(assumeNotNull(costUnit), ${priced}) AS unitMax
     FROM (
-      SELECT traceId,
+      SELECT ${key},
         latest.1 AS name,
         latest.2 AS value,
         latest.3 AS estimatedCost,
         latest.4 AS costUnit,
-        latest.5 AS hasError
+        latest.5 AS hasError,
+        latest.6 AS partialCost
       FROM (
-        SELECT traceId,
-          argMax(tuple(name, value, estimatedCost, costUnit, hasError), timestamp) AS latest
+        SELECT ${key},
+          argMax(tuple(name, value, estimatedCost, costUnit, hasError, partialCost), timestamp) AS latest
         FROM (
-          SELECT traceId, metricId, timestamp, name, value, estimatedCost, costUnit,
-            if(${costRow}, ifNull(JSONHas(costMetadata, 'error') AND JSONType(costMetadata, 'error') != 'Null', 0), 0) AS hasError
+          SELECT ${key}, metricId, timestamp, name, value, estimatedCost, costUnit,
+            if(${costRow}, ifNull(JSONHas(costMetadata, 'error') AND JSONType(costMetadata, 'error') != 'Null', 0), 0) AS hasError,
+            if(${costRow}, ifNull(JSONExtractString(costMetadata, 'error') = 'partial_cost', 0), 0) AS partialCost
           FROM ${TABLE_METRIC_EVENTS}
-          WHERE traceId IN (SELECT traceId FROM candidates)
+          WHERE ${source.usageBound}
             AND name IN (${names.join(", ")})
             AND timestamp >= ${from}${tenant}
         )
-        GROUP BY traceId, metricId
+        GROUP BY ${key}, metricId
       )
     )
-    GROUP BY traceId
+    GROUP BY ${key}
   )`;
 }
 function nullableNumber(value) {
 	return value === null || value === void 0 ? null : Number(value);
 }
-async function aggregateTraces(client, plan, timeoutMs) {
-	const result = await runWithClickHouseTraceQueryTimeout(client, { timeoutMs }, compileClickHouseTraceAggregate(plan));
+function aggregateTraces(client, plan, timeoutMs) {
+	return runAggregate(client, plan, compileClickHouseTraceAggregate(plan), timeoutMs);
+}
+async function aggregateSpans(client, plan, timeoutMs) {
+	return await runAggregate(client, plan, compileClickHouseSpanAggregate(plan), timeoutMs);
+}
+async function runAggregate(client, plan, compiled, timeoutMs) {
+	const result = await runWithClickHouseTraceQueryTimeout(client, { timeoutMs }, compiled);
 	let truncated;
 	let resultRows;
 	if (plan.interval === void 0) {
@@ -9699,6 +9890,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 spanAggregateFeatures = typeof _mastra_core_storage.planSpanAggregate === "function" ? ["span-aggregate"] : [];
 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");
@@ -9985,7 +10177,7 @@ async function detectExistingDeltaCursorStrategy(client) {
 	}
 }
 const TRACE_QUERY_DISCOVERY_DEFAULT_TIMEOUT_MS = 5e3;
-const TRACE_QUERY_DISCOVERY_DEFAULT_MEMORY_LIMIT_BYTES = 256 * 1024 * 1024;
+const TRACE_QUERY_DISCOVERY_DEFAULT_MEMORY_LIMIT_BYTES = 268435456;
 function resolveTraceQueryDiscoveryMemoryLimitBytes(memoryLimitBytes = TRACE_QUERY_DISCOVERY_DEFAULT_MEMORY_LIMIT_BYTES) {
 	if (!Number.isSafeInteger(memoryLimitBytes) || memoryLimitBytes <= 0) throw new RangeError("traceQuery.discovery.memoryLimitBytes must be a positive safe integer");
 	return memoryLimitBytes;
@@ -10142,6 +10334,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"trace-query-root-entity-id",
 			"trace-aggregate",
 			...spanQueryFeatures,
+			...spanAggregateFeatures,
 			...threadQueryFeatures
 		];
 		return [
@@ -10166,6 +10359,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"trace-query-root-entity-id",
 			"trace-aggregate",
 			...spanQueryFeatures,
+			...spanAggregateFeatures,
 			...threadQueryFeatures
 		];
 	}
@@ -10317,6 +10511,18 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			}, error);
 		}
 	}
+	async aggregateSpans(plan) {
+		try {
+			return await aggregateSpans(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_SPANS", "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);
@@ -11378,10 +11584,12 @@ var WorkflowsStorageClickhouse = class extends _mastra_core_storage.WorkflowsSto
 				conditions.push(`JSONExtractString(snapshot, 'status') = {var_status:String}`);
 				values.var_status = status;
 			}
-			if (resourceId) if (await this.#db.hasColumn(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "resourceId")) {
-				conditions.push(`resourceId = {var_resourceId:String}`);
-				values.var_resourceId = resourceId;
-			} else this.logger.warn(`[${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT}] resourceId column not found. Skipping resourceId filter.`);
+			if (resourceId) {
+				if (await this.#db.hasColumn(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT, "resourceId")) {
+					conditions.push(`resourceId = {var_resourceId:String}`);
+					values.var_resourceId = resourceId;
+				} else this.logger.warn(`[${_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT}] resourceId column not found. Skipping resourceId filter.`);
+			}
 			if (fromDate) {
 				conditions.push(`createdAt >= {var_from_date:DateTime64(3)}`);
 				values.var_from_date = fromDate.getTime() / 1e3;