DocsReferenceToolscreateVectorQueryTool()

createVectorQueryTool()

The createVectorQueryTool() function creates a tool for semantic search over vector stores. It supports filtering, reranking, and integrates with various vector store backends.

Basic Usage

import { openai } from '@ai-sdk/openai';
import { createVectorQueryTool } from "@mastra/rag";
 
const queryTool = createVectorQueryTool({
  vectorStoreName: "pinecone",
  indexName: "docs",
  model: openai.embedding('text-embedding-3-small'),
});

Parameters

vectorStoreName:

string
Name of the vector store to query (must be configured in Mastra)

indexName:

string
Name of the index within the vector store

model:

EmbeddingModel
Embedding model to use for vector search

reranker?:

RerankConfig
Options for reranking results

id?:

string
Custom ID for the tool (defaults to 'VectorQuery {vectorStoreName} {indexName} Tool')

description?:

string
Custom description for the tool (by default, provides instructions for querying the vector store with examples of filtering and reranking if enabled)

RerankConfig

model:

LanguageModelV1
Language model to use for reranking

options?:

RerankerOptions
Options for the reranking process
object

weights?:

WeightConfig
Weights for scoring components (semantic: 0.4, vector: 0.4, position: 0.2)

topK?:

number
Number of top results to return

Returns

The tool returns an object with:

relevantContext:

string
Combined text from the most relevant document chunks

Default Tool Description

The default tool description provides:

  • Instructions for querying the specified vector store
  • Examples of filter syntax when filtering is enabled

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

const queryTool = createVectorQueryTool({
  vectorStoreName: "pinecone",
  indexName: "docs",
  model: openai.embedding('text-embedding-3-small'),
  enableFilters: true,
});

With filtering enabled, the tool processes queries to construct metadata filters that combine with semantic search. The process works as follows:

  1. A user makes a query with specific filter requirements like “Find content where the ‘version’ field is greater than 2.0”
  2. The agent analyzes the query and constructs the appropriate filters: 
    {
   "version": { "$gt": 2.0 }
}

This agent-driven approach:

  • Processes natural language queries into filter specifications
  • Implements vector store-specific filter syntax
  • Translates query terms to filter operators

For detailed filter syntax and store-specific capabilities, see the Metadata Filters documentation.

For an example of how agent-driven filtering works, see the Agent-Driven Metadata Filtering example.

Example with Reranking

const queryTool = createVectorQueryTool({
  vectorStoreName: "milvus",
  indexName: "documentation",
  model: openai.embedding('text-embedding-3-small'),
  reranker: {
    model: openai('gpt-4o-mini'),
    options: {
      weights: {
        semantic: 0.5,  // Semantic relevance weight
        vector: 0.3,    // Vector similarity weight
        position: 0.2   // Original position weight
      },
      topK: 5
    }
  }
});

Reranking improves result quality by combining:

  • Semantic relevance: Using LLM-based scoring of text similarity
  • Vector similarity: Original vector distance scores
  • Position bias: Consideration of original result ordering
  • Query analysis: Adjustments based on query characteristics

The reranker processes the initial vector search results and returns a reordered list optimized for relevance.

Tool Details

The tool is created with:

  • ID: VectorQuery {vectorStoreName} {indexName} Tool
  • Input Schema: Requires queryText and filter objects
  • Output Schema: Returns relevantContext string

Related

createGraphRAGTool()MastraMCPClient