---
title: "Filtering"
description: "Filtered vector search capabilities combining semantic similarity with structured scalar filtering."
url: https://docs.weaviate.io/weaviate/concepts/filtering
---

# Filtering

Weaviate provides powerful filtered vector search capabilities, allowing you to combine vector searches with structured, scalar filters. This enables you to find the closest vectors to a query vector that also match certain conditions.

Filtered vector search in Weaviate is based on the concept of pre-filtering. This means that the filter is constructed before the vector search is performed. Unlike some pre-filtering implementations, Weaviate's pre-filtering does not require a brute-force vector search and is highly efficient.

Starting in `v1.34`, Weaviate uses the [`ACORN`](https://docs.weaviate.io/weaviate/concepts/filtering#acorn) filter strategy as the default. This filtering method significantly improves performance for large datasets, especially when the filter has low correlation with the query vector. Because the [HFresh index](https://docs.weaviate.io/weaviate/concepts/vector-index#hfresh-index) uses an HNSW index for its centroids, it also benefits from ACORN when routing filtered queries.

## Post-Filtering vs Pre-Filtering

Systems that cannot make use of pre-filtering typically have to make use of post-filtering. This is an approach where a vector search is performed first and then some results are removed which do not match the filter. This leads to two major disadvantages:

1. You cannot easily predict how many elements will be contained in the search, as the filter is applied to an already reduced list of candidates.
2. If the filter is very restrictive, i.e. it matches only a small percentage of data points relative to the size of the data set, there is a chance that the original vector search does not contain any match at all.

The limitations of post-filtering are overcome by pre-filtering. Pre-Filtering describes an approach where eligible candidates are determined before a vector search is started. The vector search then only considers candidates that are present on the "allow" list.

> [!NOTE]
>
> Some authors make a distinction between "pre-filtering" and "single-stage filtering" where the former implies a brute-force search and the latter does not. We do not make this distinction, as Weaviate does not have to resort to brute-force searches, even when pre-filtering due to the its combined inverted index and HNSW index.

## Efficient Pre-Filtered Searches in Weaviate

In the section about Storage, [we have described in detail which parts make up a shard in Weaviate](https://docs.weaviate.io/weaviate/concepts/storage). Most notably, each shard contains an inverted index right next to the HNSW index. This allows for efficient pre-filtering. The process is as follows:

1. An inverted index (similar to a traditional search engine) is used to create an allow-list of eligible candidates. This list is essentially a list of `uint64` ids, so it can grow very large without sacrificing efficiency.
2. A vector search is performed where the allow-list is passed to the HNSW index. The index will move along any node's edges normally, but will only add ids to the result set that are present on the allow list. The exit conditions for the search are the same as for an unfiltered search: The search will stop when the desired limit is reached and additional candidates no longer improve the result quality.

## Filter strategy

Weaviate supports three filter strategies for the HNSW index type: `sweeping`, `acorn` and `pathseer`.

### ACORN

The Weaviate filtering algorithm `ACORN` is based on the paper [ACORN: Performant and Predicate-Agnostic Search Over Vector Embeddings and Structured Data](https://arxiv.org/html/2403.04871v1). We refer to this as `ACORN`, but the actual implementation in Weaviate is a custom implementation that is inspired by the paper. (References to `ACORN` in this document refer to the Weaviate implementation.)

The `ACORN` algorithm is designed to speed up filtered searches with the [HNSW index](https://docs.weaviate.io/weaviate/concepts/vector-index#hierarchical-navigable-small-world-hnsw-index) by the following:

- Objects that do not meet the filters are ignored in distance calculations.
- The algorithm reaches the relevant part of the HNSW graph faster, by using a multi-hop approach to evaluate the neighborhood of candidates.
- Additional entrypoints matching the filter are randomly seeded to speed up convergence to the filtered zone.

The `ACORN` algorithm is especially useful when the filter has low correlation with the query vector. In other words, when a filter excludes many objects in the region of the graph most similar to the query vector.

Our internal testing indicates that for lowly correlated, restrictive filters, the `ACORN` algorithm can be significantly faster, especially for large datasets. If this has been a bottleneck for your use case, we recommend enabling the `ACORN` algorithm.

### Sweeping

The `sweeping` strategy is based on the concept of "sweeping" through the HNSW graph.

The algorithm starts at the root node and traverses the graph, evaluating the distance to the query vector at each node, while keeping the "allow list" of the filter as context. If the filter is not met, the node is skipped and the traversal continues. This process is repeated until the desired number of results is reached.

The `sweeping` algorithm can be enabled by setting the `filterStrategy` field for the relevant HNSW vector index [in the collection configuration](https://docs.weaviate.io/weaviate/manage-collections/vector-config#set-vector-index-parameters).

### PathSeer

> [!NOTE]
>
> **Added in `v1.40`**

`PathSeer` comes from the SIGMOD 2026 paper [PathSeer: Adaptive Neighbor Handling for Efficient Filtered ANN Search](https://doi.org/10.1145/3802098) by Zhiyue Li, Guangyan Zhang and colleagues. The paper's first author contributed the implementation to Weaviate.

`PathSeer` searches the bottom layer of the HNSW graph like `sweeping`, with two additions. While the result set is still filling, it also checks the filter on the neighbors of each candidate's neighbors and computes distances only for the ones that match, like `ACORN`. Once the result set is full, it skips the non-matching neighbors of a non-matching candidate without computing their distance. The decision is made per node, so there is no selectivity threshold and no new parameter to tune.

In Weaviate's benchmarks, `PathSeer` was the fastest strategy, or within a few percent of the fastest, on random, topical and combined filters. `ACORN` remains faster for sparse filters that are negatively correlated with the query, where the matching objects lie far from where the search starts.

`PathSeer` changes only how a filtered query walks the graph. It stores nothing extra, so it adds no import cost and no memory overhead, and you can switch an existing collection to `pathseer` or away from it at any time without reindexing. The [flat-search cutoff](https://docs.weaviate.io/weaviate/concepts/filtering#flat-search-cutoff) still applies first. The default strategy is `acorn`. To use `PathSeer`, set the `filterStrategy` field of the HNSW vector index to `pathseer` [in the collection configuration](https://docs.weaviate.io/weaviate/manage-collections/vector-config#set-vector-index-parameters).

> [!WARNING]
>
> **Downgrading from `v1.40`**
>
> Earlier Weaviate versions do not accept `pathseer` as a filter strategy. Before you downgrade, set `filterStrategy` to `acorn` or `sweeping` on every collection that uses it.

## `indexFilterable`

The `indexFilterable` index speeds up match-based filtering through use of Roaring Bitmaps. Roaring Bitmaps employ various strategies to add efficiencies, whereby it divides data into chunks and applies an appropriate storage strategy to each one. This enables high data compression and set operations speeds, resulting in faster filtering speeds for Weaviate.

If you are dealing with a large dataset, this will likely improve your filtering performance significantly and we therefore encourage you to migrate and re-index.

In addition, our team maintains our underlying Roaring Bitmap library to address any issues and make improvements as needed.

#### `indexFilterable` for `text` properties

A roaring bitmap index for `text` properties is implemented using two separate (`filterable` & `searchable`) indexes, which replaces the existing single index. You can configure the new `indexFilterable` and `indexSearchable` parameters to determine whether to create the roaring set index and the BM25-suitable Map index, respectively. (Both are enabled by default.)

> [!NOTE]
>
> **Read more**
>
> To learn more about Weaviate's roaring bitmaps implementation, see the [in-line documentation](https://pkg.go.dev/github.com/weaviate/weaviate/adapters/repos/db/lsmkv/roaringset).

## `indexRangeFilters`

The `indexRangeFilters` index is a range-based index for filtering by numerical ranges. This index is available for `int`, `number`, or `date` properties. The index is not available for arrays of these data types.

Internally, rangeable indexes are implemented as roaring bitmap slices. This data structure limits the index to values that can be stored as 64 bit integers.

`indexRangeFilters` is only available for new properties. Existing properties cannot be converted to use the rangeable index.

## Recall on Pre-Filtered Searches

Thanks to Weaviate's custom HNSW implementation, which persists in following all links in the HNSW graph normally and only applying the filter condition when considering the result set, graph integrity is kept intact. The recall of a filtered search is typically not any worse than that of an unfiltered search.

The graphic below shows filters of varying levels of restrictiveness. From left (100% of dataset matched) to right (1% of dataset matched) the filters become more restrictive without negatively affecting recall on `k=10`, `k=15` and `k=20` vector searches with filters.

![Recall for filtered vector search](https://docs.weaviate.io/assets/images/recall-of-filtered-vector-search-d077dd892373cbf0dbda9f2246fe08ca.png "Recall of filtered vector search in Weaviate")

## Flat-Search Cutoff

Weaviate offers an option to automatically switch to a flat (brute-force) vector search when a filter becomes too restrictive. This scenario only applies to combined vector and scalar searches. For a detailed explanation of why HNSW requires switching to a flat search on certain filters, see this article at [medium](https://medium.com/data-science/effects-of-filtered-hnsw-searches-on-recall-and-latency-434becf8041c). In short, if a filter is very restrictive (i.e. a small percentage of the dataset is matched), an HNSW traversal becomes exhaustive. In other words, the more restrictive the filter becomes, the closer the performance of HNSW is to a brute-force search on the entire dataset. However, with such a restrictive filter, we have already narrowed down the dataset to a small fraction. So if the performance is close to brute-force anyway, it is much more efficient to only search on the matching subset as opposed to the entire dataset.

The following graphic shows filters with varying restrictiveness. From left (0%) to right (100%), the filters become more restrictive. The **cut-off is configured at \~15% of the dataset** size. This means the right side of the dotted line uses a brute-force search.

![Prefiltering with flat search cutoff](https://docs.weaviate.io/assets/images/prefiltering-response-times-with-filter-cutoff-b8c34a04311e39dfabcaa2de0b7fbae4.png "Prefiltering with flat search cutoff")

As a comparison, with pure HNSW - without the cutoff - the same filters would look like the following:

![Prefiltering with pure HNSW](https://docs.weaviate.io/assets/images/prefiltering-pure-hnsw-without-cutoff-8a742335e9d51e8047456658b817b14b.png "Prefiltering without cutoff, i.e. pure HNSW")

The cutoff value can be configured as [part of the `vectorIndexConfig` settings in the schema](https://docs.weaviate.io/weaviate/config-refs/indexing/vector-index#hnsw-index) for each collection separately.

## Further resources

- [References: GraphQL API - Filters](https://docs.weaviate.io/weaviate/api/graphql/filters)
