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

RerankConfig

Returns

The tool returns an object with:

QueryResult object structure

{
  id: string;         // Unique chunk/document identifier
  metadata: any;      // All metadata fields (document ID, etc.)
  vector: number[];   // Embedding vector (if available)
  score: number;      // Similarity score for this retrieval
  document: string;   // Full chunk/document text (if available)
}

Default Tool Description

The default description focuses on:

• Finding relevant information in stored knowledge
• Answering user questions
• Retrieving factual content

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"),
  enableFilter: 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.

Example with Custom Description

const queryTool = createVectorQueryTool({
  vectorStoreName: "pinecone",
  indexName: "docs",
  model: openai.embedding("text-embedding-3-small"),
  description:
    "Search through document archives to find relevant information for answering questions about company policies and procedures",
});

This example shows how to customize the tool description for a specific use case while maintaining its core purpose of information retrieval.

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

• rerank()
• createGraphRAGTool