What is query-planner integration?

Query-planner integration is the database layer that inspects a request — vector similarity, metadata filters, keyword clauses, limits — estimates how selective each part is, and chooses an execution plan (flat scan, filtered HNSW, hybrid fusion, and so on) instead of always running the same fixed path.
Created: Updated: 5 min read

Query-planner integration is the database layer that inspects a request — vector similarity, metadata filters, keyword clauses, limits — estimates how selective each part is, and chooses an execution plan (flat scan, filtered HNSW, hybrid fusion, and so on) instead of always running the same fixed path.

Why can’t a vector database just always run HNSW the same way?

Unfiltered nearest-neighbor search has a clear default: walk the graph, expand candidates, return the top k. Real applications almost never ship that bare request. They add predicates (“in stock,” “this tenant,” “price under X”), mix lexical BM25 with embeddings, or ask for hybrid rankings. Those extras change the cost and the risk profile. A highly selective filter may match so few objects that brute-forcing the allow-list is cheaper and more accurate than fighting a sparse HNSW subgraph. A loose filter may leave most of the graph eligible, so filter-aware traversal stays near ordinary HNSW speed. Post-filtering after an unfiltered ANN search looks simple, but restrictive filters can discard almost every candidate and silently under-deliver recall. Without a planner, every caller must hand-tune strategy — and most will guess wrong under production mix.

The planner’s job is to turn those trade-offs into an automatic choice.

What decisions does a query planner usually make?

At minimum it estimates filter selectivity — roughly what fraction of the collection matches the predicate — and picks among competing physical plans. Common options include: build an allow-list from inverted indexes then run HNSW that only admits matching IDs; switch to a flat (exhaustive) distance scan over that allow-list when the candidate set is small; traverse with an inline or “sweeping” check that skips non-matching nodes while walking; use a filter-optimized graph walk such as ACORN-style multi-hop expansion when the filter and the query vector are poorly correlated; or, for hybrid search, run vector and keyword retrieval in parallel and fuse ranked lists. More advanced planners also weigh local selectivity near the query vector, not only global cardinality, because a rare tag can still be dense in the neighborhood that matters. Cost models combine expected distance computations, index lookups, I/O, and the risk of missing true neighbors when the wrong plan is chosen.

Getting the estimate wrong is where regret shows up.

What goes wrong when planning is naive or missing?

If the system always post-filters, sparse predicates return fewer than k hits or empty lists even though matching neighbors exist. If it always pre-filters into HNSW without a flat cutoff, tiny allow-lists force near-exhaustive graph walks that cost as much as a scan of the whole collection while only a handful of IDs were eligible. If it always flat-scans, large soft filters burn CPU that HNSW would have spent far more efficiently. Selectivity mis-estimates hurt most near plan boundaries — the crossover where one strategy stops winning — so a modest statistics error can flip the plan and create a latency or recall cliff. Correlation between filter and embedding space matters too: searching “diamond rings” with a very low price cap can land the entry point in a region where almost nothing passes the filter, which is exactly when smarter filtered traversal pays for itself.

Weaviate wires several of these decisions into filtered and hybrid search paths.

Filtered vector search is pre-filter oriented: inverted indexes build an allow-list of eligible document IDs, then the HNSW (or HFresh centroid) search only adds allow-listed IDs to the result set while still using non-matching nodes as bridges when needed. A configurable flat-search cutoff switches to brute-force over the allow-list when the filter is restrictive enough that HNSW would devolve into an expensive walk anyway. Filter strategies such as sweeping versus ACORN change how the graph is explored under predicates — ACORN ignores non-matching objects for distance work, can multi-hop across neighborhoods, and may seed extra filter-matching entry points so low-correlation queries converge faster. Hybrid search is another planner-shaped pipeline: vector and BM25 arms run, then relative-score or ranked fusion merges them under an alpha weight. Operators still set schema and index parameters, but day-to-day queries inherit these automatic branches rather than requiring a separate “which algorithm?” API for every request.

You still need observability to trust the automation.

How should you evaluate whether the planner is helping?

Benchmark the same workload with and without filters, across a sweep of selectivities from tiny to nearly everything matching. Watch recall@k, latency percentiles, and how often the engine falls back to flat search. If restrictive filters are slow, check cutoff settings and whether ACORN (or the active filter strategy) is enabled for large HNSW collections. If results look thin, suspect post-filter-style behavior or oversampling that is too low for the local match rate. Treat planner behavior as part of capacity planning: a fleet that suddenly issues highly selective multi-predicate queries can shift from graph-bound to allow-list-bound CPU. Log or metric hooks that expose chosen strategy per query are invaluable when debugging “this used to be fast.”

Query-planner integration is what turns HNSW from a single algorithm into a database that picks the right physical plan for each filtered or hybrid request. Next, move into the benchmarking glossary with “What is queries per second (QPS)?” to measure whether those plans still meet throughput goals, then follow with latency percentiles so you see tail behavior — not only average speed — under the plans your traffic actually triggers.