@mastra/astra 0.2.12-alpha.3 → 0.2.12-alpha.5

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/astra@0.2.12-alpha.3 build /home/runner/work/mastra/mastra/stores/astra
+> @mastra/astra@0.2.12-alpha.5 build /home/runner/work/mastra/mastra/stores/astra
 > 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 7673ms
+TSC ⚡️ Build success in 6781ms
 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/astra/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/astra/dist/_tsup-dts-rollup.d.cts
-DTS ⚡️ Build success in 8550ms
+DTS ⚡️ Build success in 9377ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.cjs 7.09 KB
-CJS ⚡️ Build success in 613ms
-ESM dist/index.js 7.06 KB
-ESM ⚡️ Build success in 613ms
+CJS dist/index.cjs 10.60 KB
+CJS ⚡️ Build success in 602ms
+ESM dist/index.js 10.54 KB
+ESM ⚡️ Build success in 612ms

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @mastra/astra
 
+## 0.2.12-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.2.12-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [e4943b8]
+- Updated dependencies [479f490]
+  - @mastra/core@0.9.1-alpha.4
+
 ## 0.2.12-alpha.3
 
 ### Patch Changes

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

@@ -9,6 +9,14 @@ import type { QueryVectorParams } from '@mastra/core/vector';
 import type { UpsertVectorParams } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
 
+/**
+ * Vector store specific prompt that details supported operators and examples.
+ * This prompt helps users construct valid filters for Astra Vector.
+ */
+declare const ASTRA_PROMPT = "When querying Astra, 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\nLogical Operators:\n- $and: Logical AND (can be implicit or explicit)\n  Implicit Example: { \"price\": { \"$gt\": 100 }, \"category\": \"electronics\" }\n  Explicit 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\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- Only $and, $or, and $not logical operators are supported\n- Nested fields are supported using dot notation\n- Multiple conditions on the same field are supported with both implicit and explicit $and\n- Empty arrays in $in/$nin will return no results\n- A non-empty array is required for $all operator\n- Only logical operators ($and, $or, $not) 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- 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):\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\nExample Complex Query:\n{\n  \"$and\": [\n    { \"category\": { \"$in\": [\"electronics\", \"computers\"] } },\n    { \"price\": { \"$gte\": 100, \"$lte\": 1000 } },\n    { \"tags\": { \"$all\": [\"premium\"] } },\n    { \"rating\": { \"$exists\": true, \"$gt\": 4 } },\n    { \"$or\": [\n      { \"stock\": { \"$gt\": 0 } },\n      { \"preorder\": true }\n    ]}\n  ]\n}";
+export { ASTRA_PROMPT }
+export { ASTRA_PROMPT as ASTRA_PROMPT_alias_1 }
+
 declare interface AstraDbOptions {
     token: string;
     endpoint: string;

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

@@ -9,6 +9,14 @@ import type { QueryVectorParams } from '@mastra/core/vector';
 import type { UpsertVectorParams } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
 
+/**
+ * Vector store specific prompt that details supported operators and examples.
+ * This prompt helps users construct valid filters for Astra Vector.
+ */
+declare const ASTRA_PROMPT = "When querying Astra, 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\nLogical Operators:\n- $and: Logical AND (can be implicit or explicit)\n  Implicit Example: { \"price\": { \"$gt\": 100 }, \"category\": \"electronics\" }\n  Explicit 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\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- Only $and, $or, and $not logical operators are supported\n- Nested fields are supported using dot notation\n- Multiple conditions on the same field are supported with both implicit and explicit $and\n- Empty arrays in $in/$nin will return no results\n- A non-empty array is required for $all operator\n- Only logical operators ($and, $or, $not) 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- 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):\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\nExample Complex Query:\n{\n  \"$and\": [\n    { \"category\": { \"$in\": [\"electronics\", \"computers\"] } },\n    { \"price\": { \"$gte\": 100, \"$lte\": 1000 } },\n    { \"tags\": { \"$all\": [\"premium\"] } },\n    { \"rating\": { \"$exists\": true, \"$gt\": 4 } },\n    { \"$or\": [\n      { \"stock\": { \"$gt\": 0 } },\n      { \"preorder\": true }\n    ]}\n  ]\n}";
+export { ASTRA_PROMPT }
+export { ASTRA_PROMPT as ASTRA_PROMPT_alias_1 }
+
 declare interface AstraDbOptions {
     token: string;
     endpoint: string;

package/dist/index.cjs

@@ -195,4 +195,94 @@ var AstraVector = class extends vector.MastraVector {
   }
 };
 
+// src/vector/prompt.ts
+var ASTRA_PROMPT = `When querying Astra, 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"] } }
+
+Logical Operators:
+- $and: Logical AND (can be implicit or explicit)
+  Implicit Example: { "price": { "$gt": 100 }, "category": "electronics" }
+  Explicit Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+- $not: Logical NOT
+  Example: { "$not": { "category": "electronics" } }
+
+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
+- Only $and, $or, and $not logical operators are supported
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported with both implicit and explicit $and
+- Empty arrays in $in/$nin will return no results
+- A non-empty array is required for $all operator
+- Only logical operators ($and, $or, $not) 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 }
+- 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):
+  - 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": [{...}] } } }
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "tags": { "$all": ["premium"] } },
+    { "rating": { "$exists": true, "$gt": 4 } },
+    { "$or": [
+      { "stock": { "$gt": 0 } },
+      { "preorder": true }
+    ]}
+  ]
+}`;
+
+exports.ASTRA_PROMPT = ASTRA_PROMPT;
 exports.AstraVector = AstraVector;

package/dist/index.d.cts

@@ -1,2 +1,3 @@
+export { ASTRA_PROMPT } from './_tsup-dts-rollup.cjs';
 export { AstraDbOptions } from './_tsup-dts-rollup.cjs';
 export { AstraVector } from './_tsup-dts-rollup.cjs';

package/dist/index.d.ts

@@ -1,2 +1,3 @@
+export { ASTRA_PROMPT } from './_tsup-dts-rollup.js';
 export { AstraDbOptions } from './_tsup-dts-rollup.js';
 export { AstraVector } from './_tsup-dts-rollup.js';

package/dist/index.js

@@ -193,4 +193,93 @@ var AstraVector = class extends MastraVector {
   }
 };
 
-export { AstraVector };
+// src/vector/prompt.ts
+var ASTRA_PROMPT = `When querying Astra, 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"] } }
+
+Logical Operators:
+- $and: Logical AND (can be implicit or explicit)
+  Implicit Example: { "price": { "$gt": 100 }, "category": "electronics" }
+  Explicit Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+- $not: Logical NOT
+  Example: { "$not": { "category": "electronics" } }
+
+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
+- Only $and, $or, and $not logical operators are supported
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported with both implicit and explicit $and
+- Empty arrays in $in/$nin will return no results
+- A non-empty array is required for $all operator
+- Only logical operators ($and, $or, $not) 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 }
+- 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):
+  - 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": [{...}] } } }
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "tags": { "$all": ["premium"] } },
+    { "rating": { "$exists": true, "$gt": 4 } },
+    { "$or": [
+      { "stock": { "$gt": 0 } },
+      { "preorder": true }
+    ]}
+  ]
+}`;
+
+export { ASTRA_PROMPT, AstraVector };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/astra",
-  "version": "0.2.12-alpha.3",
+  "version": "0.2.12-alpha.5",
   "description": "Astra DB provider for Mastra - includes vector store capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -21,15 +21,15 @@
   "license": "MIT",
   "dependencies": {
     "@datastax/astra-db-ts": "^1.5.0",
-    "@mastra/core": "^0.9.1-alpha.3"
+    "@mastra/core": "^0.9.1-alpha.5"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.52.1",
+    "@microsoft/api-extractor": "^7.52.5",
     "@types/node": "^20.17.27",
     "eslint": "^9.23.0",
     "tsup": "^8.4.0",
     "typescript": "^5.8.2",
-    "vitest": "^3.0.9",
+    "vitest": "^3.1.2",
     "@internal/lint": "0.0.2"
   },
   "scripts": {

package/src/index.ts

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

package/src/vector/index.test.ts

@@ -58,7 +58,7 @@ async function deleteIndexAndWait(vectorDB: AstraVector, indexName: string) {
   }
 }
 
-describe('AstraVector Integration Tests', () => {
+describe.skip('AstraVector Integration Tests', () => {
   let vectorDB: AstraVector;
   const testIndexName = 'testvectors1733728136118'; // Unique collection name
   const testIndexName2 = 'testvectors1733728136119'; // Unique collection name

package/src/vector/prompt.ts

@@ -0,0 +1,91 @@
+/**
+ * Vector store specific prompt that details supported operators and examples.
+ * This prompt helps users construct valid filters for Astra Vector.
+ */
+export const ASTRA_PROMPT = `When querying Astra, 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"] } }
+
+Logical Operators:
+- $and: Logical AND (can be implicit or explicit)
+  Implicit Example: { "price": { "$gt": 100 }, "category": "electronics" }
+  Explicit Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+- $not: Logical NOT
+  Example: { "$not": { "category": "electronics" } }
+
+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
+- Only $and, $or, and $not logical operators are supported
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported with both implicit and explicit $and
+- Empty arrays in $in/$nin will return no results
+- A non-empty array is required for $all operator
+- Only logical operators ($and, $or, $not) 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 }
+- 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):
+  - 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": [{...}] } } }
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "tags": { "$all": ["premium"] } },
+    { "rating": { "$exists": true, "$gt": 4 } },
+    { "$or": [
+      { "stock": { "$gt": 0 } },
+      { "preorder": true }
+    ]}
+  ]
+}`;