Query

Searches for the most similar vectors in a Pinecone index based on a query vector or an existing vector ID. This is the primary operation for semantic search and similarity matching.

Common Properties

Name - The custom name of the node.
Color - The custom color of the node.
Delay Before (sec) - Waits in seconds before executing the node.
Delay After (sec) - Waits in seconds after executing node.
Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs

Connection Id - Connection identifier from Connect node (optional if API Key credential is provided directly).
Host URL - Your index's host URL. Format: https://INDEX_NAME-PROJECT_ID.svc.ENVIRONMENT.pinecone.io. You can find this in your Pinecone console.
Top K - Number of most similar vectors to return. Default: 10. Higher values return more results but take longer.

Options

API Key - Pinecone API key credential (optional - use this instead of Connection Id if not using Connect node).
Name Space - Namespace to query within. Optional, defaults to the default namespace. Must match the namespace used during upsert.
Include Values - Whether to include vector values in the response. Default: true. Set to false to reduce response size if you only need IDs and metadata.
Include Metadata - Whether to include metadata in the response. Default: true. Usually you want this enabled to retrieve context.
Vector - Query vector array (same dimension as index). Use this to search by a new embedding. Either Vector or Id must be provided, not both.
Id - Vector ID to use as query. Use this to find similar vectors to an existing one. Either Vector or Id must be provided, not both.
Filter - Metadata filter object to limit search results. Only vectors matching the filter criteria will be considered.

Output

Response - Object containing query results with matched vectors, scores, and metadata.

{
  "matches": [
    {
      "id": "doc_123",
      "score": 0.95,
      "values": [0.1, 0.2, 0.3, ...],  // if includeValues=true
      "metadata": {                      // if includeMetadata=true
        "text": "Introduction to AI",
        "category": "education"
      }
    },
    {
      "id": "doc_456",
      "score": 0.87,
      "metadata": { ... }
    }
  ],
  "namespace": ""
}

How It Works

The Query node performs similarity search in your Pinecone index. When executed, the node:

Validates required inputs (Host URL, Top K)
Validates that either Vector or Id is provided, but not both
Constructs the query request with all parameters
Sends a POST request to the index's /query endpoint
Returns matched vectors sorted by similarity score (highest first)

Requirements

An existing Pinecone index with data
Either a query vector (same dimension as index) OR an existing vector ID
Sufficient quota in your Pinecone plan

Error Handling

The node will return specific errors in the following cases:

ErrInvalidArg - Host URL is empty
ErrInvalidArg - Both Id and Vector are provided (use only one)
ErrInvalidArg - Invalid Connection ID or missing API key
ErrInternal - Response format is not valid
ErrStatus - HTTP error from Pinecone API

Usage Notes

You must provide either Vector OR Id, not both and not neither
Scores range from 0 to 1 (for cosine) or can be negative (for euclidean/dotproduct)
Higher scores indicate greater similarity for cosine and dotproduct metrics
Lower scores indicate greater similarity for euclidean metric
Top K determines how many results to return (max typically 10,000)
Setting includeValues=false reduces response size significantly
Metadata filters are applied before similarity search

Understanding Similarity Scores

The score interpretation depends on your index metric:

Cosine: Range 0-1, where 1 = identical, 0 = orthogonal, closer to 1 is better
Euclidean: Distance value, lower is better (0 = identical)
Dotproduct: Can be any value, higher is better for normalized vectors

Best Practices

Set Top K based on your use case (5-20 for most applications)
Always include metadata to provide context for results
Use filters to narrow search space and improve relevance
Set includeValues=false unless you need the raw vectors
For RAG applications, retrieve top 3-10 results for context
Consider score thresholds to filter low-quality matches

Metadata Filtering

Filters allow you to search within a subset of vectors:

Equality Filter

msg.filter = {
  category: "education"
};

Comparison Filters

msg.filter = {
  price: { "$gte": 50, "$lte": 100 }  // between 50 and 100
};

Multiple Conditions (AND)

msg.filter = {
  category: "education",
  level: "beginner",
  published: true
};

OR Conditions

msg.filter = {
  "$or": [
    { category: "education" },
    { category: "tutorial" }
  ]
};

IN Operator

msg.filter = {
  category: { "$in": ["education", "tutorial", "guide"] }
};

Example: Semantic Search with Text Query

// 1. Generate embedding from user query
const userQuery = "How does machine learning work?";
const queryEmbedding = await openai.createEmbedding({
  model: "text-embedding-ada-002",
  input: userQuery
});

// 2. Set query parameters
msg.vector = queryEmbedding.data[0].embedding;
msg.topK = 5;
msg.filter = { category: "education" };

// 3. Use Query node to find similar documents
// 4. Process results
const results = msg.resQuery.matches;
results.forEach(match => {
  console.log(`${match.metadata.text} (score: ${match.score})`);
});

Example: Find Similar Products

// Find products similar to product_123
msg.id = "product_123";  // Use existing vector as query
msg.topK = 10;
msg.filter = {
  category: msg.currentProduct.category,  // Same category
  price: { "$lte": msg.currentProduct.price * 1.5 }  // Similar price
};

// Query returns similar products
const recommendations = msg.resQuery.matches.map(m => ({
  id: m.id,
  name: m.metadata.name,
  similarity: m.score
}));

Example: RAG (Retrieval-Augmented Generation)

// 1. Convert user question to embedding
const questionEmbedding = await getEmbedding(msg.userQuestion);

// 2. Query Pinecone for relevant context
msg.vector = questionEmbedding;
msg.topK = 3;
msg.namespace = "knowledge-base";

// 3. Extract context from results
const context = msg.resQuery.matches
  .map(m => m.metadata.text)
  .join("\n\n");

// 4. Build prompt for LLM
const prompt = `Context:\n${context}\n\nQuestion: ${msg.userQuestion}\n\nAnswer:`;

// 5. Send to OpenAI/Anthropic for answer generation

Example: Multi-Namespace Search

// Search in different namespaces for different user types
const namespace = msg.userType === "premium"
  ? "premium-content"
  : "free-content";

msg.namespace = namespace;
msg.vector = queryEmbedding;
msg.topK = 10;

Example: Filtering by Date Range

// Find recent articles similar to query
const oneWeekAgo = new Date();
oneWeekAgo.setDate(oneWeekAgo.getDate() - 7);

msg.vector = articleEmbedding;
msg.topK = 5;
msg.filter = {
  published_date: { "$gte": oneWeekAgo.toISOString() },
  status: "published"
};

// Search for beginner educational content
msg.vector = queryEmbedding;
msg.topK = 10;
msg.filter = {
  "$and": [
    { category: "education" },
    { level: "beginner" },
    { rating: { "$gte": 4.0 } }
  ]
};

Processing Query Results

// After Query node executes
const results = msg.resQuery.matches;

// Filter by score threshold
const highQualityMatches = results.filter(m => m.score >= 0.8);

// Extract specific fields
const documentTexts = results.map(m => m.metadata.text);

// Group by category
const byCategory = results.reduce((acc, match) => {
  const cat = match.metadata.category;
  if (!acc[cat]) acc[cat] = [];
  acc[cat].push(match);
  return acc;
}, {});

// Format for display
const formattedResults = results.map((m, i) => ({
  rank: i + 1,
  id: m.id,
  score: m.score.toFixed(3),
  title: m.metadata.title,
  snippet: m.metadata.text.substring(0, 200) + "..."
}));

Troubleshooting

Error: "Cannot provide both Id and Vector"

Use only one query method - either a vector or an ID
Check your variable assignments before the Query node

No results returned (empty matches)

Verify the index contains data (use Describe Index Stats)
Check that you're querying the correct namespace
Relax or remove metadata filters
Ensure query vector has correct dimension

Low similarity scores

Query vector may not be from the same embedding model
Check that vectors are properly normalized (for dotproduct)
Your data might not contain similar content
Consider using a different similarity metric

Query is slow

Reduce Top K value
Use more specific metadata filters to narrow search
Consider upgrading to higher performance pods (p2)
Check if your index needs more pods for your query load

Results don't match namespace

Ensure namespace parameter matches where data was upserted
Empty string or omitted namespace searches the default namespace
Namespace names are case-sensitive

Common Properties​

Inputs​

Options​

Output​

How It Works​

Requirements​

Error Handling​

Usage Notes​

Understanding Similarity Scores​

Best Practices​

Metadata Filtering​

Equality Filter​

Comparison Filters​

Multiple Conditions (AND)​

OR Conditions​

IN Operator​

Example: Semantic Search with Text Query​

Example: Find Similar Products​

Example: RAG (Retrieval-Augmented Generation)​

Example: Multi-Namespace Search​

Example: Filtering by Date Range​

Example: Hybrid Search (Filter + Similarity)​

Processing Query Results​

Troubleshooting​