@mastra/clickhouse 1.20.0-alpha.3 → 1.20.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.20.0-alpha.3"
+  version: "1.20.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/index.cjs

@@ -30,6 +30,7 @@ let _mastra_core_base = require("@mastra/core/base");
 let crypto$1 = require("crypto");
 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
 const DEFAULT_ZOOKEEPER_PATH = "/clickhouse/tables/{shard}/{database}/{table}";
@@ -6872,7 +6873,18 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters)
   )`);
 	return ctes;
 }
-function compileClickHouseTraceQuery(plan) {
+const deltaWatermarkSchema = zod_v4.z.object({
+	cursorId: zod_v4.z.string().regex(/^\d+$/).refine((value) => BigInt(value) <= 18446744073709551615n),
+	traceId: zod_v4.z.string()
+}).strict();
+function parseDeltaWatermark(value) {
+	try {
+		return deltaWatermarkSchema.parse(JSON.parse(value));
+	} catch {
+		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);
 	const predicate = plan.where ? compilePredicate(plan.where, parameters) : "1";
@@ -6892,6 +6904,28 @@ ORDER BY threadId ASC
 LIMIT ${parameters.add(plan.limit + 1, "UInt64")}`,
 		query_params: parameters.params
 	};
+	if (plan.paginationMode === "delta") {
+		const watermark = _mastra_core_storage.getTraceQueryDeltaWatermark(plan, "clickhouse");
+		const after = watermark ? parseDeltaWatermark(watermark) : {
+			cursorId: "0",
+			traceId: ""
+		};
+		return {
+			query: `${candidates}, delta_candidates AS (
+  SELECT traceId, max(cursorId) AS latestCursorId
+  FROM ${TABLE_TRACE_ROOTS_DELTA}
+  WHERE tuple(cursorId, traceId) > ${`tuple(${parameters.add(after.cursorId, "UInt64")}, ${parameters.add(after.traceId, "String")})`} ${deltaHead ? `AND tuple(cursorId, traceId) <= tuple(${parameters.add(deltaHead.cursorId, "UInt64")}, ${parameters.add(deltaHead.traceId, "String")})` : ""}
+  GROUP BY traceId
+)
+SELECT c.*, toString(d.latestCursorId) AS __delta_cursor
+FROM candidates c
+INNER JOIN delta_candidates d ON c.traceId = d.traceId
+ORDER BY d.latestCursorId ASC, c.traceId ASC
+LIMIT ${parameters.add(plan.limit + 1, "UInt64")}`,
+			query_params: parameters.params,
+			sharedSnapshot: true
+		};
+	}
 	const orderField = resolveOrderField(plan.orderBy.field);
 	const direction = plan.orderBy.direction === "asc" ? "ASC" : "DESC";
 	if (plan.paginationMode === "page") return {
@@ -7111,9 +7145,39 @@ async function getTraceQueryValues(client, plan, limits) {
 		valuesTruncated: rows.length > plan.limit
 	});
 }
-async function queryTraces(client, plan, timeoutMs) {
+async function queryTraces(client, plan, timeoutMs, strategy = null) {
+	const deadline = performance.now() + _mastra_core_storage.resolveTraceQueryTimeoutMs(timeoutMs);
+	const remaining = () => {
+		const value = Math.floor(deadline - performance.now());
+		if (value <= 0) throw new _mastra_core_storage.TraceQueryExecutionError();
+		return value;
+	};
+	let deltaHead;
+	if (plan.paginationMode === "delta") {
+		assertDeltaPollingSupported(strategy);
+		const watermark = _mastra_core_storage.getTraceQueryDeltaWatermark(plan, "clickhouse");
+		if (watermark) parseDeltaWatermark(watermark);
+	}
+	if (plan.paginationMode === "delta" || plan.paginationMode === "page" && deltaPollingSupported(strategy) && typeof _mastra_core_storage.encodeTraceQueryDeltaCursor === "function") {
+		const head = await runWithClickHouseTraceQueryTimeout(client, { timeoutMs: remaining() }, {
+			query: `SELECT toString(cursorId) AS cursorId, traceId FROM ${TABLE_TRACE_ROOTS_DELTA} ORDER BY cursorId DESC, traceId DESC LIMIT 1`,
+			query_params: {}
+		});
+		deltaHead = head[0] ? parseDeltaWatermark(JSON.stringify(head[0])) : {
+			cursorId: "0",
+			traceId: ""
+		};
+		if (plan.paginationMode === "delta" && !plan.deltaCursor) return _mastra_core_storage.traceQueryResponseSchema.parse({
+			traces: [],
+			delta: {
+				limit: plan.limit,
+				hasMore: false
+			},
+			deltaCursor: _mastra_core_storage.encodeTraceQueryDeltaCursor(plan, "clickhouse", JSON.stringify(deltaHead))
+		});
+	}
 	if (plan.paginationMode === "page") {
-		const rows = await runWithClickHouseTraceQueryTimeout(client, { timeoutMs }, compileClickHouseTraceQuery(plan));
+		const rows = await runWithClickHouseTraceQueryTimeout(client, { timeoutMs: deltaHead ? remaining() : timeoutMs }, compileClickHouseTraceQuery(plan, deltaHead));
 		const total = Number(rows.at(-1)?.total ?? 0);
 		const traces = rows.filter((row) => Number(row.__metadata) === 0).map((row) => ({
 			traceId: String(row.traceId),
@@ -7135,6 +7199,7 @@ async function queryTraces(client, plan, timeoutMs) {
 		}));
 		return _mastra_core_storage.traceQueryResponseSchema.parse({
 			traces,
+			...deltaHead ? { deltaCursor: _mastra_core_storage.encodeTraceQueryDeltaCursor(plan, "clickhouse", JSON.stringify(deltaHead)) } : {},
 			pagination: {
 				total,
 				page: plan.page,
@@ -7143,7 +7208,7 @@ async function queryTraces(client, plan, timeoutMs) {
 			}
 		});
 	}
-	const rows = await runWithClickHouseTraceQueryTimeout(client, { timeoutMs }, compileClickHouseTraceQuery(plan));
+	const rows = await runWithClickHouseTraceQueryTimeout(client, { timeoutMs: deltaHead ? remaining() : timeoutMs }, compileClickHouseTraceQuery(plan, deltaHead));
 	const visibleRows = rows.slice(0, plan.limit);
 	if (plan.result === "groups") {
 		const groups = visibleRows.map((row) => ({ threadId: String(row.threadId) }));
@@ -7175,6 +7240,23 @@ async function queryTraces(client, plan, timeoutMs) {
 		status: row.status
 	}));
 	const last = traces.at(-1);
+	if (plan.paginationMode === "delta") {
+		const lastRow = visibleRows.at(-1);
+		let watermark = lastRow ? {
+			cursorId: String(lastRow.__delta_cursor),
+			traceId: String(lastRow.traceId)
+		} : deltaHead;
+		const previous = parseDeltaWatermark(_mastra_core_storage.getTraceQueryDeltaWatermark(plan, "clickhouse"));
+		if (BigInt(previous.cursorId) > BigInt(watermark.cursorId) || previous.cursorId === watermark.cursorId && previous.traceId > watermark.traceId) watermark = previous;
+		return _mastra_core_storage.traceQueryResponseSchema.parse({
+			traces,
+			delta: {
+				limit: plan.limit,
+				hasMore: rows.length > plan.limit
+			},
+			deltaCursor: _mastra_core_storage.encodeTraceQueryDeltaCursor(plan, "clickhouse", JSON.stringify(watermark))
+		});
+	}
 	return _mastra_core_storage.traceQueryResponseSchema.parse({
 		traces,
 		page: { next: rows.length > plan.limit && last ? _mastra_core_storage.encodeTraceQueryCursor(plan, {
@@ -8533,9 +8615,9 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 	}
 	async queryTraces(plan) {
 		try {
-			return await queryTraces(this.#client, plan, this.#traceQueryTimeoutMs);
+			return await queryTraces(this.#client, plan, this.#traceQueryTimeoutMs, this.#deltaCursorStrategy);
 		} catch (error) {
-			if (error instanceof _mastra_core_error.MastraError || error instanceof _mastra_core_storage.TraceQueryExecutionError || error instanceof _mastra_core_storage.TraceQueryResourceLimitError) throw 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_TRACES", "FAILED"),
 				domain: _mastra_core_error.ErrorDomain.STORAGE,