@mastra/clickhouse 1.20.1 → 1.21.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.20.1"
+  version: "1.21.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/integrations-databases-clickhouse.md

@@ -89,7 +89,7 @@ export const mastra = new Mastra({
 
 Trace deletion cascades to spans, trace roots and branches, metrics, logs, scores, and feedback linked by trace ID. Signals without a trace ID are preserved. Mastra records the deletion predicate, then waits for ClickHouse lightweight delete masks to be applied. Normal reads no longer return the rows matched by that operation when the call resolves.
 
-Lightweight deletion is a hide-only operation that marks rows with ClickHouse's `_row_exists` mask. Physical removal depends on merges and deployment-configured retention TTLs. `ObservabilityStorageClickhouseVNext` applies retention only when you provide a `RetentionConfig`; Mastra OSS doesn't configure a default retention TTL.
+Lightweight deletion is a hide-only operation that marks rows with ClickHouse's `_row_exists` mask. Physical removal depends on merges and deployment-configured retention TTLs. `ObservabilityStorageClickhouseVNext` applies retention only when you pass the `retention` option. Mastra doesn't configure a default retention TTL.
 
 When all five observability signals have finite retention, Mastra also applies a TTL to deletion requests so they outlive the signal rows they protect. If any signal is unbounded, deletion requests remain unbounded. See [storage retention](https://mastra.ai/reference/storage/retention) for how the deletion-request TTL is calculated.
 
@@ -275,7 +275,7 @@ Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `Shar
 
 ### Observability domain options
 
-`ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`).
+`ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`). `ObservabilityStorageClickhouseVNext` also accepts `retention`, the per-signal TTL in days described in [ClickHouse native TTL](https://mastra.ai/reference/storage/retention), and `traceQuery`, the execution limits for [advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query).
 
 ## Hosting options
 

package/dist/docs/references/reference-storage-retention.md

@@ -15,7 +15,7 @@ Storage adapters use the shared core retention contract for `prune()`, or a data
 | Adapter              | Mechanism               | Retention support                                                                                                                                                                      |
 | -------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | libSQL               | `prune()`               | All supported growth domains                                                                                                                                                           |
-| PostgreSQL           | `prune()`               | All supported growth domains. V-next observability drops expired partitions or chunks                                                                                                  |
+| PostgreSQL           | `prune()`               | All supported growth domains. vNext observability drops expired partitions or chunks                                                                                                   |
 | MongoDB              | `prune()` or native TTL | All supported growth domains. Native TTL indexes are also available                                                                                                                    |
 | DuckDB               | `prune()`               | Observability spans, metrics, logs, scores, and feedback                                                                                                                               |
 | MySQL                | `prune()`               | Observability spans                                                                                                                                                                    |
@@ -102,10 +102,10 @@ Each domain specifies its age-prunable tables and the timestamp column that anch
 | `memory`          | `resources`        | `createdAt`      | Resource age                                                     |
 | `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives              |
 | `observability`   | `spans`            | `startedAt`      | Span age                                                         |
-| `observability`   | `metrics`          | `timestamp`      | Metric event age (v-next only)                                   |
-| `observability`   | `logs`             | `timestamp`      | Log event age (v-next only)                                      |
-| `observability`   | `scores`           | `timestamp`      | Score event age (v-next only)                                    |
-| `observability`   | `feedback`         | `timestamp`      | Feedback event age (v-next only)                                 |
+| `observability`   | `metrics`          | `timestamp`      | Metric event age (vNext only)                                    |
+| `observability`   | `logs`             | `timestamp`      | Log event age (vNext only)                                       |
+| `observability`   | `scores`           | `timestamp`      | Score event age (vNext only)                                     |
+| `observability`   | `feedback`         | `timestamp`      | Feedback event age (vNext only)                                  |
 | `scores`          | `scorers`          | `createdAt`      | Score record age                                                 |
 | `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive          |
 | `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned |
@@ -122,7 +122,7 @@ Each domain specifies its age-prunable tables and the timestamp column that anch
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
 > - DuckDB observability stores append-only events for all five signals. Its `spans` policy uses the event `timestamp` column rather than `startedAt`.
 > - LibSQL and PostgreSQL support all domains above except `harness`, which PostgreSQL doesn't implement. MongoDB supports all except `threadState` and `harness`. DuckDB, MySQL, Microsoft SQL Server, Oracle Database, Amazon Aurora DSQL, and Google Cloud Spanner currently support retention only in their `observability` domains, with the signal coverage shown in the support matrix.
-> - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows: effective level of detail is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
+> - The vNext PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows: effective level of detail is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
 
 ## Methods
 
@@ -208,7 +208,9 @@ You can also cancel a long-running prune with an `AbortSignal`: the loop stops b
 
 ClickHouse observability storage uses native table TTLs instead of `prune()`. Configure retention as days per signal. `init()` applies the TTLs to new and existing tables and skips `ALTER TABLE` statements when the configured TTL is already present.
 
-For deployments that need to update TTL configuration without running the full initialization path, call `applyRetention()` on the v-next observability store:
+Omitted signals, and signals set to zero or less, get no TTL. When you remove a signal from `retention`, the next `init()` or `applyRetention()` removes that table's TTL. If Mastra can't read the current TTLs from `system.tables`, it applies the configured TTLs and leaves the others unchanged.
+
+For deployments that need to update TTL configuration without running the full initialization path, call `applyRetention()` on the vNext observability store:
 
 ```typescript
 import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'

package/dist/index.cjs

@@ -6552,6 +6552,10 @@ const TRACE_FIELDS = {
 	status: {
 		sql: TRACE_STATUS_SQL,
 		parameterType: "String"
+	},
+	tags: {
+		sql: "r.tags",
+		parameterType: "String"
 	}
 };
 const SPAN_FIELDS = {
@@ -6741,6 +6745,11 @@ function compileScalarPredicate(predicate, registry, parameters, allowMetadata =
 		};
 	})() : fieldDefinition(registry, predicate.field);
 	if (predicate.type === "presence") return `${predicate.operator === "exists" ? "isNotNull" : "isNull"}(${field.sql})`;
+	if (predicate.type === "collection") {
+		if (!("value" in predicate)) return `${predicate.operator}(${field.sql})`;
+		const member = parameters.add(predicate.value, field.parameterType);
+		return predicate.operator === "includes" ? `has(${field.sql}, ${member})` : `notEmpty(${field.sql}) AND NOT has(${field.sql}, ${member})`;
+	}
 	if (predicate.type === "membership") {
 		const values = predicate.values.map((value) => parameters.add(value, field.parameterType)).join(", ");
 		return `ifNull(${`${field.sql} ${predicate.operator === "in" ? "IN" : "NOT IN"} (${values})`}, ${predicate.operator === "in" ? "0" : "1"})`;
@@ -6765,6 +6774,7 @@ function compileFeedbackScalarPredicate(predicate, parameters) {
 		const present = `(isNotNull(s.valueString) OR isNotNull(s.valueNumber))`;
 		return predicate.operator === "exists" ? present : `NOT ${present}`;
 	}
+	if (predicate.type === "collection") throw new Error("Unsupported trusted trace-query field: value");
 	return compileScalarPredicate(predicate, typeof (predicate.type === "membership" ? predicate.values[0] : predicate.value) === "number" ? { value: {
 		sql: "s.valueNumber",
 		parameterType: "Float64"
@@ -6813,9 +6823,20 @@ function compileThreadPredicate(predicate, parameters) {
 	if (predicate.type === "boolean") return predicate.args.map((arg) => `(${compileThreadPredicate(arg, parameters)})`).join(predicate.operator === "and" ? " AND " : " OR ");
 	return `NOT (${compileThreadPredicate(predicate.arg, parameters)})`;
 }
-function compileClickHouseTraceScope(selection, relationCollections, parameters) {
+/**
+* Tenant conditions ANDed into every root and related-signal scan. Columns are
+* `Nullable(String)`, so rows without a tenant never match a scope.
+*/
+function compileTenantScope(scope, parameters) {
+	if (!scope) return "";
+	let sql = `\n      AND organizationId = ${parameters.add(scope.organizationId, "String")}`;
+	if (scope.resourceId !== void 0) sql += `\n      AND resourceId = ${parameters.add(scope.resourceId, "String")}`;
+	return sql;
+}
+function compileClickHouseTraceScope(selection, relationCollections, parameters, scope) {
 	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);
 	const ctes = [`current_roots AS (
     SELECT * FROM (
       SELECT *
@@ -6829,7 +6850,7 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters)
     SELECT *
     FROM current_roots
     WHERE startedAt >= ${from}
-      AND startedAt < ${to}
+      AND startedAt < ${to}${tenant}
   )`];
 	if (relationCollections.has("spans")) ctes.push(`current_spans AS (
     SELECT
@@ -6851,7 +6872,7 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters)
       rootEntityVersionId
     FROM ${TABLE_SPAN_EVENTS}
     WHERE isNotNull(traceId)
-      AND traceId IN (SELECT traceId FROM root_scope)
+      AND traceId IN (SELECT traceId FROM root_scope)${tenant}
     ORDER BY dedupeKey
     LIMIT 1 BY dedupeKey
   )`);
@@ -6869,7 +6890,7 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters)
       rootEntityVersionId
     FROM ${currentScoresRelation()} AS current
     WHERE isNotNull(current.traceId)
-      AND current.traceId IN (SELECT traceId FROM root_scope)
+      AND current.traceId IN (SELECT traceId FROM root_scope)${tenant}
   )`);
 	if (relationCollections.has("feedback")) ctes.push(`current_feedback AS (
     SELECT
@@ -6892,7 +6913,7 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters)
       LIMIT 1 BY feedbackId
     ) AS current
     WHERE isNotNull(traceId)
-      AND traceId IN (SELECT traceId FROM root_scope)
+      AND traceId IN (SELECT traceId FROM root_scope)${tenant}
   )`);
 	return ctes;
 }
@@ -6909,7 +6930,7 @@ function parseDeltaWatermark(value) {
 }
 function compileClickHouseTraceQuery(plan, deltaHead) {
 	const parameters = new ParameterBuilder();
-	const ctes = compileClickHouseTraceScope(plan, collectRelationCollections(plan.where), parameters);
+	const ctes = compileClickHouseTraceScope(plan, collectRelationCollections(plan.where), parameters, plan.scope);
 	const predicate = plan.where ? compilePredicate(plan.where, parameters) : "1";
 	ctes.push(`candidates AS (
     SELECT ${TRACE_SELECT}
@@ -7012,7 +7033,7 @@ function compileClickHouseThreadQuery(plan) {
 	const parameters = new ParameterBuilder();
 	const relationCollections = collectRelationCollections(plan.traces.where);
 	collectThreadRelationCollections(plan.where, relationCollections);
-	const ctes = compileClickHouseTraceScope(plan.traces, relationCollections, parameters);
+	const ctes = compileClickHouseTraceScope(plan.traces, relationCollections, parameters, plan.scope);
 	const eligibility = plan.traces.where ? compilePredicate(plan.traces.where, parameters) : "1";
 	ctes.push(`eligible_roots AS (
     SELECT *
@@ -7060,7 +7081,7 @@ function discoveryCollections(scope) {
 }
 function compileClickHouseTraceQueryObservedFields(plan) {
 	const parameters = new ParameterBuilder();
-	const ctes = compileClickHouseTraceScope(plan, /* @__PURE__ */ new Set(), parameters);
+	const ctes = compileClickHouseTraceScope(plan, /* @__PURE__ */ new Set(), parameters, plan.scope);
 	const search = plan.search ? `AND positionCaseInsensitiveUTF8(concat('metadata.', key), ${parameters.add(plan.search, "String")}) > 0` : "";
 	const limit = parameters.add(plan.limit + 1, "UInt64");
 	ctes.push(`metadata_entries AS (
@@ -7090,12 +7111,13 @@ LIMIT ${limit}`,
 }
 function compileClickHouseTraceQueryValues(plan) {
 	const parameters = new ParameterBuilder();
-	const ctes = compileClickHouseTraceScope(plan, discoveryCollections(plan.predicateScope), parameters);
+	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 field = fieldDefinition(discoveryRegistry(plan.predicateScope), plan.path).sql;
+	} 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");
 	return {
@@ -8545,7 +8567,8 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"logs",
 			"trace-query",
 			"trace-query-discovery",
-			"thread-query"
+			"thread-query",
+			"trace-query-tenant-scope"
 		];
 		return [
 			"metrics",
@@ -8553,7 +8576,8 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"delta-polling",
 			"trace-query",
 			"trace-query-discovery",
-			"thread-query"
+			"thread-query",
+			"trace-query-tenant-scope"
 		];
 	}
 	async createSpan(args) {