@mastra/libsql 0.0.1-alpha.3 → 0.0.1-alpha.5

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/libsql@0.0.1-alpha.3 build /home/runner/work/mastra/mastra/stores/libsql
+> @mastra/libsql@0.0.1-alpha.5 build /home/runner/work/mastra/mastra/stores/libsql
 > tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.4.0
 TSC Build start
-TSC ⚡️ Build success in 9435ms
+TSC ⚡️ Build success in 9438ms
 DTS Build start
 CLI Target: es2022
-Analysis will use the bundled TypeScript version 5.8.2
+Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/stores/libsql/dist/_tsup-dts-rollup.d.ts
-Analysis will use the bundled TypeScript version 5.8.2
+Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/stores/libsql/dist/_tsup-dts-rollup.d.cts
-DTS ⚡️ Build success in 8455ms
+DTS ⚡️ Build success in 11373ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.cjs 35.92 KB
-CJS ⚡️ Build success in 767ms
-ESM dist/index.js 35.84 KB
-ESM ⚡️ Build success in 768ms
+ESM dist/index.js 41.28 KB
+ESM ⚡️ Build success in 1118ms
+CJS dist/index.cjs 41.41 KB
+CJS ⚡️ Build success in 1119ms

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mastra/libsql
 
+## 0.0.1-alpha.5
+
+### Patch Changes
+
+- 5f826d9: Moved vector store specific prompts from @mastra/rag to be exported from the store that the prompt belongs to, ie @mastra/pg
+- Updated dependencies [3e7b69d]
+  - @mastra/core@0.9.1-alpha.5
+
+## 0.0.1-alpha.4
+
+### Patch Changes
+
+- 479f490: [MASTRA-3131] Add getWorkflowRunByID and add resourceId as filter for getWorkflowRuns
+- Updated dependencies [e4943b8]
+- Updated dependencies [479f490]
+  - @mastra/core@0.9.1-alpha.4
+
 ## 0.0.1-alpha.3
 
 ### Patch Changes

package/dist/_tsup-dts-rollup.d.cts

@@ -23,7 +23,8 @@ import type { StorageThreadType } from '@mastra/core/memory';
 import type { TABLE_NAMES } from '@mastra/core/storage';
 import type { UpsertVectorParams } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
-import type { WorkflowRunState } from '@mastra/core/workflows';
+import type { WorkflowRun } from '@mastra/core/storage';
+import type { WorkflowRuns } from '@mastra/core/storage';
 
 export declare function buildFilterQuery(filter: VectorFilter): FilterResult;
 
@@ -42,6 +43,14 @@ export declare interface FilterResult {
 
 export declare const handleKey: (key: string) => string;
 
+/**
+ * Vector store specific prompt that details supported operators and examples.
+ * This prompt helps users construct valid filters for LibSQL Vector.
+ */
+declare const LIBSQL_PROMPT = "When querying LibSQL Vector, you can ONLY use the operators listed below. Any other operators will be rejected.\nImportant: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.\nIf a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.\n\nBasic Comparison Operators:\n- $eq: Exact match (default when using field: value)\n  Example: { \"category\": \"electronics\" }\n- $ne: Not equal\n  Example: { \"category\": { \"$ne\": \"electronics\" } }\n- $gt: Greater than\n  Example: { \"price\": { \"$gt\": 100 } }\n- $gte: Greater than or equal\n  Example: { \"price\": { \"$gte\": 100 } }\n- $lt: Less than\n  Example: { \"price\": { \"$lt\": 100 } }\n- $lte: Less than or equal\n  Example: { \"price\": { \"$lte\": 100 } }\n\nArray Operators:\n- $in: Match any value in array\n  Example: { \"category\": { \"$in\": [\"electronics\", \"books\"] } }\n- $nin: Does not match any value in array\n  Example: { \"category\": { \"$nin\": [\"electronics\", \"books\"] } }\n- $all: Match all values in array\n  Example: { \"tags\": { \"$all\": [\"premium\", \"sale\"] } }\n- $elemMatch: Match array elements that meet all specified conditions\n  Example: { \"items\": { \"$elemMatch\": { \"price\": { \"$gt\": 100 } } } }\n- $contains: Check if array contains value\n  Example: { \"tags\": { \"$contains\": \"premium\" } }\n\nLogical Operators:\n- $and: Logical AND (implicit when using multiple conditions)\n  Example: { \"$and\": [{ \"price\": { \"$gt\": 100 } }, { \"category\": \"electronics\" }] }\n- $or: Logical OR\n  Example: { \"$or\": [{ \"price\": { \"$lt\": 50 } }, { \"category\": \"books\" }] }\n- $not: Logical NOT\n  Example: { \"$not\": { \"category\": \"electronics\" } }\n- $nor: Logical NOR\n  Example: { \"$nor\": [{ \"price\": { \"$lt\": 50 } }, { \"category\": \"books\" }] }\n\nElement Operators:\n- $exists: Check if field exists\n  Example: { \"rating\": { \"$exists\": true } }\n\nSpecial Operators:\n- $size: Array length check\n  Example: { \"tags\": { \"$size\": 2 } }\n\nRestrictions:\n- Regex patterns are not supported\n- Direct RegExp patterns will throw an error\n- Nested fields are supported using dot notation\n- Multiple conditions on the same field are supported with both implicit and explicit $and\n- Array operations work on array fields only\n- Basic operators handle array values as JSON strings\n- Empty arrays in conditions are handled gracefully\n- Only logical operators ($and, $or, $not, $nor) can be used at the top level\n- All other operators must be used within a field condition\n  Valid: { \"field\": { \"$gt\": 100 } }\n  Valid: { \"$and\": [...] }\n  Invalid: { \"$gt\": 100 }\n  Invalid: { \"$contains\": \"value\" }\n- Logical operators must contain field conditions, not direct operators\n  Valid: { \"$and\": [{ \"field\": { \"$gt\": 100 } }] }\n  Invalid: { \"$and\": [{ \"$gt\": 100 }] }\n- $not operator:\n  - Must be an object\n  - Cannot be empty\n  - Can be used at field level or top level\n  - Valid: { \"$not\": { \"field\": \"value\" } }\n  - Valid: { \"field\": { \"$not\": { \"$eq\": \"value\" } } }\n- Other logical operators ($and, $or, $nor):\n  - Can only be used at top level or nested within other logical operators\n  - Can not be used on a field level, or be nested inside a field\n  - Can not be used inside an operator\n  - Valid: { \"$and\": [{ \"field\": { \"$gt\": 100 } }] }\n  - Valid: { \"$or\": [{ \"$and\": [{ \"field\": { \"$gt\": 100 } }] }] }\n  - Invalid: { \"field\": { \"$and\": [{ \"$gt\": 100 }] } }\n  - Invalid: { \"field\": { \"$or\": [{ \"$gt\": 100 }] } }\n  - Invalid: { \"field\": { \"$gt\": { \"$and\": [{...}] } } }\n- $elemMatch requires an object with conditions\n  Valid: { \"array\": { \"$elemMatch\": { \"field\": \"value\" } } }\n  Invalid: { \"array\": { \"$elemMatch\": \"value\" } }\n\nExample Complex Query:\n{\n  \"$and\": [\n    { \"category\": { \"$in\": [\"electronics\", \"computers\"] } },\n    { \"price\": { \"$gte\": 100, \"$lte\": 1000 } },\n    { \"tags\": { \"$all\": [\"premium\", \"sale\"] } },\n    { \"items\": { \"$elemMatch\": { \"price\": { \"$gt\": 50 }, \"inStock\": true } } },\n    { \"$or\": [\n      { \"stock\": { \"$gt\": 0 } },\n      { \"preorder\": true }\n    ]}\n  ]\n}";
+export { LIBSQL_PROMPT }
+export { LIBSQL_PROMPT as LIBSQL_PROMPT_alias_1 }
+
 declare interface LibSQLConfig {
     url: string;
     authToken?: string;
@@ -127,22 +136,20 @@ declare class LibSQLStore extends MastraStorage {
         attributes?: Record<string, string>;
         filters?: Record<string, any>;
     }): Promise<any[]>;
-    getWorkflowRuns({ workflowName, fromDate, toDate, limit, offset, }?: {
+    getWorkflowRuns({ workflowName, fromDate, toDate, limit, offset, resourceId, }?: {
         workflowName?: string;
         fromDate?: Date;
         toDate?: Date;
         limit?: number;
         offset?: number;
-    }): Promise<{
-        runs: Array<{
-            workflowName: string;
-            runId: string;
-            snapshot: WorkflowRunState | string;
-            createdAt: Date;
-            updatedAt: Date;
-        }>;
-        total: number;
-    }>;
+        resourceId?: string;
+    }): Promise<WorkflowRuns>;
+    getWorkflowRunById({ runId, workflowName, }: {
+        runId: string;
+        workflowName?: string;
+    }): Promise<WorkflowRun | null>;
+    private hasColumn;
+    private parseWorkflowRun;
 }
 export { LibSQLStore as DefaultStorage }
 export { LibSQLStore as DefaultStorage_alias_1 }

package/dist/_tsup-dts-rollup.d.ts

@@ -23,7 +23,8 @@ import type { StorageThreadType } from '@mastra/core/memory';
 import type { TABLE_NAMES } from '@mastra/core/storage';
 import type { UpsertVectorParams } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
-import type { WorkflowRunState } from '@mastra/core/workflows';
+import type { WorkflowRun } from '@mastra/core/storage';
+import type { WorkflowRuns } from '@mastra/core/storage';
 
 export declare function buildFilterQuery(filter: VectorFilter): FilterResult;
 
@@ -42,6 +43,14 @@ export declare interface FilterResult {
 
 export declare const handleKey: (key: string) => string;
 
+/**
+ * Vector store specific prompt that details supported operators and examples.
+ * This prompt helps users construct valid filters for LibSQL Vector.
+ */
+declare const LIBSQL_PROMPT = "When querying LibSQL Vector, you can ONLY use the operators listed below. Any other operators will be rejected.\nImportant: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.\nIf a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.\n\nBasic Comparison Operators:\n- $eq: Exact match (default when using field: value)\n  Example: { \"category\": \"electronics\" }\n- $ne: Not equal\n  Example: { \"category\": { \"$ne\": \"electronics\" } }\n- $gt: Greater than\n  Example: { \"price\": { \"$gt\": 100 } }\n- $gte: Greater than or equal\n  Example: { \"price\": { \"$gte\": 100 } }\n- $lt: Less than\n  Example: { \"price\": { \"$lt\": 100 } }\n- $lte: Less than or equal\n  Example: { \"price\": { \"$lte\": 100 } }\n\nArray Operators:\n- $in: Match any value in array\n  Example: { \"category\": { \"$in\": [\"electronics\", \"books\"] } }\n- $nin: Does not match any value in array\n  Example: { \"category\": { \"$nin\": [\"electronics\", \"books\"] } }\n- $all: Match all values in array\n  Example: { \"tags\": { \"$all\": [\"premium\", \"sale\"] } }\n- $elemMatch: Match array elements that meet all specified conditions\n  Example: { \"items\": { \"$elemMatch\": { \"price\": { \"$gt\": 100 } } } }\n- $contains: Check if array contains value\n  Example: { \"tags\": { \"$contains\": \"premium\" } }\n\nLogical Operators:\n- $and: Logical AND (implicit when using multiple conditions)\n  Example: { \"$and\": [{ \"price\": { \"$gt\": 100 } }, { \"category\": \"electronics\" }] }\n- $or: Logical OR\n  Example: { \"$or\": [{ \"price\": { \"$lt\": 50 } }, { \"category\": \"books\" }] }\n- $not: Logical NOT\n  Example: { \"$not\": { \"category\": \"electronics\" } }\n- $nor: Logical NOR\n  Example: { \"$nor\": [{ \"price\": { \"$lt\": 50 } }, { \"category\": \"books\" }] }\n\nElement Operators:\n- $exists: Check if field exists\n  Example: { \"rating\": { \"$exists\": true } }\n\nSpecial Operators:\n- $size: Array length check\n  Example: { \"tags\": { \"$size\": 2 } }\n\nRestrictions:\n- Regex patterns are not supported\n- Direct RegExp patterns will throw an error\n- Nested fields are supported using dot notation\n- Multiple conditions on the same field are supported with both implicit and explicit $and\n- Array operations work on array fields only\n- Basic operators handle array values as JSON strings\n- Empty arrays in conditions are handled gracefully\n- Only logical operators ($and, $or, $not, $nor) can be used at the top level\n- All other operators must be used within a field condition\n  Valid: { \"field\": { \"$gt\": 100 } }\n  Valid: { \"$and\": [...] }\n  Invalid: { \"$gt\": 100 }\n  Invalid: { \"$contains\": \"value\" }\n- Logical operators must contain field conditions, not direct operators\n  Valid: { \"$and\": [{ \"field\": { \"$gt\": 100 } }] }\n  Invalid: { \"$and\": [{ \"$gt\": 100 }] }\n- $not operator:\n  - Must be an object\n  - Cannot be empty\n  - Can be used at field level or top level\n  - Valid: { \"$not\": { \"field\": \"value\" } }\n  - Valid: { \"field\": { \"$not\": { \"$eq\": \"value\" } } }\n- Other logical operators ($and, $or, $nor):\n  - Can only be used at top level or nested within other logical operators\n  - Can not be used on a field level, or be nested inside a field\n  - Can not be used inside an operator\n  - Valid: { \"$and\": [{ \"field\": { \"$gt\": 100 } }] }\n  - Valid: { \"$or\": [{ \"$and\": [{ \"field\": { \"$gt\": 100 } }] }] }\n  - Invalid: { \"field\": { \"$and\": [{ \"$gt\": 100 }] } }\n  - Invalid: { \"field\": { \"$or\": [{ \"$gt\": 100 }] } }\n  - Invalid: { \"field\": { \"$gt\": { \"$and\": [{...}] } } }\n- $elemMatch requires an object with conditions\n  Valid: { \"array\": { \"$elemMatch\": { \"field\": \"value\" } } }\n  Invalid: { \"array\": { \"$elemMatch\": \"value\" } }\n\nExample Complex Query:\n{\n  \"$and\": [\n    { \"category\": { \"$in\": [\"electronics\", \"computers\"] } },\n    { \"price\": { \"$gte\": 100, \"$lte\": 1000 } },\n    { \"tags\": { \"$all\": [\"premium\", \"sale\"] } },\n    { \"items\": { \"$elemMatch\": { \"price\": { \"$gt\": 50 }, \"inStock\": true } } },\n    { \"$or\": [\n      { \"stock\": { \"$gt\": 0 } },\n      { \"preorder\": true }\n    ]}\n  ]\n}";
+export { LIBSQL_PROMPT }
+export { LIBSQL_PROMPT as LIBSQL_PROMPT_alias_1 }
+
 declare interface LibSQLConfig {
     url: string;
     authToken?: string;
@@ -127,22 +136,20 @@ declare class LibSQLStore extends MastraStorage {
         attributes?: Record<string, string>;
         filters?: Record<string, any>;
     }): Promise<any[]>;
-    getWorkflowRuns({ workflowName, fromDate, toDate, limit, offset, }?: {
+    getWorkflowRuns({ workflowName, fromDate, toDate, limit, offset, resourceId, }?: {
         workflowName?: string;
         fromDate?: Date;
         toDate?: Date;
         limit?: number;
         offset?: number;
-    }): Promise<{
-        runs: Array<{
-            workflowName: string;
-            runId: string;
-            snapshot: WorkflowRunState | string;
-            createdAt: Date;
-            updatedAt: Date;
-        }>;
-        total: number;
-    }>;
+        resourceId?: string;
+    }): Promise<WorkflowRuns>;
+    getWorkflowRunById({ runId, workflowName, }: {
+        runId: string;
+        workflowName?: string;
+    }): Promise<WorkflowRun | null>;
+    private hasColumn;
+    private parseWorkflowRun;
 }
 export { LibSQLStore as DefaultStorage }
 export { LibSQLStore as DefaultStorage_alias_1 }

package/dist/index.cjs

@@ -1088,56 +1088,203 @@ var LibSQLStore = class extends storage.MastraStorage {
     fromDate,
     toDate,
     limit,
-    offset
+    offset,
+    resourceId
   } = {}) {
+    try {
+      const conditions = [];
+      const args = [];
+      if (workflowName) {
+        conditions.push("workflow_name = ?");
+        args.push(workflowName);
+      }
+      if (fromDate) {
+        conditions.push("createdAt >= ?");
+        args.push(fromDate.toISOString());
+      }
+      if (toDate) {
+        conditions.push("createdAt <= ?");
+        args.push(toDate.toISOString());
+      }
+      if (resourceId) {
+        const hasResourceId = await this.hasColumn(storage.TABLE_WORKFLOW_SNAPSHOT, "resourceId");
+        if (hasResourceId) {
+          conditions.push("resourceId = ?");
+          args.push(resourceId);
+        } else {
+          console.warn(`[${storage.TABLE_WORKFLOW_SNAPSHOT}] resourceId column not found. Skipping resourceId filter.`);
+        }
+      }
+      const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+      let total = 0;
+      if (limit !== void 0 && offset !== void 0) {
+        const countResult = await this.client.execute({
+          sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
+          args
+        });
+        total = Number(countResult.rows?.[0]?.count ?? 0);
+      }
+      const result = await this.client.execute({
+        sql: `SELECT * FROM ${storage.TABLE_WORKFLOW_SNAPSHOT} ${whereClause} ORDER BY createdAt DESC${limit !== void 0 && offset !== void 0 ? ` LIMIT ? OFFSET ?` : ""}`,
+        args: limit !== void 0 && offset !== void 0 ? [...args, limit, offset] : args
+      });
+      const runs = (result.rows || []).map((row) => this.parseWorkflowRun(row));
+      return { runs, total: total || runs.length };
+    } catch (error) {
+      console.error("Error getting workflow runs:", error);
+      throw error;
+    }
+  }
+  async getWorkflowRunById({
+    runId,
+    workflowName
+  }) {
     const conditions = [];
     const args = [];
+    if (runId) {
+      conditions.push("run_id = ?");
+      args.push(runId);
+    }
     if (workflowName) {
       conditions.push("workflow_name = ?");
       args.push(workflowName);
     }
-    if (fromDate) {
-      conditions.push("createdAt >= ?");
-      args.push(fromDate.toISOString());
-    }
-    if (toDate) {
-      conditions.push("createdAt <= ?");
-      args.push(toDate.toISOString());
-    }
     const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-    let total = 0;
-    if (limit !== void 0 && offset !== void 0) {
-      const countResult = await this.client.execute({
-        sql: `SELECT COUNT(*) as count FROM ${storage.TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
-        args
-      });
-      total = Number(countResult.rows?.[0]?.count ?? 0);
+    const result = await this.client.execute({
+      sql: `SELECT * FROM ${storage.TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
+      args
+    });
+    if (!result.rows?.[0]) {
+      return null;
     }
+    return this.parseWorkflowRun(result.rows[0]);
+  }
+  async hasColumn(table, column) {
     const result = await this.client.execute({
-      sql: `SELECT * FROM ${storage.TABLE_WORKFLOW_SNAPSHOT} ${whereClause} ORDER BY createdAt DESC${limit !== void 0 && offset !== void 0 ? ` LIMIT ? OFFSET ?` : ""}`,
-      args: limit !== void 0 && offset !== void 0 ? [...args, limit, offset] : args
+      sql: `PRAGMA table_info(${table})`
     });
-    const runs = (result.rows || []).map((row) => {
-      let parsedSnapshot = row.snapshot;
-      if (typeof parsedSnapshot === "string") {
-        try {
-          parsedSnapshot = JSON.parse(row.snapshot);
-        } catch (e) {
-          console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
-        }
+    return (await result.rows)?.some((row) => row.name === column);
+  }
+  parseWorkflowRun(row) {
+    let parsedSnapshot = row.snapshot;
+    if (typeof parsedSnapshot === "string") {
+      try {
+        parsedSnapshot = JSON.parse(row.snapshot);
+      } catch (e) {
+        console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
       }
-      return {
-        workflowName: row.workflow_name,
-        runId: row.run_id,
-        snapshot: parsedSnapshot,
-        createdAt: new Date(row.createdAt),
-        updatedAt: new Date(row.updatedAt)
-      };
-    });
-    return { runs, total: total || runs.length };
+    }
+    return {
+      workflowName: row.workflow_name,
+      runId: row.run_id,
+      snapshot: parsedSnapshot,
+      resourceId: row.resourceId,
+      createdAt: new Date(row.created_at),
+      updatedAt: new Date(row.updated_at)
+    };
   }
 };
 
+// src/vector/prompt.ts
+var LIBSQL_PROMPT = `When querying LibSQL Vector, you can ONLY use the operators listed below. Any other operators will be rejected.
+Important: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.
+If a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.
+
+Basic Comparison Operators:
+- $eq: Exact match (default when using field: value)
+  Example: { "category": "electronics" }
+- $ne: Not equal
+  Example: { "category": { "$ne": "electronics" } }
+- $gt: Greater than
+  Example: { "price": { "$gt": 100 } }
+- $gte: Greater than or equal
+  Example: { "price": { "$gte": 100 } }
+- $lt: Less than
+  Example: { "price": { "$lt": 100 } }
+- $lte: Less than or equal
+  Example: { "price": { "$lte": 100 } }
+
+Array Operators:
+- $in: Match any value in array
+  Example: { "category": { "$in": ["electronics", "books"] } }
+- $nin: Does not match any value in array
+  Example: { "category": { "$nin": ["electronics", "books"] } }
+- $all: Match all values in array
+  Example: { "tags": { "$all": ["premium", "sale"] } }
+- $elemMatch: Match array elements that meet all specified conditions
+  Example: { "items": { "$elemMatch": { "price": { "$gt": 100 } } } }
+- $contains: Check if array contains value
+  Example: { "tags": { "$contains": "premium" } }
+
+Logical Operators:
+- $and: Logical AND (implicit when using multiple conditions)
+  Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+- $not: Logical NOT
+  Example: { "$not": { "category": "electronics" } }
+- $nor: Logical NOR
+  Example: { "$nor": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Element Operators:
+- $exists: Check if field exists
+  Example: { "rating": { "$exists": true } }
+
+Special Operators:
+- $size: Array length check
+  Example: { "tags": { "$size": 2 } }
+
+Restrictions:
+- Regex patterns are not supported
+- Direct RegExp patterns will throw an error
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported with both implicit and explicit $and
+- Array operations work on array fields only
+- Basic operators handle array values as JSON strings
+- Empty arrays in conditions are handled gracefully
+- Only logical operators ($and, $or, $not, $nor) can be used at the top level
+- All other operators must be used within a field condition
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$gt": 100 }
+  Invalid: { "$contains": "value" }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- $not operator:
+  - Must be an object
+  - Cannot be empty
+  - Can be used at field level or top level
+  - Valid: { "$not": { "field": "value" } }
+  - Valid: { "field": { "$not": { "$eq": "value" } } }
+- Other logical operators ($and, $or, $nor):
+  - Can only be used at top level or nested within other logical operators
+  - Can not be used on a field level, or be nested inside a field
+  - Can not be used inside an operator
+  - Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  - Valid: { "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }
+  - Invalid: { "field": { "$and": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$or": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$gt": { "$and": [{...}] } } }
+- $elemMatch requires an object with conditions
+  Valid: { "array": { "$elemMatch": { "field": "value" } } }
+  Invalid: { "array": { "$elemMatch": "value" } }
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "tags": { "$all": ["premium", "sale"] } },
+    { "items": { "$elemMatch": { "price": { "$gt": 50 }, "inStock": true } } },
+    { "$or": [
+      { "stock": { "$gt": 0 } },
+      { "preorder": true }
+    ]}
+  ]
+}`;
+
 exports.DefaultStorage = LibSQLStore;
+exports.LIBSQL_PROMPT = LIBSQL_PROMPT;
 exports.LibSQLStore = LibSQLStore;
 exports.LibSQLVector = LibSQLVector;

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+export { LIBSQL_PROMPT } from './_tsup-dts-rollup.cjs';
 export { LibSQLVector } from './_tsup-dts-rollup.cjs';
 export { LibSQLConfig } from './_tsup-dts-rollup.cjs';
 export { LibSQLStore } from './_tsup-dts-rollup.cjs';

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { LIBSQL_PROMPT } from './_tsup-dts-rollup.js';
 export { LibSQLVector } from './_tsup-dts-rollup.js';
 export { LibSQLConfig } from './_tsup-dts-rollup.js';
 export { LibSQLStore } from './_tsup-dts-rollup.js';

package/dist/index.js

@@ -1086,54 +1086,200 @@ var LibSQLStore = class extends MastraStorage {
     fromDate,
     toDate,
     limit,
-    offset
+    offset,
+    resourceId
   } = {}) {
+    try {
+      const conditions = [];
+      const args = [];
+      if (workflowName) {
+        conditions.push("workflow_name = ?");
+        args.push(workflowName);
+      }
+      if (fromDate) {
+        conditions.push("createdAt >= ?");
+        args.push(fromDate.toISOString());
+      }
+      if (toDate) {
+        conditions.push("createdAt <= ?");
+        args.push(toDate.toISOString());
+      }
+      if (resourceId) {
+        const hasResourceId = await this.hasColumn(TABLE_WORKFLOW_SNAPSHOT, "resourceId");
+        if (hasResourceId) {
+          conditions.push("resourceId = ?");
+          args.push(resourceId);
+        } else {
+          console.warn(`[${TABLE_WORKFLOW_SNAPSHOT}] resourceId column not found. Skipping resourceId filter.`);
+        }
+      }
+      const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+      let total = 0;
+      if (limit !== void 0 && offset !== void 0) {
+        const countResult = await this.client.execute({
+          sql: `SELECT COUNT(*) as count FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
+          args
+        });
+        total = Number(countResult.rows?.[0]?.count ?? 0);
+      }
+      const result = await this.client.execute({
+        sql: `SELECT * FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause} ORDER BY createdAt DESC${limit !== void 0 && offset !== void 0 ? ` LIMIT ? OFFSET ?` : ""}`,
+        args: limit !== void 0 && offset !== void 0 ? [...args, limit, offset] : args
+      });
+      const runs = (result.rows || []).map((row) => this.parseWorkflowRun(row));
+      return { runs, total: total || runs.length };
+    } catch (error) {
+      console.error("Error getting workflow runs:", error);
+      throw error;
+    }
+  }
+  async getWorkflowRunById({
+    runId,
+    workflowName
+  }) {
     const conditions = [];
     const args = [];
+    if (runId) {
+      conditions.push("run_id = ?");
+      args.push(runId);
+    }
     if (workflowName) {
       conditions.push("workflow_name = ?");
       args.push(workflowName);
     }
-    if (fromDate) {
-      conditions.push("createdAt >= ?");
-      args.push(fromDate.toISOString());
-    }
-    if (toDate) {
-      conditions.push("createdAt <= ?");
-      args.push(toDate.toISOString());
-    }
     const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-    let total = 0;
-    if (limit !== void 0 && offset !== void 0) {
-      const countResult = await this.client.execute({
-        sql: `SELECT COUNT(*) as count FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
-        args
-      });
-      total = Number(countResult.rows?.[0]?.count ?? 0);
+    const result = await this.client.execute({
+      sql: `SELECT * FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
+      args
+    });
+    if (!result.rows?.[0]) {
+      return null;
     }
+    return this.parseWorkflowRun(result.rows[0]);
+  }
+  async hasColumn(table, column) {
     const result = await this.client.execute({
-      sql: `SELECT * FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause} ORDER BY createdAt DESC${limit !== void 0 && offset !== void 0 ? ` LIMIT ? OFFSET ?` : ""}`,
-      args: limit !== void 0 && offset !== void 0 ? [...args, limit, offset] : args
+      sql: `PRAGMA table_info(${table})`
     });
-    const runs = (result.rows || []).map((row) => {
-      let parsedSnapshot = row.snapshot;
-      if (typeof parsedSnapshot === "string") {
-        try {
-          parsedSnapshot = JSON.parse(row.snapshot);
-        } catch (e) {
-          console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
-        }
+    return (await result.rows)?.some((row) => row.name === column);
+  }
+  parseWorkflowRun(row) {
+    let parsedSnapshot = row.snapshot;
+    if (typeof parsedSnapshot === "string") {
+      try {
+        parsedSnapshot = JSON.parse(row.snapshot);
+      } catch (e) {
+        console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
       }
-      return {
-        workflowName: row.workflow_name,
-        runId: row.run_id,
-        snapshot: parsedSnapshot,
-        createdAt: new Date(row.createdAt),
-        updatedAt: new Date(row.updatedAt)
-      };
-    });
-    return { runs, total: total || runs.length };
+    }
+    return {
+      workflowName: row.workflow_name,
+      runId: row.run_id,
+      snapshot: parsedSnapshot,
+      resourceId: row.resourceId,
+      createdAt: new Date(row.created_at),
+      updatedAt: new Date(row.updated_at)
+    };
   }
 };
 
-export { LibSQLStore as DefaultStorage, LibSQLStore, LibSQLVector };
+// src/vector/prompt.ts
+var LIBSQL_PROMPT = `When querying LibSQL Vector, you can ONLY use the operators listed below. Any other operators will be rejected.
+Important: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.
+If a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.
+
+Basic Comparison Operators:
+- $eq: Exact match (default when using field: value)
+  Example: { "category": "electronics" }
+- $ne: Not equal
+  Example: { "category": { "$ne": "electronics" } }
+- $gt: Greater than
+  Example: { "price": { "$gt": 100 } }
+- $gte: Greater than or equal
+  Example: { "price": { "$gte": 100 } }
+- $lt: Less than
+  Example: { "price": { "$lt": 100 } }
+- $lte: Less than or equal
+  Example: { "price": { "$lte": 100 } }
+
+Array Operators:
+- $in: Match any value in array
+  Example: { "category": { "$in": ["electronics", "books"] } }
+- $nin: Does not match any value in array
+  Example: { "category": { "$nin": ["electronics", "books"] } }
+- $all: Match all values in array
+  Example: { "tags": { "$all": ["premium", "sale"] } }
+- $elemMatch: Match array elements that meet all specified conditions
+  Example: { "items": { "$elemMatch": { "price": { "$gt": 100 } } } }
+- $contains: Check if array contains value
+  Example: { "tags": { "$contains": "premium" } }
+
+Logical Operators:
+- $and: Logical AND (implicit when using multiple conditions)
+  Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+- $not: Logical NOT
+  Example: { "$not": { "category": "electronics" } }
+- $nor: Logical NOR
+  Example: { "$nor": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Element Operators:
+- $exists: Check if field exists
+  Example: { "rating": { "$exists": true } }
+
+Special Operators:
+- $size: Array length check
+  Example: { "tags": { "$size": 2 } }
+
+Restrictions:
+- Regex patterns are not supported
+- Direct RegExp patterns will throw an error
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported with both implicit and explicit $and
+- Array operations work on array fields only
+- Basic operators handle array values as JSON strings
+- Empty arrays in conditions are handled gracefully
+- Only logical operators ($and, $or, $not, $nor) can be used at the top level
+- All other operators must be used within a field condition
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$gt": 100 }
+  Invalid: { "$contains": "value" }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- $not operator:
+  - Must be an object
+  - Cannot be empty
+  - Can be used at field level or top level
+  - Valid: { "$not": { "field": "value" } }
+  - Valid: { "field": { "$not": { "$eq": "value" } } }
+- Other logical operators ($and, $or, $nor):
+  - Can only be used at top level or nested within other logical operators
+  - Can not be used on a field level, or be nested inside a field
+  - Can not be used inside an operator
+  - Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  - Valid: { "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }
+  - Invalid: { "field": { "$and": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$or": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$gt": { "$and": [{...}] } } }
+- $elemMatch requires an object with conditions
+  Valid: { "array": { "$elemMatch": { "field": "value" } } }
+  Invalid: { "array": { "$elemMatch": "value" } }
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "tags": { "$all": ["premium", "sale"] } },
+    { "items": { "$elemMatch": { "price": { "$gt": 50 }, "inStock": true } } },
+    { "$or": [
+      { "stock": { "$gt": 0 } },
+      { "preorder": true }
+    ]}
+  ]
+}`;
+
+export { LibSQLStore as DefaultStorage, LIBSQL_PROMPT, LibSQLStore, LibSQLVector };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/libsql",
-  "version": "0.0.1-alpha.3",
+  "version": "0.0.1-alpha.5",
   "description": "Libsql provider for Mastra - includes both vector and db storage capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -21,17 +21,17 @@
   "license": "MIT",
   "dependencies": {
     "@libsql/client": "^0.15.4",
-    "@mastra/core": "^0.9.1-alpha.3"
+    "@mastra/core": "^0.9.1-alpha.5"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.52.1",
-    "@types/node": "^20.17.27",
-    "eslint": "^9.23.0",
+    "@microsoft/api-extractor": "^7.52.5",
+    "@types/node": "^20.17.32",
+    "eslint": "^9.25.1",
     "tsup": "^8.4.0",
-    "typescript": "^5.8.2",
-    "vitest": "^3.0.9",
-    "@internal/lint": "0.0.2",
-    "@internal/storage-test-utils": "0.0.1-alpha.2"
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2",
+    "@internal/storage-test-utils": "0.0.1-alpha.4",
+    "@internal/lint": "0.0.2"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting",

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './vector';
 export * from './storage';
+export { LIBSQL_PROMPT } from './vector/prompt';

package/src/storage/index.ts

@@ -10,7 +10,14 @@ import {
   TABLE_WORKFLOW_SNAPSHOT,
   TABLE_EVALS,
 } from '@mastra/core/storage';
-import type { EvalRow, StorageColumn, StorageGetMessagesArg, TABLE_NAMES } from '@mastra/core/storage';
+import type {
+  EvalRow,
+  StorageColumn,
+  StorageGetMessagesArg,
+  TABLE_NAMES,
+  WorkflowRun,
+  WorkflowRuns,
+} from '@mastra/core/storage';
 import type { WorkflowRunState } from '@mastra/core/workflows';
 
 function safelyParseJSON(jsonString: string): any {
@@ -544,80 +551,131 @@ export class LibSQLStore extends MastraStorage {
     toDate,
     limit,
     offset,
+    resourceId,
   }: {
     workflowName?: string;
     fromDate?: Date;
     toDate?: Date;
     limit?: number;
     offset?: number;
-  } = {}): Promise<{
-    runs: Array<{
-      workflowName: string;
-      runId: string;
-      snapshot: WorkflowRunState | string;
-      createdAt: Date;
-      updatedAt: Date;
-    }>;
-    total: number;
-  }> {
-    const conditions: string[] = [];
-    const args: InValue[] = [];
+    resourceId?: string;
+  } = {}): Promise<WorkflowRuns> {
+    try {
+      const conditions: string[] = [];
+      const args: InValue[] = [];
 
-    if (workflowName) {
-      conditions.push('workflow_name = ?');
-      args.push(workflowName);
+      if (workflowName) {
+        conditions.push('workflow_name = ?');
+        args.push(workflowName);
+      }
+
+      if (fromDate) {
+        conditions.push('createdAt >= ?');
+        args.push(fromDate.toISOString());
+      }
+
+      if (toDate) {
+        conditions.push('createdAt <= ?');
+        args.push(toDate.toISOString());
+      }
+
+      if (resourceId) {
+        const hasResourceId = await this.hasColumn(TABLE_WORKFLOW_SNAPSHOT, 'resourceId');
+        if (hasResourceId) {
+          conditions.push('resourceId = ?');
+          args.push(resourceId);
+        } else {
+          console.warn(`[${TABLE_WORKFLOW_SNAPSHOT}] resourceId column not found. Skipping resourceId filter.`);
+        }
+      }
+
+      const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+      let total = 0;
+      // Only get total count when using pagination
+      if (limit !== undefined && offset !== undefined) {
+        const countResult = await this.client.execute({
+          sql: `SELECT COUNT(*) as count FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
+          args,
+        });
+        total = Number(countResult.rows?.[0]?.count ?? 0);
+      }
+
+      // Get results
+      const result = await this.client.execute({
+        sql: `SELECT * FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause} ORDER BY createdAt DESC${limit !== undefined && offset !== undefined ? ` LIMIT ? OFFSET ?` : ''}`,
+        args: limit !== undefined && offset !== undefined ? [...args, limit, offset] : args,
+      });
+
+      const runs = (result.rows || []).map(row => this.parseWorkflowRun(row));
+
+      // Use runs.length as total when not paginating
+      return { runs, total: total || runs.length };
+    } catch (error) {
+      console.error('Error getting workflow runs:', error);
+      throw error;
     }
+  }
 
-    if (fromDate) {
-      conditions.push('createdAt >= ?');
-      args.push(fromDate.toISOString());
+  async getWorkflowRunById({
+    runId,
+    workflowName,
+  }: {
+    runId: string;
+    workflowName?: string;
+  }): Promise<WorkflowRun | null> {
+    const conditions: string[] = [];
+    const args: (string | number)[] = [];
+
+    if (runId) {
+      conditions.push('run_id = ?');
+      args.push(runId);
     }
 
-    if (toDate) {
-      conditions.push('createdAt <= ?');
-      args.push(toDate.toISOString());
+    if (workflowName) {
+      conditions.push('workflow_name = ?');
+      args.push(workflowName);
     }
 
     const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
 
-    let total = 0;
-    // Only get total count when using pagination
-    if (limit !== undefined && offset !== undefined) {
-      const countResult = await this.client.execute({
-        sql: `SELECT COUNT(*) as count FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
-        args,
-      });
-      total = Number(countResult.rows?.[0]?.count ?? 0);
-    }
-
-    // Get results
     const result = await this.client.execute({
-      sql: `SELECT * FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause} ORDER BY createdAt DESC${limit !== undefined && offset !== undefined ? ` LIMIT ? OFFSET ?` : ''}`,
-      args: limit !== undefined && offset !== undefined ? [...args, limit, offset] : args,
+      sql: `SELECT * FROM ${TABLE_WORKFLOW_SNAPSHOT} ${whereClause}`,
+      args,
     });
 
-    const runs = (result.rows || []).map(row => {
-      let parsedSnapshot: WorkflowRunState | string = row.snapshot as string;
-      if (typeof parsedSnapshot === 'string') {
-        try {
-          parsedSnapshot = JSON.parse(row.snapshot as string) as WorkflowRunState;
-        } catch (e) {
-          // If parsing fails, return the raw snapshot string
-          console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
-        }
-      }
+    if (!result.rows?.[0]) {
+      return null;
+    }
 
-      return {
-        workflowName: row.workflow_name as string,
-        runId: row.run_id as string,
-        snapshot: parsedSnapshot,
-        createdAt: new Date(row.createdAt as string),
-        updatedAt: new Date(row.updatedAt as string),
-      };
+    return this.parseWorkflowRun(result.rows[0]);
+  }
+
+  private async hasColumn(table: string, column: string): Promise<boolean> {
+    const result = await this.client.execute({
+      sql: `PRAGMA table_info(${table})`,
     });
+    return (await result.rows)?.some((row: any) => row.name === column);
+  }
 
-    // Use runs.length as total when not paginating
-    return { runs, total: total || runs.length };
+  private parseWorkflowRun(row: Record<string, any>): WorkflowRun {
+    let parsedSnapshot: WorkflowRunState | string = row.snapshot as string;
+    if (typeof parsedSnapshot === 'string') {
+      try {
+        parsedSnapshot = JSON.parse(row.snapshot as string) as WorkflowRunState;
+      } catch (e) {
+        // If parsing fails, return the raw snapshot string
+        console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
+      }
+    }
+    return {
+      workflowName: row.workflow_name as string,
+      runId: row.run_id as string,
+      snapshot: parsedSnapshot,
+      resourceId: row.resourceId as string,
+      createdAt: new Date(row.created_at as string),
+      updatedAt: new Date(row.updated_at as string),
+    };
   }
 }
 

package/src/vector/prompt.ts

@@ -0,0 +1,101 @@
+/**
+ * Vector store specific prompt that details supported operators and examples.
+ * This prompt helps users construct valid filters for LibSQL Vector.
+ */
+export const LIBSQL_PROMPT = `When querying LibSQL Vector, you can ONLY use the operators listed below. Any other operators will be rejected.
+Important: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.
+If a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.
+
+Basic Comparison Operators:
+- $eq: Exact match (default when using field: value)
+  Example: { "category": "electronics" }
+- $ne: Not equal
+  Example: { "category": { "$ne": "electronics" } }
+- $gt: Greater than
+  Example: { "price": { "$gt": 100 } }
+- $gte: Greater than or equal
+  Example: { "price": { "$gte": 100 } }
+- $lt: Less than
+  Example: { "price": { "$lt": 100 } }
+- $lte: Less than or equal
+  Example: { "price": { "$lte": 100 } }
+
+Array Operators:
+- $in: Match any value in array
+  Example: { "category": { "$in": ["electronics", "books"] } }
+- $nin: Does not match any value in array
+  Example: { "category": { "$nin": ["electronics", "books"] } }
+- $all: Match all values in array
+  Example: { "tags": { "$all": ["premium", "sale"] } }
+- $elemMatch: Match array elements that meet all specified conditions
+  Example: { "items": { "$elemMatch": { "price": { "$gt": 100 } } } }
+- $contains: Check if array contains value
+  Example: { "tags": { "$contains": "premium" } }
+
+Logical Operators:
+- $and: Logical AND (implicit when using multiple conditions)
+  Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+- $not: Logical NOT
+  Example: { "$not": { "category": "electronics" } }
+- $nor: Logical NOR
+  Example: { "$nor": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Element Operators:
+- $exists: Check if field exists
+  Example: { "rating": { "$exists": true } }
+
+Special Operators:
+- $size: Array length check
+  Example: { "tags": { "$size": 2 } }
+
+Restrictions:
+- Regex patterns are not supported
+- Direct RegExp patterns will throw an error
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported with both implicit and explicit $and
+- Array operations work on array fields only
+- Basic operators handle array values as JSON strings
+- Empty arrays in conditions are handled gracefully
+- Only logical operators ($and, $or, $not, $nor) can be used at the top level
+- All other operators must be used within a field condition
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$gt": 100 }
+  Invalid: { "$contains": "value" }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- $not operator:
+  - Must be an object
+  - Cannot be empty
+  - Can be used at field level or top level
+  - Valid: { "$not": { "field": "value" } }
+  - Valid: { "field": { "$not": { "$eq": "value" } } }
+- Other logical operators ($and, $or, $nor):
+  - Can only be used at top level or nested within other logical operators
+  - Can not be used on a field level, or be nested inside a field
+  - Can not be used inside an operator
+  - Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  - Valid: { "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }
+  - Invalid: { "field": { "$and": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$or": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$gt": { "$and": [{...}] } } }
+- $elemMatch requires an object with conditions
+  Valid: { "array": { "$elemMatch": { "field": "value" } } }
+  Invalid: { "array": { "$elemMatch": "value" } }
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "tags": { "$all": ["premium", "sale"] } },
+    { "items": { "$elemMatch": { "price": { "$gt": 50 }, "inStock": true } } },
+    { "$or": [
+      { "stock": { "$gt": 0 } },
+      { "preorder": true }
+    ]}
+  ]
+}`;