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

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @mastra/clickhouse
 
+## 1.7.0-alpha.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 [[`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d), [`7fce309`](https://github.com/mastra-ai/mastra/commit/7fce30912b14170bfc41f0ac736cca0f39fe0cd4), [`7997c2e`](https://github.com/mastra-ai/mastra/commit/7997c2e55ddd121562a4098cd8d2b89c68433bf1), [`e97ccb9`](https://github.com/mastra-ai/mastra/commit/e97ccb900f8b7a390ce82c9f8eb8d6eb2c5e3777), [`c5daf48`](https://github.com/mastra-ai/mastra/commit/c5daf48556e98c46ae06caf00f92c249912007e9), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e)]:
+  - @mastra/core@1.32.0-alpha.2
+
+## 1.6.0
+
+### Minor Changes
+
+- Added ClickhouseStoreVNext, a ClickHouse storage adapter that uses the vNext observability domain by default. Equivalent to constructing a ClickhouseStore and overriding the observability domain manually, but exposed as a single class for new projects. ([#15984](https://github.com/mastra-ai/mastra/pull/15984))
+
+  ```typescript
+  import { Mastra } from '@mastra/core';
+  import { ClickhouseStoreVNext } from '@mastra/clickhouse';
+
+  export const mastra = new Mastra({
+    storage: new ClickhouseStoreVNext({
+      id: 'clickhouse-storage',
+      url: process.env.CLICKHOUSE_URL!,
+      username: process.env.CLICKHOUSE_USERNAME!,
+      password: process.env.CLICKHOUSE_PASSWORD!,
+    }),
+  });
+  ```
+
+  ClickhouseStoreVNext accepts the same configuration as ClickhouseStore and reuses the same ClickHouse client across every domain. ClickhouseStore continues to work for projects on the legacy observability schema.
+
+### Patch Changes
+
+- Updated dependencies [[`1723e09`](https://github.com/mastra-ai/mastra/commit/1723e099829892419ddbfe49287acfeac2522724), [`629f9e9`](https://github.com/mastra-ai/mastra/commit/629f9e9a7e56aa8f129515a3923c5813298790c7), [`25168fb`](https://github.com/mastra-ai/mastra/commit/25168fb9c1de9db7f8171df4f58ceb842c53aa29), [`ab34b5a`](https://github.com/mastra-ai/mastra/commit/ab34b5a2191b8e4353df1dbf7b9155e7d6628d79), [`5fb6c2a`](https://github.com/mastra-ai/mastra/commit/5fb6c2a95c1843cc231704b91354311fc1f34a71), [`2b0f355`](https://github.com/mastra-ai/mastra/commit/2b0f3553be3e9e5524da539a66e5cf82668440a4), [`394f0cf`](https://github.com/mastra-ai/mastra/commit/394f0cfc31e6b4d801219fdef2e9cc69e5bc8682), [`b2deb29`](https://github.com/mastra-ai/mastra/commit/b2deb29412b300c868655b5840463614fbb7962d), [`66644be`](https://github.com/mastra-ai/mastra/commit/66644beac1aa560f0e417956ff007c89341dc382), [`e109607`](https://github.com/mastra-ai/mastra/commit/e10960749251e34d46b480a20648c490fd30381b), [`310b953`](https://github.com/mastra-ai/mastra/commit/310b95345f302dcd5ba3ed862bdc96f059d44122), [`3d7f709`](https://github.com/mastra-ai/mastra/commit/3d7f709b615e588050bb6283c4ee5cfe2978cbde), [`48a42f1`](https://github.com/mastra-ai/mastra/commit/48a42f114a4006a95e0b7a1b5ad1a24815a175c2), [`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006), [`2c83efc`](https://github.com/mastra-ai/mastra/commit/2c83efc4482b3efe50830e3b8b4ba9a8d219edff), [`43f0e1d`](https://github.com/mastra-ai/mastra/commit/43f0e1d5d5a74ba6fc746f2ad89ebe0c64777a7d), [`da0b9e2`](https://github.com/mastra-ai/mastra/commit/da0b9e2ba7ecc560213b426d6c097fe63946086e), [`282a10c`](https://github.com/mastra-ai/mastra/commit/282a10c9446e9922afe80e10e3770481c8ac8a28), [`04151c7`](https://github.com/mastra-ai/mastra/commit/04151c7dcea934b4fe9076708a23fac161195414), [`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006)]:
+  - @mastra/core@1.31.0
+
 ## 1.6.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.6.0-alpha.0"
+  version: "1.7.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/index.cjs

@@ -40,7 +40,11 @@ var TABLE_ENGINES = {
   [storage.TABLE_SKILLS]: `ReplacingMergeTree()`,
   [storage.TABLE_SKILL_VERSIONS]: `MergeTree()`,
   [storage.TABLE_SKILL_BLOBS]: `ReplacingMergeTree()`,
-  mastra_background_tasks: `ReplacingMergeTree()`
+  mastra_background_tasks: `ReplacingMergeTree()`,
+  [storage.TABLE_SCHEDULES]: `ReplacingMergeTree()`,
+  [storage.TABLE_SCHEDULE_TRIGGERS]: `MergeTree()`,
+  mastra_channel_installations: `ReplacingMergeTree()`,
+  mastra_channel_config: `ReplacingMergeTree()`
 };
 var COLUMN_TYPES = {
   text: "String",
@@ -2830,6 +2834,7 @@ time for large tables. Please ensure you have a backup before proceeding.
 // src/storage/domains/observability/v-next/ddl.ts
 var TABLE_SPAN_EVENTS = "mastra_span_events";
 var TABLE_TRACE_ROOTS = "mastra_trace_roots";
+var TABLE_TRACE_BRANCHES = "mastra_trace_branches";
 var TABLE_METRIC_EVENTS = "mastra_metric_events";
 var TABLE_LOG_EVENTS = "mastra_log_events";
 var TABLE_SCORE_EVENTS = "mastra_score_events";
@@ -2837,8 +2842,18 @@ var TABLE_FEEDBACK_EVENTS = "mastra_feedback_events";
 var TABLE_DISCOVERY_VALUES = "mastra_discovery_values";
 var TABLE_DISCOVERY_PAIRS = "mastra_discovery_pairs";
 var MV_TRACE_ROOTS = "mastra_mv_trace_roots";
+var MV_TRACE_BRANCHES = "mastra_mv_trace_branches";
 var MV_DISCOVERY_VALUES = "mastra_mv_discovery_values";
 var MV_DISCOVERY_PAIRS = "mastra_mv_discovery_pairs";
+var BRANCH_SPAN_TYPE_VALUES = [
+  "agent_run",
+  "workflow_run",
+  "processor_run",
+  "scorer_run",
+  "rag_ingestion",
+  "tool_call",
+  "mcp_tool_call"
+];
 var SPAN_EVENTS_DDL = `
 CREATE TABLE IF NOT EXISTS ${TABLE_SPAN_EVENTS} (
   -- Identity
@@ -2979,6 +2994,80 @@ SELECT *
 FROM ${TABLE_SPAN_EVENTS}
 WHERE parentSpanId IS NULL
 `;
+var TRACE_BRANCHES_DDL = `
+CREATE TABLE IF NOT EXISTS ${TABLE_TRACE_BRANCHES} (
+  -- Identity
+  dedupeKey          String,
+
+  -- IDs
+  traceId            String,
+  spanId             String,
+  parentSpanId       Nullable(String),
+  experimentId       Nullable(String),
+
+  -- Entity
+  entityType         LowCardinality(Nullable(String)),
+  entityId           Nullable(String),
+  entityName         Nullable(String),
+  entityVersionId    Nullable(String),
+
+  -- Parent entity
+  parentEntityVersionId Nullable(String),
+  parentEntityType   LowCardinality(Nullable(String)),
+  parentEntityId     Nullable(String),
+  parentEntityName   Nullable(String),
+
+  -- Root entity
+  rootEntityVersionId Nullable(String),
+  rootEntityType     LowCardinality(Nullable(String)),
+  rootEntityId       Nullable(String),
+  rootEntityName     Nullable(String),
+
+  -- Context
+  userId             Nullable(String),
+  organizationId     Nullable(String),
+  resourceId         Nullable(String),
+  runId              Nullable(String),
+  sessionId          Nullable(String),
+  threadId           Nullable(String),
+  requestId          Nullable(String),
+  environment        LowCardinality(Nullable(String)),
+  executionSource    LowCardinality(Nullable(String)),
+  serviceName        LowCardinality(Nullable(String)),
+
+  -- Span scalars
+  name               String,
+  spanType           LowCardinality(String),
+  isEvent            Bool DEFAULT false,
+  startedAt          DateTime64(3, 'UTC'),
+  endedAt            DateTime64(3, 'UTC'),
+
+  -- Query-relevant flexible fields
+  tags               Array(LowCardinality(String)) DEFAULT [],
+  metadataSearch     Map(LowCardinality(String), String) DEFAULT map(),
+
+  -- Information-only JSON payloads
+  attributes         Nullable(String),
+  scope              Nullable(String),
+  links              Nullable(String),
+  input              Nullable(String),
+  output             Nullable(String),
+  error              Nullable(String),
+  metadataRaw        Nullable(String),
+  requestContext     Nullable(String)
+)
+ENGINE = ReplacingMergeTree
+PARTITION BY toDate(endedAt)
+ORDER BY (spanType, startedAt, traceId, dedupeKey)
+`;
+var TRACE_BRANCHES_MV_DDL = `
+CREATE MATERIALIZED VIEW IF NOT EXISTS ${MV_TRACE_BRANCHES}
+TO ${TABLE_TRACE_BRANCHES}
+AS
+SELECT *
+FROM ${TABLE_SPAN_EVENTS}
+WHERE spanType IN (${BRANCH_SPAN_TYPE_VALUES.map((v) => `'${v}'`).join(", ")})
+`;
 var METRIC_EVENTS_DDL = `
 CREATE TABLE IF NOT EXISTS ${TABLE_METRIC_EVENTS} (
   -- Timestamp
@@ -3031,7 +3120,22 @@ CREATE TABLE IF NOT EXISTS ${TABLE_METRIC_EVENTS} (
   -- Information-only JSON payloads
   costMetadata       Nullable(String),
   metadata           Nullable(String),
-  scope              Nullable(String)
+  scope              Nullable(String),
+
+  -- Bloom-filter skip indexes for high-cardinality ID drilldowns.
+  -- Equality and IN filters on these columns can skip granule chunks that
+  -- definitely do not contain the value. GRANULARITY 2 = 16K-row chunks.
+  -- ID columns are out-of-sort-key, so without these every drilldown scans
+  -- every row in the time range.
+  INDEX idx_traceId traceId TYPE bloom_filter(0.01) GRANULARITY 2,
+  INDEX idx_threadId threadId TYPE bloom_filter(0.01) GRANULARITY 2,
+  INDEX idx_resourceId resourceId TYPE bloom_filter(0.01) GRANULARITY 2,
+  INDEX idx_userId userId TYPE bloom_filter(0.01) GRANULARITY 2,
+  INDEX idx_organizationId organizationId TYPE bloom_filter(0.01) GRANULARITY 2,
+  INDEX idx_experimentId experimentId TYPE bloom_filter(0.01) GRANULARITY 2,
+  INDEX idx_runId runId TYPE bloom_filter(0.01) GRANULARITY 2,
+  INDEX idx_sessionId sessionId TYPE bloom_filter(0.01) GRANULARITY 2,
+  INDEX idx_requestId requestId TYPE bloom_filter(0.01) GRANULARITY 2
 )
 ENGINE = ReplacingMergeTree
 PARTITION BY toDate(timestamp)
@@ -3286,6 +3390,7 @@ SELECT DISTINCT kind, key1, key2, value FROM (
 var ALL_TABLE_DDL = [
   SPAN_EVENTS_DDL,
   TRACE_ROOTS_DDL,
+  TRACE_BRANCHES_DDL,
   METRIC_EVENTS_DDL,
   LOG_EVENTS_DDL,
   SCORE_EVENTS_DDL,
@@ -3293,7 +3398,7 @@ var ALL_TABLE_DDL = [
   DISCOVERY_VALUES_DDL,
   DISCOVERY_PAIRS_DDL
 ];
-var ALL_MV_DDL = [TRACE_ROOTS_MV_DDL];
+var ALL_MV_DDL = [TRACE_ROOTS_MV_DDL, TRACE_BRANCHES_MV_DDL];
 var DISCOVERY_MV_DDL = [DISCOVERY_VALUES_MV_DDL, DISCOVERY_PAIRS_MV_DDL];
 var ALL_MIGRATIONS = [
   // Span events
@@ -3319,11 +3424,25 @@ var ALL_MIGRATIONS = [
   // Feedback
   `ALTER TABLE ${TABLE_FEEDBACK_EVENTS} ADD COLUMN IF NOT EXISTS entityVersionId Nullable(String)`,
   `ALTER TABLE ${TABLE_FEEDBACK_EVENTS} ADD COLUMN IF NOT EXISTS parentEntityVersionId Nullable(String)`,
-  `ALTER TABLE ${TABLE_FEEDBACK_EVENTS} ADD COLUMN IF NOT EXISTS rootEntityVersionId Nullable(String)`
+  `ALTER TABLE ${TABLE_FEEDBACK_EVENTS} ADD COLUMN IF NOT EXISTS rootEntityVersionId Nullable(String)`,
+  // Metric skip indexes — additive, instant DDL. Existing parts keep no index
+  // until merged or `MATERIALIZE INDEX` is run; new parts are bloom-filtered
+  // immediately. With normal retention turning over the table, the index
+  // converges to full coverage without an explicit backfill.
+  `ALTER TABLE ${TABLE_METRIC_EVENTS} ADD INDEX IF NOT EXISTS idx_traceId traceId TYPE bloom_filter(0.01) GRANULARITY 2`,
+  `ALTER TABLE ${TABLE_METRIC_EVENTS} ADD INDEX IF NOT EXISTS idx_threadId threadId TYPE bloom_filter(0.01) GRANULARITY 2`,
+  `ALTER TABLE ${TABLE_METRIC_EVENTS} ADD INDEX IF NOT EXISTS idx_resourceId resourceId TYPE bloom_filter(0.01) GRANULARITY 2`,
+  `ALTER TABLE ${TABLE_METRIC_EVENTS} ADD INDEX IF NOT EXISTS idx_userId userId TYPE bloom_filter(0.01) GRANULARITY 2`,
+  `ALTER TABLE ${TABLE_METRIC_EVENTS} ADD INDEX IF NOT EXISTS idx_organizationId organizationId TYPE bloom_filter(0.01) GRANULARITY 2`,
+  `ALTER TABLE ${TABLE_METRIC_EVENTS} ADD INDEX IF NOT EXISTS idx_experimentId experimentId TYPE bloom_filter(0.01) GRANULARITY 2`,
+  `ALTER TABLE ${TABLE_METRIC_EVENTS} ADD INDEX IF NOT EXISTS idx_runId runId TYPE bloom_filter(0.01) GRANULARITY 2`,
+  `ALTER TABLE ${TABLE_METRIC_EVENTS} ADD INDEX IF NOT EXISTS idx_sessionId sessionId TYPE bloom_filter(0.01) GRANULARITY 2`,
+  `ALTER TABLE ${TABLE_METRIC_EVENTS} ADD INDEX IF NOT EXISTS idx_requestId requestId TYPE bloom_filter(0.01) GRANULARITY 2`
 ];
 var ALL_TABLE_NAMES = [
   TABLE_SPAN_EVENTS,
   TABLE_TRACE_ROOTS,
+  TABLE_TRACE_BRANCHES,
   TABLE_METRIC_EVENTS,
   TABLE_LOG_EVENTS,
   TABLE_SCORE_EVENTS,
@@ -3334,13 +3453,14 @@ var ALL_TABLE_NAMES = [
 var SIGNAL_TTL_COLUMNS = {
   [TABLE_SPAN_EVENTS]: "endedAt",
   [TABLE_TRACE_ROOTS]: "endedAt",
+  [TABLE_TRACE_BRANCHES]: "endedAt",
   [TABLE_METRIC_EVENTS]: "timestamp",
   [TABLE_LOG_EVENTS]: "timestamp",
   [TABLE_SCORE_EVENTS]: "timestamp",
   [TABLE_FEEDBACK_EVENTS]: "timestamp"
 };
 var SIGNAL_TO_TABLES = {
-  tracing: [TABLE_SPAN_EVENTS, TABLE_TRACE_ROOTS],
+  tracing: [TABLE_SPAN_EVENTS, TABLE_TRACE_ROOTS, TABLE_TRACE_BRANCHES],
   logs: [TABLE_LOG_EVENTS],
   metrics: [TABLE_METRIC_EVENTS],
   scores: [TABLE_SCORE_EVENTS],
@@ -4559,7 +4679,16 @@ var METRIC_TYPED_COLUMNS = /* @__PURE__ */ new Set([
   "costUnit"
 ]);
 var GROUP_BY_EXCLUDED2 = /* @__PURE__ */ new Set(["metadata", "scope", "costMetadata", "tags"]);
-function getAggregationSql2(aggregation, measure = "value") {
+function resolveDistinctColumnSql(distinctColumn) {
+  if (!distinctColumn) {
+    throw new Error(`count_distinct aggregation requires a 'distinctColumn' argument`);
+  }
+  if (!storage.METRIC_DISTINCT_COLUMNS.includes(distinctColumn)) {
+    throw new Error(`Invalid distinctColumn: ${distinctColumn}`);
+  }
+  return utils.parseFieldKey(distinctColumn);
+}
+function getAggregationSql2(aggregation, measure = "value", distinctColumn) {
   switch (aggregation) {
     case "sum":
       return `sum(${measure})`;
@@ -4571,6 +4700,9 @@ function getAggregationSql2(aggregation, measure = "value") {
       return `max(${measure})`;
     case "count":
       return `toFloat64(count(${measure}))`;
+    case "count_distinct": {
+      return `toFloat64(uniq(${resolveDistinctColumnSql(distinctColumn)}))`;
+    }
     case "last":
       return `argMax(${measure}, timestamp)`;
     default:
@@ -4709,7 +4841,7 @@ async function listMetrics(client, args) {
   };
 }
 async function getMetricAggregate(client, args) {
-  const aggSql = getAggregationSql2(args.aggregation);
+  const aggSql = getAggregationSql2(args.aggregation, "value", args.distinctColumn);
   const nameFilter = buildMetricNameFilter(args.name);
   const signalFilter = buildMetricsFilterConditions(args.filters);
   const combined = mergeFilters2(nameFilter, signalFilter);
@@ -4781,7 +4913,7 @@ async function getMetricAggregate(client, args) {
   return { value, estimatedCost: costSummary.estimatedCost, costUnit: costSummary.costUnit };
 }
 async function getMetricBreakdown(client, args) {
-  const aggSql = getAggregationSql2(args.aggregation);
+  const aggSql = getAggregationSql2(args.aggregation, "value", args.distinctColumn);
   const nameFilter = buildMetricNameFilter(args.name);
   const signalFilter = buildMetricsFilterConditions(args.filters);
   const combined = mergeFilters2(nameFilter, signalFilter);
@@ -4792,14 +4924,22 @@ async function getMetricBreakdown(client, args) {
   const groupByCols = resolvedGroupBy.map((e) => e.groupSql).join(", ");
   const allConditions = [...combined.conditions, ...labelExclusions];
   const fullWhereClause = allConditions.length ? `WHERE ${allConditions.join(" AND ")}` : "";
+  const orderDirection = args.orderDirection === "ASC" ? "ASC" : "DESC";
+  const limitClause = typeof args.limit === "number" ? `LIMIT {breakdown_limit:UInt32}` : "";
+  const extraParams = typeof args.limit === "number" ? { breakdown_limit: args.limit } : {};
   const sql = `
     SELECT ${selectGroupBy}, ${aggSql} AS value, ${getCostSummarySelect()}
     FROM ${TABLE_METRIC_EVENTS}
     ${fullWhereClause}
     GROUP BY ${groupByCols}
-    ORDER BY value DESC
+    ORDER BY value ${orderDirection}
+    ${limitClause}
   `;
-  const rows = await queryJson3(client, sql, { ...combined.params, ...labelParams });
+  const rows = await queryJson3(client, sql, {
+    ...combined.params,
+    ...labelParams,
+    ...extraParams
+  });
   const groups = rows.map((row) => {
     const dimensions = {};
     for (const entry of resolvedGroupBy) {
@@ -4817,7 +4957,7 @@ async function getMetricBreakdown(client, args) {
   return { groups };
 }
 async function getMetricTimeSeries(client, args) {
-  const aggSql = getAggregationSql2(args.aggregation);
+  const aggSql = getAggregationSql2(args.aggregation, "value", args.distinctColumn);
   const intervalSql = getIntervalSql2(args.interval);
   const nameFilter = buildMetricNameFilter(args.name);
   const signalFilter = buildMetricsFilterConditions(args.filters);
@@ -5215,6 +5355,14 @@ async function listScores(client, args) {
     scores: rows.map(rowToScoreRecord)
   };
 }
+async function getScoreById(client, scoreId) {
+  const rows = await queryJson4(
+    client,
+    `SELECT * FROM ${TABLE_SCORE_EVENTS} WHERE scoreId = {scoreId:String} LIMIT 1`,
+    { scoreId }
+  );
+  return rows[0] ? rowToScoreRecord(rows[0]) : null;
+}
 async function getScoreAggregate(client, args) {
   const aggSql = getAggregationSql3(args.aggregation);
   const identity = buildScoreIdentityFilter(args);
@@ -5470,8 +5618,7 @@ async function listTraces(client, args) {
     spans: storage.toTraceSpans(spans)
   };
 }
-
-// src/storage/domains/observability/v-next/tracing.ts
+var BRANCH_SPAN_TYPE_SQL_LIST = storage.BRANCH_SPAN_TYPES.map((t) => `'${t}'`).join(", ");
 async function createSpan(client, args) {
   const row = spanRecordToRow(args.span);
   await client.insert({
@@ -5491,6 +5638,29 @@ async function batchCreateSpans(client, args) {
     clickhouse_settings: CH_INSERT_SETTINGS
   });
 }
+async function getSpans(client, args) {
+  if (args.spanIds.length === 0) {
+    return { traceId: args.traceId, spans: [] };
+  }
+  const result = await client.query({
+    query: `
+      SELECT * FROM (
+        SELECT *
+        FROM ${TABLE_SPAN_EVENTS}
+        WHERE traceId = {traceId:String}
+          AND spanId IN {spanIds:Array(String)}
+        ORDER BY dedupeKey, endedAt DESC
+        LIMIT 1 BY dedupeKey
+      )
+    `,
+    query_params: { traceId: args.traceId, spanIds: args.spanIds },
+    format: "JSONEachRow",
+    clickhouse_settings: CH_SETTINGS
+  });
+  const rows = await result.json();
+  const spans = rows.map(rowToSpanRecord);
+  return { traceId: args.traceId, spans };
+}
 async function getSpan(client, args) {
   const result = await client.query({
     query: `
@@ -5579,6 +5749,169 @@ async function batchDeleteTraces(client, args) {
     })
   ]);
 }
+async function listBranches(client, args) {
+  const { filters, pagination, orderBy } = storage.listBranchesArgsSchema.parse(args);
+  const page = pagination?.page ?? 0;
+  const perPage = pagination?.perPage ?? 10;
+  const conditions = [];
+  const params = {};
+  if (filters?.spanType) {
+    conditions.push(`spanType = {spanType:String}`);
+    params.spanType = filters.spanType;
+  } else {
+    conditions.push(`spanType IN (${BRANCH_SPAN_TYPE_SQL_LIST})`);
+  }
+  if (filters?.startedAt?.start) {
+    const op = filters.startedAt.startExclusive ? ">" : ">=";
+    conditions.push(`startedAt ${op} {startedAtStart:DateTime64(3)}`);
+    params.startedAtStart = filters.startedAt.start.getTime();
+  }
+  if (filters?.startedAt?.end) {
+    const op = filters.startedAt.endExclusive ? "<" : "<=";
+    conditions.push(`startedAt ${op} {startedAtEnd:DateTime64(3)}`);
+    params.startedAtEnd = filters.startedAt.end.getTime();
+  }
+  if (filters?.endedAt?.start) {
+    const op = filters.endedAt.startExclusive ? ">" : ">=";
+    conditions.push(`endedAt ${op} {endedAtStart:DateTime64(3)}`);
+    params.endedAtStart = filters.endedAt.start.getTime();
+  }
+  if (filters?.endedAt?.end) {
+    const op = filters.endedAt.endExclusive ? "<" : "<=";
+    conditions.push(`endedAt ${op} {endedAtEnd:DateTime64(3)}`);
+    params.endedAtEnd = filters.endedAt.end.getTime();
+  }
+  const eq = [
+    { col: "traceId", value: filters?.traceId, param: "traceId" },
+    { col: "entityType", value: filters?.entityType, param: "entityType" },
+    { col: "entityId", value: filters?.entityId, param: "entityId" },
+    { col: "entityName", value: filters?.entityName, param: "entityName" },
+    { col: "entityVersionId", value: filters?.entityVersionId, param: "entityVersionId" },
+    { col: "parentEntityVersionId", value: filters?.parentEntityVersionId, param: "parentEntityVersionId" },
+    { col: "parentEntityType", value: filters?.parentEntityType, param: "parentEntityType" },
+    { col: "parentEntityId", value: filters?.parentEntityId, param: "parentEntityId" },
+    { col: "parentEntityName", value: filters?.parentEntityName, param: "parentEntityName" },
+    { col: "rootEntityVersionId", value: filters?.rootEntityVersionId, param: "rootEntityVersionId" },
+    { col: "rootEntityType", value: filters?.rootEntityType, param: "rootEntityType" },
+    { col: "rootEntityId", value: filters?.rootEntityId, param: "rootEntityId" },
+    { col: "rootEntityName", value: filters?.rootEntityName, param: "rootEntityName" },
+    { col: "experimentId", value: filters?.experimentId, param: "experimentId" },
+    { col: "userId", value: filters?.userId, param: "userId" },
+    { col: "organizationId", value: filters?.organizationId, param: "organizationId" },
+    { col: "resourceId", value: filters?.resourceId, param: "resourceId" },
+    { col: "runId", value: filters?.runId, param: "runId" },
+    { col: "sessionId", value: filters?.sessionId, param: "sessionId" },
+    { col: "threadId", value: filters?.threadId, param: "threadId" },
+    { col: "requestId", value: filters?.requestId, param: "requestId" },
+    { col: "environment", value: filters?.environment, param: "environment" },
+    { col: "executionSource", value: filters?.source, param: "source" },
+    { col: "serviceName", value: filters?.serviceName, param: "serviceName" }
+  ];
+  for (const { col, value, param } of eq) {
+    if (value == null) continue;
+    conditions.push(`${col} = {${param}:String}`);
+    params[param] = value;
+  }
+  if (filters?.tags && filters.tags.length > 0) {
+    for (let i = 0; i < filters.tags.length; i++) {
+      const tag = filters.tags[i];
+      if (typeof tag !== "string" || tag.trim() === "") continue;
+      const param = `tag_${i}`;
+      conditions.push(`has(tags, {${param}:String})`);
+      params[param] = tag;
+    }
+  }
+  if (filters?.metadata != null && typeof filters.metadata === "object") {
+    let i = 0;
+    for (const [key, value] of Object.entries(filters.metadata)) {
+      if (typeof value !== "string") continue;
+      const keyParam = `meta_k_${i}`;
+      const valParam = `meta_v_${i}`;
+      conditions.push(`metadataSearch[{${keyParam}:String}] = {${valParam}:String}`);
+      params[keyParam] = key;
+      params[valParam] = value;
+      i++;
+    }
+  }
+  if (filters?.scope != null && typeof filters.scope === "object") {
+    let i = 0;
+    for (const [key, value] of Object.entries(filters.scope)) {
+      if (value === void 0) continue;
+      const normalized = typeof value === "string" ? value : JSON.stringify(value);
+      if (normalized == null) continue;
+      const keyParam = `scope_k_${i}`;
+      const valParam = `scope_v_${i}`;
+      conditions.push(`JSONExtractString(scope, {${keyParam}:String}) = {${valParam}:String}`);
+      params[keyParam] = key;
+      params[valParam] = normalized;
+      i++;
+    }
+  }
+  if (filters?.status === storage.TraceStatus.ERROR) {
+    conditions.push(`error IS NOT NULL`);
+  } else if (filters?.status === storage.TraceStatus.SUCCESS) {
+    conditions.push(`error IS NULL`);
+  } else if (filters?.status === storage.TraceStatus.RUNNING) {
+    conditions.push("1 = 0");
+  }
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const sortField = orderBy?.field === "endedAt" ? "endedAt" : "startedAt";
+  const sortDirection = orderBy?.direction === "ASC" ? "ASC" : "DESC";
+  const countResult = await client.query({
+    query: `
+      SELECT count() as cnt FROM (
+        SELECT dedupeKey
+        FROM ${TABLE_TRACE_BRANCHES}
+        ${whereClause}
+        ORDER BY dedupeKey
+        LIMIT 1 BY dedupeKey
+      )
+    `,
+    query_params: params,
+    format: "JSONEachRow",
+    clickhouse_settings: CH_SETTINGS
+  });
+  const countRows = await countResult.json();
+  const total = Number(countRows[0]?.cnt ?? 0);
+  if (total === 0) {
+    return {
+      pagination: { total: 0, page, perPage, hasMore: false },
+      branches: []
+    };
+  }
+  const dataResult = await client.query({
+    query: `
+      SELECT * FROM (
+        SELECT *
+        FROM ${TABLE_TRACE_BRANCHES}
+        ${whereClause}
+        ORDER BY dedupeKey
+        LIMIT 1 BY dedupeKey
+      )
+      ORDER BY ${sortField} ${sortDirection}, dedupeKey ASC
+      LIMIT {limit:UInt32}
+      OFFSET {offset:UInt32}
+    `,
+    query_params: {
+      ...params,
+      limit: perPage,
+      offset: page * perPage
+    },
+    format: "JSONEachRow",
+    clickhouse_settings: CH_SETTINGS
+  });
+  const rows = await dataResult.json();
+  const spans = rows.map(rowToSpanRecord);
+  return {
+    pagination: {
+      total,
+      page,
+      perPage,
+      hasMore: (page + 1) * perPage < total
+    },
+    branches: storage.toTraceSpans(spans)
+  };
+}
 
 // src/storage/domains/observability/v-next/index.ts
 function buildSignalMigrationRequiredMessage(args) {
@@ -5757,6 +6090,22 @@ var ObservabilityStorageClickhouseVNext = class extends storage.ObservabilitySto
       );
     }
   }
+  async getSpans(args) {
+    try {
+      return await getSpans(this.#client, args);
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("CLICKHOUSE", "GET_SPANS", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { traceId: args.traceId, count: args.spanIds.length }
+        },
+        error$1
+      );
+    }
+  }
   async getRootSpan(args) {
     try {
       return await getRootSpan(this.#client, args);
@@ -5820,6 +6169,21 @@ var ObservabilityStorageClickhouseVNext = class extends storage.ObservabilitySto
       );
     }
   }
+  async listBranches(args) {
+    try {
+      return await listBranches(this.#client, args);
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("CLICKHOUSE", "LIST_BRANCHES", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY
+        },
+        error$1
+      );
+    }
+  }
   async batchCreateLogs(args) {
     try {
       await batchCreateLogs(this.#client, args);
@@ -5928,6 +6292,22 @@ var ObservabilityStorageClickhouseVNext = class extends storage.ObservabilitySto
       );
     }
   }
+  async getScoreById(scoreId) {
+    try {
+      return await getScoreById(this.#client, scoreId);
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("CLICKHOUSE", "GET_SCORE_BY_ID", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { scoreId }
+        },
+        error$1
+      );
+    }
+  }
   async createFeedback(args) {
     try {
       await createFeedback(this.#client, args);