How to beginner · 3 min read

How to filter with Weaviate where clause

Q: How to filter with Weaviate where clause

Use the where parameter in the Weaviate Python client's query.get() method to filter results with a where clause. The where clause supports operators like Equal, GreaterThan, and And to refine vector search queries.

Quick answer

Use the where parameter in the Weaviate Python client's query.get() method to filter results with a where clause. The where clause supports operators like Equal, GreaterThan, and And to refine vector search queries.

PREREQUISITES

Python 3.8+
Weaviate instance running (cloud or local)
pip install weaviate-client
Basic knowledge of Weaviate schema and vector search

Setup

Install the official Weaviate Python client and set up your environment to connect to your Weaviate instance.

bash

pip install weaviate-client

output

Collecting weaviate-client
  Downloading weaviate_client-4.9.0-py3-none-any.whl (100 kB)
Installing collected packages: weaviate-client
Successfully installed weaviate-client-4.9.0

Step by step

Connect to Weaviate and perform a filtered vector search using the where clause. This example filters objects of class Article where the author property equals "Alice".

python

import os
import weaviate

# Connect to Weaviate instance
client = weaviate.Client(
    url=os.environ.get("WEAVIATE_URL", "http://localhost:8080"),
    additional_headers={"X-API-KEY": os.environ.get("WEAVIATE_API_KEY", "")}
)

# Define the where filter
where_filter = {
    "path": ["author"],
    "operator": "Equal",
    "valueString": "Alice"
}

# Perform a filtered query
response = (
    client.query
    .get("Article", ["title", "author"])
    .with_where(where_filter)
    .with_limit(5)
    .do()
)

print("Filtered results:")
for obj in response.get('data', {}).get('Get', {}).get('Article', []):
    print(f"Title: {obj['title']}, Author: {obj['author']}")

output

Filtered results:
Title: Introduction to AI, Author: Alice
Title: Advanced AI Techniques, Author: Alice

Common variations

You can combine multiple filters using And or Or operators in the where clause. For example, filter articles by author and a minimum publicationYear.

python

where_filter = {
    "operator": "And",
    "operands": [
        {
            "path": ["author"],
            "operator": "Equal",
            "valueString": "Alice"
        },
        {
            "path": ["publicationYear"],
            "operator": "GreaterThanEqual",
            "valueInt": 2020
        }
    ]
}

response = (
    client.query
    .get("Article", ["title", "author", "publicationYear"])
    .with_where(where_filter)
    .with_limit(5)
    .do()
)

print("Filtered results with multiple conditions:")
for obj in response.get('data', {}).get('Get', {}).get('Article', []):
    print(f"Title: {obj['title']}, Author: {obj['author']}, Year: {obj['publicationYear']}")

output

Filtered results with multiple conditions:
Title: Advanced AI Techniques, Author: Alice, Year: 2021

Troubleshooting

If you get an empty result, verify your where clause paths match your schema property names exactly.
Ensure your Weaviate instance is reachable and the API key (if required) is correct.
Use client.schema.get() to inspect your schema if unsure about property names.

✅

Key Takeaways

Use the with_where() method with a properly structured where clause to filter Weaviate queries.
Combine multiple filters with And or Or operators for complex conditions.
Always match the path in the where clause to your schema property names exactly.
Check connectivity and API keys if queries return no results or errors.

Verified 2026-04

Verify ↗