How to beginner · 3 min read

How to filter Pinecone query results

Q: How to filter Pinecone query results

To filter Pinecone query results, use the filter parameter in the query method to specify metadata-based conditions. This lets you restrict results to vectors matching criteria like tags or categories, improving relevance in retrieval-augmented generation (RAG) workflows.

Quick answer

To filter Pinecone query results, use the filter parameter in the query method to specify metadata-based conditions. This lets you restrict results to vectors matching criteria like tags or categories, improving relevance in retrieval-augmented generation (RAG) workflows.

PREREQUISITES

Python 3.8+
Pinecone API key
pip install pinecone-client

Setup Pinecone environment

Install the Pinecone client library and set your API key as an environment variable. Initialize the Pinecone client and connect to your index.

python

import os
import pinecone

# Install Pinecone client if not installed
# pip install pinecone-client

pinecone.init(api_key=os.environ["PINECONE_API_KEY"], environment="us-west1-gcp")
index = pinecone.Index("example-index")

Step by step filtering example

Use the filter argument in the query method to specify metadata conditions. For example, filter by a tag or numeric range to get only relevant vectors.

python

import os
import pinecone

pinecone.init(api_key=os.environ["PINECONE_API_KEY"], environment="us-west1-gcp")
index = pinecone.Index("example-index")

# Query with filter to only get vectors where metadata 'category' is 'technology'
query_response = index.query(
    vector=[0.1, 0.2, 0.3, 0.4],
    top_k=5,
    filter={"category": "technology"}
)

print(query_response.matches)

output

[{'id': 'vec1', 'score': 0.95, 'metadata': {'category': 'technology'}}, ...]

Common variations

Use complex filters combining multiple metadata fields with logical operators like $and, $or.
Filter by numeric ranges, e.g., {"price": {"$gte": 10, "$lte": 50}}.
Use async Pinecone client methods for high throughput applications.

python

filter_example = {
    "$and": [
        {"category": "technology"},
        {"rating": {"$gte": 4}}
    ]
}

query_response = index.query(
    vector=[0.1, 0.2, 0.3, 0.4],
    top_k=5,
    filter=filter_example
)

print(query_response.matches)

output

[{'id': 'vec3', 'score': 0.92, 'metadata': {'category': 'technology', 'rating': 4.5}}, ...]

Troubleshooting filtering issues

If your filter returns no results, verify that the metadata keys and values exactly match those stored in Pinecone. Also, ensure your index has metadata enabled and vectors were upserted with metadata.

Check for typos and confirm the filter syntax matches Pinecone's supported operators.

✅

Key Takeaways

Use the filter parameter in index.query() to restrict results by metadata.
Filters support exact matches, numeric ranges, and logical operators like $and and $or.
Ensure your vectors have metadata and the filter keys match exactly to get results.
Filtering improves relevance and efficiency in vector search for RAG applications.

Verified 2026-04

Verify ↗