MastraVector - Mastra

Overview

MastraVector is the abstract base class for implementing vector store providers in Mastra. Vector stores enable semantic search, RAG (retrieval-augmented generation), and embedding-based memory systems.

Type Definition

abstract class MastraVector<Filter = VectorFilter> extends MastraBase {
  id: string;
  abstract query(params: QueryVectorParams<Filter>): Promise<QueryResult[]>;
  abstract upsert(params: UpsertVectorParams): Promise<string[]>;
  abstract createIndex(params: CreateIndexParams): Promise<void>;
  abstract listIndexes(): Promise<string[]>;
  abstract describeIndex(params: DescribeIndexParams): Promise<IndexStats>;
  abstract deleteIndex(params: DeleteIndexParams): Promise<void>;
  abstract updateVector(params: UpdateVectorParams<Filter>): Promise<void>;
  abstract deleteVector(params: DeleteVectorParams): Promise<void>;
  abstract deleteVectors(params: DeleteVectorsParams<Filter>): Promise<void>;
}

Constructor

constructor({ id }: { id: string })

string

required

Unique identifier for the vector store instance. Cannot be empty.

Properties

string

Unique identifier for the vector store

indexSeparator

string

default:"'_'"

Separator used in index names (can be overridden by implementations)

Abstract Methods

query

abstract query(params: QueryVectorParams<Filter>): Promise<QueryResult[]>

Performs a similarity search in the vector store.

params

QueryVectorParams

required

Query parameters

Show properties

indexName

string

required

Name of the index to query

query

string | number[]

required

Query string (will be embedded) or query vector

topK

number

default:"10"

Number of results to return

filter

Filter

Metadata filter for narrowing results

includeVector

boolean

default:"false"

Whether to include vectors in results

results

QueryResult[]

Array of matching results with scores and metadata

upsert

abstract upsert(params: UpsertVectorParams): Promise<string[]>

Inserts or updates vectors in the index.

params

UpsertVectorParams

required

Upsert parameters

Show properties

indexName

string

required

Name of the index

vectors

VectorData[]

required

Array of vectors to upsert

ids

string[]

Array of vector IDs that were upserted

createIndex

abstract createIndex(params: CreateIndexParams): Promise<void>

Creates a new vector index.

params

CreateIndexParams

required

Index creation parameters

Show properties

indexName

string

required

Name for the new index

dimension

number

required

Dimensionality of the vectors (e.g., 1536 for OpenAI text-embedding-3-small)

metric

'cosine' | 'euclidean' | 'dotproduct'

default:"'cosine'"

Distance metric to use

indexConfig

object

Provider-specific index configuration

listIndexes

abstract listIndexes(): Promise<string[]>

Lists all available indexes.

indexes

string[]

Array of index names

describeIndex

abstract describeIndex(params: DescribeIndexParams): Promise<IndexStats>

Gets information about an index.

params

DescribeIndexParams

required

indexName

string

required

Name of the index to describe

stats

IndexStats

Index statistics including dimension, metric, and vector count

deleteIndex

abstract deleteIndex(params: DeleteIndexParams): Promise<void>

Deletes an index.

params

DeleteIndexParams

required

indexName

string

required

Name of the index to delete

updateVector

abstract updateVector(params: UpdateVectorParams<Filter>): Promise<void>

Updates metadata for a specific vector.

params

UpdateVectorParams

required

Show properties

indexName

string

required

Name of the index

string

required

ID of the vector to update

metadata

Record<string, any>

required

New metadata

deleteVector

abstract deleteVector(params: DeleteVectorParams): Promise<void>

Deletes a single vector by ID.

params

DeleteVectorParams

required

Show properties

indexName

string

required

Name of the index

string

required

ID of the vector to delete

deleteVectors

abstract deleteVectors(params: DeleteVectorsParams<Filter>): Promise<void>

Deletes multiple vectors by IDs or metadata filter.

params

DeleteVectorsParams

required

Show properties

indexName

string

required

Name of the index

ids

string[]

Array of vector IDs to delete (mutually exclusive with filter)

filter

Filter

Metadata filter for bulk deletion (mutually exclusive with ids)

Available Vector Stores

Mastra provides several vector store implementations:

@mastra/pinecone - Pinecone vector database
@mastra/chroma - ChromaDB vector database
@mastra/qdrant - Qdrant vector database
@mastra/pg-vector - PostgreSQL with pgvector extension

Example Usage

Basic Vector Operations

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

const vector = new PineconeVector({
  id: 'knowledge-base',
  apiKey: process.env.PINECONE_API_KEY,
  indexName: 'documents'
});

const embedder = new OpenAIEmbedder({
  apiKey: process.env.OPENAI_API_KEY,
  model: 'text-embedding-3-small'
});

// Create index
await vector.createIndex({
  indexName: 'documents',
  dimension: 1536,
  metric: 'cosine'
});

// Embed and upsert documents
const documents = [
  { id: 'doc-1', text: 'Mastra is an AI framework', metadata: { category: 'intro' } },
  { id: 'doc-2', text: 'Agents are autonomous systems', metadata: { category: 'concepts' } }
];

const embeddings = await embedder.embedMany({
  values: documents.map(d => d.text)
});

await vector.upsert({
  indexName: 'documents',
  vectors: documents.map((doc, i) => ({
    id: doc.id,
    values: embeddings.embeddings[i],
    metadata: doc.metadata
  }))
});

// Query vectors
const results = await vector.query({
  indexName: 'documents',
  query: 'What is Mastra?',
  topK: 5,
  filter: { category: 'intro' }
});

console.log(results);

Using with Memory

import { Memory } from '@mastra/memory';
import { PineconeVector } from '@mastra/pinecone';
import { LibSQLStore } from '@mastra/libsql';

const storage = new LibSQLStore({ id: 'storage', url: ':memory:' });
const vector = new PineconeVector({
  id: 'memory-vectors',
  apiKey: process.env.PINECONE_API_KEY,
  indexName: 'memory'
});

const memory = new Memory({
  name: 'conversation-memory',
  storage,
  vector,
  embedder: 'openai/text-embedding-3-small',
  options: {
    semanticRecall: true
  }
});

Bulk Operations

// Delete all vectors from a source
await vector.deleteVectors({
  indexName: 'documents',
  filter: { source_id: 'manual.pdf' }
});

// Delete specific vectors
await vector.deleteVectors({
  indexName: 'documents',
  ids: ['vec_1', 'vec_2', 'vec_3']
});

// Delete old temporary documents
await vector.deleteVectors({
  indexName: 'documents',
  filter: {
    $and: [
      { bucket: 'temp' },
      { indexed_at: { $lt: '2025-01-01' } }
    ]
  }
});

Index Management

// List all indexes
const indexes = await vector.listIndexes();
console.log('Available indexes:', indexes);

// Get index stats
const stats = await vector.describeIndex({ indexName: 'documents' });
console.log('Index stats:', stats);
// { dimension: 1536, metric: 'cosine', vectorCount: 1000 }

// Delete index
await vector.deleteIndex({ indexName: 'old-index' });

Advanced Filtering

// Query with complex filters
const results = await vector.query({
  indexName: 'documents',
  query: 'machine learning concepts',
  topK: 10,
  filter: {
    $and: [
      { category: { $in: ['ml', 'ai'] } },
      { difficulty: { $gte: 'intermediate' } },
      { published: true }
    ]
  }
});

Update Vector Metadata

await vector.updateVector({
  indexName: 'documents',
  id: 'doc-1',
  metadata: {
    category: 'advanced',
    lastModified: new Date().toISOString(),
    views: 1000
  }
});

Using with Mastra

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

const mastra = new Mastra({
  vectors: {
    knowledge: new PineconeVector({
      id: 'knowledge-base',
      apiKey: process.env.PINECONE_API_KEY,
      indexName: 'knowledge'
    }),
    products: new PineconeVector({
      id: 'product-catalog',
      apiKey: process.env.PINECONE_API_KEY,
      indexName: 'products'
    })
  }
});

// Access vectors from Mastra
const knowledgeBase = mastra.getVector('knowledge');
const results = await knowledgeBase.query({
  indexName: 'knowledge',
  query: 'How does authentication work?',
  topK: 5
});

​Overview

​Type Definition

​Constructor

​Properties

​Abstract Methods

​query

​upsert

​createIndex

​listIndexes

​describeIndex

​deleteIndex

​updateVector

​deleteVector

​deleteVectors

​Available Vector Stores

​Example Usage

​Basic Vector Operations

​Using with Memory

​Bulk Operations

​Index Management

​Advanced Filtering

​Update Vector Metadata

​Using with Mastra

Overview

Type Definition

Constructor

Properties

Abstract Methods

query

upsert

createIndex

listIndexes

describeIndex

deleteIndex

updateVector

deleteVector

deleteVectors

Available Vector Stores

Example Usage

Basic Vector Operations

Using with Memory

Bulk Operations

Index Management

Advanced Filtering

Update Vector Metadata

Using with Mastra