Additional filters

Additional filters can be used to subset the data in a single collection manually in addition to whatever filters the Query Agent decides to use in a particular search.

These persistent filters are defined at the specification of the collection, and combined with agent-generated filters using logical AND operations at search time.

Additional filters are available in both Ask Mode and Search Mode.

The syntax used is that of a standard Weaviate filter, see more on filtering in Weaviate for details.

These can be specified at instantiation of the Query Agent.

Python (Agents)JavaScript/TypeScript (Agents)

from weaviate.agents.query import QueryAgent
from weaviate.agents.classes import QueryAgentCollectionConfig
from weaviate.classes.query import Filter

qa = QueryAgent(
    client=client,
    collections=[
        QueryAgentCollectionConfig(
            name="Weather",
            additional_filters=Filter.by_property("temperature").greater_than(10)
        ),
    ],
)

import { QueryAgent } from 'weaviate-agents';

const qa = new QueryAgent(client, {
    collections: [
        {
            name: 'Weather',
            additionalFilters: weatherCollection.filter.byProperty('temperature').greaterThan(10),
        },
    ],
});

Or at runtime of Ask or Search Mode.

Python (Agents)JavaScript/TypeScript (Agents)

runtime_config = QueryAgentCollectionConfig(
    name="Weather",
    additional_filters=Filter.by_property("humidity").equal(39)
)

response = qa.ask(
    query="Provide a summary of the weather patterns", 
    collections=[runtime_config]
)

const runtimeConfig = {
    name: 'Weather',
    additionalFilters: weatherCollection.filter.byProperty('humidity').equal(39),
};

const response = await qa.ask("Provide a summary of the weather patterns", {
    collections: [runtimeConfig],
});

The additional filters are an argument to QueryAgentCollectionConfig, and used as part of collection configuration. See the page on collection configuration for more detail.

You can add as many layers of complexity to the custom filter as you need - a single filter on one property, or multiple nested filters across multiple properties.

How is it used?

The filters are applied in addition to any filters determined by any agent in a run of the Query Agent. The Query Agent could decide one or many filters, and these are combined with the additional filters specified when the final result set is being retrieved.

In addition, a sample of data from the collection is provided to the agents to better understand the data they have access to. This data subset is also filtered using the additional filters provided.

Use cases

Additional filters reduce the sample space of data to be retrieved. If you have a large data collection but only want to use the Query Agent across a subset of that data, specifying a filter enforces only a portion of the data can be used.

Since the Query Agent is a non-deterministic process (via the usage of LLMs), if you want to enforce a particular property is always being filtered, you can do so here.

For example, instead of directly trying to enforce the filter in the prompt, you could replace

Python (Agents)JavaScript/TypeScript (Agents)

response = qa.ask(
    query=(
        "What type of contracts have been signed and who were the authors?"
        "IMPORTANT: Only look at contracts from 2025."
    ),
    collections=["FinancialContracts"]
)

const badResponse = await qa.ask(
    `What type of contracts have been signed and who were the authors? 
    IMPORTANT: Only look at contracts from 2025.`,
    {
        collections: ['FinancialContracts'],
    }
);

with

Python (Agents)JavaScript/TypeScript (Agents)

from datetime import datetime, timezone

start_date = datetime(2025, 1, 1, tzinfo=timezone.utc)
end_date = datetime(2026, 1, 1, tzinfo=timezone.utc)

response = qa.ask(
    query="What type of contracts have been signed and who were the authors?",
    collections=[
        QueryAgentCollectionConfig(
            name="FinancialContracts",
            additional_filters=(
                Filter.all_of(
                    [
                        Filter.by_property("date").greater_than(start_date),
                        Filter.by_property("date").less_than(end_date)
                    ]
                )
            )
        )
    ]
)

import { Filters } from 'weaviate-client';
const goodResponse = await qa.ask(
    `What products were sold last month?`,
    {
        collections: [
            {
                name: 'FinancialContracts',
                additionalFilters: Filters.and(
                    financialCollection.filter.byProperty('date').greaterThan(new Date(2025, 0, 1)),
                    financialCollection.filter.byProperty('date').lessThan(new Date(2026, 0, 1)),
                ),
            },
        ],
    }
);

Additional Information

You would expect both examples to provide the same (or similar) output. The directness in the first prompt is very likely to ensure that the agent provides an accurate filter based on the request.

However, since the LLM agent is a non-deterministic process, it is never guaranteed. Directly passing the filter ensures it will always be used.

Another example could be in a user-facing app, if you want to restrict search results to only a single user ID, you can directly pass the filter instead of relying on the agent to use the correct filter.

Basic filtering

A single filter, such as limiting the search to only a single category, can be constructed simply.

Python (Agents)JavaScript/TypeScript (Agents)

QueryAgentCollectionConfig(
    name="ECommerce",
    additional_filters=Filter.by_property("category").equal("Tops")
)

const basicFilterConfig = {
    name: 'ECommerce',
    additionalFilters: ecommerceCollection.filter.byProperty('category').equal('Tops'),
};

Nested filtering

If you want to provide more than one filter, you can wrap it in either a logical AND or OR using Weaviate filter construction, such as:

Python (Agents)JavaScript/TypeScript (Agents)

QueryAgentCollectionConfig(
    name="ECommerce",
    additional_filters=Filter.any_of(
        [
            Filter.by_property("category").equal("Shoes"),
            Filter.all_of(
                [
                    Filter.by_property("price").greater_than(50),
                    Filter.by_property("price").less_than(100)
                ]
            )
        ]
    )
)

const nestedFilterConfig = {
    name: 'ECommerce',
    additionalFilters: Filters.or(
        ecommerceCollection.filter.byProperty('category').equal('Shoes'),
        Filters.and(
            ecommerceCollection.filter.byProperty('price').greaterThan(50),
            ecommerceCollection.filter.byProperty('price').lessThan(100),
        ),
    ),
};

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.