@mastra/clickhouse 1.6.0 → 1.7.0-alpha.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createClient } from '@clickhouse/client';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SKILLS, TABLE_WORKSPACE_VERSIONS, TABLE_WORKSPACES, TABLE_MCP_SERVER_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_CLIENTS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SCORER_DEFINITIONS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_PROMPT_BLOCKS, TABLE_EXPERIMENT_RESULTS, TABLE_EXPERIMENTS, TABLE_DATASET_VERSIONS, TABLE_DATASET_ITEMS, TABLE_DATASETS, TABLE_AGENT_VERSIONS, TABLE_SPANS, TABLE_RESOURCES, TABLE_SCORERS, TABLE_THREADS, TABLE_TRACES, TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, BackgroundTasksStorage, TABLE_SCHEMAS, TABLE_BACKGROUND_TASKS, MemoryStorage, createStorageErrorId, normalizePerPage, calculatePagination, ObservabilityStorage, SPAN_SCHEMA, listTracesArgsSchema, toTraceSpans, ScoresStorage, transformScoreRow, SCORERS_SCHEMA, WorkflowsStorage, MastraCompositeStore, getSqlType, getDefaultValue, safelyParseJSON, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listFeedbackArgsSchema, EntityType, TraceStatus } from '@mastra/core/storage';
+import { BRANCH_SPAN_TYPES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEDULES, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SKILLS, TABLE_WORKSPACE_VERSIONS, TABLE_WORKSPACES, TABLE_MCP_SERVER_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_CLIENTS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SCORER_DEFINITIONS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_PROMPT_BLOCKS, TABLE_EXPERIMENT_RESULTS, TABLE_EXPERIMENTS, TABLE_DATASET_VERSIONS, TABLE_DATASET_ITEMS, TABLE_DATASETS, TABLE_AGENT_VERSIONS, TABLE_SPANS, TABLE_RESOURCES, TABLE_SCORERS, TABLE_THREADS, TABLE_TRACES, TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, BackgroundTasksStorage, TABLE_SCHEMAS, TABLE_BACKGROUND_TASKS, MemoryStorage, createStorageErrorId, normalizePerPage, calculatePagination, ObservabilityStorage, SPAN_SCHEMA, listTracesArgsSchema, toTraceSpans, ScoresStorage, transformScoreRow, SCORERS_SCHEMA, WorkflowsStorage, MastraCompositeStore, getSqlType, getDefaultValue, safelyParseJSON, listBranchesArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listFeedbackArgsSchema, EntityType, TraceStatus, METRIC_DISTINCT_COLUMNS } from '@mastra/core/storage';
 import { MastraBase } from '@mastra/core/base';
 import { MessageList } from '@mastra/core/agent';
 import { parseFieldKey } from '@mastra/core/utils';
@@ -39,6 +39,8 @@ var TABLE_ENGINES = {
   [TABLE_SKILL_VERSIONS]: `MergeTree()`,
   [TABLE_SKILL_BLOBS]: `ReplacingMergeTree()`,
   mastra_background_tasks: `ReplacingMergeTree()`,
+  [TABLE_SCHEDULES]: `ReplacingMergeTree()`,
+  [TABLE_SCHEDULE_TRIGGERS]: `MergeTree()`,
   mastra_channel_installations: `ReplacingMergeTree()`,
   mastra_channel_config: `ReplacingMergeTree()`
 };
@@ -2830,6 +2832,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 +2840,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 +2992,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 +3118,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 +3388,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 +3396,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 +3422,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 +3451,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 +4677,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 (!METRIC_DISTINCT_COLUMNS.includes(distinctColumn)) {
+    throw new Error(`Invalid distinctColumn: ${distinctColumn}`);
+  }
+  return parseFieldKey(distinctColumn);
+}
+function getAggregationSql2(aggregation, measure = "value", distinctColumn) {
   switch (aggregation) {
     case "sum":
       return `sum(${measure})`;
@@ -4571,6 +4698,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 +4839,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 +4911,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 +4922,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 +4955,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 +5353,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 +5616,7 @@ async function listTraces(client, args) {
     spans: toTraceSpans(spans)
   };
 }
-
-// src/storage/domains/observability/v-next/tracing.ts
+var BRANCH_SPAN_TYPE_SQL_LIST = BRANCH_SPAN_TYPES.map((t) => `'${t}'`).join(", ");
 async function createSpan(client, args) {
   const row = spanRecordToRow(args.span);
   await client.insert({
@@ -5491,6 +5636,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 +5747,169 @@ async function batchDeleteTraces(client, args) {
     })
   ]);
 }
+async function listBranches(client, args) {
+  const { filters, pagination, orderBy } = 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 === TraceStatus.ERROR) {
+    conditions.push(`error IS NOT NULL`);
+  } else if (filters?.status === TraceStatus.SUCCESS) {
+    conditions.push(`error IS NULL`);
+  } else if (filters?.status === 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: toTraceSpans(spans)
+  };
+}
 
 // src/storage/domains/observability/v-next/index.ts
 function buildSignalMigrationRequiredMessage(args) {
@@ -5757,6 +6088,22 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
       );
     }
   }
+  async getSpans(args) {
+    try {
+      return await getSpans(this.#client, args);
+    } catch (error) {
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "GET_SPANS", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { traceId: args.traceId, count: args.spanIds.length }
+        },
+        error
+      );
+    }
+  }
   async getRootSpan(args) {
     try {
       return await getRootSpan(this.#client, args);
@@ -5820,6 +6167,21 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
       );
     }
   }
+  async listBranches(args) {
+    try {
+      return await listBranches(this.#client, args);
+    } catch (error) {
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "LIST_BRANCHES", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
+    }
+  }
   async batchCreateLogs(args) {
     try {
       await batchCreateLogs(this.#client, args);
@@ -5928,6 +6290,22 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
       );
     }
   }
+  async getScoreById(scoreId) {
+    try {
+      return await getScoreById(this.#client, scoreId);
+    } catch (error) {
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "GET_SCORE_BY_ID", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { scoreId }
+        },
+        error
+      );
+    }
+  }
   async createFeedback(args) {
     try {
       await createFeedback(this.#client, args);