@mastra/clickhouse 1.7.0-alpha.0 → 1.7.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @mastra/clickhouse
 
+## 1.7.1-alpha.0
+
+### Patch Changes
+
+- Track `suspendedAt` and `suspendPayload` on background tasks. SQL adapters auto-migrate the new columns via `alterTable`. ([#16260](https://github.com/mastra-ai/mastra/pull/16260))
+
+- Updated dependencies [[`9f17410`](https://github.com/mastra-ai/mastra/commit/9f1741080def23d42ee50b39887a385ae316a3c6), [`c6eb39e`](https://github.com/mastra-ai/mastra/commit/c6eb39ea6dca381c6563cb240237fbe608e02f93), [`900d086`](https://github.com/mastra-ai/mastra/commit/900d086bb737b9cf2fcf68f11b0389b801a2738c), [`4c0e286`](https://github.com/mastra-ai/mastra/commit/4c0e28637c9cfb4f416549b55e97ebfa13319dfc), [`25184ff`](https://github.com/mastra-ai/mastra/commit/25184ffaf1293ec95119426eb1a1f8d38831b96c), [`aebde9c`](https://github.com/mastra-ai/mastra/commit/aebde9cfacf56592c6b6350cae721740fe090b8a)]:
+  - @mastra/core@1.33.0-alpha.4
+
+## 1.7.0
+
+### Minor Changes
+
+- Improved metric drilldown performance with skip indexes on the high-cardinality ID columns of `metric_events`. Dashboard queries that filter metrics by `traceId`, `threadId`, `resourceId`, `userId`, `organizationId`, `experimentId`, `runId`, `sessionId`, or `requestId` skip data chunks that don't contain the filtered value instead of scanning the full time range. ([#16138](https://github.com/mastra-ai/mastra/pull/16138))
+
+  Equality (`=`) and `IN` filters benefit automatically. Aggregations and `GROUP BY` queries without a filter on these columns are unaffected.
+
+  **Migration**
+
+  Existing deployments pick up the indexes on next start. The migration is metadata-only and instant — no table lock, no rewrite, no downtime. Insert overhead is negligible and index storage is well under 1% of table size. Existing data is indexed lazily as parts merge under normal retention; no operator action is required.
+
+- Added `count_distinct` aggregation and server-side TopK to the metrics storage API so dashboards built on high-cardinality fields (like `threadId` or `resourceId`) stay fast and bounded. ([#16137](https://github.com/mastra-ai/mastra/pull/16137))
+
+  **New aggregation**
+
+  `getMetricAggregate`, `getMetricBreakdown`, and `getMetricTimeSeries` accept `aggregation: 'count_distinct'` with a `distinctColumn`. Backends pick the most efficient native implementation — `uniq` on ClickHouse, `approx_count_distinct` on DuckDB.
+
+  `distinctColumn` is restricted to a low/medium-cardinality categorical allowlist (`entityType`, `entityName`, `parentEntityType`, `parentEntityName`, `rootEntityType`, `rootEntityName`, `name`, `provider`, `model`, `environment`, `executionSource`, `serviceName`). ID columns are not allowed — distinct counts over near-unique values converge to the row count and are rarely useful.
+
+  ```ts
+  await store.getMetricAggregate({
+    name: ['mastra_llm_tokens_total'],
+    aggregation: 'count_distinct',
+    distinctColumn: 'model',
+    filters: { timestamp: { start, end } },
+  });
+  ```
+
+  **Server-side TopK**
+
+  `getMetricBreakdown` accepts `limit` and `orderDirection`, so breakdowns never return the full cardinality of a column from the database. Ordering is always by the aggregated `value`; `orderDirection` flips between top-N (`DESC`, default) and bottom-N (`ASC`).
+
+  ```ts
+  await store.getMetricBreakdown({
+    name: ['mastra_agent_duration_ms'],
+    aggregation: 'sum',
+    groupBy: ['threadId'],
+    limit: 20,
+    orderDirection: 'DESC',
+  });
+  ```
+
+- - **Added** `listBranches` and `getSpans` implementations. ([#16154](https://github.com/mastra-ai/mastra/pull/16154))
+  - Only spans recorded after this version is deployed are queryable via `listBranches`; historical traces remain accessible through the existing `listTraces` / `getTrace` APIs.
+
+### Patch Changes
+
+- Added direct score lookup support to observability storage so score records can be fetched by `scoreId` without scanning paginated score lists, including DuckDB and ClickHouse vNext observability stores. ([#16162](https://github.com/mastra-ai/mastra/pull/16162))
+
+- Updated dependencies [[`6dcd65f`](https://github.com/mastra-ai/mastra/commit/6dcd65f2a34069e6dc43ba35f1d11119b9b40bef), [`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d), [`c05c9a1`](https://github.com/mastra-ai/mastra/commit/c05c9a13230988cef6d438a62f37760f31927bc7), [`ca28c23`](https://github.com/mastra-ai/mastra/commit/ca28c232a2f18801a6cf20fe053479237b4d4fb0), [`e24aacb`](https://github.com/mastra-ai/mastra/commit/e24aacba07bd66f5d95b636dc24016fca26b52cf), [`7679a63`](https://github.com/mastra-ai/mastra/commit/7679a634eae8e8ca459fd87538fdf72b4389b07f), [`7fce309`](https://github.com/mastra-ai/mastra/commit/7fce30912b14170bfc41f0ac736cca0f39fe0cd4), [`1d64a76`](https://github.com/mastra-ai/mastra/commit/1d64a765861a0772ea187bab76e5ed37bf82d042), [`1c2dda8`](https://github.com/mastra-ai/mastra/commit/1c2dda805fbfccc0abf55d4cb20cc34402dc3f0c), [`c721164`](https://github.com/mastra-ai/mastra/commit/c7211643f7ac861f83b19a3757cc921487fc9d75), [`1b55954`](https://github.com/mastra-ai/mastra/commit/1b559541c1e08a10e49d01ffc51a634dfc37a286), [`7997c2e`](https://github.com/mastra-ai/mastra/commit/7997c2e55ddd121562a4098cd8d2b89c68433bf1), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`7679a63`](https://github.com/mastra-ai/mastra/commit/7679a634eae8e8ca459fd87538fdf72b4389b07f), [`a0d9b6d`](https://github.com/mastra-ai/mastra/commit/a0d9b6d6b810aeaa9e177a0dcc99a4402e609634), [`e97ccb9`](https://github.com/mastra-ai/mastra/commit/e97ccb900f8b7a390ce82c9f8eb8d6eb2c5e3777), [`c5daf48`](https://github.com/mastra-ai/mastra/commit/c5daf48556e98c46ae06caf00f92c249912007e9), [`70017d7`](https://github.com/mastra-ai/mastra/commit/70017d72ab741b5d7040e2a15c251a317782e39e), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e), [`b0c7022`](https://github.com/mastra-ai/mastra/commit/b0c70224f80dad7c0cdbfb22cbff22e0f75c064f), [`e4942bc`](https://github.com/mastra-ai/mastra/commit/e4942bc7fdc903572f7d84f26d5e15f9d39c763d)]:
+  - @mastra/core@1.32.0
+
 ## 1.7.0-alpha.0
 
 ### Minor Changes

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.7.0-alpha.0"
+  version: "1.7.1-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/index.cjs

@@ -689,6 +689,12 @@ function serializeJson(v) {
   if (typeof v === "object" && v != null) return JSON.stringify(v);
   return v ?? "";
 }
+function readNullableDate(val) {
+  if (val == null || val === "") return void 0;
+  const d = new Date(val);
+  if (Number.isNaN(d.getTime()) || d.getTime() === 0) return void 0;
+  return d;
+}
 function rowToTask(row) {
   const parseJson2 = (val) => {
     if (val == null || val === "") return void 0;
@@ -713,12 +719,14 @@ function rowToTask(row) {
     runId: row.run_id ?? "",
     result: parseJson2(row.result),
     error: parseJson2(row.error),
+    suspendPayload: parseJson2(row.suspend_payload),
     retryCount: Number(row.retry_count ?? 0),
     maxRetries: Number(row.max_retries ?? 0),
     timeoutMs: Number(row.timeout_ms ?? 3e5),
     createdAt: new Date(row.createdAt),
-    startedAt: row.startedAt ? new Date(row.startedAt) : void 0,
-    completedAt: row.completedAt ? new Date(row.completedAt) : void 0
+    startedAt: readNullableDate(row.startedAt),
+    suspendedAt: readNullableDate(row.suspendedAt),
+    completedAt: readNullableDate(row.completedAt)
   };
 }
 var BackgroundTasksStorageClickhouse = class extends storage.BackgroundTasksStorage {
@@ -732,6 +740,11 @@ var BackgroundTasksStorageClickhouse = class extends storage.BackgroundTasksStor
   }
   async init() {
     await this.#db.createTable({ tableName: storage.TABLE_BACKGROUND_TASKS, schema: storage.TABLE_SCHEMAS[storage.TABLE_BACKGROUND_TASKS] });
+    await this.#db.alterTable({
+      tableName: storage.TABLE_BACKGROUND_TASKS,
+      schema: storage.TABLE_SCHEMAS[storage.TABLE_BACKGROUND_TASKS],
+      ifNotExists: ["suspend_payload", "suspendedAt"]
+    });
   }
   async dangerouslyClearAll() {
     await this.#db.clearTable({ tableName: storage.TABLE_BACKGROUND_TASKS });
@@ -752,11 +765,13 @@ var BackgroundTasksStorageClickhouse = class extends storage.BackgroundTasksStor
           args: serializeJson(task.args),
           result: serializeJson(task.result),
           error: serializeJson(task.error),
+          suspend_payload: serializeJson(task.suspendPayload),
           retry_count: task.retryCount,
           max_retries: task.maxRetries,
           timeout_ms: task.timeoutMs,
           createdAt: task.createdAt.toISOString(),
           startedAt: task.startedAt?.toISOString() ?? "1970-01-01T00:00:00.000Z",
+          suspendedAt: task.suspendedAt?.toISOString() ?? "1970-01-01T00:00:00.000Z",
           completedAt: task.completedAt?.toISOString() ?? "1970-01-01T00:00:00.000Z"
         }
       ],
@@ -771,8 +786,10 @@ var BackgroundTasksStorageClickhouse = class extends storage.BackgroundTasksStor
     if ("status" in update) merged.status = update.status;
     if ("result" in update) merged.result = update.result;
     if ("error" in update) merged.error = update.error;
+    if ("suspendPayload" in update) merged.suspendPayload = update.suspendPayload;
     if ("retryCount" in update) merged.retryCount = update.retryCount;
     if ("startedAt" in update) merged.startedAt = update.startedAt;
+    if ("suspendedAt" in update) merged.suspendedAt = update.suspendedAt;
     if ("completedAt" in update) merged.completedAt = update.completedAt;
     await this.createTask(merged);
   }
@@ -810,7 +827,11 @@ var BackgroundTasksStorageClickhouse = class extends storage.BackgroundTasksStor
       conditions.push(`tool_name = {var_tool:String}`);
       params.var_tool = filter.toolName;
     }
-    const dateCol = filter.dateFilterBy === "startedAt" ? "startedAt" : filter.dateFilterBy === "completedAt" ? "completedAt" : "createdAt";
+    if (filter.toolCallId) {
+      conditions.push(`tool_call_id = {var_tool_call:String}`);
+      params.var_tool_call = filter.toolCallId;
+    }
+    const dateCol = filter.dateFilterBy === "startedAt" ? "startedAt" : filter.dateFilterBy === "suspendedAt" ? "suspendedAt" : filter.dateFilterBy === "completedAt" ? "completedAt" : "createdAt";
     if (filter.fromDate) {
       conditions.push(`${dateCol} >= parseDateTimeBestEffort({var_from_date:String})`);
       params.var_from_date = filter.fromDate.toISOString();
@@ -832,7 +853,7 @@ var BackgroundTasksStorageClickhouse = class extends storage.BackgroundTasksStor
     });
     const countRows = await countResult.json();
     const total = Number(countRows[0]?.count ?? 0);
-    const orderCol = filter.orderBy === "startedAt" ? "startedAt" : filter.orderBy === "completedAt" ? "completedAt" : "createdAt";
+    const orderCol = filter.orderBy === "startedAt" ? "startedAt" : filter.orderBy === "suspendedAt" ? "suspendedAt" : filter.orderBy === "completedAt" ? "completedAt" : "createdAt";
     const direction = filter.orderDirection === "desc" ? "DESC" : "ASC";
     let sql = `SELECT * FROM ${storage.TABLE_BACKGROUND_TASKS} FINAL ${where} ORDER BY ${orderCol} ${direction}`;
     if (filter.perPage != null) {