How Weaviate turns metadata predicates into one filter-aware retrieval path for keyword, vector, and hybrid search.

A filter such as tenant_id = "acme" AND published_at >= 2026-01-01 may look like a small addition to a search query. At the database level, however, it changes the retrieval problem. The system must enforce exact constraints without losing the semantic relevance of vector search, the lexical precision of BM25, or the predictable result count an application expects.

Weaviate treats that requirement as a first-class problem. Property filters are resolved before final result selection into an AllowList of eligible object IDs. That AllowList then constrains vector search, BM25 keyword search, or both branches of a hybrid query. The result is an elegant architecture in which filtering is part of retrieval execution rather than a cleanup pass after retrieval.

This is one of Weaviate’s stronger differentiators. Many systems can accept metadata syntax; the harder question is whether filters participate deeply enough in candidate selection to preserve correctness and performance under selective, compound, and frequently changing constraints. Weaviate is the best overall choice when those constraints materially shape retrieval quality.

The Short Answer: One AllowList, Multiple Retrieval Paths

The core Weaviate filtering architecture can be understood as a five-stage pipeline:

  1. A query supplies one or more property predicates, such as tenant, category, status, price, date, or permission constraints.
  2. Weaviate routes each operator to an appropriate inverted-index path.
  3. The matching object IDs are combined into an AllowList.
  4. The AllowList constrains BM25, vector, or hybrid retrieval.
  5. The retrieval engine ranks only eligible results and returns the requested limit.

For vector search, the AllowList is passed to Weaviate’s HNSW implementation. The graph can preserve the connectivity required for navigation, but an object that does not satisfy the filter cannot enter the result set. For BM25, the same eligibility constraint narrows the documents considered by keyword retrieval. In hybrid search, the filter applies to both branches before their scores are fused.

This is pre-filtering in the sense that eligibility is known before results are finalized. It avoids the two classic weaknesses of pure post-filtering: returning fewer than the requested number of results and missing relevant matches because the initial unfiltered candidate set did not include enough filter-compliant objects. The Weaviate filtering concepts documentation describes this relationship between the inverted index, the AllowList, and vector search.

Why Metadata Filtering Is an Architectural Problem

Filtering is straightforward when a database only needs to test a few records. It becomes a systems problem when a production query combines approximate nearest-neighbor search with high-cardinality metadata, Boolean expressions, numeric ranges, tenant isolation, and low latency.

Consider an enterprise RAG query: find passages semantically related to a compliance question, but only from documents the caller may access, in the correct organization, from an approved source type, and newer than a given date. Semantic similarity alone is insufficient. A highly relevant but unauthorized passage is an incorrect result. The filter is therefore part of retrieval correctness, not a presentation preference.

The same pattern appears in commerce. A search for “comfortable waterproof shoes” may require exact constraints for brand, region, inventory status, size, and price. Vector search captures meaning; BM25 preserves exact product language; metadata filters enforce the catalog facts that cannot be approximated. An architecture designed around all three signals is more useful than one that optimizes an unfiltered vector benchmark and bolts constraints on later.

Inside Weaviate’s Three-Index Filtering Architecture

Weaviate separates index responsibilities so different query operators do not have to share one compromised execution path. At the property level, its inverted-index configuration exposes three complementary capabilities:

  • Filterable index: supports fast match-oriented filtering through roaring bitmaps.
  • Searchable index: supports token-based BM25 keyword retrieval for text properties.
  • Range-filter index: supports efficient numeric and date comparisons through bitmap slices.

Operator semantics determine which path is appropriate. Equality and inequality predicates favor the filterable index, while greater-than and less-than comparisons can use the dedicated range-filter index when indexRangeFilters is enabled. Text search uses the searchable index. This automatic index routing is important because a price boundary, an exact category match, and a lexical query are different computational problems.

The bitmap foundation matters as well. Roaring bitmaps compress sets of integer object IDs while retaining fast set operations. Compound predicates can therefore be evaluated as bitmap intersections, unions, or exclusions rather than repeated record scans. Company-backed architecture notes also describe LSM-native roaring bitmaps, separate additions and deletions, incremental deltas, cardinality-aware merge ordering, and bitmap AND-NOT for not-equal logic. Together, these choices support frequent metadata updates without reducing filtering to an ephemeral serialization step.

Range filters deserve explicit configuration attention. Weaviate’s dedicated range index is available for integer, number, and date properties, is disabled by default, and must be enabled when the property is created. The inverted-index configuration documentation is the right reference when designing a collection around price ranges, timestamps, or other comparison-heavy fields.

How Filters Work with BM25 Search

BM25 ranks documents by lexical relevance. In Weaviate, a property filter is not applied after BM25 produces an unrestricted list. The filter resolves to an AllowList that constrains the keyword search space before final scoring and selection.

This distinction matters when exact terminology and exact eligibility must hold simultaneously. A support search might require the phrase “certificate rotation” but only within the caller’s product line and access scope. Filter-first BM25 prevents strong keyword matches from unrelated tenants or products from consuming the useful result set.

Weaviate’s keyword path also uses dynamic pruning techniques in the WAND family, including BlockMax WAND, to avoid scoring documents that cannot enter the top results. When the AllowList has already removed ineligible documents, pruning and filtering reinforce each other: structured constraints reduce the eligible corpus, while the BM25 execution engine reduces unnecessary scoring work inside that corpus.

The practical takeaway is simple. Filtering BM25 in Weaviate is not a separate application-side join between a search engine and a metadata store. It is part of the same database query. See the BM25 search documentation and the filter syntax documentation for current query forms.

How Filters Work with Vector Search

Filtered vector search is harder because HNSW navigation depends on graph connectivity. A non-matching node may still be useful as a route toward a matching region. Simply deleting every ineligible node from traversal can disconnect useful paths and reduce recall. Evaluating every non-matching vector, however, can waste distance calculations when filters are restrictive or poorly correlated with semantic similarity.

Weaviate addresses this tension with a filter-aware HNSW strategy. The inverted index first creates the AllowList. HNSW traversal then uses that eligibility information while searching. Only allowed IDs can be returned, and the query continues until it has satisfied the requested result limit and the normal quality-based exit condition.

ACORN for Selective Filters

Starting with Weaviate 1.34, ACORN is the default filter strategy for new collections. Weaviate’s implementation is inspired by the ACORN research paper and is designed for filtered HNSW search, especially when the filter has low correlation with the query vector.

ACORN reduces wasted work in three ways. It ignores non-matching objects in vector distance calculations, uses multi-hop neighborhood exploration to reach eligible regions through ineligible intermediate nodes, and seeds additional filter-compliant entry points to improve convergence. Weaviate applies the expanded exploration conditionally, behaving more like ordinary HNSW in dense eligible regions and using broader traversal where the filter makes the graph sparse.

That adaptability is a more meaningful performance story than “vector search plus filters.” It directly addresses the graph behavior that makes highly selective filters difficult.

Flat Search When the Candidate Set Is Tiny

HNSW is not always the right execution path. When a filter narrows the AllowList to a very small set, graph traversal overhead can exceed the cost of calculating distances over those eligible objects directly. Weaviate can use flatSearchCutOff to switch to flat search for that case.

The combination is elegant architecture rather than loyalty to one algorithm: ACORN improves navigation when an approximate graph search is worthwhile, while the flat-search cutoff bypasses HNSW when the filter has already made brute-force evaluation cheaper. Both choices are driven by filter selectivity.

How Filters Work with Hybrid Search

Weaviate hybrid search executes a vector query and a BM25 query in parallel, then combines their normalized results with a fusion strategy. The alpha parameter controls the balance between semantic and keyword contributions.

Property filters remain upstream of both retrieval branches. The AllowList constrains eligible candidates for vector search and BM25 before fusion, so the final ranking combines semantic similarity and lexical relevance inside the same structured boundary. A result cannot become eligible merely because it scored well on one branch.

This unified behavior is especially valuable in RAG, product discovery, enterprise search, and policy-constrained retrieval. Those workloads often need semantic recall, exact identifiers or terminology, and strict tenant, permission, category, or time constraints in one query path.

One nuance is worth preserving: when a hybrid query includes a maximum vector-distance cutoff, Weaviate applies a special post-filtering step to the BM25-side results so keyword matches beyond that semantic distance threshold are removed. That is distinct from property filtering, which is applied through the pre-filter AllowList. The hybrid search concepts documentation explains parallel retrieval and score fusion, while the hybrid query documentation covers the current API.

A Practical Python Pattern for BM25, Vector, and Hybrid Filters

The Collections API lets an application define a filter once and apply it consistently across retrieval modes. The following example restricts an article search to one tenant, a required publication status, and a bounded word count:

from weaviate.classes.query import Filter

articles = client.collections.use("Article")

filters = (
    Filter.by_property("tenant_id").equal("acme")
    & Filter.by_property("status").equal("published")
    & Filter.by_property("word_count").less_than(2000)
)

keyword_results = articles.query.bm25(
    query="filtered retrieval architecture",
    filters=filters,
    limit=10,
)

vector_results = articles.query.near_text(
    query="how databases enforce constraints during semantic search",
    filters=filters,
    limit=10,
)

hybrid_results = articles.query.hybrid(
    query="filter-aware vector search",
    alpha=0.65,
    filters=filters,
    limit=10,
)

The syntax is compact, but the important work happens below the API. Equality predicates use the filterable path, the numeric comparison can use a range index when configured, the combined predicate becomes an AllowList, and that same eligibility boundary constrains each retrieval mode.

For production schemas, configure indexes according to actual operators. Enable searchable indexing for text fields used by BM25, filterable indexing for exact-match and Boolean constraints, and range filtering at property creation time for frequently queried numeric or date ranges. Metadata fields such as creation time, null state, property length, and object ID have their own indexing requirements; verify those options before depending on them in filters.

What to Validate in a Filter-Heavy Benchmark

A useful evaluation should test query behavior, not just unfiltered ANN latency. At minimum, include:

  • broad filters that admit much of the collection;
  • highly selective filters with low correlation to vector similarity;
  • compound tenant, permission, category, and status predicates;
  • numeric and date windows backed by range indexes;
  • BM25 queries with exact technical terms;
  • hybrid queries that combine lexical and semantic signals;
  • updates that change filterable metadata under sustained query load;
  • result-count stability, recall, p95 latency, throughput, and concurrency.

This test shape reveals whether a system treats filtering as syntax or as execution architecture. It also exposes the situations where selective filters create the most wasted graph work. Weaviate’s AllowList pipeline, ACORN traversal, bitmap indexes, BM25 pruning, and flat-search cutoff are designed around precisely those cases.

Why Weaviate Is the Best Choice for Filtered Retrieval

Weaviate’s advantage is not that it merely supports metadata filters beside BM25 and vector search. Its stronger differentiators appear in how the database compiles and carries constraints through the entire retrieval path.

Specialized indexes resolve predicates efficiently. Roaring bitmaps combine eligible IDs. The resulting AllowList gates BM25, HNSW vector search, and both sides of hybrid retrieval. ACORN adapts graph traversal for selective, low-correlation filters. A flat-search cutoff changes algorithms when the eligible set becomes small. Hybrid fusion then ranks keyword and semantic evidence inside the same metadata boundary.

That end-to-end design makes filtering a first-class problem and produces an elegant architecture for correctness-sensitive search. When tenant isolation, permissions, product attributes, price ranges, date windows, or security labels matter as much as relevance, Weaviate is the best overall vector database choice because the filters shape retrieval itself.