Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mastra-ai/mastra/llms.txt

Use this file to discover all available pages before exploring further.

Vector stores enable semantic search, similarity matching, and retrieval-augmented generation (RAG) by storing and querying high-dimensional embeddings.

​
Vector Store Overview

Vector stores are specialized databases optimized for:
  • Storing embedding vectors (arrays of floats)
  • Similarity search using distance metrics (cosine, euclidean, dot product)
  • Filtering by metadata
  • Hybrid search (vector + keyword)

​
Pinecone

Managed vector database with serverless scaling.

​
Installation

npm install @mastra/pinecone

​
Configuration

import { PineconeVector } from '@mastra/pinecone';

const vectorStore = new PineconeVector({
  id: 'embeddings',
  apiKey: process.env.PINECONE_API_KEY,
  cloud: 'aws',
  region: 'us-east-1',
});

​
Usage

// Create index
await vectorStore.createIndex({
  name: 'documents',
  dimension: 1536,  // OpenAI embedding dimension
  metric: 'cosine',
});

// Upsert vectors
await vectorStore.upsert({
  indexName: 'documents',
  vectors: [
    {
      id: 'doc-1',
      values: embedding,  // [0.1, 0.2, ...]
      metadata: {
        title: 'Getting Started',
        category: 'docs',
      },
    },
  ],
});

// Query similar vectors
const results = await vectorStore.query({
  indexName: 'documents',
  vector: queryEmbedding,
  topK: 5,
  filter: {
    category: { $eq: 'docs' },
  },
});

​
Qdrant

High-performance vector database with filtering capabilities.

​
Installation

npm install @mastra/qdrant

​
Configuration

import { QdrantVector } from '@mastra/qdrant';

// Qdrant Cloud
const vectorStore = new QdrantVector({
  id: 'embeddings',
  url: process.env.QDRANT_URL,
  apiKey: process.env.QDRANT_API_KEY,
});

// Self-hosted
const vectorStore = new QdrantVector({
  id: 'embeddings',
  url: 'http://localhost:6333',
});

​
Usage

// Create collection
await vectorStore.createIndex({
  name: 'documents',
  dimension: 1536,
  metric: 'cosine',
});

// Insert vectors
await vectorStore.upsert({
  indexName: 'documents',
  vectors: [
    {
      id: 'doc-1',
      values: embedding,
      metadata: {
        content: 'Document text',
        tags: ['ai', 'ml'],
      },
    },
  ],
});

// Search with filtering
const results = await vectorStore.query({
  indexName: 'documents',
  vector: queryEmbedding,
  topK: 10,
  filter: {
    must: [
      {
        key: 'tags',
        match: { value: 'ai' },
      },
    ],
  },
});

​
Chroma

Open-source embedding database with simple API.

​
Installation

npm install @mastra/chroma

​
Configuration

import { ChromaVector } from '@mastra/chroma';

const vectorStore = new ChromaVector({
  id: 'embeddings',
  url: process.env.CHROMA_URL || 'http://localhost:8000',
});

​
Usage

// Create collection
await vectorStore.createIndex({
  name: 'documents',
  dimension: 1536,
  metric: 'cosine',
});

// Add vectors
await vectorStore.upsert({
  indexName: 'documents',
  vectors: [
    {
      id: 'doc-1',
      values: embedding,
      metadata: {
        text: 'Original document text',
      },
    },
  ],
});

// Query
const results = await vectorStore.query({
  indexName: 'documents',
  vector: queryEmbedding,
  topK: 5,
});

​
PostgreSQL with pgvector

Add vector search to existing PostgreSQL databases.

​
Installation

npm install @mastra/pg

​
Configuration

import { PgVector } from '@mastra/pg';

const vectorStore = new PgVector({
  id: 'embeddings',
  connectionString: process.env.DATABASE_URL,
});

​
Usage

// Create table with vector column
await vectorStore.createIndex({
  name: 'documents',
  dimension: 1536,
  metric: 'cosine',
});

// Insert vectors
await vectorStore.upsert({
  indexName: 'documents',
  vectors: [
    {
      id: 'doc-1',
      values: embedding,
      metadata: {
        content: 'Document content',
      },
    },
  ],
});

// Query with SQL power
const results = await vectorStore.query({
  indexName: 'documents',
  vector: queryEmbedding,
  topK: 5,
  filter: {
    metadata: {
      created_at: { $gte: '2024-01-01' },
    },
  },
});

​
Upstash Vector

Serverless vector database with HTTP API.

​
Installation

npm install @mastra/upstash

​
Configuration

import { UpstashVector } from '@mastra/upstash';

const vectorStore = new UpstashVector({
  id: 'embeddings',
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

​
Features

  • Edge-compatible
  • HTTP-based API
  • No connection management
  • Built-in metadata filtering
  • Namespace support

​
S3 Vectors

Vector search using AWS S3 storage.

​
Installation

npm install @mastra/s3vectors

​
Configuration

import { S3Vector } from '@mastra/s3vectors';

const vectorStore = new S3Vector({
  id: 'embeddings',
  bucket: process.env.S3_BUCKET,
  region: 'us-east-1',
});

​
Turbopuffer

Fast vector search with smart caching.

​
Installation

npm install @mastra/turbopuffer

​
Configuration

import { TurbopufferVector } from '@mastra/turbopuffer';

const vectorStore = new TurbopufferVector({
  id: 'embeddings',
  apiKey: process.env.TURBOPUFFER_API_KEY,
});

​
RAG Implementation

Use vector stores for retrieval-augmented generation: 
import { embed } from '@mastra/core/embedding';
import { PineconeVector } from '@mastra/pinecone';
import { Agent } from '@mastra/core/agent';

const vectorStore = new PineconeVector({ /* ... */ });

// Index documents
for (const doc of documents) {
  const embedding = await embed(doc.content);
  
  await vectorStore.upsert({
    indexName: 'knowledge-base',
    vectors: [{
      id: doc.id,
      values: embedding,
      metadata: {
        content: doc.content,
        title: doc.title,
      },
    }],
  });
}

// RAG query
const query = 'How do I create tools?';
const queryEmbedding = await embed(query);

const results = await vectorStore.query({
  indexName: 'knowledge-base',
  vector: queryEmbedding,
  topK: 3,
});

const context = results.matches
  .map(m => m.metadata.content)
  .join('\n\n');

const agent = new Agent({
  id: 'rag-agent',
  instructions: `Answer based on this context:\n${context}`,
  model: 'openai/gpt-4',
});

const answer = await agent.generate(query);
Combine vector similarity with keyword search: 
const results = await vectorStore.query({
  indexName: 'documents',
  vector: queryEmbedding,
  topK: 10,
  filter: {
    $and: [
      { category: { $eq: 'technical' } },
      { 
        $or: [
          { title: { $contains: 'vector' } },
          { content: { $contains: 'embedding' } },
        ],
      },
    ],
  },
});

​
Namespace Organization

Organize vectors into namespaces: 
// User-specific namespace
await vectorStore.upsert({
  indexName: 'documents',
  namespace: `user-${userId}`,
  vectors: userDocuments,
});

// Query within namespace
const results = await vectorStore.query({
  indexName: 'documents',
  namespace: `user-${userId}`,
  vector: queryEmbedding,
  topK: 5,
});

​
Vector Store Comparison

FeaturePineconeQdrantChromapgvectorUpstash
ManagedYesCloud/SelfSelfSelfYes
ServerlessYesNoNoNoYes
Filtering✓✓✓✓✓✓✓✓✓
Hybrid Search✓✓✓✓✓✓✓✓✓
Multi-tenancyNamespaceCollectionCollectionSchemaNamespace
Edge SupportNoNoNoNoYes

​
Performance Tips

Batch multiple vector upserts into single API calls to reduce latency
Choose appropriate index parameters (dimension, metric) based on your embedding model
Create indexes on frequently filtered metadata fields for faster queries
Consider dimensionality reduction techniques for faster search on large embeddings

​
Next Steps

Storage Overview

Learn about storage architecture

Storage Adapters

Explore SQL and NoSQL stores

Build docs developers (and LLMs) love

Get started for freeTalk to us