Skip to main content

DatabaseConfig

The DatabaseConfig type allows you to specify database-specific configurations when using vector query tools. These configurations enable you to use features and optimizations offered by different vector stores.

Type definition
Direct link to Type definition

export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  mongodb?: MongoDBConfig
  turbopuffer?: TurbopufferConfig
  [key: string]: any // Extensible for future databases
}

Database-specific types
Direct link to Database-specific types

PineconeConfig
Direct link to pineconeconfig

Configuration options specific to Pinecone vector store.

namespace?:

string
Pinecone namespace for organizing and isolating vectors within the same index. Useful for multi-tenancy or environment separation.

sparseVector?:

{ indices: number[]; values: number[]; }
Sparse vector for hybrid search combining dense and sparse embeddings. Enables better search quality for keyword-based queries. The indices and values arrays must be the same length.
object

indices:

number[]
Array of indices for sparse vector components

values:

number[]
Array of values corresponding to the indices

Use Cases:

  • Multi-tenant applications (separate namespaces per tenant)
  • Environment isolation (dev/staging/prod namespaces)
  • Hybrid search combining semantic and keyword matching

PgVectorConfig
Direct link to pgvectorconfig

Configuration options specific to PostgreSQL with pgvector extension.

minScore?:

number
Minimum similarity score threshold for results. Only vectors with similarity scores above this value will be returned.

ef?:

number
HNSW search parameter that controls the size of the dynamic candidate list during search. Higher values improve accuracy at the cost of speed. Typically set between topK and 200.

probes?:

number
IVFFlat probe parameter that specifies the number of index cells to visit during search. Higher values improve recall at the cost of speed.

Performance Guidelines:

  • ef: Start with 2-4x your topK value, increase for better accuracy
  • probes: Start with 1-10, increase for better recall
  • minScore: Use values between 0.5-0.9 depending on your quality requirements

Use Cases:

  • Performance optimization for high-load scenarios
  • Quality filtering to remove irrelevant results
  • Fine-tuning search accuracy vs speed tradeoffs

ChromaConfig
Direct link to chromaconfig

Configuration options specific to Chroma vector store.

where?:

Where
Metadata filtering conditions. Each field maps to a literal value or an operator expression ($gt, $gte, $lt, $lte, $ne, $eq, $in, $nin). Combine conditions with $and and $or.

whereDocument?:

WhereDocument
Document content filtering conditions using $contains and $not_contains. Combine conditions with $and and $or.

Filter Syntax Examples:

// Simple equality
where: { "category": "technical" }

// Operators
where: { "price": { "$gt": 100 } }

// Multiple conditions
where: {
  "category": "electronics",
  "inStock": true
}

// Document content filtering
whereDocument: { "$contains": "API documentation" }

Use Cases:

  • Advanced metadata filtering
  • Content-based document filtering
  • Complex query combinations

MongoDBConfig
Direct link to mongodbconfig

Configuration options specific to MongoDB Atlas Vector Search.

numCandidates?:

number
Number of candidates the HNSW graph considers before selecting the top-K results. Higher values improve recall at the cost of query latency. Must be greater than or equal to topK. Defaults to 20 × topK, capped at 10,000.

Use Cases:

  • Improving recall for large collections
  • Lowering latency when approximate results are acceptable

TurbopufferConfig
Direct link to turbopufferconfig

Configuration options specific to Turbopuffer vector store.

consistency?:

'strong' | 'eventual'
The consistency level for queries. "strong" (default) guarantees queries see all data written before the query started, at the cost of higher latency. "eventual" offers lower latency, but recently written data may not be visible yet.

Use Cases:

  • Latency-sensitive queries where slightly stale data is acceptable (eventual)
  • Read-your-writes workflows that must see the latest data (strong)

Usage examples
Direct link to Usage examples

Basic Database Configuration
Direct link to Basic Database Configuration

import { createVectorQueryTool } from '@mastra/rag'

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'production',
    },
  },
})

Extensibility
Direct link to Extensibility

The DatabaseConfig type is designed to be extensible. To add support for a new vector database:

// 1. Define the configuration interface
export interface NewDatabaseConfig {
  customParam1?: string
  customParam2?: number
}

// 2. Extend DatabaseConfig type
export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  newdatabase?: NewDatabaseConfig
  [key: string]: any
}

// 3. Use in vector query tool
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'newdatabase',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    newdatabase: {
      customParam1: 'value',
      customParam2: 42,
    },
  },
})

Best practices
Direct link to Best practices

  1. Environment Configuration: Use different namespaces or configurations for different environments
  2. Performance Tuning: Start with default values and adjust based on your specific needs
  3. Quality Filtering: Use minScore to filter out low-quality results
  4. Runtime Flexibility: Override configurations at runtime for runtime-defined scenarios
  5. Documentation: Document your specific configuration choices for team members

Migration guide
Direct link to Migration guide

Existing vector query tools continue to work without changes. To add database configurations:

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
+ databaseConfig: {
+   pinecone: {
+     namespace: 'production'
+   }
+ }
});
On this page