@mastra/clickhouse 1.26.0 → 1.27.0-alpha.1

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region \0rolldown/runtime.js
+// \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -20,7 +20,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
-//#endregion
 let _clickhouse_client = require("@clickhouse/client");
 let _mastra_core_error = require("@mastra/core/error");
 let _mastra_core_storage = require("@mastra/core/storage");
@@ -31,7 +30,7 @@ let _mastra_core_utils = require("@mastra/core/utils");
 let _mastra_core_features = require("@mastra/core/features");
 let zod_v4 = require("zod/v4");
 let _mastra_core_evals = require("@mastra/core/evals");
-//#region src/storage/db/replication.ts
+// src/storage/db/replication.ts
 const DEFAULT_ZOOKEEPER_PATH = "/clickhouse/tables/{shard}/{database}/{table}";
 const DEFAULT_REPLICA_NAME = "{replica}";
 const SUPPORTED_ENGINE_NAMES = /* @__PURE__ */ new Set([
@@ -231,8 +230,7 @@ function rewriteEngineClauses(sql, replication) {
 function applyReplicationToDDL(sql, replication) {
 	return addOnClusterToDDL(replication ? rewriteEngineClauses(sql, replication) : sql, replication);
 }
-//#endregion
-//#region src/storage/db/utils.ts
+// src/storage/db/utils.ts
 const TABLE_ENGINES = {
 	[_mastra_core_storage.TABLE_MESSAGES]: `MergeTree()`,
 	[_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT]: `ReplacingMergeTree()`,
@@ -341,8 +339,7 @@ function transformRow(row) {
 function transformRows(rows) {
 	return rows.map((row) => transformRow(row));
 }
-//#endregion
-//#region src/storage/db/index.ts
+// src/storage/db/index.ts
 /**
 * Resolves ClickhouseDomainConfig to a ClickHouse client and ttl config.
 * Handles creating a new client if config is provided.
@@ -868,8 +865,7 @@ var ClickhouseDB = class extends _mastra_core_base.MastraBase {
 		}
 	}
 };
-//#endregion
-//#region src/storage/domains/memory/index.ts
+// src/storage/domains/memory/index.ts
 /**
 * Serialize metadata object to JSON string for storage in ClickHouse.
 * Ensures we always store valid JSON, defaulting to '{}' for null/undefined.
@@ -2012,8 +2008,7 @@ var MemoryStorageClickhouse = class extends _mastra_core_storage.MemoryStorage {
 		}
 	}
 };
-//#endregion
-//#region src/storage/domains/observability/index.ts
+// src/storage/domains/observability/index.ts
 var ObservabilityStorageClickhouse = class extends _mastra_core_storage.ObservabilityStorage {
 	client;
 	#db;
@@ -2618,8 +2613,7 @@ var ObservabilityStorageClickhouse = class extends _mastra_core_storage.Observab
 		}
 	}
 };
-//#endregion
-//#region src/storage/domains/observability/v-next/ddl.ts
+// src/storage/domains/observability/v-next/ddl.ts
 const TABLE_SPAN_EVENTS = "mastra_span_events";
 const TABLE_TRACE_ROOTS = "mastra_trace_roots";
 const TABLE_TRACE_BRANCHES = "mastra_trace_branches";
@@ -3671,6 +3665,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)"),
@@ -3819,8 +3816,7 @@ function parseTtlExpression(expr) {
 		days
 	};
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/preview-compat.ts
+// src/storage/domains/observability/v-next/preview-compat.ts
 const generator = _mastra_core_storage.buildStoredPreview;
 const canGeneratePreviews = typeof generator === "function";
 function needsPreview(value) {
@@ -3873,8 +3869,7 @@ function buildSpanQueryResponse(...args) {
 	}
 	return response;
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/previews.ts
+// src/storage/domains/observability/v-next/previews.ts
 /**
 * Stored span previews (`inputPreview` / `outputPreview` / `errorPreview`).
 *
@@ -3909,8 +3904,7 @@ function resolveStoredPreviews(row, payloads = row) {
 	}
 	return previews;
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/review-status.ts
+// src/storage/domains/observability/v-next/review-status.ts
 const FEEDBACK_REVIEW_STATUSES = ["needs-review", "reviewed"];
 function isFeedbackReviewStatus(value) {
 	return FEEDBACK_REVIEW_STATUSES.some((status) => status === value);
@@ -3934,8 +3928,7 @@ function parseUpdateFeedbackReviewStatusArgs(args) {
 		reviewStatus: args.reviewStatus
 	};
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/helpers.ts
+// src/storage/domains/observability/v-next/helpers.ts
 const CH_SETTINGS = {
 	date_time_input_format: "best_effort",
 	date_time_output_format: "iso",
@@ -4505,8 +4498,7 @@ function feedbackRecordToRow(feedback) {
 		scope: jsonEncode(feedback.scope)
 	};
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/deletion-requests.ts
+// src/storage/domains/observability/v-next/deletion-requests.ts
 const EPOCH = "1970-01-01T00:00:00.000Z";
 async function recordDeletionRequest(client, args) {
 	const row = {
@@ -4563,8 +4555,7 @@ async function insertDeletionRequest(client, row, replication) {
 		} : CH_INSERT_SETTINGS
 	});
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/discovery.ts
+// src/storage/domains/observability/v-next/discovery.ts
 async function queryJson$3(client, query, params = {}) {
 	return await (await client.query({
 		query,
@@ -4604,8 +4595,7 @@ async function getTags(client, args) {
 	}
 	return { tags: (await queryJson$3(client, `SELECT DISTINCT value FROM ${TABLE_DISCOVERY_VALUES} WHERE ${conditions.join(" AND ")} ORDER BY value`, params)).map((r) => r.value) };
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/filters.ts
+// src/storage/domains/observability/v-next/filters.ts
 /**
 * ClickHouse v-next filter builders.
 *
@@ -4877,8 +4867,7 @@ function buildPaginationClause(pagination) {
 		offset: page * perPage
 	};
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/polling.ts
+// src/storage/domains/observability/v-next/polling.ts
 const OBSERVABILITY_DELTA_POLLING_FEATURE = "observability-delta-polling";
 function deltaPollingFeatureEnabled() {
 	return _mastra_core_features.coreFeatures.has(OBSERVABILITY_DELTA_POLLING_FEATURE);
@@ -4909,8 +4898,7 @@ function appendWhere(whereClause, ...conditions) {
 	const parts = [whereClause.replace(/^\s*WHERE\s+/i, ""), ...conditions].filter(Boolean);
 	return parts.length > 0 ? `WHERE ${parts.join(" AND ")}` : "";
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/feedback.ts
+// src/storage/domains/observability/v-next/feedback.ts
 const FEEDBACK_TYPED_COLUMNS = /* @__PURE__ */ new Set([
 	"timestamp",
 	"traceId",
@@ -5412,8 +5400,7 @@ async function getFeedbackPercentiles(client, args) {
 		}))
 	})) };
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/logs.ts
+// src/storage/domains/observability/v-next/logs.ts
 async function batchCreateLogs(client, args) {
 	if (args.logs.length === 0) return;
 	await client.insert({
@@ -5552,8 +5539,7 @@ async function getStreamHeadCursor$4(client) {
 function buildLogsCursor(row) {
 	return row.cursorId ?? "0";
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/metrics.ts
+// src/storage/domains/observability/v-next/metrics.ts
 /** Map typed columns to their ClickHouse column names. */
 const METRIC_TYPED_COLUMNS = /* @__PURE__ */ new Set([
 	"timestamp",
@@ -6050,8 +6036,7 @@ async function getMetricLabelValues(client, args) {
 	if (args.limit) params.valLimit = args.limit;
 	return { values: (await queryJson$1(client, `SELECT DISTINCT value FROM ${TABLE_DISCOVERY_PAIRS} WHERE ${conditions.join(" AND ")} ORDER BY value ${limitClause}`, params)).map((r) => r.value) };
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/migration.ts
+// src/storage/domains/observability/v-next/migration.ts
 const SIGNAL_MIGRATIONS = [
 	{
 		table: TABLE_METRIC_EVENTS,
@@ -6367,8 +6352,7 @@ async function migrateSignalTables(client, logger) {
 		}
 	}
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/score-current.ts
+// src/storage/domains/observability/v-next/score-current.ts
 const SCORE_CURRENT_BACKFILL_MARKER = "v1";
 async function backfillCurrentScores(client) {
 	const markerRows = await (await client.query({
@@ -6397,8 +6381,7 @@ async function backfillCurrentScores(client) {
 		query_params: { marker: SCORE_CURRENT_BACKFILL_MARKER }
 	});
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/scores.ts
+// src/storage/domains/observability/v-next/scores.ts
 const SCORE_TYPED_COLUMNS = /* @__PURE__ */ new Set([
 	"timestamp",
 	"traceId",
@@ -6865,8 +6848,7 @@ async function getScorePercentiles(client, args) {
 		}))
 	})) };
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/trace-query.ts
+// 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.
@@ -8012,8 +7994,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
@@ -8029,8 +8010,7 @@ function compileThreadQueryPredicate(predicate, parameters = new ParameterBuilde
 		params: parameters.params
 	};
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/span-query.ts
+// src/storage/domains/observability/v-next/span-query.ts
 const identityFields = [
 	"organizationId",
 	"resourceId",
@@ -8174,6 +8154,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();
@@ -8262,8 +8367,7 @@ async function querySpans(client, plan, timeoutMs) {
 	}) : null;
 	return result;
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/thread-query.ts
+// src/storage/domains/observability/v-next/thread-query.ts
 const contextFields = [
 	"resourceId",
 	"userId",
@@ -8557,8 +8661,7 @@ async function queryThreadRows(client, plan, timeoutMs, strategy = "auto") {
 		}) : null }
 	};
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/trace-aggregate.ts
+// 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",
@@ -8577,6 +8680,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,
@@ -8603,13 +8728,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();
@@ -8620,7 +8773,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}`);
@@ -8630,14 +8783,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) => {
@@ -8752,26 +8905,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,
@@ -8780,34 +8935,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) {
@@ -8831,8 +8994,7 @@ async function aggregateTraces(client, plan, timeoutMs) {
 		truncated
 	};
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/trace-roots.ts
+// src/storage/domains/observability/v-next/trace-roots.ts
 /**
 * Get the root span for a trace, reading from trace_roots as compatibility path.
 * Uses ordinary LIMIT 1 (duplicates are byte-identical per design).
@@ -9109,8 +9271,7 @@ async function getStreamHeadCursor$1(client) {
 function buildTraceCursor(row) {
 	return row.cursorId ?? "0";
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/tracing.ts
+// src/storage/domains/observability/v-next/tracing.ts
 const BRANCH_SPAN_TYPE_SQL_LIST = _mastra_core_storage.BRANCH_SPAN_TYPES.map((t) => `'${t}'`).join(", ");
 /** Insert a single completed span. */
 async function createSpan(client, args) {
@@ -9700,9 +9861,9 @@ async function getStreamHeadCursor(client) {
 function buildBranchCursor(row) {
 	return row.cursorId ?? "0";
 }
-//#endregion
-//#region src/storage/domains/observability/v-next/index.ts
+// 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");
@@ -10146,6 +10307,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"trace-query-root-entity-id",
 			"trace-aggregate",
 			...spanQueryFeatures,
+			...spanAggregateFeatures,
 			...threadQueryFeatures
 		];
 		return [
@@ -10170,6 +10332,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"trace-query-root-entity-id",
 			"trace-aggregate",
 			...spanQueryFeatures,
+			...spanAggregateFeatures,
 			...threadQueryFeatures
 		];
 	}
@@ -10321,6 +10484,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);
@@ -10824,8 +10999,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 		}
 	}
 };
-//#endregion
-//#region src/storage/domains/scores/index.ts
+// src/storage/domains/scores/index.ts
 /**
 * Builds a multi-tenant scope SQL fragment and its named query params.
 * Returns a clause prefixed with ` AND ` (empty when no filters) plus params.
@@ -11246,8 +11420,7 @@ var ScoresStorageClickhouse = class extends _mastra_core_storage.ScoresStorage {
 		}
 	}
 };
-//#endregion
-//#region src/storage/domains/workflows/index.ts
+// src/storage/domains/workflows/index.ts
 var WorkflowsStorageClickhouse = class extends _mastra_core_storage.WorkflowsStorage {
 	client;
 	#db;
@@ -11514,8 +11687,7 @@ var WorkflowsStorageClickhouse = class extends _mastra_core_storage.WorkflowsSto
 		}
 	}
 };
-//#endregion
-//#region src/storage/index.ts
+// src/storage/index.ts
 /**
 * Type guard for pre-configured client config
 */
@@ -11678,7 +11850,6 @@ var ClickhouseStoreVNext = class extends ClickhouseStore {
 		};
 	}
 };
-//#endregion
 exports.COLUMN_TYPES = COLUMN_TYPES;
 exports.ClickhouseStore = ClickhouseStore;
 exports.ClickhouseStoreVNext = ClickhouseStoreVNext;