@mastra/pg 1.2.0-alpha.0 → 1.3.0-alpha.0

package/dist/docs/{tools/01-reference.md → references/reference-tools-vector-query-tool.md}

@@ -1,13 +1,4 @@
-# Tools API Reference
-
-> API reference for tools - 1 entries
-
-
----
-
-## Reference: createVectorQueryTool()
-
-> Documentation for the Vector Query Tool in Mastra, which facilitates semantic search over vector stores with filtering and reranking capabilities.
+# createVectorQueryTool()
 
 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.
 
@@ -26,24 +17,56 @@ const queryTool = createVectorQueryTool({
 
 ## Parameters
 
-> **Note:**
+> **Note:** **Parameter Requirements:** Most fields can be set at creation as defaults. Some fields can be overridden at runtime via the request context or input. If a required field is missing from both creation and runtime, an error will be thrown. Note that `model`, `id`, and `description` can only be set at creation time.
+
+**id?:** (`string`): Custom ID for the tool. By default: 'VectorQuery {vectorStoreName} {indexName} Tool'. (Set at creation only.)
+
+**description?:** (`string`): Custom description for the tool. By default: 'Access the knowledge base to find information needed to answer user questions' (Set at creation only.)
+
+**model:** (`EmbeddingModel`): Embedding model to use for vector search. (Set at creation only.)
+
+**vectorStoreName:** (`string`): Name of the vector store to query. (Can be set at creation or overridden at runtime.)
 
-**Parameter Requirements:** Most fields can be set at creation as defaults.
-Some fields can be overridden at runtime via the request context or input. If
-a required field is missing from both creation and runtime, an error will be
-thrown. Note that `model`, `id`, and `description` can only be set at creation
-time.
+**indexName:** (`string`): Name of the index within the vector store. (Can be set at creation or overridden at runtime.)
+
+**enableFilter?:** (`boolean`): Enable filtering of results based on metadata. (Set at creation only, but will be automatically enabled if a filter is provided in the request context.) (Default: `false`)
+
+**includeVectors?:** (`boolean`): Include the embedding vectors in the results. (Can be set at creation or overridden at runtime.) (Default: `false`)
+
+**includeSources?:** (`boolean`): Include the full retrieval objects in the results. (Can be set at creation or overridden at runtime.) (Default: `true`)
+
+**reranker?:** (`RerankConfig`): Options for reranking results. (Can be set at creation or overridden at runtime.)
+
+**databaseConfig?:** (`DatabaseConfig`): Database-specific configuration options for optimizing queries. (Can be set at creation or overridden at runtime.)
+
+**providerOptions?:** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
+
+**vectorStore?:** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, \`vectorStoreName\` becomes optional.
 
 ### DatabaseConfig
 
 The `DatabaseConfig` type allows you to specify database-specific configurations that are automatically applied to query operations. This enables you to take advantage of unique features and optimizations offered by different vector stores.
 
+**pinecone?:** (`PineconeConfig`): objectnamespace?:stringPinecone namespace for organizing vectorssparseVector?:{ indices: number\[]; values: number\[]; }Sparse vector for hybrid search
+
+**pgvector?:** (`PgVectorConfig`): objectminScore?:numberMinimum similarity score threshold for resultsef?:numberHNSW search parameter - controls accuracy vs speed tradeoffprobes?:numberIVFFlat probe parameter - number of cells to visit during search
+
+**chroma?:** (`ChromaConfig`): objectwhere?:Record\<string, any>Metadata filtering conditionswhereDocument?:Record\<string, any>Document content filtering conditions
+
 ### RerankConfig
 
+**model:** (`MastraLanguageModel`): Language model to use for reranking
+
+**options?:** (`RerankerOptions`): objectweights?:WeightConfigWeights for scoring components (semantic: 0.4, vector: 0.4, position: 0.2)topK?:numberNumber of top results to return
+
 ## Returns
 
 The tool returns an object with:
 
+**relevantContext:** (`string`): Combined text from the most relevant document chunks
+
+**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
 
 ```typescript
@@ -95,7 +118,7 @@ This agent-driven approach:
 - Implements vector store-specific filter syntax
 - Translates query terms to filter operators
 
-For detailed filter syntax and store-specific capabilities, see the [Metadata Filters](../rag/metadata-filters) documentation.
+For detailed filter syntax and store-specific capabilities, see the [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters) documentation.
 
 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.
 
@@ -147,122 +170,118 @@ This example shows how to customize the tool description for a specific use case
 
 The `databaseConfig` parameter allows you to leverage unique features and optimizations specific to each vector database. These configurations are automatically applied during query execution.
 
-  **pinecone:**
+**Pinecone**:
 
-    ### Pinecone Configuration
+### Pinecone Configuration
 
-    ```typescript
-    const pineconeQueryTool = createVectorQueryTool({
-      vectorStoreName: "pinecone",
-      indexName: "docs",
-      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-      databaseConfig: {
-        pinecone: {
-          namespace: "production",  // Organize vectors by environment
-          sparseVector: {          // Enable hybrid search
-            indices: [0, 1, 2, 3],
-            values: [0.1, 0.2, 0.15, 0.05]
-          }
-        }
+```typescript
+const pineconeQueryTool = createVectorQueryTool({
+  vectorStoreName: "pinecone",
+  indexName: "docs",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  databaseConfig: {
+    pinecone: {
+      namespace: "production",  // Organize vectors by environment
+      sparseVector: {          // Enable hybrid search
+        indices: [0, 1, 2, 3],
+        values: [0.1, 0.2, 0.15, 0.05]
       }
-    });
-    ```
+    }
+  }
+});
+```
 
-    **Pinecone Features:**
-    - **Namespace**: Isolate different data sets within the same index
-    - **Sparse Vector**: Combine dense and sparse embeddings for improved search quality
-    - **Use Cases**: Multi-tenant applications, hybrid semantic search
+**Pinecone Features:**
 
-  
+- **Namespace**: Isolate different data sets within the same index
+- **Sparse Vector**: Combine dense and sparse embeddings for improved search quality
+- **Use Cases**: Multi-tenant applications, hybrid semantic search
 
-  **pgvector:**
+**pgVector**:
 
-    ### pgVector Configuration
+### pgVector Configuration
 
-    ```typescript
-    const pgVectorQueryTool = createVectorQueryTool({
-      vectorStoreName: "postgres",
-      indexName: "embeddings",
-      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-      databaseConfig: {
-        pgvector: {
-          minScore: 0.7,    // Only return results above 70% similarity
-          ef: 200,          // Higher value = better accuracy, slower search
-          probes: 10        // For IVFFlat: more probes = better recall
-        }
-      }
-    });
-    ```
+```typescript
+const pgVectorQueryTool = createVectorQueryTool({
+  vectorStoreName: "postgres",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  databaseConfig: {
+    pgvector: {
+      minScore: 0.7,    // Only return results above 70% similarity
+      ef: 200,          // Higher value = better accuracy, slower search
+      probes: 10        // For IVFFlat: more probes = better recall
+    }
+  }
+});
+```
 
-    **pgVector Features:**
-    - **minScore**: Filter out low-quality matches
-    - **ef (HNSW)**: Control accuracy vs speed for HNSW indexes
-    - **probes (IVFFlat)**: Control recall vs speed for IVFFlat indexes
-    - **Use Cases**: Performance tuning, quality filtering
+**pgVector Features:**
 
-  
+- **minScore**: Filter out low-quality matches
+- **ef (HNSW)**: Control accuracy vs speed for HNSW indexes
+- **probes (IVFFlat)**: Control recall vs speed for IVFFlat indexes
+- **Use Cases**: Performance tuning, quality filtering
 
-  **chroma:**
+**Chroma**:
 
-    ### Chroma Configuration
+### Chroma Configuration
 
-    ```typescript
-    const chromaQueryTool = createVectorQueryTool({
-      vectorStoreName: "chroma",
-      indexName: "documents",
-      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-      databaseConfig: {
-        chroma: {
-          where: {                    // Metadata filtering
-            "category": "technical",
-            "status": "published"
-          },
-          whereDocument: {            // Document content filtering
-            "$contains": "API"
-          }
-        }
+```typescript
+const chromaQueryTool = createVectorQueryTool({
+  vectorStoreName: "chroma",
+  indexName: "documents",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  databaseConfig: {
+    chroma: {
+      where: {                    // Metadata filtering
+        "category": "technical",
+        "status": "published"
+      },
+      whereDocument: {            // Document content filtering
+        "$contains": "API"
       }
-    });
-    ```
+    }
+  }
+});
+```
 
-    **Chroma Features:**
-    - **where**: Filter by metadata fields
-    - **whereDocument**: Filter by document content
-    - **Use Cases**: Advanced filtering, content-based search
+**Chroma Features:**
 
-  
+- **where**: Filter by metadata fields
+- **whereDocument**: Filter by document content
+- **Use Cases**: Advanced filtering, content-based search
 
-  **multiple-configs:**
+**Multiple Configs**:
 
-    ### Multiple Database Configurations
+### Multiple Database Configurations
 
-    ```typescript
-    // Configure for multiple databases (useful for dynamic stores)
-    const multiDbQueryTool = createVectorQueryTool({
-      vectorStoreName: "dynamic-store", // Will be set at runtime
-      indexName: "docs",
-      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-      databaseConfig: {
-        pinecone: {
-          namespace: "default"
-        },
-        pgvector: {
-          minScore: 0.8,
-          ef: 150
-        },
-        chroma: {
-          where: { "type": "documentation" }
-        }
-      }
-    });
-    ```
+```typescript
+// Configure for multiple databases (useful for dynamic stores)
+const multiDbQueryTool = createVectorQueryTool({
+  vectorStoreName: "dynamic-store", // Will be set at runtime
+  indexName: "docs",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  databaseConfig: {
+    pinecone: {
+      namespace: "default"
+    },
+    pgvector: {
+      minScore: 0.8,
+      ef: 150
+    },
+    chroma: {
+      where: { "type": "documentation" }
+    }
+  }
+});
+```
 
-    **Multi-Config Benefits:**
-    - Support multiple vector stores with one tool
-    - Database-specific optimizations are automatically applied
-    - Flexible deployment scenarios
+**Multi-Config Benefits:**
 
-  
+- Support multiple vector stores with one tool
+- Database-specific optimizations are automatically applied
+- Flexible deployment scenarios
 
 ### Runtime Configuration Override
 
@@ -341,13 +360,13 @@ const response = await agent.generate(
 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#accessing-values-with-tools)
+- [Request Context](https://mastra.ai/docs/server/request-context)
 
 ## Usage Without a Mastra Server
 
 The tool can be used by itself to retrieve documents matching a query:
 
-```typescript title="src/index.ts"
+```typescript
 import { RequestContext } from "@mastra/core/request-context";
 import { createVectorQueryTool } from "@mastra/rag";
 import { PgVector } from "@mastra/pg";
@@ -377,7 +396,7 @@ console.log(queryResult.sources);
 
 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:
 
-```typescript title="src/index.ts"
+```typescript
 import { createVectorQueryTool, VectorStoreResolver } from "@mastra/rag";
 import { PgVector } from "@mastra/pg";
 
@@ -387,7 +406,7 @@ const vectorStoreCache = new Map<string, PgVector>();
 // Resolver function that returns the correct vector store based on tenant
 const vectorStoreResolver: VectorStoreResolver = async ({ requestContext }) => {
   const tenantId = requestContext?.get("tenantId");
-  
+
   if (!tenantId) {
     throw new Error("tenantId is required in request context");
   }
@@ -436,5 +455,5 @@ The tool is created with:
 
 ## Related
 
-- [rerank()](../rag/rerank)
-- [createGraphRAGTool](./graph-rag-tool)
+- [rerank()](https://mastra.ai/reference/rag/rerank)
+- [createGraphRAGTool](https://mastra.ai/reference/tools/graph-rag-tool)

package/dist/docs/{vectors/01-reference.md → references/reference-vectors-pg.md}

@@ -1,18 +1,30 @@
-# Vectors API Reference
+# PG Vector Store
 
-> API reference for vectors - 1 entries
+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
 
----
+**connectionString?:** (`string`): PostgreSQL connection URL
 
-## Reference: PG Vector Store
+**host?:** (`string`): PostgreSQL server host
 
-> Documentation for the PgVector class in Mastra, which provides vector search using PostgreSQL with pgvector extension.
+**port?:** (`number`): PostgreSQL server port
 
-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.
+**database?:** (`string`): PostgreSQL database name
 
-## Constructor Options
+**user?:** (`string`): PostgreSQL user
+
+**password?:** (`string`): PostgreSQL password
+
+**ssl?:** (`boolean | ConnectionOptions`): Enable SSL or provide custom SSL configuration
+
+**schemaName?:** (`string`): The name of the schema you want the vector store to use. Will use the default schema if not provided.
+
+**max?:** (`number`): Maximum number of pool connections (default: 20)
+
+**idleTimeoutMillis?:** (`number`): Idle connection timeout in milliseconds (default: 30000)
+
+**pgPoolOptions?:** (`PoolConfig`): Additional pg pool configuration options
 
 ## Constructor Examples
 
@@ -60,28 +72,68 @@ const vectorStore = new PgVector({
 
 ### createIndex()
 
+**indexName:** (`string`): Name of the index to create
+
+**dimension:** (`number`): Vector dimension (must match your embedding model)
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+
+**indexConfig?:** (`IndexConfig`): Index configuration (Default: `{ type: 'ivfflat' }`)
+
+**buildIndex?:** (`boolean`): Whether to build the index (Default: `true`)
+
 #### IndexConfig
 
+**type:** (`'flat' | 'hnsw' | 'ivfflat'`): stringflat:flatSequential scan (no index) that performs exhaustive search.ivfflat:ivfflatClusters vectors into lists for approximate search.hnsw:hnswGraph-based index offering fast search times and high recall. (Default: `ivfflat`)
+
+**ivf?:** (`IVFConfig`): objectlists?:numberNumber of lists. If not specified, automatically calculated based on dataset size. (Minimum 100, Maximum 4000)
+
+**hnsw?:** (`HNSWConfig`): objectm?:numberMaximum number of connections per node (default: 8)efConstruction?:numberBuild-time complexity (default: 32)
+
 #### Memory Requirements
 
 HNSW indexes require significant shared memory during construction. For 100K vectors:
 
-- Small dimensions (64d): ~60MB with default settings
-- Medium dimensions (256d): ~180MB with default settings
-- Large dimensions (384d+): ~250MB+ with default settings
+- Small dimensions (64d): \~60MB with default settings
+- Medium dimensions (256d): \~180MB with default settings
+- Large dimensions (384d+): \~250MB+ with default settings
 
 Higher M values or efConstruction values will increase memory requirements significantly. Adjust your system's shared memory limits if needed.
 
 ### upsert()
 
+**indexName:** (`string`): Name of the index to upsert vectors into
+
+**vectors:** (`number[][]`): Array of embedding vectors
+
+**metadata?:** (`Record<string, any>[]`): Metadata for each vector
+
+**ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)
+
 ### query()
 
+**indexName:** (`string`): Name of the index to query
+
+**vector:** (`number[]`): Query vector
+
+**topK?:** (`number`): Number of results to return (Default: `10`)
+
+**filter?:** (`Record<string, any>`): Metadata filters
+
+**includeVector?:** (`boolean`): Whether to include the vector in the result (Default: `false`)
+
+**minScore?:** (`number`): Minimum similarity score threshold (Default: `0`)
+
+**options?:** (`{ ef?: number; probes?: number }`): objectef?:numberHNSW search parameterprobes?:numberIVF search parameter
+
 ### listIndexes()
 
 Returns an array of index names as strings.
 
 ### describeIndex()
 
+**indexName:** (`string`): Name of the index to describe
+
 Returns:
 
 ```typescript
@@ -101,10 +153,20 @@ interface PGIndexStats {
 
 ### deleteIndex()
 
+**indexName:** (`string`): Name of the index to delete
+
 ### updateVector()
 
 Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
 
+**indexName:** (`string`): Name of the index containing the vector
+
+**id?:** (`string`): ID of the vector to update (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
+
+**update:** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
+
 Updates an existing vector by ID or filter. At least one of vector or metadata must be provided in the update object.
 
 ```typescript
@@ -130,6 +192,10 @@ await pgVector.updateVector({
 
 ### deleteVector()
 
+**indexName:** (`string`): Name of the index containing the vector
+
+**id:** (`string`): ID of the vector to delete
+
 Deletes a single vector by ID from the specified index.
 
 ```typescript
@@ -140,12 +206,24 @@ await pgVector.deleteVector({ indexName: "my_vectors", id: "vector123" });
 
 Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
 
+**indexName:** (`string`): Name of the index containing the vectors to delete
+
+**ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
+
 ### disconnect()
 
 Closes the database connection pool. Should be called when done using the store.
 
 ### buildIndex()
 
+**indexName:** (`string`): Name of the index to define
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+
+**indexConfig:** (`IndexConfig`): Configuration for the index type and parameters
+
 Builds or rebuilds an index with specified metric and configuration. Will drop any existing index before creating the new one.
 
 ```typescript
@@ -216,10 +294,13 @@ try {
 #### HNSW Tuning
 
 - **m parameter**:
+
   - 8-16: Moderate accuracy, lower memory
   - 16-32: High accuracy, moderate memory
   - 32-64: Very high accuracy, high memory
+
 - **efConstruction**:
+
   - 32-64: Fast build, good quality
   - 64-128: Slower build, better quality
   - 128-256: Slowest build, best quality
@@ -263,13 +344,33 @@ Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve rel
 
 Install `fastembed` to get started:
 
-```bash npm2yarn
+**npm**:
+
+```bash
 npm install @mastra/fastembed@latest
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/fastembed@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/fastembed@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/fastembed@latest
+```
+
 Add the following to your agent:
 
-```typescript title="src/mastra/agents/example-pg-agent.ts"
+```typescript
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { PostgresStore, PgVector } from "@mastra/pg";
@@ -304,4 +405,4 @@ export const pgAgent = new Agent({
 
 ## Related
 
-- [Metadata Filters](../rag/metadata-filters)
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)