@mastra/pg 1.7.2 → 1.8.0

package/dist/docs/references/reference-rag-metadata-filters.md

@@ -1,8 +1,8 @@
-# Metadata Filters
+# Metadata filters
 
 Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into their native format.
 
-## Basic Example
+## Basic example
 
 ```typescript
 import { PgVector } from '@mastra/pg'
@@ -24,7 +24,7 @@ const results = await store.query({
 })
 ```
 
-## Supported Operators
+## Supported operators
 
 ### Basic Comparison
 
@@ -46,9 +46,9 @@ const results = await store.query({
 
 `$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB`$size`Array length check{ tags: { $size: { $gt: 2 } } }Supported by: Astra, libSQL, PgVector, MongoDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
 
-## Common Rules and Restrictions
+## Common rules and restrictions
 
-1. Field names cannot:
+1. Field names can't:
 
    - Contain dots (.) unless referring to nested fields
    - Start with $ or contain null characters
@@ -63,11 +63,11 @@ const results = await store.query({
 3. Logical operators:
 
    - Must contain valid conditions
-   - Cannot be empty
+   - Can't be empty
    - Must be properly nested
    - Can only be used at top level or nested within other logical operators
-   - Cannot be used at field level or nested inside a field
-   - Cannot be used inside an operator
+   - Can't be used at field level or nested inside a field
+   - Can't be used inside an operator
    - Valid: `{ "$and": [{ "field": { "$gt": 100 } }] }`
    - Valid: `{ "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }`
    - Invalid: `{ "field": { "$and": [{ "$gt": 100 }] } }`
@@ -76,7 +76,7 @@ const results = await store.query({
 4. $not operator:
 
    - Must be an object
-   - Cannot be empty
+   - Can't be empty
    - Can be used at field level or top level
    - Valid: `{ "$not": { "field": "value" } }`
    - Valid: `{ "field": { "$not": { "$eq": "value" } } }`
@@ -87,7 +87,7 @@ const results = await store.query({
    - Valid: `{ "$and": [{ "field": { "$gt": 100 } }] }`
    - Invalid: `{ "$and": [{ "$gt": 100 }] }`
 
-## Store-Specific Notes
+## Store-specific notes
 
 ### Astra
 
@@ -98,7 +98,7 @@ const results = await store.query({
 ### ChromaDB
 
 - Where filters only return results where the filtered field exists in metadata
-- Empty metadata fields are not included in filter results
+- Empty metadata fields aren't included in filter results
 - Metadata fields must be present for negative matches (e.g., $ne won't match documents missing the field)
 
 ### Cloudflare Vectorize
@@ -109,7 +109,7 @@ const results = await store.query({
 - String values are indexed up to first 64 bytes (truncated on UTF-8 boundaries)
 - Number values use float64 precision
 - Filter JSON must be under 2048 bytes
-- Field names cannot contain dots (.) or start with $
+- Field names can't contain dots (.) or start with $
 - Field names limited to 512 characters
 - Vectors must be re-upserted after creating new metadata indexes to be included in filtered results
 - Range queries may have reduced accuracy with very large datasets (\~10M+ vectors)
@@ -186,12 +186,12 @@ const results = await store.query({
 
 ### Couchbase
 
-- Currently does not have support for metadata filters. Filtering must be done client-side after retrieving results or by using the Couchbase SDK's Search capabilities directly for more complex queries.
+- Currently doesn't have support for metadata filters. Filtering must be done client-side after retrieving results or by using the Couchbase SDK's Search capabilities directly for more complex queries.
 
 ### Amazon S3 Vectors
 
-- Equality values must be primitives (string/number/boolean). `null`/`undefined`, arrays, objects, and Date are not allowed for equality. Range operators accept numbers or Date (Dates are normalized to epoch ms).
-- `$in`/`$nin` require **non-empty arrays of primitives**; Date elements are allowed and normalized to epoch ms. **Array equality** is not supported.
+- Equality values must be primitives (string/number/boolean). `null`/`undefined`, arrays, objects, and Date aren't allowed for equality. Range operators accept numbers or Date (Dates are normalized to epoch ms).
+- `$in`/`$nin` require **non-empty arrays of primitives**; Date elements are allowed and normalized to epoch ms. **Array equality** isn't supported.
 - Implicit AND is canonicalized (`{a:1,b:2}` → `{$and:[{a:1},{b:2}]}`). Logical operators must contain field conditions, use non-empty arrays, and appear only at the root or within other logical operators (not inside field values).
 - Keys listed in `nonFilterableMetadataKeys` at index creation are stored but not filterable; this setting is immutable.
 - $exists requires a boolean value.

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

@@ -1,4 +1,4 @@
-# Composite Storage
+# Composite storage
 
 `MastraCompositeStore` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
 

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

@@ -1,8 +1,8 @@
-# DynamoDB Storage
+# DynamoDB storage
 
 The DynamoDB storage implementation provides a scalable and performant NoSQL database solution for Mastra, leveraging a single-table design pattern with [ElectroDB](https://electrodb.dev/).
 
-> **Observability Not Supported:** DynamoDB storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to DynamoDB, and Mastra Studio's observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** DynamoDB storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted to DynamoDB, and Mastra Studio's observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
 
 > **Item Size Limit:** DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
 
@@ -120,7 +120,7 @@ For local development, you can use [DynamoDB Local](https://docs.aws.amazon.com/
 
 **config.ttl** (`object`): TTL (Time To Live) configuration for automatic data expiration. Configure per entity type: thread, message, trace, eval, workflow\_snapshot, resource, score. Each entity config includes: enabled (boolean), attributeName (string, default: 'ttl'), defaultTtlSeconds (number).
 
-## TTL (Time To Live) Configuration
+## TTL (time to live) configuration
 
 DynamoDB TTL allows you to automatically delete items after a specified time period. This is useful for:
 
@@ -211,12 +211,12 @@ aws dynamodb update-time-to-live \
 1. Go to the DynamoDB console
 2. Select your table
 3. Go to "Additional settings" tab
-4. Under "Time to Live (TTL)", click "Manage TTL"
+4. Under "Time to Live (TTL)", select "Manage TTL"
 5. Enable TTL and specify the attribute name (default: `ttl`)
 
 > **Note:** DynamoDB deletes expired items within 48 hours after expiration. Items remain queryable until actually deleted.
 
-## AWS IAM Permissions
+## AWS IAM permissions
 
 The IAM role or user executing the code needs appropriate permissions to interact with the specified DynamoDB table and its indexes. Below is a sample policy. Replace `${YOUR_TABLE_NAME}` with your actual table name and `${YOUR_AWS_REGION}` and `${YOUR_AWS_ACCOUNT_ID}` with appropriate values.
 
@@ -246,7 +246,7 @@ The IAM role or user executing the code needs appropriate permissions to interac
 }
 ```
 
-## Key Considerations
+## Key considerations
 
 Before diving into the architectural details, keep these key points in mind when working with the DynamoDB storage adapter:
 
@@ -255,7 +255,7 @@ Before diving into the architectural details, keep these key points in mind when
 - **Understanding GSIs:** Familiarity with how the GSIs are structured (as per `TABLE_SETUP.md`) is important for understanding data retrieval and potential query patterns.
 - **ElectroDB:** The adapter uses ElectroDB to manage interactions with DynamoDB, providing a layer of abstraction and type safety over raw DynamoDB operations.
 
-## Architectural Approach
+## Architectural approach
 
 This storage adapter utilizes a **single-table design pattern** leveraging [ElectroDB](https://electrodb.dev/), a common and recommended approach for DynamoDB. This differs architecturally from relational database adapters (like `@mastra/pg` or `@mastra/libsql`) that typically use multiple tables, each dedicated to a specific entity (threads, messages, etc.).
 

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

@@ -1,4 +1,4 @@
-# PostgreSQL Storage
+# PostgreSQL storage
 
 The PostgreSQL storage implementation provides a production-ready storage solution using PostgreSQL databases.
 
@@ -71,7 +71,7 @@ const storage = new PostgresStore({
 
 **indexes** (`CreateIndexOptions[]`): Custom indexes to create during initialization.
 
-## Constructor Examples
+## Constructor examples
 
 You can instantiate `PostgresStore` in the following ways:
 
@@ -119,7 +119,7 @@ const store4 = new PostgresStore({
 })
 ```
 
-## Additional Notes
+## Additional notes
 
 ### Schema Management
 
@@ -177,7 +177,7 @@ const memoryStore = await storage.getStore('memory')
 const thread = await memoryStore?.getThreadById({ threadId: '...' })
 ```
 
-> **Warning:** If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+> **Warning:** If `init()` isn't called, tables won't be created and storage operations will fail silently or throw errors.
 
 ### Using an Existing Pool
 
@@ -201,7 +201,7 @@ const storage = new PostgresStore({
 
 **Pool lifecycle behavior:**
 
-- When you **provide a pool**: Mastra uses your pool but does **not** close it when `store.close()` is called. You manage the pool lifecycle.
+- When you **provide a pool**: Mastra uses your pool but **doesn't** close it when `store.close()` is called. You manage the pool lifecycle.
 - When Mastra **creates a pool**: Mastra owns the pool and will close it when `store.close()` is called.
 
 ### Direct Database and Pool Access
@@ -316,7 +316,7 @@ This pattern ensures only one `PostgresStore` instance is created regardless of
 
 > **Tip:** This singleton pattern is only necessary during local development with HMR. In production builds, modules are only loaded once.
 
-## Usage Example
+## Usage example
 
 ### Adding memory to an agent
 
@@ -387,7 +387,7 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-## Index Management
+## Index management
 
 PostgreSQL storage provides index management to optimize query performance.
 

package/dist/docs/references/reference-tools-vector-query-tool.md

@@ -2,7 +2,7 @@
 
 The `createVectorQueryTool()` function creates a tool for semantic search over vector stores. It supports filtering, reranking, database-specific configurations, and integrates with various vector store backends.
 
-## Basic Usage
+## Basic usage
 
 ```typescript
 import { createVectorQueryTool } from '@mastra/rag'
@@ -79,7 +79,7 @@ The tool returns an object with:
 
 **sources** (`QueryResult[]`): Array of full retrieval result objects. Each object contains all information needed to reference the original document, chunk, and similarity score.
 
-### QueryResult object structure
+### `QueryResult` object structure
 
 ```typescript
 {
@@ -91,7 +91,7 @@ The tool returns an object with:
 }
 ```
 
-## Default Tool Description
+## Default tool description
 
 The default description focuses on:
 
@@ -99,11 +99,11 @@ The default description focuses on:
 - Answering user questions
 - Retrieving factual content
 
-## Result Handling
+## Result handling
 
 The tool determines the number of results to return based on the user's query, with a default of 10 results. This can be adjusted based on the query requirements.
 
-## Example with Filters
+## Example with filters
 
 ```typescript
 const queryTool = createVectorQueryTool({
@@ -134,7 +134,7 @@ For detailed filter syntax and store-specific capabilities, see the [Metadata Fi
 
 For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag) example.
 
-## Example with Reranking
+## Example with reranking
 
 ```typescript
 const queryTool = createVectorQueryTool({
@@ -164,7 +164,7 @@ Reranking improves result quality by combining:
 
 The reranker processes the initial vector search results and returns a reordered list optimized for relevance.
 
-## Example with Custom Description
+## Example with custom description
 
 ```typescript
 const queryTool = createVectorQueryTool({
@@ -178,7 +178,7 @@ const queryTool = createVectorQueryTool({
 
 This example shows how to customize the tool description for a specific use case while maintaining its core purpose of information retrieval.
 
-## Database-Specific Configuration Examples
+## Database-specific configuration examples
 
 The `databaseConfig` parameter allows you to leverage unique features and optimizations specific to each vector database. These configurations are automatically applied during query execution.
 
@@ -335,7 +335,7 @@ This approach allows you to:
 - Adjust performance parameters based on load
 - Apply different filtering strategies per request
 
-## Example: Using Request Context
+## Example: Using request context
 
 ```typescript
 const queryTool = createVectorQueryTool({
@@ -374,7 +374,7 @@ For more information on request context, please see:
 - [Agent Request Context](https://mastra.ai/docs/server/request-context)
 - [Request Context](https://mastra.ai/docs/server/request-context)
 
-## Usage Without a Mastra Server
+## Usage without a Mastra server
 
 The tool can be used by itself to retrieve documents matching a query:
 
@@ -401,7 +401,7 @@ const queryResult = await vectorQueryTool.execute({ queryText: 'foo', topK: 1 },
 console.log(queryResult.sources)
 ```
 
-## Dynamic Vector Store for Multi-Tenant Applications
+## Dynamic vector store for multi-tenant applications
 
 For multi-tenant applications where each tenant has isolated data (e.g., separate PostgreSQL schemas), you can pass a resolver function instead of a static vector store instance. The function receives the request context and can return the appropriate vector store for the current tenant:
 
@@ -457,7 +457,7 @@ This pattern is similar to how `Agent.memory` supports dynamic configuration and
 - **Database isolation**: Route to different database instances per tenant
 - **Dynamic configuration**: Adjust vector store settings based on request context
 
-## Tool Details
+## Tool details
 
 The tool is created with:
 

package/dist/docs/references/reference-vectors-pg.md

@@ -1,8 +1,8 @@
-# PG Vector Store
+# PG vector store
 
 The PgVector class provides vector search using [PostgreSQL](https://www.postgresql.org/) with [pgvector](https://github.com/pgvector/pgvector) extension. It provides robust vector similarity search capabilities within your existing PostgreSQL database.
 
-## Constructor Options
+## Constructor options
 
 **connectionString** (`string`): PostgreSQL connection URL
 
@@ -26,7 +26,7 @@ The PgVector class provides vector search using [PostgreSQL](https://www.postgre
 
 **pgPoolOptions** (`PoolConfig`): Additional pg pool configuration options
 
-## Constructor Examples
+## Constructor examples
 
 ### Connection String
 
@@ -70,7 +70,7 @@ const vectorStore = new PgVector({
 
 ## Methods
 
-### createIndex()
+### `createIndex()`
 
 **indexName** (`string`): Name of the index to create
 
@@ -82,7 +82,9 @@ const vectorStore = new PgVector({
 
 **buildIndex** (`boolean`): Whether to build the index (Default: `true`)
 
-#### IndexConfig
+**metadataIndexes** (`string[]`): Array of metadata field names to create btree indexes on. Improves query performance when filtering by these metadata fields.
+
+#### `IndexConfig`
 
 **type** (`'flat' | 'hnsw' | 'ivfflat'`): Index type (Default: `ivfflat`)
 
@@ -112,7 +114,7 @@ HNSW indexes require significant shared memory during construction. For 100K vec
 
 Higher M values or efConstruction values will increase memory requirements significantly. Adjust your system's shared memory limits if needed.
 
-### upsert()
+### `upsert()`
 
 **indexName** (`string`): Name of the index to upsert vectors into
 
@@ -122,7 +124,7 @@ Higher M values or efConstruction values will increase memory requirements signi
 
 **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
 
-### query()
+### `query()`
 
 **indexName** (`string`): Name of the index to query
 
@@ -142,11 +144,11 @@ Higher M values or efConstruction values will increase memory requirements signi
 
 **options.probes** (`number`): IVF search parameter
 
-### listIndexes()
+### `listIndexes()`
 
 Returns an array of index names as strings.
 
-### describeIndex()
+### `describeIndex()`
 
 **indexName** (`string`): Name of the index to describe
 
@@ -167,11 +169,11 @@ interface PGIndexStats {
 }
 ```
 
-### deleteIndex()
+### `deleteIndex()`
 
 **indexName** (`string`): Name of the index to delete
 
-### updateVector()
+### `updateVector()`
 
 Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
 
@@ -206,7 +208,7 @@ await pgVector.updateVector({
 })
 ```
 
-### deleteVector()
+### `deleteVector()`
 
 **indexName** (`string`): Name of the index containing the vector
 
@@ -218,7 +220,7 @@ Deletes a single vector by ID from the specified index.
 await pgVector.deleteVector({ indexName: 'my_vectors', id: 'vector123' })
 ```
 
-### deleteVectors()
+### `deleteVectors()`
 
 Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
 
@@ -228,11 +230,11 @@ Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` m
 
 **filter** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
 
-### disconnect()
+### `disconnect()`
 
 Closes the database connection pool. Should be called when done using the store.
 
-### buildIndex()
+### `buildIndex()`
 
 **indexName** (`string`): Name of the index to define
 
@@ -266,7 +268,7 @@ await pgVector.buildIndex('my_vectors', 'cosine', {
 })
 ```
 
-## Response Types
+## Response types
 
 Query results are returned in this format:
 
@@ -279,7 +281,7 @@ interface QueryResult {
 }
 ```
 
-## Error Handling
+## Error handling
 
 The store throws typed errors that can be caught:
 
@@ -297,7 +299,7 @@ try {
 }
 ```
 
-## Index Configuration Guide
+## Index configuration guide
 
 ### Performance Optimization
 
@@ -329,14 +331,14 @@ The system automatically detects configuration changes and only rebuilds indexes
 - Changed configuration: Index is dropped and rebuilt
 - This prevents the performance issues from unnecessary index recreations
 
-## Best Practices
+## Best practices
 
 - Regularly evaluate your index configuration to ensure optimal performance.
 - Adjust parameters like `lists` and `m` based on dataset size and query requirements.
 - **Monitor index performance** using `describeIndex()` to track usage
 - Rebuild indexes periodically to maintain efficiency, especially after significant data changes
 
-## Direct Pool Access
+## Direct pool access
 
 The `PgVector` class exposes its underlying PostgreSQL connection pool as a public field:
 
@@ -352,7 +354,7 @@ This enables advanced usage such as running direct SQL queries, managing transac
 
 This design supports advanced use cases but requires careful resource management by the user.
 
-## Usage Example
+## Usage example
 
 ### Local embeddings with fastembed