@mastra/clickhouse 1.12.0 → 1.13.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @mastra/clickhouse
 
+## 1.13.0-alpha.0
+
+### Minor Changes
+
+- Added exact metadata filtering to message history queries across Memory APIs and supported storage providers. ([#19991](https://github.com/mastra-ai/mastra/pull/19991))
+
+  ```ts
+  const messages = await memory.recall({
+    threadId: 'thread-1',
+    filter: {
+      metadata: {
+        status: 'done',
+        priority: 'high',
+      },
+    },
+  });
+  ```
+
+  Multiple fields use AND semantics. Supported values are strings, finite numbers, booleans, and `null`.
+
+### Patch Changes
+
+- Updated dependencies [[`0dca9d0`](https://github.com/mastra-ai/mastra/commit/0dca9d0b1356024a53b72ea6f040db528b126caa)]:
+  - @mastra/core@1.54.0-alpha.0
+
 ## 1.12.0
 
 ### Minor Changes
@@ -293,9 +318,7 @@
   **Example**
 
   ```ts
-  const storage = new LibSQLStore({
-    /* config */
-  });
+  const storage = new LibSQLStore({/* config */});
   const favorites = await storage.getStore('favorites');
 
   await favorites?.favorite({
@@ -321,9 +344,7 @@
   **Example**
 
   ```ts
-  const storage = new LibSQLStore({
-    /* config */
-  });
+  const storage = new LibSQLStore({/* config */});
   const favorites = await storage.getStore('favorites');
 
   await favorites?.favorite({

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

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/reference-storage-clickhouse.md

@@ -131,7 +131,7 @@ bun x mastra migrate
 
 The migration copies span data from `mastra_ai_spans` into `mastra_span_events` in day-sized batches. It handles column mapping, deduplicates legacy rows, and preserves the original table as a backup. After migration, traces appear in Studio through the vNext adapter.
 
-> **Note:** The legacy table is not deleted. Drop it manually after verifying the migration.
+> **Note:** The legacy table isn't deleted. Drop it manually after verifying the migration.
 
 ### ClickHouse for every domain
 

package/dist/index.cjs

@@ -1092,6 +1092,23 @@ function parseMetadata(metadata) {
     return {};
   }
 }
+function appendClickhouseMessageMetadataFilter(query, params, metadataFilter) {
+  if (!metadataFilter) return query;
+  let nextQuery = query;
+  Object.entries(metadataFilter).forEach(([key, value], index) => {
+    const keyParam = `metadataKey${index}`;
+    params[keyParam] = key;
+    nextQuery += ` AND isValidJSON(content) AND JSONHas(content, 'metadata') AND JSONHas(JSONExtractRaw(content, 'metadata'), {${keyParam}:String})`;
+    if (value === null) {
+      nextQuery += ` AND JSONExtractRaw(content, 'metadata', {${keyParam}:String}) = 'null'`;
+      return;
+    }
+    const valueParam = `metadataValue${index}`;
+    params[valueParam] = JSON.stringify(value);
+    nextQuery += ` AND JSONExtractRaw(content, 'metadata', {${keyParam}:String}) = {${valueParam}:String}`;
+  });
+  return nextQuery;
+}
 var MemoryStorageClickhouse = class extends storage.MemoryStorage {
   client;
   #db;
@@ -1203,6 +1220,7 @@ var MemoryStorageClickhouse = class extends storage.MemoryStorage {
   }
   async listMessages(args) {
     const { threadId, resourceId, include, filter, perPage: perPageInput, page = 0, orderBy } = args;
+    const metadataFilter = storage.validateStorageMetadataFilter(filter?.metadata);
     const rawThreadIds = Array.isArray(threadId) ? threadId : [threadId];
     const threadIds = rawThreadIds.filter((id) => id !== void 0 && id !== null).map((id) => (typeof id === "string" ? id : String(id)).trim()).filter((id) => id.length > 0);
     if (page < 0) {
@@ -1263,6 +1281,7 @@ var MemoryStorageClickhouse = class extends storage.MemoryStorage {
         dataQuery += ` AND createdAt ${endOp} parseDateTime64BestEffort({toDate:String}, 3)`;
         dataParams.toDate = endDate;
       }
+      dataQuery = appendClickhouseMessageMetadataFilter(dataQuery, dataParams, metadataFilter);
       const { field, direction } = this.parseOrderBy(orderBy, "ASC");
       dataQuery += ` ORDER BY "${field}" ${direction}`;
       if (perPageForQuery === 0 && (!include || include.length === 0)) {
@@ -1318,6 +1337,7 @@ var MemoryStorageClickhouse = class extends storage.MemoryStorage {
         countQuery += ` AND createdAt ${endOp} parseDateTime64BestEffort({toDate:String}, 3)`;
         countParams.toDate = endDate;
       }
+      countQuery = appendClickhouseMessageMetadataFilter(countQuery, countParams, metadataFilter);
       const countResult = await this.client.query({
         query: countQuery,
         query_params: countParams,
@@ -1356,7 +1376,7 @@ var MemoryStorageClickhouse = class extends storage.MemoryStorage {
         finalMessages.filter((m) => m.threadId && threadIdSet.has(m.threadId)).map((m) => m.id)
       );
       const allThreadMessagesReturned = returnedThreadMessageIds.size >= total;
-      const hasMore = perPageForResponse === false ? false : allThreadMessagesReturned ? false : offset + paginatedCount < total;
+      const hasMore = metadataFilter && perPageForResponse !== false ? offset + paginatedCount < total : perPageForResponse === false ? false : allThreadMessagesReturned ? false : offset + paginatedCount < total;
       return {
         messages: finalMessages,
         total,