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

package/README.md

@@ -8,13 +8,6 @@ Clickhouse implementation for Mastra, providing efficient storage capabilities w
 npm install @mastra/clickhouse
 ```
 
-## Prerequisites
-
-- Clickhouse server (version 23.3 or higher required for delete operations; earlier versions may work for read/write operations)
-  - Lightweight `DELETE FROM` requires ClickHouse 22.8+ with `allow_experimental_lightweight_delete = 1` (for 22.8–23.2), or 23.3+ where it is generally available.
-  - The `deleteTask`, `deleteTasks`, and `deleteMessages` methods use `DELETE FROM` — ensure your server supports lightweight delete before using those operations.
-- Node.js 22.13.0 or later
-
 ## Usage
 
 ```typescript
@@ -59,120 +52,15 @@ const { messages } = await store.listMessages({ threadId: 'thread-123' });
 await store.close();
 ```
 
-## Configuration
-
-The Clickhouse store can be initialized with the following configuration:
-
-```typescript
-type ClickhouseConfig = {
-  url: string; // Clickhouse HTTP interface URL
-  username: string; // Database username
-  password: string; // Database password
-  replication?: {
-    cluster?: string; // Adds ON CLUSTER to Mastra-owned DDL when set
-    zookeeperPath?: string; // Defaults to '/clickhouse/tables/{shard}/{database}/{table}'
-    replicaName?: string; // Defaults to '{replica}'
-  };
-};
-```
-
-### Replicated ClickHouse clusters
-
-Set `replication` when Mastra writes to a multi-replica ClickHouse cluster through a load balancer. Mastra will create its tables with replicated MergeTree engines and add `ON CLUSTER` to Mastra-owned DDL when `cluster` is provided.
-
-```typescript
-const store = new ClickhouseStore({
-  url: 'http://clickhouse-lb:8123',
-  username: 'default',
-  password: 'password',
-  replication: {
-    cluster: 'company_cluster',
-  },
-});
-```
-
-The default `zookeeperPath` is `/clickhouse/tables/{shard}/{database}/{table}`. If your cluster's existing tables use a different layout (for example `/clickhouse/tables/{shard}/{table}` without the `{database}` segment), set `zookeeperPath` explicitly to match. Mastra does not infer your cluster's convention from Keeper.
-
-Manual maintenance such as `optimizeTable()` and `materializeTtl()` runs on every replica when `cluster` is set. These operations can be expensive on a large cluster. Prefer running them outside peak hours.
-
-If Mastra finds an existing local `MergeTree` or `ReplacingMergeTree` table while replication is enabled, initialization fails instead of silently mixing local and replicated tables. Migrate existing local tables manually before enabling this option.
-
-## Features
-
-### Storage Features
-
-- Thread and message storage with JSON support
-- Efficient batch operations
-- Rich metadata support
-- Timestamp tracking
-- Workflow snapshot persistence
-- Optimized for high-volume data ingestion
-- Uses Clickhouse's MergeTree and ReplacingMergeTree engines for optimal performance
-
-### Table Engines
-
-The store uses different table engines for different types of data:
-
-- `MergeTree()`: Used for messages, traces, and evals
-- `ReplacingMergeTree()`: Used for threads and workflow snapshots
-- `ReplicatedMergeTree(...)` / `ReplicatedReplacingMergeTree(...)`: Used instead when `replication` is enabled
-
-## Storage Methods
-
-### Thread Operations
-
-- `saveThread({ thread })`: Create or update a thread
-- `getThreadById({ threadId })`: Get a thread by ID
-- `listThreadsByResourceId({ resourceId, offset, limit, orderBy? })`: List paginated threads for a resource
-- `updateThread({ id, title, metadata })`: Update thread title and metadata
-- `deleteThread({ threadId })`: Delete a thread and its messages
-
-### Message Operations
-
-- `saveMessages({ messages })`: Save multiple messages
-- `listMessages({ threadId, perPage?, page? })`: Get messages for a thread with pagination
-- `updateMessages({ messages })`: Update existing messages
-
-### Resource Operations
-
-- `getResourceById({ resourceId })`: Get a resource by ID
-- `saveResource({ resource })`: Create or save a resource
-- `updateResource({ resourceId, workingMemory })`: Update resource working memory
-
-### Workflow Operations
-
-- `persistWorkflowSnapshot({ workflowName, runId, snapshot })`: Save workflow state
-- `loadWorkflowSnapshot({ workflowName, runId })`: Load workflow state
-- `listWorkflowRuns({ workflowName, pagination })`: List workflow runs with pagination
-- `getWorkflowRunById({ workflowName, runId })`: Get a specific workflow run
-
-### Evaluation/Scoring Operations
-
-- `getScoreById({ id })`: Get a score by ID
-- `saveScore(score)`: Save an evaluation score
-- `listScoresByScorerId({ scorerId, pagination })`: List scores by scorer with pagination
-- `listScoresByRunId({ runId, pagination })`: List scores by run with pagination
-- `listScoresByEntityId({ entityId, entityType, pagination })`: List scores by entity with pagination
-- `listScoresBySpan({ traceId, spanId, pagination })`: List scores by span with pagination
-
-### Operations Not Currently Supported
-
-- AI Observability (traces/spans): Not currently supported
+## Documentation
 
-## Data Types
+- [ClickHouse integration guide](https://mastra.ai/integrations/databases/clickhouse)
+- [Storage reference](https://mastra.ai/reference/storage/overview)
 
-The store supports the following data types:
+## Changelog
 
-- `text`: String
-- `timestamp`: DateTime64(3)
-- `uuid`: String
-- `jsonb`: String (JSON serialized)
-- `integer`: Int64
-- `bigint`: Int64
-- `float`: Float64
-- `boolean`: Bool
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/stores/clickhouse/CHANGELOG.md) for version history and release notes.
 
-## Related Links
+## Support
 
-- [Clickhouse Documentation](https://clickhouse.com/docs)
-- [Clickhouse Node.js Client](https://github.com/clickhouse/clickhouse-js)
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

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

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/index.cjs

@@ -3173,6 +3173,9 @@ CREATE TABLE IF NOT EXISTS ${TABLE_FEEDBACK_EVENTS} (
   feedbackUserId     Nullable(String),
   sourceId           Nullable(String),
 
+  -- Review workflow
+  reviewStatus       LowCardinality(String) DEFAULT 'needs-review',
+
   -- Feedback identity
   feedbackSource     LowCardinality(String),
   feedbackType       LowCardinality(String),
@@ -3406,6 +3409,7 @@ const ALL_MIGRATIONS = [
 	addColumn(TABLE_SCORE_EVENTS, "parentEntityVersionId", "Nullable(String)"),
 	addColumn(TABLE_SCORE_EVENTS, "rootEntityVersionId", "Nullable(String)"),
 	addColumn(TABLE_FEEDBACK_EVENTS, "entityVersionId", "Nullable(String)"),
+	addColumn(TABLE_FEEDBACK_EVENTS, "reviewStatus", "LowCardinality(String) DEFAULT 'needs-review'"),
 	addColumn(TABLE_FEEDBACK_EVENTS, "parentEntityVersionId", "Nullable(String)"),
 	addColumn(TABLE_FEEDBACK_EVENTS, "rootEntityVersionId", "Nullable(String)"),
 	addBloomIndex(TABLE_METRIC_EVENTS, "idx_traceId", "traceId"),
@@ -3498,6 +3502,31 @@ function parseTtlExpression(expr) {
 	};
 }
 //#endregion
+//#region src/storage/domains/observability/v-next/review-status.ts
+const FEEDBACK_REVIEW_STATUSES = ["needs-review", "reviewed"];
+function isFeedbackReviewStatus(value) {
+	return FEEDBACK_REVIEW_STATUSES.some((status) => status === value);
+}
+/** Normalize a stored value to a review status, defaulting legacy/unknown values to `needs-review`. */
+function coerceFeedbackReviewStatus(value) {
+	return isFeedbackReviewStatus(value) ? value : "needs-review";
+}
+function parseUpdateFeedbackReviewStatusArgs(args) {
+	const invalid = (text) => new _mastra_core_error.MastraError({
+		id: "OBSERVABILITY_UPDATE_FEEDBACK_REVIEW_STATUS_INVALID_ARGS",
+		domain: _mastra_core_error.ErrorDomain.STORAGE,
+		category: _mastra_core_error.ErrorCategory.USER,
+		text
+	});
+	if (typeof args !== "object" || args === null) throw invalid("args must be an object");
+	if (typeof args.feedbackId !== "string" || args.feedbackId.length === 0) throw invalid("feedbackId is required");
+	if (!isFeedbackReviewStatus(args.reviewStatus)) throw invalid(`reviewStatus must be one of: ${FEEDBACK_REVIEW_STATUSES.join(", ")}`);
+	return {
+		feedbackId: args.feedbackId,
+		reviewStatus: args.reviewStatus
+	};
+}
+//#endregion
 //#region src/storage/domains/observability/v-next/helpers.ts
 const CH_SETTINGS = {
 	date_time_input_format: "best_effort",
@@ -4004,6 +4033,7 @@ function rowToFeedbackRecord(row) {
 		serviceName: nullableString(row.serviceName),
 		feedbackUserId,
 		sourceId: nullableString(row.sourceId),
+		reviewStatus: coerceFeedbackReviewStatus(row.reviewStatus),
 		feedbackSource,
 		feedbackType: row.feedbackType,
 		value: hasNumber ? Number(row.valueNumber) : nullableString(row.valueString) ?? "",
@@ -4047,6 +4077,7 @@ function feedbackRecordToRow(feedback) {
 		serviceName: feedback.serviceName ?? null,
 		feedbackUserId,
 		sourceId: feedback.sourceId ?? null,
+		reviewStatus: feedback.reviewStatus ?? "needs-review",
 		feedbackSource,
 		feedbackType: feedback.feedbackType,
 		valueString: typeof feedback.value === "string" ? feedback.value : null,
@@ -4344,6 +4375,7 @@ function buildFeedbackFilterConditions(filters, tableAlias) {
 	const fbActor = filters.feedbackUserId ?? filters.userId;
 	addEq(col("feedbackUserId"), fbActor, "feedbackUserId", "String", out);
 	addEq(col("feedbackSource"), filters.feedbackSource, "feedbackSource", "String", out);
+	addEq(col("reviewStatus"), filters.reviewStatus, "reviewStatus", "String", out);
 	if (typeof filters.feedbackType === "string") addEq(col("feedbackType"), filters.feedbackType, "feedbackType", "String", out);
 	else if (Array.isArray(filters.feedbackType)) addIn(col("feedbackType"), filters.feedbackType, "feedbackTypes", out);
 	return out;
@@ -4521,6 +4553,28 @@ async function batchCreateFeedback(client, args) {
 		clickhouse_settings: CH_INSERT_SETTINGS
 	});
 }
+async function updateFeedbackReviewStatus(client, args) {
+	const { feedbackId, reviewStatus } = parseUpdateFeedbackReviewStatusArgs(args);
+	const existing = await queryJson$2(client, `SELECT * FROM ${TABLE_FEEDBACK_EVENTS} FINAL WHERE feedbackId = {feedbackId:String} LIMIT 1`, { feedbackId });
+	if (!existing[0]) throw new _mastra_core_error.MastraError({
+		id: "OBSERVABILITY_UPDATE_FEEDBACK_REVIEW_STATUS_NOT_FOUND",
+		domain: _mastra_core_error.ErrorDomain.MASTRA_OBSERVABILITY,
+		category: _mastra_core_error.ErrorCategory.USER,
+		text: "Feedback record not found",
+		details: { feedbackId }
+	});
+	const updated = rowToFeedbackRecord({
+		...existing[0],
+		reviewStatus
+	});
+	await client.insert({
+		table: TABLE_FEEDBACK_EVENTS,
+		values: [feedbackRecordToRow(updated)],
+		format: "JSONEachRow",
+		clickhouse_settings: CH_INSERT_SETTINGS
+	});
+	return updated;
+}
 async function listFeedback(client, args, strategy) {
 	const parsed = _mastra_core_storage.listFeedbackArgsSchema.parse(args);
 	const deltaCursorEnabled = deltaPollingSupported(strategy);
@@ -4552,8 +4606,8 @@ async function listFeedback(client, args, strategy) {
 		};
 	}
 	const currentDeltaCursor = deltaCursorEnabled ? await getDeltaCursor$5(client, whereClause, filter.params) : void 0;
-	const countResult = await queryJson$2(client, `SELECT count() AS total FROM ${TABLE_FEEDBACK_EVENTS} AS f ${whereClause}`, filter.params);
-	const rows = await queryJson$2(client, `SELECT * FROM ${TABLE_FEEDBACK_EVENTS} AS f ${whereClause} ORDER BY ${orderBy} LIMIT {limit:UInt32} OFFSET {offset:UInt32}`, {
+	const countResult = await queryJson$2(client, `SELECT count() AS total FROM ${TABLE_FEEDBACK_EVENTS} AS f FINAL ${whereClause}`, filter.params);
+	const rows = await queryJson$2(client, `SELECT * FROM ${TABLE_FEEDBACK_EVENTS} AS f FINAL ${whereClause} ORDER BY ${orderBy} LIMIT {limit:UInt32} OFFSET {offset:UInt32}`, {
 		...filter.params,
 		limit: pagination.limit,
 		offset: pagination.offset
@@ -4579,7 +4633,7 @@ async function queryFeedbackAfterCursor(client, whereClause, params, limit, curs
         f.feedbackId AS feedbackId,
         toString(d.cursorId) AS cursorId
       FROM ${TABLE_FEEDBACK_EVENTS_DELTA} d
-      INNER JOIN ${TABLE_FEEDBACK_EVENTS} f
+      INNER JOIN ${TABLE_FEEDBACK_EVENTS} f FINAL
         ON ((f.traceId = d.traceId) OR (f.traceId IS NULL AND d.traceId IS NULL))
        AND f.timestamp = d.timestamp
        AND f.feedbackId = d.feedbackId
@@ -4596,7 +4650,7 @@ async function getDeltaCursor$5(client, whereClause, params) {
 	const cursorId = (await queryJson$2(client, `
       SELECT toString(max(d.cursorId)) AS cursorId
       FROM mastra_feedback_events_delta d
-      INNER JOIN mastra_feedback_events f
+      INNER JOIN mastra_feedback_events f FINAL
         ON ((f.traceId = d.traceId) OR (f.traceId IS NULL AND d.traceId IS NULL))
        AND f.timestamp = d.timestamp
        AND f.feedbackId = d.feedbackId
@@ -4615,7 +4669,7 @@ async function getFeedbackAggregate(client, args) {
 	const aggSql = getAggregationSql$2(args.aggregation);
 	const identity = buildFeedbackIdentityFilter(args);
 	const combined = mergeFilters$2(identity, buildFeedbackFilterConditions(args.filters));
-	const result = await queryJson$2(client, `SELECT ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} ${toWhereClause$2(combined)}`, combined.params);
+	const result = await queryJson$2(client, `SELECT ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} FINAL ${toWhereClause$2(combined)}`, combined.params);
 	const value = result[0]?.value == null ? null : Number(result[0]?.value);
 	if (args.comparePeriod && args.filters?.timestamp) {
 		const ts = args.filters.timestamp;
@@ -4649,7 +4703,7 @@ async function getFeedbackAggregate(client, args) {
 					endExclusive: ts.endExclusive
 				}
 			}));
-			const prevResult = await queryJson$2(client, `SELECT ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} ${toWhereClause$2(prevCombined)}`, prevCombined.params);
+			const prevResult = await queryJson$2(client, `SELECT ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} FINAL ${toWhereClause$2(prevCombined)}`, prevCombined.params);
 			const previousValue = prevResult[0]?.value == null ? null : Number(prevResult[0]?.value);
 			let changePercent = null;
 			if (previousValue !== null && previousValue !== 0 && value !== null) changePercent = (value - previousValue) / Math.abs(previousValue) * 100;
@@ -4667,7 +4721,7 @@ async function getFeedbackBreakdown(client, args) {
 	const combined = mergeFilters$2(buildFeedbackIdentityFilter(args), buildFeedbackFilterConditions(args.filters));
 	const whereClause = toWhereClause$2(combined);
 	const resolved = resolveFeedbackGroupBy(args.groupBy);
-	return { groups: (await queryJson$2(client, `SELECT ${resolved.map((e) => e.selectSql).join(", ")}, ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} ${whereClause} GROUP BY ${resolved.map((e) => e.groupSql).join(", ")} ORDER BY value DESC`, combined.params)).map((row) => ({
+	return { groups: (await queryJson$2(client, `SELECT ${resolved.map((e) => e.selectSql).join(", ")}, ${aggSql} AS value FROM ${TABLE_FEEDBACK_EVENTS} FINAL ${whereClause} GROUP BY ${resolved.map((e) => e.groupSql).join(", ")} ORDER BY value DESC`, combined.params)).map((row) => ({
 		dimensions: Object.fromEntries(resolved.map((entry, index) => {
 			const v = row[`group_by_${index}`];
 			return [entry.key, v == null ? null : String(v)];
@@ -4686,7 +4740,7 @@ async function getFeedbackTimeSeries(client, args) {
       SELECT toStartOfInterval(timestamp, ${intervalSql}) AS bucket,
              ${resolved.map((e) => e.selectSql).join(", ")},
              ${aggSql} AS value
-      FROM ${TABLE_FEEDBACK_EVENTS} ${whereClause}
+      FROM ${TABLE_FEEDBACK_EVENTS} FINAL ${whereClause}
       GROUP BY bucket, ${resolved.map((e) => e.groupSql).join(", ")}
       ORDER BY bucket
     `, combined.params);
@@ -4708,7 +4762,7 @@ async function getFeedbackTimeSeries(client, args) {
 	const rows = await queryJson$2(client, `
     SELECT toStartOfInterval(timestamp, ${intervalSql}) AS bucket,
            ${aggSql} AS value
-    FROM ${TABLE_FEEDBACK_EVENTS} ${whereClause}
+    FROM ${TABLE_FEEDBACK_EVENTS} FINAL ${whereClause}
     GROUP BY bucket
     ORDER BY bucket
   `, combined.params);
@@ -4731,7 +4785,7 @@ async function getFeedbackPercentiles(client, args) {
 		const rows = await queryJson$2(client, `
       SELECT toStartOfInterval(timestamp, ${intervalSql}) AS bucket,
              quantile(${p})(valueNumber) AS pvalue
-      FROM ${TABLE_FEEDBACK_EVENTS}
+      FROM ${TABLE_FEEDBACK_EVENTS} FINAL
       ${whereClause}
       GROUP BY bucket
       ORDER BY bucket
@@ -7359,6 +7413,19 @@ var ObservabilityStorageClickhouseVNext = class extends _mastra_core_storage.Obs
 			}, error);
 		}
 	}
+	async updateFeedbackReviewStatus(args) {
+		try {
+			return await updateFeedbackReviewStatus(this.#client, args);
+		} catch (error) {
+			if (error instanceof _mastra_core_error.MastraError) throw error;
+			throw new _mastra_core_error.MastraError({
+				id: (0, _mastra_core_storage.createStorageErrorId)("CLICKHOUSE", "UPDATE_FEEDBACK_REVIEW_STATUS", "FAILED"),
+				domain: _mastra_core_error.ErrorDomain.STORAGE,
+				category: _mastra_core_error.ErrorCategory.THIRD_PARTY,
+				details: { feedbackId: args.feedbackId }
+			}, error);
+		}
+	}
 	async listFeedback(args) {
 		try {
 			return await listFeedback(this.#client, args, this.#deltaCursorStrategy);