@mastra/pg 1.0.0-beta.12 → 1.0.0-beta.13

package/CHANGELOG.md

@@ -1,5 +1,132 @@
 # @mastra/pg
 
+## 1.0.0-beta.13
+
+### Minor Changes
+
+- Changed JSON columns from TEXT to JSONB in `mastra_threads` and `mastra_workflow_snapshot` tables. ([#11853](https://github.com/mastra-ai/mastra/pull/11853))
+
+  **Why this change?**
+
+  These were the last remaining columns storing JSON as TEXT. This change aligns them with other tables that already use JSONB, enabling native JSON operators and improved performance. See [#8978](https://github.com/mastra-ai/mastra/issues/8978) for details.
+
+  **Columns Changed:**
+  - `mastra_threads.metadata` - Thread metadata
+  - `mastra_workflow_snapshot.snapshot` - Workflow run state
+
+  **PostgreSQL**
+
+  Migration Required - PostgreSQL enforces column types, so existing tables must be migrated. Note: Migration will fail if existing column values contain invalid JSON.
+
+  ```sql
+  ALTER TABLE mastra_threads
+  ALTER COLUMN metadata TYPE jsonb
+  USING metadata::jsonb;
+
+  ALTER TABLE mastra_workflow_snapshot
+  ALTER COLUMN snapshot TYPE jsonb
+  USING snapshot::jsonb;
+  ```
+
+  **LibSQL**
+
+  No Migration Required - LibSQL now uses native SQLite JSONB format (added in SQLite 3.45) for ~3x performance improvement on JSON operations. The changes are fully backwards compatible:
+  - Existing TEXT JSON data continues to work
+  - New data is stored in binary JSONB format
+  - Both formats can coexist in the same table
+  - All JSON functions (`json_extract`, etc.) work on both formats
+
+  New installations automatically use JSONB. Existing applications continue to work without any changes.
+
+### Patch Changes
+
+- Fix `listWorkflowRuns` failing with "unsupported Unicode escape sequence" error when filtering by status on snapshots containing null characters (`\u0000`) or unpaired Unicode surrogates (`\uD800-\uDFFF`). ([#11616](https://github.com/mastra-ai/mastra/pull/11616))
+
+  The fix uses `regexp_replace` to sanitize problematic escape sequences before casting to JSONB in the WHERE clause, while preserving the original data in the returned results.
+
+- Fixed PostgreSQL migration errors when upgrading from v0.x to v1 ([#11633](https://github.com/mastra-ai/mastra/pull/11633))
+
+  **What changed:** PostgreSQL storage now automatically adds missing `spanId` and `requestContext` columns to the scorers table during initialization, preventing "column does not exist" errors when upgrading from v0.x to v1.0.0.
+
+  **Why:** Previously, upgrading to v1 could fail with errors like `column "requestContext" of relation "mastra_scorers" does not exist` if your database was created with an older version.
+
+  Related: #11631
+
+- Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. ([#11742](https://github.com/mastra-ai/mastra/pull/11742))
+
+  **Why this change?**
+
+  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.
+
+  **@mastra/libsql** (Breaking)
+
+  Renamed `connectionUrl` to `url` to match the `@libsql/client` API and align with LibSQLStorage.
+
+  ```typescript
+  // Before
+  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
+
+  // After
+  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });
+  ```
+
+  **@mastra/opensearch** (Breaking)
+
+  Renamed `url` to `node` and added support for all OpenSearch `ClientOptions` including authentication, SSL, and compression.
+
+  ```typescript
+  // Before
+  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
+
+  // After
+  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
+
+  // With authentication (now possible)
+  new OpenSearchVector({
+    id: 'my-vector',
+    node: 'https://localhost:9200',
+    auth: { username: 'admin', password: 'admin' },
+    ssl: { rejectUnauthorized: false },
+  });
+  ```
+
+  **@mastra/pinecone** (Breaking)
+
+  Removed `environment` parameter. Use `controllerHostUrl` instead (the actual Pinecone SDK field name). Added support for all `PineconeConfiguration` options.
+
+  ```typescript
+  // Before
+  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
+
+  // After
+  new PineconeVector({ id: 'my-vector', apiKey: '...' });
+
+  // With custom controller host (if needed)
+  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });
+  ```
+
+  **@mastra/clickhouse**
+
+  Added support for all `ClickHouseClientConfigOptions` like `request_timeout`, `compression`, `keep_alive`, and `database`. Existing configurations continue to work unchanged.
+
+  **@mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash**
+
+  Improved logging by replacing `console.warn` with structured logger in workflow storage domains.
+
+  **@mastra/deployer-cloud**
+
+  Updated internal LibSQLVector configuration for compatibility with the new API.
+
+- Fixed PostgreSQL storage issues after JSONB migration. ([#11906](https://github.com/mastra-ai/mastra/pull/11906))
+
+  **Bug Fixes**
+  - Fixed `clearTable()` using incorrect default schema. The method was checking for table existence in the 'mastra' schema instead of PostgreSQL's default 'public' schema, causing table truncation to be skipped and leading to duplicate key violations in tests and production code that uses `dangerouslyClearAll()`.
+  - Fixed `listWorkflowRuns()` status filter failing with "function regexp_replace(jsonb, ...) does not exist" error. After the TEXT to JSONB migration, the query tried to use `regexp_replace()` directly on a JSONB column. Now casts to text first: `regexp_replace(snapshot::text, ...)`.
+  - Added Unicode sanitization when persisting workflow snapshots to handle null characters (\u0000) and unpaired surrogates (\uD800-\uDFFF) that PostgreSQL's JSONB type rejects, preventing "unsupported Unicode escape sequence" errors.
+
+- Updated dependencies [[`ebae12a`](https://github.com/mastra-ai/mastra/commit/ebae12a2dd0212e75478981053b148a2c246962d), [`c61a0a5`](https://github.com/mastra-ai/mastra/commit/c61a0a5de4904c88fd8b3718bc26d1be1c2ec6e7), [`69136e7`](https://github.com/mastra-ai/mastra/commit/69136e748e32f57297728a4e0f9a75988462f1a7), [`449aed2`](https://github.com/mastra-ai/mastra/commit/449aed2ba9d507b75bf93d427646ea94f734dfd1), [`eb648a2`](https://github.com/mastra-ai/mastra/commit/eb648a2cc1728f7678768dd70cd77619b448dab9), [`0131105`](https://github.com/mastra-ai/mastra/commit/0131105532e83bdcbb73352fc7d0879eebf140dc), [`9d5059e`](https://github.com/mastra-ai/mastra/commit/9d5059eae810829935fb08e81a9bb7ecd5b144a7), [`ef756c6`](https://github.com/mastra-ai/mastra/commit/ef756c65f82d16531c43f49a27290a416611e526), [`b00ccd3`](https://github.com/mastra-ai/mastra/commit/b00ccd325ebd5d9e37e34dd0a105caae67eb568f), [`3bdfa75`](https://github.com/mastra-ai/mastra/commit/3bdfa7507a91db66f176ba8221aa28dd546e464a), [`e770de9`](https://github.com/mastra-ai/mastra/commit/e770de941a287a49b1964d44db5a5763d19890a6), [`52e2716`](https://github.com/mastra-ai/mastra/commit/52e2716b42df6eff443de72360ae83e86ec23993), [`27b4040`](https://github.com/mastra-ai/mastra/commit/27b4040bfa1a95d92546f420a02a626b1419a1d6), [`610a70b`](https://github.com/mastra-ai/mastra/commit/610a70bdad282079f0c630e0d7bb284578f20151), [`8dc7f55`](https://github.com/mastra-ai/mastra/commit/8dc7f55900395771da851dc7d78d53ae84fe34ec), [`8379099`](https://github.com/mastra-ai/mastra/commit/8379099fc467af6bef54dd7f80c9bd75bf8bbddf), [`8c0ec25`](https://github.com/mastra-ai/mastra/commit/8c0ec25646c8a7df253ed1e5ff4863a0d3f1316c), [`ff4d9a6`](https://github.com/mastra-ai/mastra/commit/ff4d9a6704fc87b31a380a76ed22736fdedbba5a), [`69821ef`](https://github.com/mastra-ai/mastra/commit/69821ef806482e2c44e2197ac0b050c3fe3a5285), [`1ed5716`](https://github.com/mastra-ai/mastra/commit/1ed5716830867b3774c4a1b43cc0d82935f32b96), [`4186bdd`](https://github.com/mastra-ai/mastra/commit/4186bdd00731305726fa06adba0b076a1d50b49f), [`7aaf973`](https://github.com/mastra-ai/mastra/commit/7aaf973f83fbbe9521f1f9e7a4fd99b8de464617)]:
+  - @mastra/core@1.0.0-beta.22
+
 ## 1.0.0-beta.12
 
 ### Patch Changes

package/dist/docs/README.md

@@ -33,4 +33,4 @@ docs/
 ## Version
 
 Package: @mastra/pg
-Version: 1.0.0-beta.12
+Version: 1.0.0-beta.13

package/dist/docs/SKILL.md

@@ -5,7 +5,7 @@ description: Documentation for @mastra/pg. Includes links to type definitions an
 
 # @mastra/pg Documentation
 
-> **Version**: 1.0.0-beta.12
+> **Version**: 1.0.0-beta.13
 > **Package**: @mastra/pg
 
 ## Quick Navigation

package/dist/docs/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.13",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/docs/memory/01-storage.md

@@ -4,11 +4,11 @@
 
 For Mastra to remember previous interactions, you must configure a storage adapter. Mastra is designed to work with your preferred database provider - choose from the [supported providers](#supported-providers) and pass it to your Mastra instance.
 
-```typescript 
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
-const mastra = new Mastra({
+export const mastra = new Mastra({
   storage: new LibSQLStore({
     id: 'mastra-storage',
     url: "file:./mastra.db",
@@ -17,7 +17,7 @@ const mastra = new Mastra({
 ```
 On first interaction, Mastra automatically creates the necessary tables following the [core schema](https://mastra.ai/reference/v1/storage/overview#core-schema). This includes tables for messages, threads, resources, workflows, traces, and evaluation datasets.
 
-## Supported Providers
+## Supported providers
 
 Each provider page includes installation instructions, configuration parameters, and usage examples:
 
@@ -35,19 +35,19 @@ Each provider page includes installation instructions, configuration parameters,
 > **Note:**
 libSQL is the easiest way to get started because it doesn’t require running a separate database server
 
-## Configuration Scope
+## Configuration scope
 
 You can configure storage at two different scopes:
 
 ### Instance-level storage
 
-Add storage to your Mastra instance so all agents share the same memory provider:
+Add storage to your Mastra instance so all agents, workflows, observability traces and scores share the same memory provider:
 
-```typescript 
+```typescript
 import { Mastra } from "@mastra/core";
 import { PostgresStore } from "@mastra/pg";
 
-const mastra = new Mastra({
+export const mastra = new Mastra({
   storage: new PostgresStore({
     id: 'mastra-storage',
     connectionString: process.env.DATABASE_URL,
@@ -55,20 +55,55 @@ const mastra = new Mastra({
 });
 
 // All agents automatically use this storage
-const agent1 = new Agent({ memory: new Memory() });
-const agent2 = new Agent({ memory: new Memory() });
+const agent1 = new Agent({ id: "agent-1", memory: new Memory() });
+const agent2 = new Agent({ id: "agent-2", memory: new Memory() });
+```
+
+This is useful when all primitives share the same storage backend and have similar performance, scaling, and operational requirements.
+
+#### Composite storage
+
+Add storage to your Mastra instance using `MastraStorage` and configure individual storage domains to use different storage providers.
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { MastraStorage } from "@mastra/core/storage";
+import { MemoryLibSQL } from "@mastra/libsql";
+import { WorkflowsPG } from "@mastra/pg";
+import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
+
+export const mastra = new Mastra({
+  storage: new MastraStorage({
+    id: "composite",
+    domains: {
+      memory: new MemoryLibSQL({ url: "file:./memory.db" }),
+      workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+      observability: new ObservabilityStorageClickhouse({
+        url: process.env.CLICKHOUSE_URL,
+        username: process.env.CLICKHOUSE_USERNAME,
+        password: process.env.CLICKHOUSE_PASSWORD,
+      }),
+    },
+  }),
+});
 ```
 
+This is useful when different types of data have different performance or operational requirements, such as low-latency storage for memory, durable storage for workflows, and high-throughput storage for observability.
+
+> **Note:**
+See [Storage Domains](https://mastra.ai/reference/v1/storage/composite#storage-domains) for more information.
+
 ### Agent-level storage
 
-Add storage to a specific agent when you need data boundaries or compliance requirements:
+Agent-level storage overrides storage configured at the instance-level. Add storage to a specific agent when you need data boundaries or compliance requirements:
 
-```typescript 
+```typescript title="src/mastra/agents/memory-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { PostgresStore } from "@mastra/pg";
 
-const agent = new Agent({
+export const agent = new Agent({
+  id: "agent",
   memory: new Memory({
     storage: new PostgresStore({
       id: 'agent-storage',
@@ -80,7 +115,7 @@ const agent = new Agent({
 
 This is useful when different agents need to store data in separate databases for security, compliance, or organizational reasons.
 
-## Threads and Resources
+## Threads and resources
 
 Mastra organizes memory into threads using two identifiers:
 
@@ -89,7 +124,7 @@ Mastra organizes memory into threads using two identifiers:
 
 Both identifiers are required for agents to store and recall information:
 
-```typescript 
+```typescript
 const stream = await agent.stream("message for agent", {
   memory: {
     thread: "convo_123",
@@ -107,8 +142,9 @@ Mastra can automatically generate descriptive thread titles based on the user's
 
 Use this option when implementing a ChatGPT-style chat interface to render a title alongside each thread in the conversation list (for example, in a sidebar) derived from the thread’s initial user message.
 
-```typescript 
+```typescript
 export const testAgent = new Agent({
+  id: "test-agent",
   memory: new Memory({
     options: {
       generateTitle: true,
@@ -123,13 +159,12 @@ To optimize cost or behavior, provide a smaller `model` and custom `instructions
 
 ```typescript
 export const testAgent = new Agent({
+  id: "test-agent",
   memory: new Memory({
     options: {
-      threads: {
-        generateTitle: {
-          model: "openai/gpt-4o-mini",
-          instructions: "Generate a concise title based on the user's first message",
-        },
+      generateTitle: {
+        model: "openai/gpt-4o-mini",
+        instructions: "Generate a concise title based on the user's first message",
       },
     },
   }),
@@ -142,7 +177,7 @@ Semantic recall uses vector embeddings to retrieve relevant past messages based
 
 The vector database doesn't have to be the same as your storage provider. For example, you might use PostgreSQL for storage and Pinecone for vectors:
 
-```typescript 
+```typescript
 import { Mastra } from "@mastra/core";
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
@@ -150,7 +185,7 @@ import { PostgresStore } from "@mastra/pg";
 import { PineconeVector } from "@mastra/pinecone";
 
 // Instance-level vector configuration
-const mastra = new Mastra({
+export const mastra = new Mastra({
   storage: new PostgresStore({
     id: 'mastra-storage',
     connectionString: process.env.DATABASE_URL,
@@ -158,13 +193,12 @@ const mastra = new Mastra({
 });
 
 // Agent-level vector configuration
-const agent = new Agent({
+export const agent = new Agent({
+  id: "agent",
   memory: new Memory({
     vector: new PineconeVector({
       id: 'agent-vector',
       apiKey: process.env.PINECONE_API_KEY,
-      environment: process.env.PINECONE_ENVIRONMENT,
-      indexName: 'agent-embeddings',
     }),
     options: {
       semanticRecall: {

package/dist/docs/memory/02-working-memory.md

@@ -80,13 +80,15 @@ const memory = new Memory({
 
 ### Usage with Agents
 
-When using resource-scoped memory, make sure to pass the `resourceId` parameter:
+When using resource-scoped memory, make sure to pass the `resource` parameter in the memory options:
 
 ```typescript
-// Resource-scoped memory requires resourceId
+// Resource-scoped memory requires resource
 const response = await agent.generate("Hello!", {
-  threadId: "conversation-123",
-  resourceId: "user-alice-456", // Same user across different threads
+  memory: {
+    thread: "conversation-123",
+    resource: "user-alice-456", // Same user across different threads
+  },
 });
 ```
 
@@ -339,8 +341,10 @@ const thread = await memory.createThread({
 
 // The agent will now have access to this information in all messages
 await agent.generate("What's my blood type?", {
-  threadId: thread.id,
-  resourceId: "user-456",
+  memory: {
+    thread: thread.id,
+    resource: "user-456",
+  },
 });
 // Response: "Your blood type is O+."
 ```

package/dist/docs/memory/03-semantic-recall.md

@@ -56,7 +56,7 @@ const agent = new Agent({
     // this is the default vector db if omitted
     vector: new LibSQLVector({
       id: 'agent-vector',
-      connectionUrl: "file:./local.db",
+      url: "file:./local.db",
     }),
   }),
 });
@@ -230,6 +230,4 @@ You might want to disable semantic recall in scenarios like:
 
 ## Viewing Recalled Messages
 
-When tracing is enabled, any messages retrieved via semantic recall will appear in the agent's trace output, alongside recent message history (if configured).
-
-For more info on viewing message traces, see [Viewing Retrieved Messages](./overview#viewing-retrieved-messages).
+When tracing is enabled, any messages retrieved via semantic recall will appear in the agent's trace output, alongside recent message history (if configured).

package/dist/docs/memory/04-reference.md

@@ -57,7 +57,7 @@ export const agent = new Agent({
     }),
     vector: new LibSQLVector({
       id: 'test-agent-vector',
-      connectionUrl: "file:./vector-memory.db",
+      url: "file:./vector-memory.db",
     }),
     options: {
       lastMessages: 10,
@@ -69,9 +69,7 @@ export const agent = new Agent({
       workingMemory: {
         enabled: true,
       },
-      threads: {
-        generateTitle: true,
-      },
+      generateTitle: true,
     },
   }),
 });

package/dist/docs/processors/01-reference.md

@@ -117,10 +117,12 @@ import { PgVector } from "@mastra/pg";
 import { openai } from "@ai-sdk/openai";
 
 const storage = new PostgresStorage({
+  id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
 });
 
 const vector = new PgVector({
+  id: 'pg-vector',
   connectionString: process.env.DATABASE_URL,
 });
 

package/dist/docs/rag/02-vector-databases.md

@@ -12,6 +12,7 @@ After generating embeddings, you need to store them in a database that supports
 import { MongoDBVector } from "@mastra/mongodb";
 
 const store = new MongoDBVector({
+  id: 'mongodb-vector',
   uri: process.env.MONGODB_URI,
   dbName: process.env.MONGODB_DATABASE,
 });
@@ -144,6 +145,7 @@ await store.upsert({
 import { AstraVector } from "@mastra/astra";
 
 const store = new AstraVector({
+  id: 'astra-vector',
   token: process.env.ASTRA_DB_TOKEN,
   endpoint: process.env.ASTRA_DB_ENDPOINT,
   keyspace: process.env.ASTRA_DB_KEYSPACE,
@@ -170,7 +172,7 @@ import { LibSQLVector } from "@mastra/core/vector/libsql";
 
 const store = new LibSQLVector({
   id: 'libsql-vector',
-  connectionUrl: process.env.DATABASE_URL,
+  url: process.env.DATABASE_URL,
   authToken: process.env.DATABASE_AUTH_TOKEN, // Optional: for Turso cloud databases
 });
 
@@ -217,6 +219,7 @@ await store.upsert({
 import { CloudflareVector } from "@mastra/vectorize";
 
 const store = new CloudflareVector({
+  id: 'cloudflare-vector',
   accountId: process.env.CF_ACCOUNT_ID,
   apiToken: process.env.CF_API_TOKEN,
 });
@@ -238,7 +241,7 @@ await store.upsert({
 ```ts title="vector-store.ts"
 import { OpenSearchVector } from "@mastra/opensearch";
 
-const store = new OpenSearchVector({ url: process.env.OPENSEARCH_URL });
+const store = new OpenSearchVector({ id: "opensearch", node: process.env.OPENSEARCH_URL });
 
 await store.createIndex({
   indexName: "my-collection",
@@ -259,7 +262,7 @@ await store.upsert({
 ```ts title="vector-store.ts"
 import { ElasticSearchVector } from "@mastra/elasticsearch";
 
-const store = new ElasticSearchVector({ url: process.env.ELASTICSEARCH_URL });
+const store = new ElasticSearchVector({ id: 'elasticsearch-vector', url: process.env.ELASTICSEARCH_URL });
 
 await store.createIndex({
   indexName: "my-collection",
@@ -280,6 +283,7 @@ await store.upsert({
 import { CouchbaseVector } from "@mastra/couchbase";
 
 const store = new CouchbaseVector({
+  id: 'couchbase-vector',
   connectionString: process.env.COUCHBASE_CONNECTION_STRING,
   username: process.env.COUCHBASE_USERNAME,
   password: process.env.COUCHBASE_PASSWORD,
@@ -331,6 +335,7 @@ For detailed setup instructions and best practices, see the [official LanceDB do
 import { S3Vectors } from "@mastra/s3vectors";
 
 const store = new S3Vectors({
+  id: 's3-vectors',
   vectorBucketName: "my-vector-bucket",
   clientConfig: {
     region: "us-east-1",
@@ -373,7 +378,7 @@ The dimension size must match the output dimension of your chosen embedding mode
 - Cohere embed-multilingual-v3: 1024 dimensions
 - Google text-embedding-004: 768 dimensions (or custom)
 
-important
+> **Note:**
 Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
 
 ### Naming Rules for Databases
@@ -537,7 +542,7 @@ The upsert operation:
 
 Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
 
-important
+> **Note:**
 Metadata is crucial for vector storage - without it, you'd only have numerical embeddings with no way to return the original text or filter results. Always store at least the source text as metadata.
 
 ```ts

package/dist/docs/rag/03-retrieval.md

@@ -171,7 +171,7 @@ The Vector Query Tool supports database-specific configurations that enable you
 > **Note:**
 These configurations are for **query-time options** like namespaces, performance tuning, and filtering—not for database connection setup. 
 
-Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ connectionUrl: '...' })`).
+Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ url: '...' })`).
 
 ```ts
 import { createVectorQueryTool } from "@mastra/rag";
@@ -258,11 +258,10 @@ requestContext.set("databaseConfig", {
   },
 });
 
-await pineconeQueryTool.execute({
-  context: { queryText: "search query" },
-  mastra,
-  requestContext,
-});
+await pineconeQueryTool.execute(
+  { queryText: "search query" },
+  { mastra, requestContext }
+);
 ```
 
 For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](https://mastra.ai/reference/v1/tools/vector-query-tool).

package/dist/docs/rag/04-reference.md

@@ -295,6 +295,24 @@ const results = await store.query({
 
 - Supports advanced filtering with nested conditions
 - Payload (metadata) fields must be explicitly indexed for filtering
+- Use `createPayloadIndex()` to index fields you want to filter on:
+
+```typescript
+// Index a field before filtering on it
+await store.createPayloadIndex({
+  indexName: "my_index",
+  fieldName: "source",
+  fieldSchema: "keyword", // 'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'
+});
+
+// Now filtering works
+const results = await store.query({
+  indexName: "my_index",
+  queryVector: queryVector,
+  filter: { source: "document-a" },
+});
+```
+
 - Efficient handling of geo-spatial queries
 - Special handling for null and empty values
 - Vector-specific filtering capabilities