@mastra/clickhouse 1.21.0-alpha.0 → 1.21.0-alpha.2

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.21.0-alpha.0"
+  version: "1.21.0-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.21.0-alpha.0",
+  "version": "1.21.0-alpha.2",
   "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

@@ -6516,6 +6516,9 @@ async function getScorePercentiles(client, args) {
 //#endregion
 //#region src/storage/domains/observability/v-next/trace-query.ts
 const TRACE_STATUS_SQL = `if(isNotNull(r.error), 'error', 'success')`;
+function durationMsSql(startedAt, endedAt) {
+	return `dateDiff('millisecond', ${startedAt}, ${endedAt})`;
+}
 const TRACE_FIELDS = {
 	traceId: {
 		sql: "r.traceId",
@@ -6537,6 +6540,10 @@ const TRACE_FIELDS = {
 		sql: "r.endedAt",
 		parameterType: "DateTime64(3, 'UTC')"
 	},
+	durationMs: {
+		sql: durationMsSql("r.startedAt", "r.endedAt"),
+		parameterType: "Float64"
+	},
 	entityName: {
 		sql: "r.entityName",
 		parameterType: "String"
@@ -6552,6 +6559,10 @@ const TRACE_FIELDS = {
 	status: {
 		sql: TRACE_STATUS_SQL,
 		parameterType: "String"
+	},
+	tags: {
+		sql: "r.tags",
+		parameterType: "String"
 	}
 };
 const SPAN_FIELDS = {
@@ -6741,6 +6752,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 +6781,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"
@@ -6851,7 +6868,7 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters,
       if(JSONType(attributes, 'provider') = 'String', JSONExtractString(attributes, 'provider'), NULL) AS provider,
       startedAt,
       endedAt,
-      dateDiff('millisecond', startedAt, endedAt) AS durationMs,
+      ${durationMsSql("startedAt", "endedAt")} AS durationMs,
       if(isNotNull(error), 'error', 'success') AS status,
       error,
       entityType,
@@ -7106,7 +7123,8 @@ function compileClickHouseTraceQueryValues(plan) {
 	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 {
@@ -8555,6 +8573,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"metrics",
 			"logs",
 			"trace-query",
+			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
 			"trace-query-tenant-scope"
@@ -8564,6 +8583,7 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			"logs",
 			"delta-polling",
 			"trace-query",
+			"trace-query-root-duration",
 			"trace-query-discovery",
 			"thread-query",
 			"trace-query-tenant-scope"