@mastra/clickhouse 1.23.0-alpha.0 → 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.23.0-alpha.0"
+  version: "1.23.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/index.cjs

@@ -7443,6 +7443,201 @@ 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. */
@@ -8434,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 `
@@ -8865,6 +9061,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"tag-discovery",
 			"metric-discovery",
 			"trace-query",
+			...spanQueryFeatures,
 			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
@@ -8884,6 +9081,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"metric-discovery",
 			"delta-polling",
 			"trace-query",
+			...spanQueryFeatures,
 			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
@@ -9005,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);