@mastra/rag 0.1.20-alpha.1 → 0.1.20-alpha.3

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/rag@0.1.20-alpha.1 build /home/runner/work/mastra/mastra/packages/rag
+> @mastra/rag@0.1.20-alpha.3 build /home/runner/work/mastra/mastra/packages/rag
 > 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 15527ms
+TSC ⚡️ Build success in 15036ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.8.2
 Writing package typings: /home/runner/work/mastra/mastra/packages/rag/dist/_tsup-dts-rollup.d.ts
 Analysis will use the bundled TypeScript version 5.8.2
 Writing package typings: /home/runner/work/mastra/mastra/packages/rag/dist/_tsup-dts-rollup.d.cts
-DTS ⚡️ Build success in 12190ms
+DTS ⚡️ Build success in 12853ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.js 232.46 KB
-ESM ⚡️ Build success in 4467ms
-CJS dist/index.cjs 234.13 KB
-CJS ⚡️ Build success in 4471ms
+CJS dist/index.cjs 237.80 KB
+CJS ⚡️ Build success in 4424ms
+ESM dist/index.js 236.10 KB
+ESM ⚡️ Build success in 4424ms

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mastra/rag
 
+## 0.1.20-alpha.3
+
+### Patch Changes
+
+- c4c6f04: added and updated docs for mongodb
+- Updated dependencies [6262bd5]
+  - @mastra/core@0.9.1-alpha.3
+
+## 0.1.20-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [405b63d]
+- Updated dependencies [61e92f5]
+- Updated dependencies [c71013a]
+  - @mastra/core@0.9.1-alpha.2
+
 ## 0.1.20-alpha.1
 
 ### Patch Changes

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

@@ -518,6 +518,10 @@ declare type Metadata = Record<string, any>;
 export { Metadata }
 export { Metadata as Metadata_alias_1 }
 
+declare const MONGODB_PROMPT = "When querying MongoDB, 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 by criteria\n  Example: { \"scores\": { \"$elemMatch\": { \"$gt\": 80 } } }\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: { \"field\": { \"$not\": { \"$eq\": \"value\" } } }\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- $regex: Regular expression match\n  Example: { \"title\": { \"$regex\": \"^laptop\", \"$options\": \"i\" } }\n- $size: Array length check\n  Example: { \"tags\": { \"$size\": 2 } }\n\nUsage Notes:\n- You can use both 'filter' (for metadata fields) and 'documentFilter' (for document content fields).\n- Nested fields are supported using dot notation (e.g., \"metadata.author.name\").\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- All logical operators ($and, $or, $not, $nor) can be used at the top level or nested.\n- All other operators must be used within a field condition.\n  Valid: { \"field\": { \"$gt\": 100 } }\n  Valid: { \"$and\": [...] }\n  Invalid: { \"$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- Logical operators must contain field conditions, not direct operators\n  Valid: { \"$and\": [{ \"field\": { \"$gt\": 100 } }] }\n  Invalid: { \"$and\": [{ \"$gt\": 100 }] }\n- Regex uses standard MongoDB regex syntax (with optional $options).\n- Metadata values can be strings, numbers, booleans, or arrays.\n- Metadata and document fields can be filtered in the same query.\n\nExample Complex Query:\n{\n  \"category\": { \"$in\": [\"electronics\", \"computers\"] },\n  \"price\": { \"$gte\": 100, \"$lte\": 1000 },\n  \"inStock\": true,\n  \"title\": { \"$regex\": \"laptop\", \"$options\": \"i\" },\n  \"$or\": [\n    { \"brand\": \"Apple\" },\n    { \"rating\": { \"$gte\": 4.5 } }\n  ]\n}\n";
+export { MONGODB_PROMPT }
+export { MONGODB_PROMPT as MONGODB_PROMPT_alias_1 }
+
 declare enum NodeRelationship {
     SOURCE = "SOURCE",
     PREVIOUS = "PREVIOUS",

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

@@ -518,6 +518,10 @@ declare type Metadata = Record<string, any>;
 export { Metadata }
 export { Metadata as Metadata_alias_1 }
 
+declare const MONGODB_PROMPT = "When querying MongoDB, 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 by criteria\n  Example: { \"scores\": { \"$elemMatch\": { \"$gt\": 80 } } }\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: { \"field\": { \"$not\": { \"$eq\": \"value\" } } }\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- $regex: Regular expression match\n  Example: { \"title\": { \"$regex\": \"^laptop\", \"$options\": \"i\" } }\n- $size: Array length check\n  Example: { \"tags\": { \"$size\": 2 } }\n\nUsage Notes:\n- You can use both 'filter' (for metadata fields) and 'documentFilter' (for document content fields).\n- Nested fields are supported using dot notation (e.g., \"metadata.author.name\").\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- All logical operators ($and, $or, $not, $nor) can be used at the top level or nested.\n- All other operators must be used within a field condition.\n  Valid: { \"field\": { \"$gt\": 100 } }\n  Valid: { \"$and\": [...] }\n  Invalid: { \"$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- Logical operators must contain field conditions, not direct operators\n  Valid: { \"$and\": [{ \"field\": { \"$gt\": 100 } }] }\n  Invalid: { \"$and\": [{ \"$gt\": 100 }] }\n- Regex uses standard MongoDB regex syntax (with optional $options).\n- Metadata values can be strings, numbers, booleans, or arrays.\n- Metadata and document fields can be filtered in the same query.\n\nExample Complex Query:\n{\n  \"category\": { \"$in\": [\"electronics\", \"computers\"] },\n  \"price\": { \"$gte\": 100, \"$lte\": 1000 },\n  \"inStock\": true,\n  \"title\": { \"$regex\": \"laptop\", \"$options\": \"i\" },\n  \"$or\": [\n    { \"brand\": \"Apple\" },\n    { \"rating\": { \"$gte\": 4.5 } }\n  ]\n}\n";
+export { MONGODB_PROMPT }
+export { MONGODB_PROMPT as MONGODB_PROMPT_alias_1 }
+
 declare enum NodeRelationship {
     SOURCE = "SOURCE",
     PREVIOUS = "PREVIOUS",

package/dist/index.cjs

@@ -2309,11 +2309,23 @@ var reasoningModels = {
   "o1-preview-2024-09-12": {
     systemMessageMode: "remove"
   },
+  o3: {
+    systemMessageMode: "developer"
+  },
+  "o3-2025-04-16": {
+    systemMessageMode: "developer"
+  },
   "o3-mini": {
     systemMessageMode: "developer"
   },
   "o3-mini-2025-01-31": {
     systemMessageMode: "developer"
+  },
+  "o4-mini": {
+    systemMessageMode: "developer"
+  },
+  "o4-mini-2025-04-16": {
+    systemMessageMode: "developer"
   }
 };
 function convertToOpenAICompletionPrompt({
@@ -7213,12 +7225,97 @@ Example Complex Query:
   "price": { "$gte": 100, "$lte": 1000 },
   "inStock": true
 }`;
+var MONGODB_PROMPT = `When querying MongoDB, 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 by criteria
+  Example: { "scores": { "$elemMatch": { "$gt": 80 } } }
+
+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: { "field": { "$not": { "$eq": "value" } } }
+- $nor: Logical NOR
+  Example: { "$nor": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Element Operators:
+- $exists: Check if field exists
+  Example: { "rating": { "$exists": true } }
+
+Special Operators:
+- $regex: Regular expression match
+  Example: { "title": { "$regex": "^laptop", "$options": "i" } }
+- $size: Array length check
+  Example: { "tags": { "$size": 2 } }
+
+Usage Notes:
+- You can use both 'filter' (for metadata fields) and 'documentFilter' (for document content fields).
+- Nested fields are supported using dot notation (e.g., "metadata.author.name").
+- Multiple conditions on the same field are supported with both implicit and explicit $and.
+- Empty arrays in $in/$nin will return no results.
+- All logical operators ($and, $or, $not, $nor) can be used at the top level or nested.
+- All other operators must be used within a field condition.
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$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" } } }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- Regex uses standard MongoDB regex syntax (with optional $options).
+- Metadata values can be strings, numbers, booleans, or arrays.
+- Metadata and document fields can be filtered in the same query.
+
+Example Complex Query:
+{
+  "category": { "$in": ["electronics", "computers"] },
+  "price": { "$gte": 100, "$lte": 1000 },
+  "inStock": true,
+  "title": { "$regex": "laptop", "$options": "i" },
+  "$or": [
+    { "brand": "Apple" },
+    { "rating": { "$gte": 4.5 } }
+  ]
+}
+`;
 
 exports.ASTRA_PROMPT = ASTRA_PROMPT;
 exports.CHROMA_PROMPT = CHROMA_PROMPT;
 exports.GraphRAG = GraphRAG;
 exports.LIBSQL_PROMPT = LIBSQL_PROMPT;
 exports.MDocument = MDocument;
+exports.MONGODB_PROMPT = MONGODB_PROMPT;
 exports.PGVECTOR_PROMPT = PGVECTOR_PROMPT;
 exports.PINECONE_PROMPT = PINECONE_PROMPT;
 exports.QDRANT_PROMPT = QDRANT_PROMPT;

package/dist/index.d.cts

@@ -16,6 +16,7 @@ export { PINECONE_PROMPT } from './_tsup-dts-rollup.cjs';
 export { QDRANT_PROMPT } from './_tsup-dts-rollup.cjs';
 export { UPSTASH_PROMPT } from './_tsup-dts-rollup.cjs';
 export { VECTORIZE_PROMPT } from './_tsup-dts-rollup.cjs';
+export { MONGODB_PROMPT } from './_tsup-dts-rollup.cjs';
 export { defaultVectorQueryDescription } from './_tsup-dts-rollup.cjs';
 export { defaultGraphRagDescription } from './_tsup-dts-rollup.cjs';
 export { queryTextDescription } from './_tsup-dts-rollup.cjs';

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export { PINECONE_PROMPT } from './_tsup-dts-rollup.js';
 export { QDRANT_PROMPT } from './_tsup-dts-rollup.js';
 export { UPSTASH_PROMPT } from './_tsup-dts-rollup.js';
 export { VECTORIZE_PROMPT } from './_tsup-dts-rollup.js';
+export { MONGODB_PROMPT } from './_tsup-dts-rollup.js';
 export { defaultVectorQueryDescription } from './_tsup-dts-rollup.js';
 export { defaultGraphRagDescription } from './_tsup-dts-rollup.js';
 export { queryTextDescription } from './_tsup-dts-rollup.js';

package/dist/index.js

@@ -2307,11 +2307,23 @@ var reasoningModels = {
   "o1-preview-2024-09-12": {
     systemMessageMode: "remove"
   },
+  o3: {
+    systemMessageMode: "developer"
+  },
+  "o3-2025-04-16": {
+    systemMessageMode: "developer"
+  },
   "o3-mini": {
     systemMessageMode: "developer"
   },
   "o3-mini-2025-01-31": {
     systemMessageMode: "developer"
+  },
+  "o4-mini": {
+    systemMessageMode: "developer"
+  },
+  "o4-mini-2025-04-16": {
+    systemMessageMode: "developer"
   }
 };
 function convertToOpenAICompletionPrompt({
@@ -7211,5 +7223,89 @@ Example Complex Query:
   "price": { "$gte": 100, "$lte": 1000 },
   "inStock": true
 }`;
+var MONGODB_PROMPT = `When querying MongoDB, 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 by criteria
+  Example: { "scores": { "$elemMatch": { "$gt": 80 } } }
+
+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: { "field": { "$not": { "$eq": "value" } } }
+- $nor: Logical NOR
+  Example: { "$nor": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Element Operators:
+- $exists: Check if field exists
+  Example: { "rating": { "$exists": true } }
+
+Special Operators:
+- $regex: Regular expression match
+  Example: { "title": { "$regex": "^laptop", "$options": "i" } }
+- $size: Array length check
+  Example: { "tags": { "$size": 2 } }
+
+Usage Notes:
+- You can use both 'filter' (for metadata fields) and 'documentFilter' (for document content fields).
+- Nested fields are supported using dot notation (e.g., "metadata.author.name").
+- Multiple conditions on the same field are supported with both implicit and explicit $and.
+- Empty arrays in $in/$nin will return no results.
+- All logical operators ($and, $or, $not, $nor) can be used at the top level or nested.
+- All other operators must be used within a field condition.
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$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" } } }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- Regex uses standard MongoDB regex syntax (with optional $options).
+- Metadata values can be strings, numbers, booleans, or arrays.
+- Metadata and document fields can be filtered in the same query.
+
+Example Complex Query:
+{
+  "category": { "$in": ["electronics", "computers"] },
+  "price": { "$gte": 100, "$lte": 1000 },
+  "inStock": true,
+  "title": { "$regex": "laptop", "$options": "i" },
+  "$or": [
+    { "brand": "Apple" },
+    { "rating": { "$gte": 4.5 } }
+  ]
+}
+`;
 
-export { ASTRA_PROMPT, CHROMA_PROMPT, GraphRAG, LIBSQL_PROMPT, MDocument, PGVECTOR_PROMPT, PINECONE_PROMPT, QDRANT_PROMPT, UPSTASH_PROMPT, VECTORIZE_PROMPT, createDocumentChunkerTool, createGraphRAGTool, createVectorQueryTool, defaultGraphRagDescription, defaultVectorQueryDescription, filterDescription, queryTextDescription, rerank, topKDescription };
+export { ASTRA_PROMPT, CHROMA_PROMPT, GraphRAG, LIBSQL_PROMPT, MDocument, MONGODB_PROMPT, PGVECTOR_PROMPT, PINECONE_PROMPT, QDRANT_PROMPT, UPSTASH_PROMPT, VECTORIZE_PROMPT, createDocumentChunkerTool, createGraphRAGTool, createVectorQueryTool, defaultGraphRagDescription, defaultVectorQueryDescription, filterDescription, queryTextDescription, rerank, topKDescription };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/rag",
-  "version": "0.1.20-alpha.1",
+  "version": "0.1.20-alpha.3",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "node-html-better-parser": "^1.4.7",
     "pathe": "^2.0.3",
     "zod": "^3.24.2",
-    "@mastra/core": "^0.9.1-alpha.1"
+    "@mastra/core": "^0.9.1-alpha.3"
   },
   "peerDependencies": {
     "ai": "^4.0.0"

package/src/utils/vector-prompts.ts

@@ -727,3 +727,88 @@ Example Complex Query:
   "price": { "$gte": 100, "$lte": 1000 },
   "inStock": true
 }`;
+
+export const MONGODB_PROMPT = `When querying MongoDB, 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 by criteria
+  Example: { "scores": { "$elemMatch": { "$gt": 80 } } }
+
+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: { "field": { "$not": { "$eq": "value" } } }
+- $nor: Logical NOR
+  Example: { "$nor": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Element Operators:
+- $exists: Check if field exists
+  Example: { "rating": { "$exists": true } }
+
+Special Operators:
+- $regex: Regular expression match
+  Example: { "title": { "$regex": "^laptop", "$options": "i" } }
+- $size: Array length check
+  Example: { "tags": { "$size": 2 } }
+
+Usage Notes:
+- You can use both 'filter' (for metadata fields) and 'documentFilter' (for document content fields).
+- Nested fields are supported using dot notation (e.g., "metadata.author.name").
+- Multiple conditions on the same field are supported with both implicit and explicit $and.
+- Empty arrays in $in/$nin will return no results.
+- All logical operators ($and, $or, $not, $nor) can be used at the top level or nested.
+- All other operators must be used within a field condition.
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$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" } } }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- Regex uses standard MongoDB regex syntax (with optional $options).
+- Metadata values can be strings, numbers, booleans, or arrays.
+- Metadata and document fields can be filtered in the same query.
+
+Example Complex Query:
+{
+  "category": { "$in": ["electronics", "computers"] },
+  "price": { "$gte": 100, "$lte": 1000 },
+  "inStock": true,
+  "title": { "$regex": "laptop", "$options": "i" },
+  "$or": [
+    { "brand": "Apple" },
+    { "rating": { "$gte": 4.5 } }
+  ]
+}
+`;