From e8d0564cadfc664153b6020f9de03d8808217e44 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Wed, 15 Jul 2026 20:40:44 +0800
Subject: [PATCH 01/25] Add live per-node filtered search + multiple-filter
 test report

Adds a production-style, query-time filter-match path for multihop search and
the benchmark/report artifacts from the multiple-filter evaluation.

diskann-label-filter:
- New live_filter module: InlineAttributeIndex (builder) -> FrozenAttributeIndex
  exposing a QueryLabelProvider whose is_match evaluates an AND/OR (+equality)
  predicate live, per visited node, against the node's roaring attribute-id set
  (lock-free read, integer-encoded terminals, no FFI, no global posting list).
  NOT/relational operators are rejected; evaluation errors are treated as
  non-match. Includes unit tests.

diskann-benchmark:
- New search type 'topk-multihop-live-filter' (plugin + SearchPhase wiring) that
  builds the attribute index once from the label file and evaluates the filter
  live during search, so reported latency includes the real per-node filter cost.
- filters.rs helpers: build_inline_attribute_index / make_live_providers.

diskann-benchmark-core / diskann-benchmark-runner:
- Add p99.9 latency percentile to the search output (percentiles, knn Summary,
  result DTO + console table).

Adds diskann-benchmark/multiple_filter_test_report.md documenting the 9-case
multihop vs beta vs live-filter comparison (recall + latency incl. p90/p99/p99.9).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../src/search/graph/knn.rs                   |  17 +-
 .../src/utils/percentiles.rs                  |   9 +
 .../multiple_filter_test_report.md            | 217 +++++++++++++++
 .../src/backend/index/benchmarks.rs           |  57 +++-
 diskann-benchmark/src/backend/index/result.rs |  29 +-
 .../src/backend/index/search/plugins.rs       |  12 +
 diskann-benchmark/src/inputs/graph_index.rs   |  17 ++
 diskann-benchmark/src/utils/filters.rs        |  53 ++++
 diskann-label-filter/src/lib.rs               |   2 +
 diskann-label-filter/src/live_filter.rs       | 253 ++++++++++++++++++
 10 files changed, 661 insertions(+), 5 deletions(-)
 create mode 100644 diskann-benchmark/multiple_filter_test_report.md
 create mode 100644 diskann-label-filter/src/live_filter.rs

diff --git a/diskann-benchmark-core/src/search/graph/knn.rs b/diskann-benchmark-core/src/search/graph/knn.rs
index c46217b416..9eca27390f 100644
--- a/diskann-benchmark-core/src/search/graph/knn.rs
+++ b/diskann-benchmark-core/src/search/graph/knn.rs
@@ -164,6 +164,11 @@ pub struct Summary {
     /// This contains one entry per repetition in the batch.
     pub p99_latencies: Vec<MicroSeconds>,
 
+    /// The 99.9th percentile latency for individual queries.
+    ///
+    /// This contains one entry per repetition in the batch.
+    pub p999_latencies: Vec<MicroSeconds>,
+
     /// The recall metrics for search.
     ///
     /// This implementation assumes that search is deterministic and only
@@ -239,20 +244,29 @@ where
         let mut mean_latencies = Vec::with_capacity(results.len());
         let mut p90_latencies = Vec::with_capacity(results.len());
         let mut p99_latencies = Vec::with_capacity(results.len());
+        let mut p999_latencies = Vec::with_capacity(results.len());
 
         results.iter_mut().for_each(|r| {
             match percentiles::compute_percentiles(r.latencies_mut()) {
                 Ok(values) => {
-                    let percentiles::Percentiles { mean, p90, p99, .. } = values;
+                    let percentiles::Percentiles {
+                        mean,
+                        p90,
+                        p99,
+                        p999,
+                        ..
+                    } = values;
                     mean_latencies.push(mean);
                     p90_latencies.push(p90);
                     p99_latencies.push(p99);
+                    p999_latencies.push(p999);
                 }
                 Err(_) => {
                     let zero = MicroSeconds::new(0);
                     mean_latencies.push(0.0);
                     p90_latencies.push(zero);
                     p99_latencies.push(zero);
+                    p999_latencies.push(zero);
                 }
             }
         });
@@ -265,6 +279,7 @@ where
             mean_latencies,
             p90_latencies,
             p99_latencies,
+            p999_latencies,
             mean_cmps: utils::average_all(
                 results
                     .iter()
diff --git a/diskann-benchmark-runner/src/utils/percentiles.rs b/diskann-benchmark-runner/src/utils/percentiles.rs
index 7b519e5f28..5f85571dc6 100644
--- a/diskann-benchmark-runner/src/utils/percentiles.rs
+++ b/diskann-benchmark-runner/src/utils/percentiles.rs
@@ -18,6 +18,7 @@ pub struct Percentiles<T> {
     pub median: f64,
     pub p90: T,
     pub p99: T,
+    pub p999: T,
 }
 
 pub trait AsF64Lossy: Copy {
@@ -77,6 +78,7 @@ where
 
     let p90 = x[((9 * len) / 10).min(len - 1)];
     let p99 = x[((99 * len) / 100).min(len - 1)];
+    let p999 = x[((999 * len) / 1000).min(len - 1)];
 
     Ok(Percentiles {
         minimum: x[0],
@@ -84,6 +86,7 @@ where
         median,
         p90,
         p99,
+        p999,
     })
 }
 
@@ -163,6 +166,7 @@ mod tests {
                 median: 10.0,
                 p90: 10,
                 p99: 10,
+                p999: 10,
             };
             assert_eq!(p, e);
         }
@@ -177,6 +181,7 @@ mod tests {
                 median: 1.5,
                 p90: 2,
                 p99: 2,
+                p999: 2,
             };
             assert_eq!(p, e);
         }
@@ -191,6 +196,7 @@ mod tests {
                 median: 2.0,
                 p90: 3,
                 p99: 3,
+                p999: 3,
             };
             assert_eq!(p, e);
         }
@@ -205,6 +211,7 @@ mod tests {
                 median: 5.0,
                 p90: 9,
                 p99: 9,
+                p999: 9,
             };
             assert_eq!(p, e);
         }
@@ -219,6 +226,7 @@ mod tests {
                 median: 5.5,
                 p90: 10,
                 p99: 10,
+                p999: 10,
             };
             assert_eq!(p, e);
         }
@@ -233,6 +241,7 @@ mod tests {
                 median: 6.0,
                 p90: 10,
                 p99: 11,
+                p999: 11,
             };
             assert_eq!(p, e);
         }
diff --git a/diskann-benchmark/multiple_filter_test_report.md b/diskann-benchmark/multiple_filter_test_report.md
new file mode 100644
index 0000000000..0d4d15f46b
--- /dev/null
+++ b/diskann-benchmark/multiple_filter_test_report.md
@@ -0,0 +1,217 @@
+# Multiple-Filter Search Test Report (corrected: set-membership labels)
+
+DiskANN filtered ANN search: **multihop** (hard filter) vs **beta** (soft filter), over 9 metadata-filter predicates, plus a **live per-node filter** variant that measures the real query-time filter cost (section 8). Labels use a **set-membership** model (each token is a boolean membership label), which correctly handles **multi-valued** attributes.
+
+_Generated: 2026-07-15 19:42_
+
+## 0. Correction note (vs earlier version)
+
+The source labels are positional (`GeoLocationID_a, GeoLocationID_b, EN-US, ...`) and **geo is multi-valued**: 27.9% of the 9,996,160 lines carry more than one GeoLocationID (up to 49), and token0 is always *a* GeoLocationID but not the only one.
+
+The earlier encoding modeled only **token0** as a single-valued string field `geo`, so a predicate like `geo = GeoLocationID_9` matched only docs where 9 was the **first** token (1,357 docs), missing docs tagged with 9 elsewhere. The corrected model treats **every token as a boolean membership label**, so `contains GeoLocationID_9` matches all 363,817 docs. Effects are confined to the geo cases (S5-S8); market cases (S1-S4, S9) were already boolean and are unchanged.
+
+| Case | old "token0-geo" selectivity | corrected "contains" selectivity |
+|---|---:|---:|
+| S5 GeoLocationID_190 | 55.631% | 60.1133% |
+| S6 GeoLocationID_90 | 11.303% | 12.5768% |
+| S7 GeoLocationID_9 | 0.014% | 3.6396% |
+| S8 GeoLocationID_119 | 0.790% | 1.1682% |
+
+Recall impact of the correction (multihop, recall@150):
+- **S7 (geo 9): 0.49 -> 0.88 @L150, 0.77 -> 0.97 @L1000.** The earlier "collapse" was an encoding artifact (ultra-sparse 1,357-doc set); the true "tagged-with-9" set (363k) is dense and reachable.
+- S5/S6/S8 grew slightly in selectivity with little recall change (already broad enough).
+
+## 1. Environment & dataset
+
+| | |
+|---|---|
+| Host | Windows, 16 logical cores |
+| Points | 9,996,160 | 
+| Dimensions | 64 (int8 source, converted to float32 for build) |
+| Queries | first 1,000 embeddings |
+| Distinct labels | 596 (548 GeoLocationIDs + 48 market codes) |
+
+## 2. Index build (once, reused)
+
+float32, distance squared_l2, max_degree 64, l_build 100, alpha 1.2, medoid start, 16 build threads; build ~400 s; saved as `idxsave_full` and loaded for every search job.
+
+## 3. Methodology
+
+- **Labels (set-membership):** each line token -> boolean field `{"doc_id":i,"GeoLocationID_190":true,"EN-US":true,...}`. A label matches regardless of position. Predicates use `{"<label>":{"$eq":true}}` composed with `$and`/`$or`.
+- Full-vocabulary file `data_labels_set.jsonl` (all 596 labels) supports *any* query. For the 9 test cases the referenced-label subset `data_labels_min.jsonl` (11 labels) yields **identical** match-sets/recall/latency and is used here for speed.
+- **Filtered groundtruth** via `compute_groundtruth` (shared evaluator with the benchmark), true top-150 among matching docs, `recall_at=150`.
+- **Search:** k=150, L in {150,200,300,500,1000}, 3 reps, single thread. Beta uses `beta=0.1`. Recall = recall@150 vs the same filtered GT for both methods.
+
+## 4. Filter cases & (corrected) selectivity
+
+| Case | Predicate | Matches | Selectivity |
+|---|---|---:|---:|
+| S1 | EN-US | ~6,636,960 | 66.3951% |
+| S2 | EN-CA AND FR-CA | ~759,678 | 7.5997% |
+| S3 | EN-CA OR FR-CA | ~1,467,686 | 14.6825% |
+| S4 | (EN-CA AND FR-CA) OR (ES-MX AND ES-AR) | ~1,003,045 | 10.0343% |
+| S5 | GeoLocationID_190 | ~6,009,022 | 60.1133% |
+| S6 | GeoLocationID_90 | ~1,257,197 | 12.5768% |
+| S7 | GeoLocationID_9 | ~363,820 | 3.6396% |
+| S8 | GeoLocationID_119 | ~116,775 | 1.1682% |
+| S9 | GeoLocationID_4079 AND GeoLocationID_4092 | ~566,852 | 5.6707% |
+
+## 5. Results (latency in ms, single thread, k=150)
+
+### 5.1 Multihop (hard filter)
+
+| Case | L | recall | QPS | mean | p90 | p99 | p99.9 |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| S1 | 150 | 0.9710 | 319 | 3.15 | 6.49 | 10.19 | 13.70 |
+| S1 | 200 | 0.9779 | 260 | 3.85 | 7.75 | 12.97 | 18.88 |
+| S1 | 300 | 0.9847 | 196 | 5.10 | 10.51 | 17.17 | 22.23 |
+| S1 | 500 | 0.9909 | 125 | 8.00 | 16.44 | 27.05 | 45.60 |
+| S1 | 1000 | 0.9947 | 77 | 12.93 | 26.48 | 40.48 | 52.05 |
+| S2 | 150 | 0.9458 | 230 | 4.35 | 6.66 | 8.50 | 11.10 |
+| S2 | 200 | 0.9590 | 187 | 5.34 | 8.15 | 10.12 | 11.69 |
+| S2 | 300 | 0.9725 | 137 | 7.27 | 11.10 | 14.03 | 16.55 |
+| S2 | 500 | 0.9830 | 89 | 11.23 | 17.14 | 20.85 | 26.02 |
+| S2 | 1000 | 0.9901 | 48 | 20.84 | 31.21 | 39.21 | 55.81 |
+| S3 | 150 | 0.9503 | 229 | 4.37 | 7.24 | 10.06 | 11.57 |
+| S3 | 200 | 0.9607 | 183 | 5.47 | 9.15 | 12.59 | 14.47 |
+| S3 | 300 | 0.9731 | 131 | 7.62 | 12.73 | 16.96 | 19.41 |
+| S3 | 500 | 0.9825 | 86 | 11.66 | 19.67 | 26.19 | 31.93 |
+| S3 | 1000 | 0.9887 | 46 | 21.58 | 35.37 | 45.76 | 52.36 |
+| S4 | 150 | 0.9534 | 222 | 4.50 | 7.24 | 9.72 | 12.63 |
+| S4 | 200 | 0.9634 | 179 | 5.60 | 9.00 | 12.14 | 13.69 |
+| S4 | 300 | 0.9758 | 127 | 7.88 | 12.83 | 17.28 | 22.73 |
+| S4 | 500 | 0.9847 | 83 | 12.07 | 19.51 | 26.43 | 31.67 |
+| S4 | 1000 | 0.9912 | 44 | 22.64 | 36.22 | 47.26 | 51.65 |
+| S5 | 150 | 0.9724 | 280 | 3.57 | 6.96 | 10.05 | 13.63 |
+| S5 | 200 | 0.9791 | 230 | 4.34 | 8.57 | 12.55 | 15.39 |
+| S5 | 300 | 0.9862 | 170 | 5.87 | 11.40 | 17.08 | 20.15 |
+| S5 | 500 | 0.9925 | 111 | 8.97 | 17.89 | 26.25 | 31.36 |
+| S5 | 1000 | 0.9961 | 65 | 15.48 | 31.03 | 45.38 | 56.29 |
+| S6 | 150 | 0.8707 | 170 | 5.87 | 8.30 | 9.74 | 11.13 |
+| S6 | 200 | 0.8973 | 137 | 7.27 | 10.32 | 12.16 | 13.81 |
+| S6 | 300 | 0.9264 | 99 | 10.13 | 14.35 | 16.64 | 21.54 |
+| S6 | 500 | 0.9504 | 64 | 15.51 | 21.95 | 25.34 | 30.74 |
+| S6 | 1000 | 0.9690 | 35 | 28.47 | 39.62 | 46.58 | 58.52 |
+| S7 | 150 | 0.8835 | 150 | 6.64 | 8.85 | 10.25 | 12.43 |
+| S7 | 200 | 0.9073 | 119 | 8.42 | 11.20 | 12.71 | 15.98 |
+| S7 | 300 | 0.9320 | 83 | 12.09 | 16.02 | 19.73 | 29.56 |
+| S7 | 500 | 0.9539 | 54 | 18.65 | 24.42 | 27.92 | 33.29 |
+| S7 | 1000 | 0.9698 | 29 | 34.84 | 44.62 | 50.24 | 72.93 |
+| S8 | 150 | 0.8337 | 146 | 6.84 | 8.63 | 10.12 | 11.60 |
+| S8 | 200 | 0.8615 | 119 | 8.43 | 10.64 | 12.30 | 14.91 |
+| S8 | 300 | 0.8951 | 86 | 11.63 | 14.68 | 16.29 | 20.25 |
+| S8 | 500 | 0.9244 | 54 | 18.42 | 23.23 | 26.88 | 33.14 |
+| S8 | 1000 | 0.9509 | 30 | 33.60 | 41.09 | 45.45 | 51.38 |
+| S9 | 150 | 0.9189 | 220 | 4.55 | 6.68 | 8.05 | 9.42 |
+| S9 | 200 | 0.9380 | 173 | 5.79 | 8.52 | 10.21 | 13.13 |
+| S9 | 300 | 0.9594 | 125 | 8.00 | 11.89 | 14.13 | 17.20 |
+| S9 | 500 | 0.9763 | 82 | 12.19 | 17.92 | 21.32 | 25.72 |
+| S9 | 1000 | 0.9869 | 45 | 22.37 | 32.75 | 38.50 | 47.65 |
+
+### 5.2 Beta (soft filter, beta=0.1)
+
+| Case | L | recall | QPS | mean | p90 | p99 | p99.9 |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| S1 | 150 | 0.8387 | 1481 | 0.67 | 1.09 | 1.51 | 2.22 |
+| S1 | 200 | 0.8534 | 1183 | 0.84 | 1.34 | 1.88 | 2.42 |
+| S1 | 300 | 0.8659 | 853 | 1.17 | 1.88 | 2.61 | 3.29 |
+| S1 | 500 | 0.8766 | 548 | 1.83 | 2.93 | 4.01 | 5.10 |
+| S1 | 1000 | 0.8843 | 287 | 3.48 | 5.61 | 7.53 | 10.02 |
+| S2 | 150 | 0.6581 | 1157 | 0.86 | 1.24 | 1.68 | 2.12 |
+| S2 | 200 | 0.6838 | 916 | 1.09 | 1.58 | 2.26 | 2.99 |
+| S2 | 300 | 0.7144 | 651 | 1.54 | 2.27 | 3.16 | 9.96 |
+| S2 | 500 | 0.7391 | 430 | 2.33 | 3.36 | 4.43 | 6.36 |
+| S2 | 1000 | 0.7609 | 235 | 4.26 | 5.97 | 7.31 | 9.30 |
+| S3 | 150 | 0.6789 | 1200 | 0.83 | 1.27 | 1.68 | 2.28 |
+| S3 | 200 | 0.7037 | 990 | 1.01 | 1.53 | 1.99 | 2.46 |
+| S3 | 300 | 0.7311 | 708 | 1.41 | 2.14 | 2.72 | 3.42 |
+| S3 | 500 | 0.7566 | 455 | 2.20 | 3.29 | 4.37 | 5.62 |
+| S3 | 1000 | 0.7751 | 239 | 4.18 | 6.10 | 7.49 | 8.77 |
+| S4 | 150 | 0.6699 | 1133 | 0.88 | 1.32 | 1.80 | 2.52 |
+| S4 | 200 | 0.6935 | 924 | 1.08 | 1.61 | 2.10 | 2.60 |
+| S4 | 300 | 0.7235 | 679 | 1.47 | 2.20 | 2.84 | 3.36 |
+| S4 | 500 | 0.7493 | 437 | 2.29 | 3.37 | 4.26 | 5.42 |
+| S4 | 1000 | 0.7711 | 229 | 4.36 | 6.25 | 7.88 | 17.94 |
+| S5 | 150 | 0.7996 | 1414 | 0.71 | 1.15 | 1.54 | 2.07 |
+| S5 | 200 | 0.8149 | 1124 | 0.89 | 1.44 | 1.93 | 2.35 |
+| S5 | 300 | 0.8311 | 817 | 1.22 | 1.99 | 2.68 | 3.20 |
+| S5 | 500 | 0.8438 | 526 | 1.90 | 3.08 | 3.99 | 4.73 |
+| S5 | 1000 | 0.8535 | 275 | 3.63 | 5.88 | 7.59 | 9.07 |
+| S6 | 150 | 0.4630 | 852 | 1.17 | 1.55 | 1.93 | 2.24 |
+| S6 | 200 | 0.4962 | 678 | 1.48 | 1.94 | 2.39 | 3.04 |
+| S6 | 300 | 0.5385 | 489 | 2.04 | 2.67 | 3.38 | 4.05 |
+| S6 | 500 | 0.5848 | 319 | 3.13 | 4.10 | 4.83 | 5.66 |
+| S6 | 1000 | 0.6399 | 168 | 5.95 | 7.68 | 9.11 | 19.75 |
+| S7 | 150 | 0.3884 | 785 | 1.27 | 1.62 | 2.08 | 2.43 |
+| S7 | 200 | 0.4185 | 630 | 1.59 | 2.01 | 2.54 | 3.21 |
+| S7 | 300 | 0.4653 | 459 | 2.18 | 2.80 | 3.47 | 4.32 |
+| S7 | 500 | 0.5234 | 296 | 3.37 | 4.34 | 5.17 | 6.30 |
+| S7 | 1000 | 0.5776 | 160 | 6.26 | 8.05 | 10.00 | 13.25 |
+| S8 | 150 | 0.3774 | 730 | 1.37 | 1.63 | 2.13 | 3.39 |
+| S8 | 200 | 0.4114 | 566 | 1.77 | 2.15 | 2.73 | 3.33 |
+| S8 | 300 | 0.4631 | 402 | 2.49 | 3.07 | 4.18 | 10.73 |
+| S8 | 500 | 0.5132 | 268 | 3.73 | 4.52 | 5.63 | 7.08 |
+| S8 | 1000 | 0.5680 | 149 | 6.71 | 8.09 | 9.51 | 11.02 |
+| S9 | 150 | 0.5580 | 1103 | 0.91 | 1.31 | 1.78 | 2.47 |
+| S9 | 200 | 0.5913 | 904 | 1.11 | 1.58 | 2.02 | 2.49 |
+| S9 | 300 | 0.6351 | 628 | 1.59 | 2.30 | 3.00 | 3.97 |
+| S9 | 500 | 0.6786 | 412 | 2.43 | 3.45 | 4.35 | 5.18 |
+| S9 | 1000 | 0.7213 | 223 | 4.49 | 6.27 | 7.64 | 8.89 |
+
+## 6. Recall side-by-side (multihop vs beta)
+
+| Case (sel.) | L=150 MH / Beta | L=1000 MH / Beta |
+|---|---|---|
+| S1 (66.40%) | 0.971 / 0.839 | 0.995 / 0.884 |
+| S2 (7.60%) | 0.946 / 0.658 | 0.990 / 0.761 |
+| S3 (14.68%) | 0.950 / 0.679 | 0.989 / 0.775 |
+| S4 (10.03%) | 0.953 / 0.670 | 0.991 / 0.771 |
+| S5 (60.11%) | 0.972 / 0.800 | 0.996 / 0.853 |
+| S6 (12.58%) | 0.871 / 0.463 | 0.969 / 0.640 |
+| S7 (3.64%) | 0.883 / 0.388 | 0.970 / 0.578 |
+| S8 (1.17%) | 0.834 / 0.377 | 0.951 / 0.568 |
+| S9 (5.67%) | 0.919 / 0.558 | 0.987 / 0.721 |
+
+## 7. Observations
+
+- **Multihop reaches high recall across all cases now** (>=0.83 @L150, >=0.95 @L1000), including the geo cases, because corrected "contains" sets are dense enough to traverse.
+- **Beta is much faster but recall-limited** and collapses on selective filters; recall plateaus with L (soft re-rank keeps globally-close non-matches).
+- **Selectivity drives cost/recall** more than AND/OR structure; the previous "S7 is unsolvable" conclusion was an artifact of mis-encoding a multi-valued attribute as single-valued.
+
+## 8. Live per-node filter vs precomputed bitmap
+
+Both multihop runs above use a **precomputed whole-corpus bitmap** for the filter: the match set of each query is computed offline (a full-dataset scan) and `is_match(id)` is an O(1) bitmap lookup. That work is **not** included in the reported search latency.
+
+To measure the **real** filter cost, a new search type `topk-multihop-live-filter` evaluates the predicate **live, per visited node**: each vector's labels are stored as a roaring set of integer attribute-ids (built once, like an index), the query predicate is encoded once to integer terminals, and `is_match(id)` reads the node's set (lock-free) and evaluates the AND/OR expression via `contains`. No FFI, no global posting list. Only AND/OR + equality are supported (NOT/relational rejected).
+
+Results at **L=150, k=150, single thread** (recall is identical because traversal is the same; only how `is_match` is computed differs):
+
+| Case (sel.) | recall (live == bitmap) | mean live / bitmap | p90 live | p99 live / bitmap | p99.9 live | live QPS |
+|---|---:|---|---:|---|---:|---:|
+| S1 (66.4%) | 0.9710 | 20.9 / 3.2 ms | 46.1 ms | 93.9 / 10.2 ms | 139.5 ms | 48 |
+| S2 (7.6%) | 0.9458 | 48.1 / 4.3 ms | 84.7 ms | 124.7 / 8.5 ms | 221.8 ms | 21 |
+| S3 (14.7%) | 0.9503 | 54.1 / 4.4 ms | 99.9 ms | 150.4 / 10.1 ms | 185.3 ms | 18 |
+| S4 (10.0%) | 0.9534 | 83.1 / 4.5 ms | 155.7 ms | 214.9 / 9.7 ms | 238.0 ms | 12 |
+| S5 (60.1%) | 0.9724 | 24.7 / 3.6 ms | 54.4 ms | 99.5 / 10.1 ms | 132.4 ms | 41 |
+| S6 (12.6%) | 0.8707 | 69.8 / 5.9 ms | 108.0 ms | 133.8 / 9.7 ms | 145.9 ms | 14 |
+| S7 (3.6%) | 0.8835 | 88.9 / 6.6 ms | 123.5 ms | 146.4 / 10.3 ms | 160.9 ms | 11 |
+| S8 (1.2%) | 0.8337 | 98.3 / 6.8 ms | 130.3 ms | 145.9 / 10.1 ms | 181.1 ms | 10 |
+| S9 (5.7%) | 0.9189 | 55.6 / 4.5 ms | 97.4 ms | 124.8 / 8.0 ms | 150.2 ms | 18 |
+
+- **Correctness:** live recall equals the bitmap recall to 5 decimals for every case (recall diff = 0.00000) — the live match is functionally identical.
+- **The hidden cost is large:** live mean latency is ~7-18x the bitmap number (e.g. S4 4.5 -> 83 ms, S8 6.8 -> 98 ms) and p99 is ~10-22x higher. The precomputed-bitmap benchmark amortized predicate evaluation into an untimed offline pass, so its latency only reflected O(1) lookups.
+- **Cost scales with expression complexity and traversal size:** the AND/OR combo (S4) and selective geo filters (S6-S8, more hops through non-matching regions -> more `is_match` calls) are the most expensive; broad single-term filters (S1, S5) are cheapest.
+- This is the production-relevant number: a real system evaluates the filter at query time (per node), not from a precomputed whole-corpus answer.
+
+## 9. Artifacts (`Q:\test6\filtered_test2\bench\full\`)
+
+- Labels: `data_labels_set.jsonl` (596 labels, general), `data_labels_min.jsonl` (11, fast)
+- Predicates: `predmin_S1..S9.jsonl` (also `predset_S1..S9.jsonl`)
+- Groundtruth: `gtmin_S1..S9.bin`
+- Runbooks: `runbook_setmin.json` (multihop), `runbook_beta_setmin.json` (beta), `runbook_livefilter.json` (live per-node)
+- Outputs: `out_setmin.json`, `out_beta_setmin.json`, `out_livefilter.json` (+ `out_live_S8.json`, `out_live_S9.json`)
+- Encoders: `gen_setmembership.py` (full), `gen_setmin.py` (minimal)
+- Live-filter code: `diskann-label-filter/src/live_filter.rs` (InlineAttributeIndex / FrozenAttributeIndex + QueryLabelProvider); benchmark search-type `topk-multihop-live-filter`
+- Index (reused): `idxsave_full`(+`.data`)
+
+_Note: an earlier version of this report used a single-valued `geo` string field; it is superseded by the set-membership results above._
\ No newline at end of file
diff --git a/diskann-benchmark/src/backend/index/benchmarks.rs b/diskann-benchmark/src/backend/index/benchmarks.rs
index e0684923ae..20085795e3 100644
--- a/diskann-benchmark/src/backend/index/benchmarks.rs
+++ b/diskann-benchmark/src/backend/index/benchmarks.rs
@@ -76,7 +76,8 @@ pub(super) fn register_benchmarks(registry: &mut Registry) -> anyhow::Result<()>
             .search(plugins::Topk)
             .search(plugins::Range)
             .search(plugins::TopkBetaFilter)
-            .search(plugins::TopkMultihopFilter),
+            .search(plugins::TopkMultihopFilter)
+            .search(plugins::TopkMultihopLiveFilter),
     )?;
 
     registry.register(
@@ -638,6 +639,60 @@ where
     }
 }
 
+//--------------------//
+// MultihopLiveFilter //
+//--------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>> for plugins::TopkMultihopLiveFilter
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<DP, &'a [DP::Element]> + Clone + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        let multihop = phase.as_topk_multihop_live_filter()?;
+
+        let queries: Arc<Matrix<DP::Element>> = Arc::new(datafiles::load_dataset(
+            datafiles::BinFile(&multihop.queries),
+        )?);
+
+        let groundtruth =
+            datafiles::load_range_groundtruth(datafiles::BinFile(&multihop.groundtruth))?;
+
+        let steps =
+            search::knn::SearchSteps::new(multihop.reps, &multihop.num_threads, &multihop.runs);
+
+        // Build the in-memory attribute index once (a one-time index build), then construct a
+        // live per-query provider that evaluates the predicate against each visited node's
+        // attributes during search.
+        let attribute_index =
+            utils::filters::build_inline_attribute_index(&multihop.data_labels)?;
+        let providers =
+            utils::filters::make_live_providers(&attribute_index, &multihop.query_predicates)?;
+
+        let multihop = benchmark_core::search::graph::MultiHop::new(
+            index,
+            queries,
+            benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
+            providers.into(),
+        )?;
+
+        let result = search::knn::run(&multihop, &groundtruth, steps)?;
+        Ok(AggregatedSearchResults::Topk(result))
+    }
+}
 /// The stack looks like this:
 ///
 /// - Bottom: [`FullPrecisionStream`]: The core streaming index implementation.
diff --git a/diskann-benchmark/src/backend/index/result.rs b/diskann-benchmark/src/backend/index/result.rs
index a68650d148..52a5a57634 100644
--- a/diskann-benchmark/src/backend/index/result.rs
+++ b/diskann-benchmark/src/backend/index/result.rs
@@ -92,6 +92,7 @@ pub(super) struct SearchResults {
     pub(super) mean_latencies: Vec<f64>,
     pub(super) p90_latencies: Vec<MicroSeconds>,
     pub(super) p99_latencies: Vec<MicroSeconds>,
+    pub(super) p999_latencies: Vec<MicroSeconds>,
     pub(super) recall: utils::recall::RecallMetrics,
     pub(super) mean_cmps: f32,
     pub(super) mean_hops: f32,
@@ -106,6 +107,7 @@ impl SearchResults {
             mean_latencies,
             p90_latencies,
             p99_latencies,
+            p999_latencies,
             recall,
             mean_cmps,
             mean_hops,
@@ -126,6 +128,7 @@ impl SearchResults {
             mean_latencies,
             p90_latencies,
             p99_latencies,
+            p999_latencies,
             recall: (&recall).into(),
             mean_cmps: mean_cmps as f32,
             mean_hops: mean_hops as f32,
@@ -155,7 +158,9 @@ where
             "Avg hops",
             "QPS - mean(max)",
             "Avg Latency",
+            "p90 Latency",
             "p99 Latency",
+            "p999 Latency",
             "Recall",
             "Threads",
         ]
@@ -167,7 +172,9 @@ where
             "Avg hops",
             "QPS - mean(max)",
             "Avg Latency",
+            "p90 Latency",
             "p99 Latency",
+            "p999 Latency",
             "Recall",
             "Threads",
         ]
@@ -203,16 +210,32 @@ where
             ),
             col_idx + 5,
         );
+        row.insert(
+            format!(
+                "{:.1}us ({:.1})",
+                MaybeDisplay(percentiles::mean(&r.p90_latencies), "missing"),
+                MaybeDisplay(r.p90_latencies.iter().max(), "missing"),
+            ),
+            col_idx + 6,
+        );
         row.insert(
             format!(
                 "{:.1}us ({:.1})",
                 MaybeDisplay(percentiles::mean(&r.p99_latencies), "missing"),
                 MaybeDisplay(r.p99_latencies.iter().max(), "missing"),
             ),
-            col_idx + 6,
+            col_idx + 7,
+        );
+        row.insert(
+            format!(
+                "{:.1}us ({:.1})",
+                MaybeDisplay(percentiles::mean(&r.p999_latencies), "missing"),
+                MaybeDisplay(r.p999_latencies.iter().max(), "missing"),
+            ),
+            col_idx + 8,
         );
-        row.insert(format!("{:3}", r.recall.average), col_idx + 7);
-        row.insert(r.num_tasks, col_idx + 8);
+        row.insert(format!("{:3}", r.recall.average), col_idx + 9);
+        row.insert(r.num_tasks, col_idx + 10);
     });
 
     write!(f, "{}", table)
diff --git a/diskann-benchmark/src/backend/index/search/plugins.rs b/diskann-benchmark/src/backend/index/search/plugins.rs
index e0aca593f6..c78553f723 100644
--- a/diskann-benchmark/src/backend/index/search/plugins.rs
+++ b/diskann-benchmark/src/backend/index/search/plugins.rs
@@ -183,3 +183,15 @@ impl TopkMultihopFilter {
         SearchPhaseKind::TopkMultihopFilter
     }
 }
+
+/// A search plugin for multi-hop filtered search that evaluates the filter predicate live
+/// (per visited node) against an in-memory attribute index, instead of a precomputed bitmap.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkMultihopLiveFilter;
+
+impl TopkMultihopLiveFilter {
+    /// Returns [`SearchPhaseKind::TopkMultihopLiveFilter`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkMultihopLiveFilter
+    }
+}
diff --git a/diskann-benchmark/src/inputs/graph_index.rs b/diskann-benchmark/src/inputs/graph_index.rs
index 5a3231825b..286968a42c 100644
--- a/diskann-benchmark/src/inputs/graph_index.rs
+++ b/diskann-benchmark/src/inputs/graph_index.rs
@@ -314,6 +314,7 @@ pub(crate) enum SearchPhase {
     Range(RangeSearchPhase),
     TopkBetaFilter(BetaSearchPhase),
     TopkMultihopFilter(MultiHopSearchPhase),
+    TopkMultihopLiveFilter(MultiHopSearchPhase),
 }
 
 #[derive(Debug, Error)]
@@ -340,6 +341,7 @@ impl SearchPhase {
             Self::Range(_) => SearchPhaseKind::Range,
             Self::TopkBetaFilter(_) => SearchPhaseKind::TopkBetaFilter,
             Self::TopkMultihopFilter(_) => SearchPhaseKind::TopkMultihopFilter,
+            Self::TopkMultihopLiveFilter(_) => SearchPhaseKind::TopkMultihopLiveFilter,
         }
     }
 
@@ -384,6 +386,18 @@ impl SearchPhase {
             )),
         }
     }
+
+    pub(crate) fn as_topk_multihop_live_filter(
+        &self,
+    ) -> Result<&MultiHopSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkMultihopLiveFilter(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkMultihopLiveFilter,
+                self.kind(),
+            )),
+        }
+    }
 }
 
 impl SearchPhase {
@@ -393,6 +407,7 @@ impl SearchPhase {
             SearchPhase::Range(phase) => phase.validate(checker),
             SearchPhase::TopkBetaFilter(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopFilter(phase) => phase.validate(checker),
+            SearchPhase::TopkMultihopLiveFilter(phase) => phase.validate(checker),
         }
     }
 }
@@ -403,6 +418,7 @@ pub(crate) enum SearchPhaseKind {
     Range,
     TopkBetaFilter,
     TopkMultihopFilter,
+    TopkMultihopLiveFilter,
 }
 
 impl SearchPhaseKind {
@@ -412,6 +428,7 @@ impl SearchPhaseKind {
             Self::Range => "range",
             Self::TopkBetaFilter => "topk-beta-filter",
             Self::TopkMultihopFilter => "topk-multihop-filter",
+            Self::TopkMultihopLiveFilter => "topk-multihop-live-filter",
         }
     }
 }
diff --git a/diskann-benchmark/src/utils/filters.rs b/diskann-benchmark/src/utils/filters.rs
index 43d528c18b..361b5148ef 100644
--- a/diskann-benchmark/src/utils/filters.rs
+++ b/diskann-benchmark/src/utils/filters.rs
@@ -22,6 +22,11 @@ use diskann_providers::model::graph::provider::layers::BetaFilter;
 use diskann_tools::utils::ground_truth::read_labels_and_compute_bitmap;
 use std::sync::Arc;
 
+use diskann_label_filter::attribute::Attribute;
+use diskann_label_filter::{
+    read_and_parse_queries, read_baselabels, FrozenAttributeIndex, InlineAttributeIndex,
+};
+
 pub struct QueryBitmapEvaluator {
     pub ast_expr: ASTExpr,
     evaluated_bitmap: RoaringPostingList,
@@ -116,6 +121,54 @@ pub(crate) fn as_query_label_provider(set: BitSet) -> Arc<dyn QueryLabelProvider
     Arc::new(BitmapFilter(set))
 }
 
+/// Build an in-memory inline attribute index from a jsonl label file (one document per line).
+///
+/// Each document's flattened `(field, value)` pairs are encoded to integer attribute-ids and
+/// stored as a roaring set keyed by `doc_id`. This is a one-time index build, reused across
+/// all queries; the per-node match decision itself is computed live during search.
+pub(crate) fn build_inline_attribute_index(
+    data_labels: &InputFile,
+) -> anyhow::Result<Arc<FrozenAttributeIndex>> {
+    let docs = read_baselabels(data_labels.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to read base labels: {e}"))?;
+    let mut index = InlineAttributeIndex::new();
+    let mut attrs: Vec<Attribute> = Vec::new();
+    for doc in &docs {
+        attrs.clear();
+        if let Some(obj) = doc.label.as_object() {
+            for (field, value) in obj {
+                attrs.push(Attribute::from_json_value(field, value).map_err(|e| {
+                    anyhow::anyhow!("attribute conversion failed for field '{field}': {e:?}")
+                })?);
+            }
+        }
+        index
+            .insert_document(doc.doc_id as u32, &attrs)
+            .map_err(|e| anyhow::anyhow!("failed to insert document {}: {e:?}", doc.doc_id))?;
+    }
+    Ok(Arc::new(index.freeze()))
+}
+
+/// Parse per-query predicates and build one live [`QueryLabelProvider`] per query, all sharing
+/// the same attribute `index`. The predicate is encoded once here; matching happens per node
+/// during search.
+pub(crate) fn make_live_providers(
+    index: &FrozenAttributeIndex,
+    query_predicates: &InputFile,
+) -> anyhow::Result<Vec<Arc<dyn QueryLabelProvider<u32>>>> {
+    let parsed = read_and_parse_queries(query_predicates.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to parse query predicates: {e}"))?;
+    let mut providers = Vec::with_capacity(parsed.len());
+    for (_query_id, ast) in parsed {
+        providers.push(
+            index
+                .make_provider(&ast)
+                .map_err(|e| anyhow::anyhow!("failed to build live provider: {e:?}"))?,
+        );
+    }
+    Ok(providers)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/diskann-label-filter/src/lib.rs b/diskann-label-filter/src/lib.rs
index 106845f984..179230fd95 100644
--- a/diskann-label-filter/src/lib.rs
+++ b/diskann-label-filter/src/lib.rs
@@ -57,6 +57,7 @@ pub mod tests {
 
 pub mod attribute;
 pub mod document;
+pub mod live_filter;
 pub mod query;
 pub mod set;
 
@@ -67,6 +68,7 @@ pub mod kv_index;
 pub mod stores;
 
 // Re-exports for convenience
+pub use live_filter::{FrozenAttributeIndex, InlineAttributeIndex};
 pub use parser::ast::{ASTExpr, CompareOp};
 pub use parser::evaluator::eval_query_expr;
 pub use parser::query_parser::{get_value_by_path, parse_query_filter};
diff --git a/diskann-label-filter/src/live_filter.rs b/diskann-label-filter/src/live_filter.rs
new file mode 100644
index 0000000000..8cd8e7a05c
--- /dev/null
+++ b/diskann-label-filter/src/live_filter.rs
@@ -0,0 +1,253 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+
+//! Live (query-time, per-node) filter matching for graph search.
+//!
+//! This module provides a [`QueryLabelProvider`] implementation whose `is_match` evaluates
+//! a filter predicate **against a single node's attributes at search time**, rather than
+//! consulting a precomputed whole-corpus bitmap.
+//!
+//! Design:
+//! * Each vector's labels are stored as a roaring set of integer attribute-ids in an
+//!   in-memory [`RoaringTreemapSetProvider`] ([`InlineAttributeIndex`]). This is built once
+//!   from the label data (analogous to building the vector index).
+//! * A query's filter expression is encoded **once** into an [`EncodedFilterExpr`]
+//!   (`ASTIdExpr<u64>`), turning field/value comparisons into integer terminals.
+//! * At each visited node, [`PredicateEvaluator`] walks the encoded expression, resolving
+//!   each terminal by an `O(1)`-ish roaring `contains` against the node's own attribute set.
+//!   No FFI and no global posting-list materialization.
+//!
+//! Only the `AND`/`OR` + equality (set-membership) subset is supported; `NOT` and relational
+//! operators are rejected at construction time.
+
+use std::borrow::Cow;
+use std::sync::{Arc, RwLock};
+
+use diskann::graph::index::QueryLabelProvider;
+use diskann::{ANNError, ANNErrorKind, ANNResult};
+use roaring::RoaringTreemap;
+
+use crate::attribute::Attribute;
+use crate::encoded_attribute_provider::ast_id_expr::ASTIdExprVisitor;
+use crate::encoded_attribute_provider::attribute_encoder::AttributeEncoder;
+use crate::encoded_attribute_provider::encoded_filter_expr::EncodedFilterExpr;
+use crate::inline_beta_search::predicate_evaluator::PredicateEvaluator;
+use crate::set::roaring_set_provider::RoaringTreemapSetProvider;
+use crate::set::SetProvider;
+use crate::{ASTExpr, CompareOp};
+
+/// An in-memory attribute index mapping vector ids to their encoded attribute-id sets.
+///
+/// This is the **builder**: attributes are inserted while building. Call [`Self::freeze`] to
+/// obtain a read-only, lock-free [`FrozenAttributeIndex`] for use during search.
+/// Vector ids are `u32` (the graph internal id) and attribute ids are `u64`.
+pub struct InlineAttributeIndex {
+    attribute_map: AttributeEncoder,
+    index: RoaringTreemapSetProvider<u32>,
+}
+
+impl Default for InlineAttributeIndex {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl InlineAttributeIndex {
+    /// Create an empty index.
+    pub fn new() -> Self {
+        Self {
+            attribute_map: AttributeEncoder::new(),
+            index: RoaringTreemapSetProvider::<u32>::new(),
+        }
+    }
+
+    /// Register the attributes of a single vector (build-time).
+    ///
+    /// Each attribute is encoded to a stable integer id and inserted into the vector's set.
+    /// A vector with no attributes is allowed (it simply has no entry, and will fail every
+    /// equality predicate).
+    pub fn insert_document(&mut self, vec_id: u32, attributes: &[Attribute]) -> ANNResult<()> {
+        for attr in attributes {
+            let attr_id = self.attribute_map.insert(attr);
+            self.index.insert(&vec_id, &attr_id)?;
+        }
+        Ok(())
+    }
+
+    /// Freeze the builder into a read-only, shareable index for search.
+    ///
+    /// The attribute set store is shared lock-free (`Arc<..>`); the attribute encoder is placed
+    /// behind an `RwLock` since it is only consulted once per query (at predicate encoding
+    /// time), never per node.
+    pub fn freeze(self) -> FrozenAttributeIndex {
+        FrozenAttributeIndex {
+            attribute_map: Arc::new(RwLock::new(self.attribute_map)),
+            index: Arc::new(self.index),
+        }
+    }
+}
+
+/// A read-only, lock-free (for per-node reads) attribute index shared across queries.
+pub struct FrozenAttributeIndex {
+    attribute_map: Arc<RwLock<AttributeEncoder>>,
+    index: Arc<RoaringTreemapSetProvider<u32>>,
+}
+
+impl FrozenAttributeIndex {
+    /// Build a per-query [`QueryLabelProvider`] for `ast`.
+    ///
+    /// The expression is encoded once against the attribute map. Only `AND`/`OR` combined with
+    /// equality terminals are permitted; `NOT` and relational operators (`!=`, `<`, `<=`, `>`,
+    /// `>=`) are rejected.
+    ///
+    /// # Errors
+    /// Returns an error if the expression uses an unsupported operator, or references a
+    /// field/value that does not exist in the dataset.
+    pub fn make_provider(&self, ast: &ASTExpr) -> ANNResult<Arc<dyn QueryLabelProvider<u32>>> {
+        ensure_and_or_only(ast)?;
+        let encoded = EncodedFilterExpr::new(ast, self.attribute_map.clone())?;
+        Ok(Arc::new(InlineAttributeLabelProvider {
+            encoded,
+            index: self.index.clone(),
+        }))
+    }
+}
+
+/// Reject anything outside the supported `AND`/`OR` + equality subset.
+fn ensure_and_or_only(ast: &ASTExpr) -> ANNResult<()> {
+    match ast {
+        ASTExpr::And(exprs) | ASTExpr::Or(exprs) => {
+            for e in exprs {
+                ensure_and_or_only(e)?;
+            }
+            Ok(())
+        }
+        ASTExpr::Compare {
+            op: CompareOp::Eq(_),
+            ..
+        } => Ok(()),
+        ASTExpr::Not(_) => Err(ANNError::message(
+            ANNErrorKind::Opaque,
+            "NOT is not supported by the live AND/OR filter",
+        )),
+        ASTExpr::Compare { op, .. } => Err(ANNError::message(
+            ANNErrorKind::Opaque,
+            format!(
+                "operator {} is not supported by the live AND/OR filter (only $eq)",
+                op
+            ),
+        )),
+    }
+}
+
+/// A [`QueryLabelProvider`] that evaluates the encoded predicate against each node's own
+/// attribute set at search time, reading the shared index lock-free.
+struct InlineAttributeLabelProvider {
+    encoded: EncodedFilterExpr,
+    index: Arc<RoaringTreemapSetProvider<u32>>,
+}
+
+impl std::fmt::Debug for InlineAttributeLabelProvider {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("InlineAttributeLabelProvider").finish()
+    }
+}
+
+impl QueryLabelProvider<u32> for InlineAttributeLabelProvider {
+    fn is_match(&self, vec_id: u32) -> bool {
+        // Fetch the node's attribute set, or use an empty set when the node has no
+        // attributes (equality terminals then evaluate to false, i.e. non-match).
+        let empty;
+        let labels: &RoaringTreemap = match self.index.get(&vec_id) {
+            Ok(Some(Cow::Borrowed(set))) => set,
+            Ok(Some(Cow::Owned(ref set))) => {
+                empty = set.clone();
+                &empty
+            }
+            Ok(None) => {
+                empty = RoaringTreemap::new();
+                &empty
+            }
+            Err(_) => {
+                tracing::warn!("live filter: failed to read node attributes; non-match");
+                return false;
+            }
+        };
+
+        let evaluator = PredicateEvaluator::new(labels);
+        match evaluator.visit(self.encoded.encoded_filter_expr()) {
+            Ok(matched) => matched,
+            Err(_) => {
+                tracing::warn!("live filter: predicate evaluation failed; treating as non-match");
+                false
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn attr(field: &str, value: bool) -> Attribute {
+        Attribute::from_json_value(field, &json!(value)).unwrap()
+    }
+
+    fn eq_true(field: &str) -> ASTExpr {
+        ASTExpr::Compare {
+            field: field.to_string(),
+            op: CompareOp::Eq(json!(true)),
+        }
+    }
+
+    #[test]
+    fn matches_and_or_predicates() {
+        let mut index = InlineAttributeIndex::new();
+        // doc 0: {A, B}, doc 1: {A}, doc 2: {C}, doc 3: {} (no attributes)
+        index.insert_document(0, &[attr("A", true), attr("B", true)]).unwrap();
+        index.insert_document(1, &[attr("A", true)]).unwrap();
+        index.insert_document(2, &[attr("C", true)]).unwrap();
+        index.insert_document(3, &[]).unwrap();
+        let index = index.freeze();
+
+        // A AND B
+        let p = index
+            .make_provider(&ASTExpr::And(vec![eq_true("A"), eq_true("B")]))
+            .unwrap();
+        assert!(p.is_match(0));
+        assert!(!p.is_match(1));
+        assert!(!p.is_match(2));
+        assert!(!p.is_match(3));
+
+        // A OR C
+        let p = index
+            .make_provider(&ASTExpr::Or(vec![eq_true("A"), eq_true("C")]))
+            .unwrap();
+        assert!(p.is_match(0));
+        assert!(p.is_match(1));
+        assert!(p.is_match(2));
+        assert!(!p.is_match(3));
+    }
+
+    #[test]
+    fn rejects_not_and_relational() {
+        let mut index = InlineAttributeIndex::new();
+        index.insert_document(0, &[attr("A", true)]).unwrap();
+        let index = index.freeze();
+
+        // NOT is rejected
+        assert!(index
+            .make_provider(&ASTExpr::Not(Box::new(eq_true("A"))))
+            .is_err());
+
+        // relational is rejected
+        let rel = ASTExpr::Compare {
+            field: "n".to_string(),
+            op: CompareOp::Gt(1.0),
+        };
+        assert!(index.make_provider(&rel).is_err());
+    }
+}

From 2c5766b598cfeff1e2166132ebedf3117889b7c6 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Mon, 27 Jul 2026 14:54:38 +0800
Subject: [PATCH 02/25] diskann-label-filter: add flat-CSR live filter provider

Adds InlineAttributeIndexCsr/FrozenAttributeIndexCsr, an alternative to the roaring InlineAttributeIndex that stores each node's sorted attribute-ids in a flat CSR layout (offsets: Vec<u32> + values: Vec<u32>). is_match reads one contiguous row and answers each equality terminal with a binary_search, avoiding the HashMap probe and RoaringTreemap heap pointer-chases of the roaring path. Reuses AttributeEncoder/EncodedFilterExpr so predicate parsing, semantics, and errors are identical. Exported from lib.rs; includes parity unit tests asserting CSR == roaring per node.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 19cdd8e8-cc28-4b87-af2b-97a3f1ac9488
---
 diskann-label-filter/src/lib.rs         |   4 +-
 diskann-label-filter/src/live_filter.rs | 265 +++++++++++++++++++++++-
 2 files changed, 266 insertions(+), 3 deletions(-)

diff --git a/diskann-label-filter/src/lib.rs b/diskann-label-filter/src/lib.rs
index 179230fd95..cc054349c1 100644
--- a/diskann-label-filter/src/lib.rs
+++ b/diskann-label-filter/src/lib.rs
@@ -68,7 +68,9 @@ pub mod kv_index;
 pub mod stores;
 
 // Re-exports for convenience
-pub use live_filter::{FrozenAttributeIndex, InlineAttributeIndex};
+pub use live_filter::{
+    FrozenAttributeIndex, FrozenAttributeIndexCsr, InlineAttributeIndex, InlineAttributeIndexCsr,
+};
 pub use parser::ast::{ASTExpr, CompareOp};
 pub use parser::evaluator::eval_query_expr;
 pub use parser::query_parser::{get_value_by_path, parse_query_filter};
diff --git a/diskann-label-filter/src/live_filter.rs b/diskann-label-filter/src/live_filter.rs
index 8cd8e7a05c..5418a83e37 100644
--- a/diskann-label-filter/src/live_filter.rs
+++ b/diskann-label-filter/src/live_filter.rs
@@ -30,7 +30,7 @@ use diskann::{ANNError, ANNErrorKind, ANNResult};
 use roaring::RoaringTreemap;
 
 use crate::attribute::Attribute;
-use crate::encoded_attribute_provider::ast_id_expr::ASTIdExprVisitor;
+use crate::encoded_attribute_provider::ast_id_expr::{ASTIdExpr, ASTIdExprVisitor};
 use crate::encoded_attribute_provider::attribute_encoder::AttributeEncoder;
 use crate::encoded_attribute_provider::encoded_filter_expr::EncodedFilterExpr;
 use crate::inline_beta_search::predicate_evaluator::PredicateEvaluator;
@@ -187,6 +187,181 @@ impl QueryLabelProvider<u32> for InlineAttributeLabelProvider {
     }
 }
 
+/// A flat CSR (compressed-sparse-row) attribute index: an alternative to
+/// [`InlineAttributeIndex`] that trades the per-node `HashMap<u32, RoaringTreemap>` for two
+/// contiguous arrays.
+///
+/// * `offsets[id]..offsets[id + 1]` slices `values` to yield node `id`'s sorted attribute-id row.
+/// * `is_match` reads that one contiguous slice (≈1 cache line for typical small rows) and answers
+///   each equality terminal with a `binary_search`, avoiding the hash probe, the heap pointer chase
+///   to a `RoaringTreemap`, and the `BTreeMap`/`RoaringBitmap` container lookups of the roaring path.
+///
+/// This is the **builder**: attributes are inserted while building. Call [`Self::freeze`] to obtain
+/// a read-only, lock-free [`FrozenAttributeIndexCsr`] for use during search. Vector ids are `u32`
+/// and are expected to be dense (`0..n`); attribute ids are `u32` (supports up to `u32::MAX`
+/// distinct attributes and `u32::MAX` total attribute occurrences).
+pub struct InlineAttributeIndexCsr {
+    attribute_map: AttributeEncoder,
+    rows: Vec<Vec<u32>>,
+}
+
+impl Default for InlineAttributeIndexCsr {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl InlineAttributeIndexCsr {
+    /// Create an empty index.
+    pub fn new() -> Self {
+        Self {
+            attribute_map: AttributeEncoder::new(),
+            rows: Vec::new(),
+        }
+    }
+
+    /// Register the attributes of a single vector (build-time).
+    ///
+    /// Each attribute is encoded to a stable integer id (shared with the query encoder, so query
+    /// terminals resolve to the same ids) and appended to the vector's row. A vector with no
+    /// attributes is allowed. Vector ids need not be inserted in order; gaps are filled with empty
+    /// rows.
+    ///
+    /// # Errors
+    /// Returns an error if more than `u32::MAX` distinct attributes are encountered.
+    pub fn insert_document(&mut self, vec_id: u32, attributes: &[Attribute]) -> ANNResult<()> {
+        let idx = vec_id as usize;
+        if idx >= self.rows.len() {
+            self.rows.resize_with(idx + 1, Vec::new);
+        }
+        for attr in attributes {
+            let attr_id = self.attribute_map.insert(attr);
+            let attr_id = u32::try_from(attr_id).map_err(|_| {
+                ANNError::message(
+                    ANNErrorKind::Opaque,
+                    "live CSR filter supports at most u32::MAX distinct attributes",
+                )
+            })?;
+            self.rows[idx].push(attr_id);
+        }
+        Ok(())
+    }
+
+    /// Freeze the builder into a read-only, shareable index for search.
+    ///
+    /// Each row is sorted and deduped (so `is_match` can `binary_search`), then flattened into the
+    /// contiguous `values` array with a parallel `offsets` array. The attribute encoder is placed
+    /// behind an `RwLock` since it is only consulted once per query (at predicate encoding time),
+    /// never per node.
+    pub fn freeze(mut self) -> FrozenAttributeIndexCsr {
+        let mut offsets: Vec<u32> = Vec::with_capacity(self.rows.len() + 1);
+        offsets.push(0);
+        let total: usize = self.rows.iter().map(Vec::len).sum();
+        let mut values: Vec<u32> = Vec::with_capacity(total);
+        for row in &mut self.rows {
+            row.sort_unstable();
+            row.dedup();
+            values.extend_from_slice(row);
+            let end = u32::try_from(values.len())
+                .expect("live CSR filter supports at most u32::MAX total attribute occurrences");
+            offsets.push(end);
+        }
+        FrozenAttributeIndexCsr {
+            attribute_map: Arc::new(RwLock::new(self.attribute_map)),
+            offsets: offsets.into(),
+            values: values.into(),
+        }
+    }
+}
+
+/// A read-only, lock-free (for per-node reads) CSR attribute index shared across queries.
+pub struct FrozenAttributeIndexCsr {
+    attribute_map: Arc<RwLock<AttributeEncoder>>,
+    offsets: Arc<[u32]>,
+    values: Arc<[u32]>,
+}
+
+impl FrozenAttributeIndexCsr {
+    /// Build a per-query [`QueryLabelProvider`] for `ast`.
+    ///
+    /// The expression is encoded once against the shared attribute map (identical semantics to
+    /// [`FrozenAttributeIndex::make_provider`]): only `AND`/`OR` combined with equality terminals
+    /// are permitted; `NOT` and relational operators are rejected.
+    ///
+    /// # Errors
+    /// Returns an error if the expression uses an unsupported operator, or references a field/value
+    /// absent from the dataset.
+    pub fn make_provider(&self, ast: &ASTExpr) -> ANNResult<Arc<dyn QueryLabelProvider<u32>>> {
+        ensure_and_or_only(ast)?;
+        let encoded = EncodedFilterExpr::new(ast, self.attribute_map.clone())?;
+        Ok(Arc::new(CsrAttributeLabelProvider {
+            encoded,
+            offsets: self.offsets.clone(),
+            values: self.values.clone(),
+        }))
+    }
+}
+
+/// A [`QueryLabelProvider`] that evaluates the encoded predicate against each node's contiguous
+/// CSR attribute row at search time, reading the shared arrays lock-free.
+struct CsrAttributeLabelProvider {
+    encoded: EncodedFilterExpr,
+    offsets: Arc<[u32]>,
+    values: Arc<[u32]>,
+}
+
+impl std::fmt::Debug for CsrAttributeLabelProvider {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("CsrAttributeLabelProvider").finish()
+    }
+}
+
+impl QueryLabelProvider<u32> for CsrAttributeLabelProvider {
+    fn is_match(&self, vec_id: u32) -> bool {
+        let idx = vec_id as usize;
+        // A node id outside the built range has no attributes: every equality terminal is a
+        // non-match (consistent with the roaring path treating a missing node as an empty set).
+        let (Some(&start), Some(&end)) = (self.offsets.get(idx), self.offsets.get(idx + 1)) else {
+            return false;
+        };
+        let row = &self.values[start as usize..end as usize];
+        let evaluator = CsrRowEvaluator { row };
+        evaluator.visit(self.encoded.encoded_filter_expr())
+    }
+}
+
+/// Evaluates an encoded `AND`/`OR` + equality predicate against a single node's sorted CSR row.
+struct CsrRowEvaluator<'a> {
+    row: &'a [u32],
+}
+
+impl ASTIdExprVisitor<u64> for CsrRowEvaluator<'_> {
+    type Output = bool;
+
+    fn visit_and(&self, exprs: &[ASTIdExpr<u64>]) -> bool {
+        exprs.iter().all(|e| self.visit(e))
+    }
+
+    fn visit_or(&self, exprs: &[ASTIdExpr<u64>]) -> bool {
+        exprs.iter().any(|e| self.visit(e))
+    }
+
+    fn visit_not(&self, expr: &ASTIdExpr<u64>) -> bool {
+        // `NOT` is rejected at construction, so this is unreachable in practice; handle it
+        // correctly anyway for completeness.
+        !self.visit(expr)
+    }
+
+    fn visit_terminal(&self, id: &u64) -> bool {
+        match u32::try_from(*id) {
+            Ok(id) => self.row.binary_search(&id).is_ok(),
+            // Attribute ids are assigned densely from 0, so this never triggers; a terminal beyond
+            // the `u32` range cannot be present in any row.
+            Err(_) => false,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -207,7 +382,9 @@ mod tests {
     fn matches_and_or_predicates() {
         let mut index = InlineAttributeIndex::new();
         // doc 0: {A, B}, doc 1: {A}, doc 2: {C}, doc 3: {} (no attributes)
-        index.insert_document(0, &[attr("A", true), attr("B", true)]).unwrap();
+        index
+            .insert_document(0, &[attr("A", true), attr("B", true)])
+            .unwrap();
         index.insert_document(1, &[attr("A", true)]).unwrap();
         index.insert_document(2, &[attr("C", true)]).unwrap();
         index.insert_document(3, &[]).unwrap();
@@ -250,4 +427,88 @@ mod tests {
         };
         assert!(index.make_provider(&rel).is_err());
     }
+
+    #[test]
+    fn csr_matches_and_or_predicates() {
+        let mut index = InlineAttributeIndexCsr::new();
+        // doc 0: {A, B}, doc 1: {A}, doc 2: {C}, doc 3: {} (no attributes)
+        index
+            .insert_document(0, &[attr("A", true), attr("B", true)])
+            .unwrap();
+        index.insert_document(1, &[attr("A", true)]).unwrap();
+        index.insert_document(2, &[attr("C", true)]).unwrap();
+        index.insert_document(3, &[]).unwrap();
+        let index = index.freeze();
+
+        // A AND B
+        let p = index
+            .make_provider(&ASTExpr::And(vec![eq_true("A"), eq_true("B")]))
+            .unwrap();
+        assert!(p.is_match(0));
+        assert!(!p.is_match(1));
+        assert!(!p.is_match(2));
+        assert!(!p.is_match(3));
+        // A node id beyond the built range is a non-match.
+        assert!(!p.is_match(99));
+
+        // A OR C
+        let p = index
+            .make_provider(&ASTExpr::Or(vec![eq_true("A"), eq_true("C")]))
+            .unwrap();
+        assert!(p.is_match(0));
+        assert!(p.is_match(1));
+        assert!(p.is_match(2));
+        assert!(!p.is_match(3));
+    }
+
+    #[test]
+    fn csr_rejects_not_and_relational() {
+        let mut index = InlineAttributeIndexCsr::new();
+        index.insert_document(0, &[attr("A", true)]).unwrap();
+        let index = index.freeze();
+
+        // NOT is rejected
+        assert!(index
+            .make_provider(&ASTExpr::Not(Box::new(eq_true("A"))))
+            .is_err());
+
+        // relational is rejected
+        let rel = ASTExpr::Compare {
+            field: "n".to_string(),
+            op: CompareOp::Gt(1.0),
+        };
+        assert!(index.make_provider(&rel).is_err());
+    }
+
+    #[test]
+    fn csr_out_of_order_inserts_match_roaring() {
+        // Insert documents out of vec_id order to exercise gap-filling in the CSR builder, and
+        // assert the CSR provider agrees with the roaring provider on the same data + predicate.
+        let docs: [(u32, &[(&str, bool)]); 4] = [
+            (2, &[("A", true), ("C", true)]),
+            (0, &[("A", true), ("B", true)]),
+            (3, &[("B", true)]),
+            (1, &[]),
+        ];
+
+        let mut roaring = InlineAttributeIndex::new();
+        let mut csr = InlineAttributeIndexCsr::new();
+        for (id, labels) in docs {
+            let attrs: Vec<Attribute> = labels.iter().map(|(f, v)| attr(f, *v)).collect();
+            roaring.insert_document(id, &attrs).unwrap();
+            csr.insert_document(id, &attrs).unwrap();
+        }
+        let roaring = roaring.freeze();
+        let csr = csr.freeze();
+
+        let ast = ASTExpr::Or(vec![
+            ASTExpr::And(vec![eq_true("A"), eq_true("B")]),
+            eq_true("C"),
+        ]);
+        let rp = roaring.make_provider(&ast).unwrap();
+        let cp = csr.make_provider(&ast).unwrap();
+        for id in 0..4u32 {
+            assert_eq!(rp.is_match(id), cp.is_match(id), "mismatch at node {id}");
+        }
+    }
 }

From e377dea8c0bc51f1cda4c6ddda03308d0a176673 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Mon, 27 Jul 2026 14:55:09 +0800
Subject: [PATCH 03/25] diskann-label-filter: add live-filter is_match
 microbenchmark

New criterion bench (live_filter_bench) comparing the per-node is_match cost of three representations of the same corpus/predicate: roaring treemap (current), flat CSR, and per-attribute posting bitmaps. All three are asserted to agree on every probe before timing. Tunable via LF_BENCH_N / LF_BENCH_PROBES. Run: cargo bench -p diskann-label-filter --bench main -- live_filter. Also repairs evaluator_bench, which used the removed \\\ operator and panicked at setup, blocking the shared bench binary; swapped for equivalent exact-array \\\ clauses.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 19cdd8e8-cc28-4b87-af2b-97a3f1ac9488
---
 .../benches/benchmarks/evaluator_bench.rs     |  10 +-
 .../benches/benchmarks/live_filter_bench.rs   | 249 ++++++++++++++++++
 .../benches/benchmarks/mod.rs                 |   2 +
 diskann-label-filter/benches/main.rs          |   4 +-
 4 files changed, 259 insertions(+), 6 deletions(-)
 create mode 100644 diskann-label-filter/benches/benchmarks/live_filter_bench.rs

diff --git a/diskann-label-filter/benches/benchmarks/evaluator_bench.rs b/diskann-label-filter/benches/benchmarks/evaluator_bench.rs
index 7ffe9f4353..ac2d8ee925 100644
--- a/diskann-label-filter/benches/benchmarks/evaluator_bench.rs
+++ b/diskann-label-filter/benches/benchmarks/evaluator_bench.rs
@@ -62,9 +62,11 @@ fn bench_array_query(c: &mut Criterion) {
         "scores": [85, 90, 95, 100]
     });
 
+    // `$in` was removed from the parser; use exact-array `$eq` to keep this a valid,
+    // matching compound predicate over array-valued fields.
     let filter = json!({"$and": [
-        {"tags": {"$in": ["c", "f", "g"]}},
-        {"scores": {"$in": [85, 100]}}
+        {"tags": {"$eq": ["a", "b", "c", "d", "e"]}},
+        {"scores": {"$eq": [85, 90, 95, 100]}}
     ]});
 
     let mut group = c.benchmark_group("array_query");
@@ -101,8 +103,8 @@ fn bench_complex_query(c: &mut Criterion) {
             {"c": {"$lt": 2}},
             {"c": {"$gte": 3}}
         ]},
-        {"arr": {"$in": [2,3]}},
-        {"tags": {"$in": ["b", "x"]}},
+        {"arr": {"$eq": [1, 2, 3]}},
+        {"tags": {"$eq": ["a", "b", "c"]}},
         {"flt": {"$lte": 3.5}},
         {"int": {"$gte": 5}},
         {"str": {"$eq": "abc"}}
diff --git a/diskann-label-filter/benches/benchmarks/live_filter_bench.rs b/diskann-label-filter/benches/benchmarks/live_filter_bench.rs
new file mode 100644
index 0000000000..b2ae4b0e13
--- /dev/null
+++ b/diskann-label-filter/benches/benchmarks/live_filter_bench.rs
@@ -0,0 +1,249 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+
+//! Microbenchmark isolating the per-node `is_match` cost of live filter matching.
+//!
+//! It compares three representations of the *same* corpus of per-document attribute
+//! sets, evaluating the *same* predicate over the *same* probed node ids:
+//!
+//! * `treemap`  — the current production path: [`InlineAttributeIndex`]
+//!   (`HashMap<u32, RoaringTreemap>`) frozen into a live provider whose `is_match`
+//!   walks the encoded predicate calling `RoaringTreemap::contains` per terminal.
+//! * `csr`      — a flat CSR layout (`offsets: Vec<u32>` + sorted `values: Vec<u16>`):
+//!   a match is a contiguous-slice membership test on the node's own row.
+//! * `posting`  — one `RoaringBitmap` per attribute id (the doc-ids carrying it):
+//!   a match is an `AND`/`OR` of `posting[term].contains(node)`.
+//!
+//! Before timing, all three are asserted to agree on every probe, so the benchmark
+//! measures only *how* the match decision is computed, not *what* it decides.
+//!
+//! Tunables (env): `LF_BENCH_N` corpus size (default 1_000_000),
+//! `LF_BENCH_PROBES` ids probed per iteration (default 50_000).
+
+use criterion::{criterion_group, Criterion, Throughput};
+use diskann::graph::index::QueryLabelProvider;
+use diskann_label_filter::attribute::Attribute;
+use diskann_label_filter::{ASTExpr, CompareOp, InlineAttributeIndex};
+use rand::rngs::StdRng;
+use rand::{Rng, SeedableRng};
+use roaring::RoaringBitmap;
+use serde_json::json;
+use std::hint::black_box;
+use std::sync::Arc;
+
+/// Number of distinct attribute ids (mirrors the report's 548 geo + 48 market = 596).
+const VOCAB: u16 = 596;
+
+/// A predicate over integer attribute-id terminals, shared by all three eval paths so
+/// they perform logically identical work.
+#[derive(Clone)]
+enum Pred {
+    Term(u16),
+    And(Vec<Pred>),
+    Or(Vec<Pred>),
+}
+
+impl Pred {
+    /// CSR eval: membership tests against the node's sorted attribute slice.
+    fn eval_csr(&self, node_attrs: &[u16]) -> bool {
+        match self {
+            Pred::Term(id) => node_attrs.binary_search(id).is_ok(),
+            Pred::And(v) => v.iter().all(|p| p.eval_csr(node_attrs)),
+            Pred::Or(v) => v.iter().any(|p| p.eval_csr(node_attrs)),
+        }
+    }
+
+    /// Posting eval: membership tests against per-attribute doc-id bitmaps.
+    fn eval_posting(&self, node: u32, posting: &[RoaringBitmap]) -> bool {
+        match self {
+            Pred::Term(id) => posting[*id as usize].contains(node),
+            Pred::And(v) => v.iter().all(|p| p.eval_posting(node, posting)),
+            Pred::Or(v) => v.iter().any(|p| p.eval_posting(node, posting)),
+        }
+    }
+
+    /// Convert to the string-keyed [`ASTExpr`] consumed by the production live provider.
+    fn to_ast(&self) -> ASTExpr {
+        match self {
+            Pred::Term(id) => ASTExpr::Compare {
+                field: format!("L{id}"),
+                op: CompareOp::Eq(json!(true)),
+            },
+            Pred::And(v) => ASTExpr::And(v.iter().map(Pred::to_ast).collect()),
+            Pred::Or(v) => ASTExpr::Or(v.iter().map(Pred::to_ast).collect()),
+        }
+    }
+}
+
+/// Skewed label sampler: small ids are much more common (Zipf-like), so `AND`
+/// predicates over low ids retain meaningful overlap instead of collapsing to empty.
+fn sample_label(rng: &mut StdRng) -> u16 {
+    let u: f64 = rng.random();
+    let id = (f64::from(VOCAB) * u.powf(2.5)).floor() as u16;
+    id.min(VOCAB - 1)
+}
+
+/// Build the shared corpus: each doc gets a small sorted, deduped set of attribute ids.
+fn build_corpus(n: usize, rng: &mut StdRng) -> Vec<Vec<u16>> {
+    let mut corpus = Vec::with_capacity(n);
+    for _ in 0..n {
+        let k = 1 + rng.random_range(0..4u32); // 1..=4 draws before dedup
+        let mut attrs: Vec<u16> = (0..k).map(|_| sample_label(rng)).collect();
+        attrs.sort_unstable();
+        attrs.dedup();
+        corpus.push(attrs);
+    }
+    corpus
+}
+
+/// Flatten the corpus into a CSR layout: `offsets[node]..offsets[node + 1]` slices `values`.
+fn build_csr(corpus: &[Vec<u16>]) -> (Vec<u32>, Vec<u16>) {
+    let mut offsets = Vec::with_capacity(corpus.len() + 1);
+    let mut values = Vec::new();
+    offsets.push(0u32);
+    for attrs in corpus {
+        values.extend_from_slice(attrs);
+        offsets.push(values.len() as u32);
+    }
+    (offsets, values)
+}
+
+/// Invert the corpus into one doc-id bitmap per attribute id.
+fn build_posting(corpus: &[Vec<u16>]) -> Vec<RoaringBitmap> {
+    let mut posting: Vec<RoaringBitmap> = (0..VOCAB).map(|_| RoaringBitmap::new()).collect();
+    for (doc, attrs) in corpus.iter().enumerate() {
+        for &id in attrs {
+            posting[id as usize].insert(doc as u32);
+        }
+    }
+    posting
+}
+
+/// Build the current production index (`HashMap<u32, RoaringTreemap>` via string-keyed
+/// attribute encoding), matching what the live filter uses at search time.
+fn build_treemap(corpus: &[Vec<u16>]) -> InlineAttributeIndex {
+    // Cache one Attribute per label id so we do not rebuild the field string per document.
+    let attr_cache: Vec<Attribute> = (0..VOCAB)
+        .map(|id| Attribute::from_json_value(&format!("L{id}"), &json!(true)).unwrap())
+        .collect();
+    let mut index = InlineAttributeIndex::new();
+    let mut scratch: Vec<Attribute> = Vec::new();
+    for (doc, attrs) in corpus.iter().enumerate() {
+        scratch.clear();
+        scratch.extend(attrs.iter().map(|&id| attr_cache[id as usize].clone()));
+        index.insert_document(doc as u32, &scratch).unwrap();
+    }
+    index
+}
+
+fn bench_live_filter(c: &mut Criterion) {
+    let n: usize = std::env::var("LF_BENCH_N")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(1_000_000);
+    let num_probes: usize = std::env::var("LF_BENCH_PROBES")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(50_000);
+
+    let mut rng = StdRng::seed_from_u64(0x0DDF_117E_5EED);
+    let corpus = build_corpus(n, &mut rng);
+    let (offsets, values) = build_csr(&corpus);
+    let posting = build_posting(&corpus);
+    let frozen = build_treemap(&corpus).freeze();
+
+    // Random node ids mimic the data-dependent traversal order (defeats prefetching).
+    let probes: Vec<u32> = (0..num_probes)
+        .map(|_| rng.random_range(0..n as u32))
+        .collect();
+
+    let predicates: [(&str, Pred); 3] = [
+        ("p1_single_term", Pred::Term(0)),
+        ("p2_and2", Pred::And(vec![Pred::Term(0), Pred::Term(1)])),
+        (
+            "p4_and_or",
+            Pred::Or(vec![
+                Pred::And(vec![Pred::Term(0), Pred::Term(1)]),
+                Pred::And(vec![Pred::Term(2), Pred::Term(3)]),
+            ]),
+        ),
+    ];
+
+    for (name, pred) in &predicates {
+        let ast = pred.to_ast();
+        let provider: Arc<dyn QueryLabelProvider<u32>> = frozen.make_provider(&ast).unwrap();
+
+        // Correctness gate: all three representations must agree on every probe.
+        let mut match_count = 0usize;
+        for &node in &probes {
+            let treemap_hit = provider.is_match(node);
+            let start = offsets[node as usize] as usize;
+            let end = offsets[node as usize + 1] as usize;
+            let csr_hit = pred.eval_csr(&values[start..end]);
+            let posting_hit = pred.eval_posting(node, &posting);
+            assert_eq!(
+                treemap_hit, csr_hit,
+                "treemap vs csr disagree ({name}, node {node})"
+            );
+            assert_eq!(
+                treemap_hit, posting_hit,
+                "treemap vs posting disagree ({name}, node {node})"
+            );
+            if treemap_hit {
+                match_count += 1;
+            }
+        }
+        let sel_tag = format!(
+            "sel={:.1}%",
+            match_count as f64 / probes.len() as f64 * 100.0
+        );
+
+        let mut group = c.benchmark_group(format!("live_filter/{name}"));
+        group.throughput(Throughput::Elements(probes.len() as u64));
+        group.sample_size(30);
+
+        group.bench_function(format!("treemap[{sel_tag}]"), |b| {
+            b.iter(|| {
+                let mut hits = 0u64;
+                for &node in &probes {
+                    if provider.is_match(black_box(node)) {
+                        hits += 1;
+                    }
+                }
+                black_box(hits)
+            })
+        });
+
+        group.bench_function(format!("csr[{sel_tag}]"), |b| {
+            b.iter(|| {
+                let mut hits = 0u64;
+                for &node in &probes {
+                    let start = offsets[node as usize] as usize;
+                    let end = offsets[node as usize + 1] as usize;
+                    if pred.eval_csr(black_box(&values[start..end])) {
+                        hits += 1;
+                    }
+                }
+                black_box(hits)
+            })
+        });
+
+        group.bench_function(format!("posting[{sel_tag}]"), |b| {
+            b.iter(|| {
+                let mut hits = 0u64;
+                for &node in &probes {
+                    if pred.eval_posting(black_box(node), &posting) {
+                        hits += 1;
+                    }
+                }
+                black_box(hits)
+            })
+        });
+
+        group.finish();
+    }
+}
+
+criterion_group!(live_filter_benches, bench_live_filter);
diff --git a/diskann-label-filter/benches/benchmarks/mod.rs b/diskann-label-filter/benches/benchmarks/mod.rs
index e1c7a15dae..847d9fc6c1 100644
--- a/diskann-label-filter/benches/benchmarks/mod.rs
+++ b/diskann-label-filter/benches/benchmarks/mod.rs
@@ -4,7 +4,9 @@
  */
 
 pub mod evaluator_bench;
+pub mod live_filter_bench;
 pub mod parser_bench;
 
 pub use evaluator_bench::evaluator_benches;
+pub use live_filter_bench::live_filter_benches;
 pub use parser_bench::parser_benches;
diff --git a/diskann-label-filter/benches/main.rs b/diskann-label-filter/benches/main.rs
index 66d461dadc..f47a71eccf 100644
--- a/diskann-label-filter/benches/main.rs
+++ b/diskann-label-filter/benches/main.rs
@@ -3,9 +3,9 @@
  * Licensed under the MIT license.
  */
 
-use benchmarks::{evaluator_benches, parser_benches};
+use benchmarks::{evaluator_benches, live_filter_benches, parser_benches};
 use criterion::criterion_main;
 
 mod benchmarks;
 
-criterion_main!(parser_benches, evaluator_benches);
+criterion_main!(parser_benches, evaluator_benches, live_filter_benches);

From 55677456693c0d5f7f6869167b86f90ecbf174ee Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Mon, 27 Jul 2026 14:55:21 +0800
Subject: [PATCH 04/25] diskann-benchmark: add topk-multihop-live-filter-csr
 search type

New multihop live-filter search type backed by the flat-CSR attribute index instead of the roaring HashMap<u32, RoaringTreemap>. Identical traversal and recall to topk-multihop-live-filter; only the per-node is_match differs. Wires the SearchPhase variant (graph_index.rs), the plugin (plugins.rs), registration + Plugin impl (benchmarks.rs), and build_inline_attribute_index_csr / make_live_providers_csr (filters.rs). End-to-end on the 10M index (k=150, L=150, 1 thread): 3.4x (S1) - 4.4x (S4) lower mean/p99 latency at equal recall.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 19cdd8e8-cc28-4b87-af2b-97a3f1ac9488
---
 .../src/backend/index/benchmarks.rs           | 60 ++++++++++++++++++-
 .../src/backend/index/search/plugins.rs       | 13 ++++
 diskann-benchmark/src/inputs/graph_index.rs   | 17 ++++++
 diskann-benchmark/src/utils/filters.rs        | 50 +++++++++++++++-
 4 files changed, 136 insertions(+), 4 deletions(-)

diff --git a/diskann-benchmark/src/backend/index/benchmarks.rs b/diskann-benchmark/src/backend/index/benchmarks.rs
index 20085795e3..a2e9f3b14a 100644
--- a/diskann-benchmark/src/backend/index/benchmarks.rs
+++ b/diskann-benchmark/src/backend/index/benchmarks.rs
@@ -77,7 +77,8 @@ pub(super) fn register_benchmarks(registry: &mut Registry) -> anyhow::Result<()>
             .search(plugins::Range)
             .search(plugins::TopkBetaFilter)
             .search(plugins::TopkMultihopFilter)
-            .search(plugins::TopkMultihopLiveFilter),
+            .search(plugins::TopkMultihopLiveFilter)
+            .search(plugins::TopkMultihopLiveFilterCsr),
     )?;
 
     registry.register(
@@ -677,8 +678,7 @@ where
         // Build the in-memory attribute index once (a one-time index build), then construct a
         // live per-query provider that evaluates the predicate against each visited node's
         // attributes during search.
-        let attribute_index =
-            utils::filters::build_inline_attribute_index(&multihop.data_labels)?;
+        let attribute_index = utils::filters::build_inline_attribute_index(&multihop.data_labels)?;
         let providers =
             utils::filters::make_live_providers(&attribute_index, &multihop.query_predicates)?;
 
@@ -693,6 +693,60 @@ where
         Ok(AggregatedSearchResults::Topk(result))
     }
 }
+
+//--------------------------//
+// MultihopLiveFilter (CSR) //
+//--------------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>> for plugins::TopkMultihopLiveFilterCsr
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<DP, &'a [DP::Element]> + Clone + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        let multihop = phase.as_topk_multihop_live_filter_csr()?;
+
+        let queries: Arc<Matrix<DP::Element>> = Arc::new(datafiles::load_dataset(
+            datafiles::BinFile(&multihop.queries),
+        )?);
+
+        let groundtruth =
+            datafiles::load_range_groundtruth(datafiles::BinFile(&multihop.groundtruth))?;
+
+        let steps =
+            search::knn::SearchSteps::new(multihop.reps, &multihop.num_threads, &multihop.runs);
+
+        // Build the in-memory CSR attribute index once, then construct a live per-query provider
+        // that evaluates the predicate against each visited node's contiguous attribute row.
+        let attribute_index =
+            utils::filters::build_inline_attribute_index_csr(&multihop.data_labels)?;
+        let providers =
+            utils::filters::make_live_providers_csr(&attribute_index, &multihop.query_predicates)?;
+
+        let multihop = benchmark_core::search::graph::MultiHop::new(
+            index,
+            queries,
+            benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
+            providers.into(),
+        )?;
+
+        let result = search::knn::run(&multihop, &groundtruth, steps)?;
+        Ok(AggregatedSearchResults::Topk(result))
+    }
+}
 /// The stack looks like this:
 ///
 /// - Bottom: [`FullPrecisionStream`]: The core streaming index implementation.
diff --git a/diskann-benchmark/src/backend/index/search/plugins.rs b/diskann-benchmark/src/backend/index/search/plugins.rs
index c78553f723..30f16cd460 100644
--- a/diskann-benchmark/src/backend/index/search/plugins.rs
+++ b/diskann-benchmark/src/backend/index/search/plugins.rs
@@ -195,3 +195,16 @@ impl TopkMultihopLiveFilter {
         SearchPhaseKind::TopkMultihopLiveFilter
     }
 }
+
+/// A multi-hop live-filter plugin backed by a flat CSR attribute index (contiguous
+/// `offsets`/`values` arrays) instead of the roaring `HashMap<u32, RoaringTreemap>`, so each
+/// per-node match reads one contiguous row rather than chasing heap-allocated roaring sets.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkMultihopLiveFilterCsr;
+
+impl TopkMultihopLiveFilterCsr {
+    /// Returns [`SearchPhaseKind::TopkMultihopLiveFilterCsr`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkMultihopLiveFilterCsr
+    }
+}
diff --git a/diskann-benchmark/src/inputs/graph_index.rs b/diskann-benchmark/src/inputs/graph_index.rs
index 286968a42c..dbbbe1b62c 100644
--- a/diskann-benchmark/src/inputs/graph_index.rs
+++ b/diskann-benchmark/src/inputs/graph_index.rs
@@ -315,6 +315,7 @@ pub(crate) enum SearchPhase {
     TopkBetaFilter(BetaSearchPhase),
     TopkMultihopFilter(MultiHopSearchPhase),
     TopkMultihopLiveFilter(MultiHopSearchPhase),
+    TopkMultihopLiveFilterCsr(MultiHopSearchPhase),
 }
 
 #[derive(Debug, Error)]
@@ -342,6 +343,7 @@ impl SearchPhase {
             Self::TopkBetaFilter(_) => SearchPhaseKind::TopkBetaFilter,
             Self::TopkMultihopFilter(_) => SearchPhaseKind::TopkMultihopFilter,
             Self::TopkMultihopLiveFilter(_) => SearchPhaseKind::TopkMultihopLiveFilter,
+            Self::TopkMultihopLiveFilterCsr(_) => SearchPhaseKind::TopkMultihopLiveFilterCsr,
         }
     }
 
@@ -398,6 +400,18 @@ impl SearchPhase {
             )),
         }
     }
+
+    pub(crate) fn as_topk_multihop_live_filter_csr(
+        &self,
+    ) -> Result<&MultiHopSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkMultihopLiveFilterCsr(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkMultihopLiveFilterCsr,
+                self.kind(),
+            )),
+        }
+    }
 }
 
 impl SearchPhase {
@@ -408,6 +422,7 @@ impl SearchPhase {
             SearchPhase::TopkBetaFilter(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopFilter(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopLiveFilter(phase) => phase.validate(checker),
+            SearchPhase::TopkMultihopLiveFilterCsr(phase) => phase.validate(checker),
         }
     }
 }
@@ -419,6 +434,7 @@ pub(crate) enum SearchPhaseKind {
     TopkBetaFilter,
     TopkMultihopFilter,
     TopkMultihopLiveFilter,
+    TopkMultihopLiveFilterCsr,
 }
 
 impl SearchPhaseKind {
@@ -429,6 +445,7 @@ impl SearchPhaseKind {
             Self::TopkBetaFilter => "topk-beta-filter",
             Self::TopkMultihopFilter => "topk-multihop-filter",
             Self::TopkMultihopLiveFilter => "topk-multihop-live-filter",
+            Self::TopkMultihopLiveFilterCsr => "topk-multihop-live-filter-csr",
         }
     }
 }
diff --git a/diskann-benchmark/src/utils/filters.rs b/diskann-benchmark/src/utils/filters.rs
index 361b5148ef..bf6240b5ed 100644
--- a/diskann-benchmark/src/utils/filters.rs
+++ b/diskann-benchmark/src/utils/filters.rs
@@ -24,7 +24,8 @@ use std::sync::Arc;
 
 use diskann_label_filter::attribute::Attribute;
 use diskann_label_filter::{
-    read_and_parse_queries, read_baselabels, FrozenAttributeIndex, InlineAttributeIndex,
+    read_and_parse_queries, read_baselabels, FrozenAttributeIndex, FrozenAttributeIndexCsr,
+    InlineAttributeIndex, InlineAttributeIndexCsr,
 };
 
 pub struct QueryBitmapEvaluator {
@@ -169,6 +170,53 @@ pub(crate) fn make_live_providers(
     Ok(providers)
 }
 
+/// Build an in-memory flat CSR attribute index from a jsonl label file (one document per line).
+///
+/// Identical inputs and integer encoding to [`build_inline_attribute_index`], but stores each
+/// document's attribute ids in a contiguous CSR layout (`offsets` + sorted `values`) instead of a
+/// roaring treemap, so the per-node live match reads a single contiguous row.
+pub(crate) fn build_inline_attribute_index_csr(
+    data_labels: &InputFile,
+) -> anyhow::Result<Arc<FrozenAttributeIndexCsr>> {
+    let docs = read_baselabels(data_labels.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to read base labels: {e}"))?;
+    let mut index = InlineAttributeIndexCsr::new();
+    let mut attrs: Vec<Attribute> = Vec::new();
+    for doc in &docs {
+        attrs.clear();
+        if let Some(obj) = doc.label.as_object() {
+            for (field, value) in obj {
+                attrs.push(Attribute::from_json_value(field, value).map_err(|e| {
+                    anyhow::anyhow!("attribute conversion failed for field '{field}': {e:?}")
+                })?);
+            }
+        }
+        index
+            .insert_document(doc.doc_id as u32, &attrs)
+            .map_err(|e| anyhow::anyhow!("failed to insert document {}: {e:?}", doc.doc_id))?;
+    }
+    Ok(Arc::new(index.freeze()))
+}
+
+/// Parse per-query predicates and build one live CSR [`QueryLabelProvider`] per query, all sharing
+/// the same CSR attribute `index`. Mirrors [`make_live_providers`].
+pub(crate) fn make_live_providers_csr(
+    index: &FrozenAttributeIndexCsr,
+    query_predicates: &InputFile,
+) -> anyhow::Result<Vec<Arc<dyn QueryLabelProvider<u32>>>> {
+    let parsed = read_and_parse_queries(query_predicates.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to parse query predicates: {e}"))?;
+    let mut providers = Vec::with_capacity(parsed.len());
+    for (_query_id, ast) in parsed {
+        providers.push(
+            index
+                .make_provider(&ast)
+                .map_err(|e| anyhow::anyhow!("failed to build live provider: {e:?}"))?,
+        );
+    }
+    Ok(providers)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

From d0894b034fbb4f686a49a97db938646c9765ac92 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Mon, 27 Jul 2026 14:55:35 +0800
Subject: [PATCH 05/25] docs: add CSR live-filter optimization results to
 multiple-filter report

New section 8.1 documenting the is_match microbenchmark (roaring 14-20x slower than flat CSR) and the end-to-end A/B of topk-multihop-live-filter vs -csr (3.4-4.4x lower latency at equal recall), plus CSR artifacts in section 9.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 19cdd8e8-cc28-4b87-af2b-97a3f1ac9488
---
 .../multiple_filter_test_report.md            | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/diskann-benchmark/multiple_filter_test_report.md b/diskann-benchmark/multiple_filter_test_report.md
index 0d4d15f46b..314e189b16 100644
--- a/diskann-benchmark/multiple_filter_test_report.md
+++ b/diskann-benchmark/multiple_filter_test_report.md
@@ -203,6 +203,29 @@ Results at **L=150, k=150, single thread** (recall is identical because traversa
 - **Cost scales with expression complexity and traversal size:** the AND/OR combo (S4) and selective geo filters (S6-S8, more hops through non-matching regions -> more `is_match` calls) are the most expensive; broad single-term filters (S1, S5) are cheapest.
 - This is the production-relevant number: a real system evaluates the filter at query time (per node), not from a precomputed whole-corpus answer.
 
+## 8.1 CSR optimization of the live per-node filter
+
+The live cost in section 8 is dominated by the roaring representation. `is_match` does a `HashMap<u32, RoaringTreemap>` probe into the 10M-entry index (random access + heap pointer-chase) plus, per equality terminal, a `RoaringTreemap::contains` (`BTreeMap` lookup → `RoaringBitmap` container binary-search). A criterion microbenchmark isolating just `is_match` (1M docs, 50k random probes) shows this is **14-20x slower** than a flat **CSR** layout that stores each node's sorted attribute-ids contiguously (`offsets: Vec<u32>` + `values: Vec<u32>`) and answers each terminal with a `binary_search` over the node's one contiguous row:
+
+| predicate | roaring treemap | flat CSR | posting bitmap/attr |
+|---|---:|---:|---:|
+| 1 term | 277 ns | 13.6 ns (20.4x) | 8.8 ns |
+| AND-2 | 298 ns | 20.7 ns (14.4x) | 23.6 ns |
+| (a AND b) OR (c AND d) | 596 ns | 36.0 ns (16.6x) | 74.2 ns |
+
+(microbench: `cargo bench -p diskann-label-filter --bench main -- live_filter`; posting = one doc-id bitmap per attribute, wins only for a single broad term but degrades with term count since each terminal is a separate random bitmap probe.)
+
+A CSR-backed provider (`InlineAttributeIndexCsr` / `FrozenAttributeIndexCsr`) was added and exposed as the benchmark search type `topk-multihop-live-filter-csr`. It reuses the same `AttributeEncoder`/`EncodedFilterExpr`, so predicate semantics and errors are identical. End-to-end (same index, k=150, L=150, single thread, 1000 queries) it is a drop-in replacement — **identical traversal** (same avg cmps/hops) and **identical recall** — differing only in how `is_match` is computed:
+
+| Case | impl | recall | mean | p90 | p99 | QPS |
+|---|---|---:|---:|---:|---:|---:|
+| S1 (66.4%) | live (roaring) | 0.9710 | 18.4 ms | 39.6 | 85.1 | 54 |
+| S1 | **live-csr** | 0.9710 | **5.5 ms** | 11.8 | 22.4 | 183 |
+| S4 (10.0%) | live (roaring) | 0.9534 | 76.7 ms | 142.1 | 197.7 | 13 |
+| S4 | **live-csr** | 0.9534 | **17.4 ms** | 31.8 | 43.7 | 57 |
+
+CSR gives a **3.4x (S1) - 4.4x (S4)** end-to-end latency/QPS improvement at equal recall, closing ~82-85% of the live-vs-precomputed-bitmap gap from section 8 while still evaluating the predicate live per node. The end-to-end factor is smaller than the ~15-20x on `is_match` alone because the ~13k vector-distance comparisons per query are unchanged and now dominate the remaining latency.
+
 ## 9. Artifacts (`Q:\test6\filtered_test2\bench\full\`)
 
 - Labels: `data_labels_set.jsonl` (596 labels, general), `data_labels_min.jsonl` (11, fast)
@@ -212,6 +235,7 @@ Results at **L=150, k=150, single thread** (recall is identical because traversa
 - Outputs: `out_setmin.json`, `out_beta_setmin.json`, `out_livefilter.json` (+ `out_live_S8.json`, `out_live_S9.json`)
 - Encoders: `gen_setmembership.py` (full), `gen_setmin.py` (minimal)
 - Live-filter code: `diskann-label-filter/src/live_filter.rs` (InlineAttributeIndex / FrozenAttributeIndex + QueryLabelProvider); benchmark search-type `topk-multihop-live-filter`
+- CSR live-filter code (section 8.1): `InlineAttributeIndexCsr` / `FrozenAttributeIndexCsr` in the same module; benchmark search-type `topk-multihop-live-filter-csr`; is_match microbenchmark `diskann-label-filter/benches/benchmarks/live_filter_bench.rs`
 - Index (reused): `idxsave_full`(+`.data`)
 
 _Note: an earlier version of this report used a single-valued `geo` string field; it is superseded by the set-membership results above._
\ No newline at end of file

From b39b8da7ae3573c6c84013f3b44b1da0e176e50f Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Mon, 27 Jul 2026 14:55:36 +0800
Subject: [PATCH 06/25] diskann-tools: add bin_cast and tsv_to_diskann_bin
 data-prep tools

bin_cast: widen a DiskANN .bin file's element type (u8/i8/f16 -> f32). tsv_to_diskann_bin: convert a label-tagged TSV of embeddings into DiskANN bin + JSONL label/predicate files for compute_groundtruth and the filtered-search benchmark. Both are standalone CLIs used to prepare the multiple-filter test data.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 19cdd8e8-cc28-4b87-af2b-97a3f1ac9488
---
 diskann-tools/src/bin/bin_cast.rs           | 119 ++++++++
 diskann-tools/src/bin/tsv_to_diskann_bin.rs | 302 ++++++++++++++++++++
 2 files changed, 421 insertions(+)
 create mode 100644 diskann-tools/src/bin/bin_cast.rs
 create mode 100644 diskann-tools/src/bin/tsv_to_diskann_bin.rs

diff --git a/diskann-tools/src/bin/bin_cast.rs b/diskann-tools/src/bin/bin_cast.rs
new file mode 100644
index 0000000000..bae71a5dad
--- /dev/null
+++ b/diskann-tools/src/bin/bin_cast.rs
@@ -0,0 +1,119 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+
+//! Convert a DiskANN `.bin` vector file from one POD element type to another.
+//!
+//! Only widening casts (`u8 → f32`, `i8 → f32`, `f16 → f32`) and the identity
+//! cast are supported. Use this when an existing dataset is in `u8` but the
+//! benchmark you want to run only accepts `f32`.
+
+use std::{
+    fs::File,
+    io::{BufReader, BufWriter, Write},
+    path::PathBuf,
+};
+
+use anyhow::{anyhow, bail, Context, Result};
+use clap::{Parser, ValueEnum};
+use diskann_utils::io::{read_bin, Metadata};
+use half::f16;
+
+#[derive(Copy, Clone, Debug, ValueEnum)]
+#[value(rename_all = "lower")]
+enum InType {
+    U8,
+    I8,
+    F16,
+    F32,
+}
+
+#[derive(Copy, Clone, Debug, ValueEnum)]
+#[value(rename_all = "lower")]
+enum OutType {
+    F32,
+}
+
+#[derive(Parser, Debug)]
+#[command(
+    name = "bin_cast",
+    about = "Cast a DiskANN .bin file to a different element type"
+)]
+struct Args {
+    /// Input .bin file.
+    #[arg(long)]
+    input: PathBuf,
+
+    /// Element type stored in the input file.
+    #[arg(long, value_enum)]
+    in_type: InType,
+
+    /// Output .bin file.
+    #[arg(long)]
+    output: PathBuf,
+
+    /// Element type to emit in the output file. Currently only `f32` is supported.
+    #[arg(long, value_enum, default_value_t = OutType::F32)]
+    out_type: OutType,
+}
+
+fn main() -> Result<()> {
+    let args = Args::parse();
+
+    let mut reader = BufReader::new(
+        File::open(&args.input).with_context(|| format!("opening {}", args.input.display()))?,
+    );
+    let mut writer = BufWriter::new(
+        File::create(&args.output)
+            .with_context(|| format!("creating {}", args.output.display()))?,
+    );
+
+    // Read the entire input file into a typed Matrix using the existing reader.
+    match (args.in_type, args.out_type) {
+        (InType::U8, OutType::F32) => cast::<u8, f32>(&mut reader, &mut writer, |x| x as f32)?,
+        (InType::I8, OutType::F32) => cast::<i8, f32>(&mut reader, &mut writer, |x| x as f32)?,
+        (InType::F16, OutType::F32) => cast::<f16, f32>(&mut reader, &mut writer, |x| x.to_f32())?,
+        (InType::F32, OutType::F32) => cast::<f32, f32>(&mut reader, &mut writer, |x| x)?,
+    }
+
+    writer.flush()?;
+    Ok(())
+}
+
+fn cast<I, O>(
+    reader: &mut BufReader<File>,
+    writer: &mut BufWriter<File>,
+    mut f: impl FnMut(I) -> O,
+) -> Result<()>
+where
+    I: bytemuck::Pod,
+    O: bytemuck::Pod,
+{
+    let m = read_bin::<I>(reader)?;
+    let (nrows, ncols) = (m.nrows(), m.ncols());
+    if nrows > u32::MAX as usize || ncols > u32::MAX as usize {
+        bail!(
+            "dimensions too large for the bin format (nrows={}, ncols={})",
+            nrows,
+            ncols
+        );
+    }
+    Metadata::new(nrows as u32, ncols as u32)
+        .map_err(|_| anyhow!("dimension overflow building bin metadata"))?
+        .write(writer)?;
+
+    // Stream the conversion row by row to avoid allocating a second full
+    // matrix in memory.
+    let mut out_row: Vec<O> = vec![bytemuck::Zeroable::zeroed(); ncols];
+    for r in 0..nrows {
+        let in_row = m.row(r);
+        for c in 0..ncols {
+            out_row[c] = f(in_row[c]);
+        }
+        writer.write_all(bytemuck::cast_slice::<O, u8>(&out_row))?;
+    }
+
+    println!("converted {} rows × {} cols", nrows, ncols);
+    Ok(())
+}
diff --git a/diskann-tools/src/bin/tsv_to_diskann_bin.rs b/diskann-tools/src/bin/tsv_to_diskann_bin.rs
new file mode 100644
index 0000000000..8f18e0ad7a
--- /dev/null
+++ b/diskann-tools/src/bin/tsv_to_diskann_bin.rs
@@ -0,0 +1,302 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+
+//! Convert a TSV with embeddings + multi-label rows to the DiskANN binary +
+//! JSONL label files used by `compute_groundtruth` and the filtered search
+//! benchmark.
+//!
+//! Expected TSV columns (tab-separated):
+//!   col 0: embedding, space-separated integer values (parsed as `u8`)
+//!   col 1: ignored
+//!   col 2: comma-separated label codes (e.g. `AT,CH,DE`)
+//!
+//! Output files:
+//!   --base-out             : DiskANN u8 binary of all rows
+//!   --queries-out          : DiskANN u8 binary of the first --num-queries rows
+//!   --base-labels-out      : JSONL, one `Document` per row
+//!                            `{"doc_id": i, "<code1>": true, "<code2>": true, ...}`
+//!   --query-predicates-out : JSONL, one `QueryExpression` per query, all with
+//!                            the same predicate
+//!
+//! Predicate sources (mutually exclusive):
+//!   --query-label   <CODE>     : shorthand for `{"<CODE>": {"$eq": true}}`
+//!   --query-filter-json <JSON> : arbitrary filter JSON, e.g.
+//!                                `{"$and":[{"MG":{"$eq":true}},{"PT":{"$eq":true}}]}`
+//!
+//! The presence-flag encoding is required because the label-filter evaluator
+//! uses strict `serde_json::Value` equality (`$in`/`$nin` were removed), so
+//! `$eq` against a JSON array does NOT do set-membership matching.
+
+use std::{
+    fs::File,
+    io::{BufRead, BufReader, BufWriter, Write},
+    path::PathBuf,
+};
+
+use anyhow::{anyhow, bail, Context, Result};
+use clap::Parser;
+use diskann_utils::io::Metadata;
+
+#[derive(Parser, Debug)]
+#[command(
+    name = "tsv_to_diskann_bin",
+    about = "Convert label-tagged TSV embeddings into DiskANN bin + JSONL label files"
+)]
+struct Args {
+    /// Input TSV file.
+    #[arg(long)]
+    input: PathBuf,
+
+    /// Output base vectors (DiskANN u8 binary).
+    #[arg(long)]
+    base_out: PathBuf,
+
+    /// Output query vectors (DiskANN u8 binary), the first `--num-queries` rows.
+    #[arg(long)]
+    queries_out: PathBuf,
+
+    /// Output base labels (JSONL Documents).
+    #[arg(long)]
+    base_labels_out: PathBuf,
+
+    /// Output per-query predicates (JSONL QueryExpressions). All queries use
+    /// the same predicate, taken from either `--query-label` or
+    /// `--query-filter-json`.
+    #[arg(long)]
+    query_predicates_out: PathBuf,
+
+    /// Number of queries to extract from the head of the file.
+    #[arg(long, default_value_t = 1000)]
+    num_queries: usize,
+
+    /// Single-label shorthand: every query filters on `{<label>: {"$eq": true}}`.
+    /// Mutually exclusive with `--query-filter-json`.
+    #[arg(long, conflicts_with = "query_filter_json")]
+    query_label: Option<String>,
+
+    /// Raw JSON predicate, applied identically to every query. Use this for
+    /// multi-label or boolean expressions, e.g.
+    /// `{"$and":[{"MG":{"$eq":true}},{"PT":{"$eq":true}}]}`.
+    /// Mutually exclusive with `--query-label`.
+    #[arg(long, conflicts_with = "query_label")]
+    query_filter_json: Option<String>,
+
+    /// Skip emitting the base bin and base label JSONL. Use this when you have
+    /// already produced those files for the same TSV and only want to refresh
+    /// the queries / per-query predicates for a different filter.
+    #[arg(long, default_value_t = false)]
+    queries_only: bool,
+}
+
+fn main() -> Result<()> {
+    let args = Args::parse();
+
+    // Validate and resolve the query predicate up front.
+    if args.query_label.is_none() && args.query_filter_json.is_none() {
+        bail!("either --query-label or --query-filter-json must be provided");
+    }
+    let predicate_json: String = if let Some(label) = &args.query_label {
+        if !is_safe_key(label) {
+            bail!(
+                "--query-label `{}` contains characters not allowed in a JSON field name",
+                label
+            );
+        }
+        format!("{{\"{}\":{{\"$eq\":true}}}}", label)
+    } else {
+        args.query_filter_json.as_ref().unwrap().trim().to_string()
+    };
+
+    let input =
+        File::open(&args.input).with_context(|| format!("opening {}", args.input.display()))?;
+    let reader = BufReader::new(input);
+
+    // Optionally skip the base outputs. We still need a sink for them so the
+    // loop stays branch-free; use a tiny in-memory throwaway when skipping.
+    let mut base_writer: Box<dyn WriteSeek> = if args.queries_only {
+        Box::new(SinkWithSeek)
+    } else {
+        Box::new(BufWriter::new(File::create(&args.base_out).with_context(
+            || format!("creating {}", args.base_out.display()),
+        )?))
+    };
+    let mut queries_writer = BufWriter::new(
+        File::create(&args.queries_out)
+            .with_context(|| format!("creating {}", args.queries_out.display()))?,
+    );
+    let mut base_labels_writer: Box<dyn Write> = if args.queries_only {
+        Box::new(std::io::sink())
+    } else {
+        Box::new(BufWriter::new(
+            File::create(&args.base_labels_out)
+                .with_context(|| format!("creating {}", args.base_labels_out.display()))?,
+        ))
+    };
+    let mut query_pred_writer = BufWriter::new(
+        File::create(&args.query_predicates_out)
+            .with_context(|| format!("creating {}", args.query_predicates_out.display()))?,
+    );
+
+    // Reserve room for the 8-byte header on both bin files; we rewrite it after
+    // the final count is known (matching the pattern in subsample_bin.rs).
+    let placeholder = Metadata::new(0u32, 0u32)?;
+    placeholder.write(&mut base_writer)?;
+    placeholder.write(&mut queries_writer)?;
+
+    let mut dim: Option<usize> = None;
+    let mut row_buf: Vec<u8> = Vec::new();
+    let mut npoints: u32 = 0;
+    let mut nqueries: u32 = 0;
+
+    for (line_num, line) in reader.lines().enumerate() {
+        let line = line.with_context(|| format!("reading line {}", line_num + 1))?;
+        if line.is_empty() {
+            continue;
+        }
+
+        let mut cols = line.split('\t');
+        let embedding_str = cols
+            .next()
+            .ok_or_else(|| anyhow!("line {}: missing embedding column", line_num + 1))?;
+        let _ignored = cols.next();
+        let labels_str = cols
+            .next()
+            .ok_or_else(|| anyhow!("line {}: missing label column", line_num + 1))?;
+
+        // Parse embedding values.
+        row_buf.clear();
+        for tok in embedding_str.split_ascii_whitespace() {
+            let v: u8 = tok
+                .parse()
+                .with_context(|| format!("line {}: invalid u8 token `{}`", line_num + 1, tok))?;
+            row_buf.push(v);
+        }
+
+        match dim {
+            None => dim = Some(row_buf.len()),
+            Some(d) if d != row_buf.len() => {
+                bail!(
+                    "line {}: dim mismatch (expected {}, got {})",
+                    line_num + 1,
+                    d,
+                    row_buf.len()
+                );
+            }
+            _ => {}
+        }
+
+        // Write base vector (or discard if --queries-only).
+        base_writer.write_all(&row_buf)?;
+
+        // Write query vector if within the head slice.
+        if (npoints as usize) < args.num_queries {
+            queries_writer.write_all(&row_buf)?;
+            nqueries += 1;
+        }
+
+        // Write the base label as a JSONL Document with a presence flag per code
+        // (no-op when --queries-only).
+        write!(base_labels_writer, "{{\"doc_id\":{}", npoints)?;
+        for raw in labels_str.split(',') {
+            let code = raw.trim();
+            if code.is_empty() {
+                continue;
+            }
+            if !is_safe_key(code) {
+                bail!(
+                    "line {}: label code `{}` contains characters not allowed in a JSON field name",
+                    line_num + 1,
+                    code
+                );
+            }
+            write!(base_labels_writer, ",\"{}\":true", code)?;
+        }
+        writeln!(base_labels_writer, "}}")?;
+
+        npoints = npoints
+            .checked_add(1)
+            .ok_or_else(|| anyhow!("too many rows (>{})", u32::MAX))?;
+
+        // When we only want queries, stop reading the TSV once we've gathered
+        // enough query rows.
+        if args.queries_only && (nqueries as usize) >= args.num_queries {
+            break;
+        }
+    }
+
+    let dim = dim.ok_or_else(|| anyhow!("input is empty"))?;
+
+    if (nqueries as usize) < args.num_queries {
+        bail!(
+            "requested {} queries but input only has {} rows",
+            args.num_queries,
+            nqueries
+        );
+    }
+
+    // Rewrite the bin headers with the real counts.
+    use std::io::Seek;
+    if !args.queries_only {
+        base_writer.flush()?;
+        base_writer.seek(std::io::SeekFrom::Start(0))?;
+        Metadata::new(npoints, dim as u32)?.write(&mut base_writer)?;
+    }
+
+    queries_writer.flush()?;
+    queries_writer.get_mut().seek(std::io::SeekFrom::Start(0))?;
+    Metadata::new(nqueries, dim as u32)?.write(&mut queries_writer)?;
+
+    // Emit the per-query predicates: identical filter for every query.
+    for q in 0..nqueries {
+        writeln!(
+            query_pred_writer,
+            "{{\"query_id\":{},\"filter\":{}}}",
+            q, predicate_json
+        )?;
+    }
+
+    base_writer.flush()?;
+    queries_writer.flush()?;
+    base_labels_writer.flush()?;
+    query_pred_writer.flush()?;
+
+    println!(
+        "rows={} dim={} queries={} predicate={} queries_only={}",
+        npoints, dim, nqueries, predicate_json, args.queries_only
+    );
+    Ok(())
+}
+
+/// Restrict label codes to characters that are safe to embed unquoted in a JSON
+/// field name. The country-code style labels in the target TSV (e.g. `MG`,
+/// `AT`) are all in this set; this guards against malformed input.
+fn is_safe_key(s: &str) -> bool {
+    !s.is_empty()
+        && s.chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
+}
+
+/// Trait alias used so the base writer can be either a real file or a discard
+/// sink in --queries-only mode while still satisfying `Write + Seek`.
+trait WriteSeek: Write + std::io::Seek {}
+impl<T: Write + std::io::Seek> WriteSeek for T {}
+
+/// `io::sink()` does not implement `Seek`. Provide a tiny wrapper that
+/// discards all writes and ignores seeks, used only when the base output is
+/// suppressed.
+struct SinkWithSeek;
+impl Write for SinkWithSeek {
+    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+        Ok(buf.len())
+    }
+    fn flush(&mut self) -> std::io::Result<()> {
+        Ok(())
+    }
+}
+impl std::io::Seek for SinkWithSeek {
+    fn seek(&mut self, _pos: std::io::SeekFrom) -> std::io::Result<u64> {
+        Ok(0)
+    }
+}

From 42b8fc949fe701bb7540cc2e368b955ee79df128 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Tue, 28 Jul 2026 19:31:37 +0800
Subject: [PATCH 07/25] diskann-label-filter: add optimized live filter
 providers

Add posting-list materialization, selectivity-adaptive CSR/bitmap selection, and bit-sliced lookup providers with parity and boundary tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 diskann-label-filter/src/lib.rs         |   5 +-
 diskann-label-filter/src/live_filter.rs | 671 +++++++++++++++++++++++-
 2 files changed, 673 insertions(+), 3 deletions(-)

diff --git a/diskann-label-filter/src/lib.rs b/diskann-label-filter/src/lib.rs
index cc054349c1..5ee39f0d1a 100644
--- a/diskann-label-filter/src/lib.rs
+++ b/diskann-label-filter/src/lib.rs
@@ -69,7 +69,10 @@ pub mod stores;
 
 // Re-exports for convenience
 pub use live_filter::{
-    FrozenAttributeIndex, FrozenAttributeIndexCsr, InlineAttributeIndex, InlineAttributeIndexCsr,
+    FrozenAttributeIndex, FrozenAttributeIndexAuto, FrozenAttributeIndexBitslice,
+    FrozenAttributeIndexCsr, FrozenAttributeIndexPosting, InlineAttributeIndex,
+    InlineAttributeIndexAuto, InlineAttributeIndexBitslice, InlineAttributeIndexCsr,
+    InlineAttributeIndexPosting,
 };
 pub use parser::ast::{ASTExpr, CompareOp};
 pub use parser::evaluator::eval_query_expr;
diff --git a/diskann-label-filter/src/live_filter.rs b/diskann-label-filter/src/live_filter.rs
index 5418a83e37..ced737e70e 100644
--- a/diskann-label-filter/src/live_filter.rs
+++ b/diskann-label-filter/src/live_filter.rs
@@ -23,11 +23,11 @@
 //! operators are rejected at construction time.
 
 use std::borrow::Cow;
-use std::sync::{Arc, RwLock};
+use std::sync::{Arc, OnceLock, RwLock};
 
 use diskann::graph::index::QueryLabelProvider;
 use diskann::{ANNError, ANNErrorKind, ANNResult};
-use roaring::RoaringTreemap;
+use roaring::{RoaringBitmap, RoaringTreemap};
 
 use crate::attribute::Attribute;
 use crate::encoded_attribute_provider::ast_id_expr::{ASTIdExpr, ASTIdExprVisitor};
@@ -142,6 +142,15 @@ fn ensure_and_or_only(ast: &ASTExpr) -> ANNResult<()> {
     }
 }
 
+fn checked_vector_count(vec_id: u32) -> ANNResult<u32> {
+    vec_id.checked_add(1).ok_or_else(|| {
+        ANNError::message(
+            ANNErrorKind::Opaque,
+            "dense live-filter indexes do not support vector id u32::MAX",
+        )
+    })
+}
+
 /// A [`QueryLabelProvider`] that evaluates the encoded predicate against each node's own
 /// attribute set at search time, reading the shared index lock-free.
 struct InlineAttributeLabelProvider {
@@ -230,6 +239,7 @@ impl InlineAttributeIndexCsr {
     /// # Errors
     /// Returns an error if more than `u32::MAX` distinct attributes are encountered.
     pub fn insert_document(&mut self, vec_id: u32, attributes: &[Attribute]) -> ANNResult<()> {
+        checked_vector_count(vec_id)?;
         let idx = vec_id as usize;
         if idx >= self.rows.len() {
             self.rows.resize_with(idx + 1, Vec::new);
@@ -362,6 +372,513 @@ impl ASTIdExprVisitor<u64> for CsrRowEvaluator<'_> {
     }
 }
 
+/// A posting-list attribute index: an in-memory inverted index mapping each attribute-id to a
+/// [`RoaringBitmap`] of the vector-ids that carry it. This is the representation used by
+/// Lucene/Milvus/FAISS-style filtered search.
+///
+/// Unlike the roaring/CSR providers (which evaluate the predicate *per visited node*), this
+/// builder feeds a provider that evaluates the predicate **once per query** via roaring set-algebra
+/// (`AND`=intersect, `OR`=union) over the posting lists, materializes the resulting match set into a
+/// dense bitset, and then answers each per-node `is_match` with an `O(1)` bit test. The match-set
+/// materialization is done lazily at the first `is_match` so its cost is counted as live query time
+/// (not amortized into an offline pass).
+///
+/// This is the **builder**; call [`Self::freeze`] for the shareable read-only index.
+pub struct InlineAttributeIndexPosting {
+    attribute_map: AttributeEncoder,
+    posting: Vec<RoaringBitmap>,
+    num_vectors: u32,
+}
+
+impl Default for InlineAttributeIndexPosting {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl InlineAttributeIndexPosting {
+    /// Create an empty index.
+    pub fn new() -> Self {
+        Self {
+            attribute_map: AttributeEncoder::new(),
+            posting: Vec::new(),
+            num_vectors: 0,
+        }
+    }
+
+    /// Register the attributes of a single vector (build-time): insert `vec_id` into the posting
+    /// list of each of its (encoded) attribute-ids.
+    pub fn insert_document(&mut self, vec_id: u32, attributes: &[Attribute]) -> ANNResult<()> {
+        self.num_vectors = self.num_vectors.max(checked_vector_count(vec_id)?);
+        for attr in attributes {
+            let attr_id = self.attribute_map.insert(attr);
+            let attr_id = usize::try_from(attr_id).map_err(|_| {
+                ANNError::message(
+                    ANNErrorKind::Opaque,
+                    "posting-list filter supports at most usize::MAX distinct attributes",
+                )
+            })?;
+            if attr_id >= self.posting.len() {
+                self.posting.resize_with(attr_id + 1, RoaringBitmap::new);
+            }
+            self.posting[attr_id].insert(vec_id);
+        }
+        Ok(())
+    }
+
+    /// Freeze the builder into a read-only, shareable index for search.
+    pub fn freeze(self) -> FrozenAttributeIndexPosting {
+        FrozenAttributeIndexPosting {
+            attribute_map: Arc::new(RwLock::new(self.attribute_map)),
+            posting: Arc::from(self.posting),
+            num_vectors: self.num_vectors,
+        }
+    }
+}
+
+/// A read-only, shareable posting-list index.
+pub struct FrozenAttributeIndexPosting {
+    attribute_map: Arc<RwLock<AttributeEncoder>>,
+    posting: Arc<[RoaringBitmap]>,
+    num_vectors: u32,
+}
+
+impl FrozenAttributeIndexPosting {
+    /// Build a per-query [`QueryLabelProvider`] for `ast`.
+    ///
+    /// The predicate is encoded once (same `AND`/`OR` + equality subset as the other live
+    /// providers); the actual match-set bitmap is materialized lazily on first use. See
+    /// [`InlineAttributeIndexPosting`] for the rationale.
+    ///
+    /// # Errors
+    /// Returns an error if the expression uses an unsupported operator, or references a field/value
+    /// absent from the dataset.
+    pub fn make_provider(&self, ast: &ASTExpr) -> ANNResult<Arc<dyn QueryLabelProvider<u32>>> {
+        ensure_and_or_only(ast)?;
+        let encoded = EncodedFilterExpr::new(ast, self.attribute_map.clone())?;
+        Ok(Arc::new(MaterializedBitmapProvider {
+            encoded,
+            posting: self.posting.clone(),
+            num_vectors: self.num_vectors,
+            dense: OnceLock::new(),
+        }))
+    }
+}
+
+/// A [`QueryLabelProvider`] that materializes the query's whole match set once (via roaring
+/// set-algebra over posting lists) into a dense bitset, then answers each node with an `O(1)` test.
+struct MaterializedBitmapProvider {
+    encoded: EncodedFilterExpr,
+    posting: Arc<[RoaringBitmap]>,
+    num_vectors: u32,
+    /// Dense match bitset, lazily built on first `is_match` so its cost is timed as query latency.
+    dense: OnceLock<Vec<u64>>,
+}
+
+impl std::fmt::Debug for MaterializedBitmapProvider {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("MaterializedBitmapProvider").finish()
+    }
+}
+
+/// Evaluate an encoded `AND`/`OR` + equality predicate into the roaring set of matching vector-ids,
+/// using per-attribute posting lists. `num_vectors` is only used for the (unreachable) empty-`AND`
+/// case (vacuously true).
+fn eval_posting_to_roaring(
+    expr: &ASTIdExpr<u64>,
+    posting: &[RoaringBitmap],
+    num_vectors: u32,
+) -> RoaringBitmap {
+    match expr {
+        ASTIdExpr::Terminal(id) => usize::try_from(*id)
+            .ok()
+            .and_then(|i| posting.get(i))
+            .cloned()
+            .unwrap_or_default(),
+        ASTIdExpr::And(children) => {
+            let mut iter = children.iter();
+            let Some(first) = iter.next() else {
+                let mut all = RoaringBitmap::new();
+                all.insert_range(0..num_vectors);
+                return all;
+            };
+            let mut acc = eval_posting_to_roaring(first, posting, num_vectors);
+            for child in iter {
+                if acc.is_empty() {
+                    break;
+                }
+                acc &= eval_posting_to_roaring(child, posting, num_vectors);
+            }
+            acc
+        }
+        ASTIdExpr::Or(children) => {
+            let mut acc = RoaringBitmap::new();
+            for child in children {
+                acc |= eval_posting_to_roaring(child, posting, num_vectors);
+            }
+            acc
+        }
+        // `NOT` is rejected at construction, so this is unreachable in practice.
+        ASTIdExpr::Not(_) => RoaringBitmap::new(),
+    }
+}
+
+/// Materialize a roaring match set into a dense bitset indexed by vector-id.
+fn densify(result: &RoaringBitmap, num_vectors: u32) -> Vec<u64> {
+    let mut bits = vec![0u64; (num_vectors as usize).div_ceil(64)];
+    for id in result.iter() {
+        let i = id as usize;
+        bits[i / 64] |= 1u64 << (i % 64);
+    }
+    bits
+}
+
+/// Test a bit in a dense bitset produced by [`densify`].
+#[inline]
+fn dense_contains(bits: &[u64], vec_id: u32) -> bool {
+    let i = vec_id as usize;
+    (bits[i / 64] >> (i % 64)) & 1 == 1
+}
+
+impl QueryLabelProvider<u32> for MaterializedBitmapProvider {
+    fn is_match(&self, vec_id: u32) -> bool {
+        if vec_id >= self.num_vectors {
+            return false;
+        }
+        let bits = self.dense.get_or_init(|| {
+            let result = eval_posting_to_roaring(
+                self.encoded.encoded_filter_expr(),
+                &self.posting,
+                self.num_vectors,
+            );
+            densify(&result, self.num_vectors)
+        });
+        dense_contains(bits, vec_id)
+    }
+}
+
+/// An adaptive live index that stores *both* a flat CSR layout and per-attribute posting lists
+/// (sharing one encoder). At query time it materializes the match set's roaring bitmap once (via the
+/// posting lists), reads its cardinality for free, and then picks the regime that is fastest for
+/// that selectivity:
+///
+/// * **selective** match set (`<=` threshold) -> densify to a bitset, answer each node with an
+///   `O(1)` bit test (best when few match and traversal is heavy);
+/// * **broad** match set -> per-node **CSR** row scan (avoids the expensive densify of a large set).
+///
+/// The decision is made lazily on first `is_match`, so its (cheap) cost is counted as query latency.
+pub struct InlineAttributeIndexAuto {
+    attribute_map: AttributeEncoder,
+    rows: Vec<Vec<u32>>,
+    posting: Vec<RoaringBitmap>,
+    num_vectors: u32,
+}
+
+impl Default for InlineAttributeIndexAuto {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl InlineAttributeIndexAuto {
+    /// Create an empty index.
+    pub fn new() -> Self {
+        Self {
+            attribute_map: AttributeEncoder::new(),
+            rows: Vec::new(),
+            posting: Vec::new(),
+            num_vectors: 0,
+        }
+    }
+
+    /// Register a vector's attributes into both the CSR rows and the posting lists.
+    pub fn insert_document(&mut self, vec_id: u32, attributes: &[Attribute]) -> ANNResult<()> {
+        self.num_vectors = self.num_vectors.max(checked_vector_count(vec_id)?);
+        let idx = vec_id as usize;
+        if idx >= self.rows.len() {
+            self.rows.resize_with(idx + 1, Vec::new);
+        }
+        for attr in attributes {
+            let attr_id = self.attribute_map.insert(attr);
+            let attr_idx = usize::try_from(attr_id).map_err(|_| {
+                ANNError::message(
+                    ANNErrorKind::Opaque,
+                    "auto filter supports at most usize::MAX distinct attributes",
+                )
+            })?;
+            let attr_id_u32 = u32::try_from(attr_id).map_err(|_| {
+                ANNError::message(
+                    ANNErrorKind::Opaque,
+                    "auto filter (CSR) supports at most u32::MAX distinct attributes",
+                )
+            })?;
+            self.rows[idx].push(attr_id_u32);
+            if attr_idx >= self.posting.len() {
+                self.posting.resize_with(attr_idx + 1, RoaringBitmap::new);
+            }
+            self.posting[attr_idx].insert(vec_id);
+        }
+        Ok(())
+    }
+
+    /// Freeze the builder into a read-only, shareable index for search.
+    pub fn freeze(mut self) -> FrozenAttributeIndexAuto {
+        let mut offsets: Vec<u32> = Vec::with_capacity(self.rows.len() + 1);
+        offsets.push(0);
+        let total: usize = self.rows.iter().map(Vec::len).sum();
+        let mut values: Vec<u32> = Vec::with_capacity(total);
+        for row in &mut self.rows {
+            row.sort_unstable();
+            row.dedup();
+            values.extend_from_slice(row);
+            let end = u32::try_from(values.len())
+                .expect("auto filter supports at most u32::MAX total attribute occurrences");
+            offsets.push(end);
+        }
+        FrozenAttributeIndexAuto {
+            attribute_map: Arc::new(RwLock::new(self.attribute_map)),
+            offsets: offsets.into(),
+            values: values.into(),
+            posting: Arc::from(self.posting),
+            num_vectors: self.num_vectors,
+        }
+    }
+}
+
+/// A read-only, shareable adaptive index. See [`InlineAttributeIndexAuto`].
+pub struct FrozenAttributeIndexAuto {
+    attribute_map: Arc<RwLock<AttributeEncoder>>,
+    offsets: Arc<[u32]>,
+    values: Arc<[u32]>,
+    posting: Arc<[RoaringBitmap]>,
+    num_vectors: u32,
+}
+
+impl FrozenAttributeIndexAuto {
+    /// Build a per-query [`QueryLabelProvider`] for `ast`.
+    ///
+    /// # Errors
+    /// Returns an error if the expression uses an unsupported operator, or references a field/value
+    /// absent from the dataset.
+    pub fn make_provider(&self, ast: &ASTExpr) -> ANNResult<Arc<dyn QueryLabelProvider<u32>>> {
+        ensure_and_or_only(ast)?;
+        let encoded = EncodedFilterExpr::new(ast, self.attribute_map.clone())?;
+        // Treat a match set below 1/8 of the corpus as "selective" -> bitmap; else CSR. This sits
+        // below the measured bitmap<->CSR crossover (~10-15% selectivity).
+        let selectivity_threshold = u64::from(self.num_vectors) / 8;
+        Ok(Arc::new(AutoProvider {
+            encoded,
+            offsets: self.offsets.clone(),
+            values: self.values.clone(),
+            posting: self.posting.clone(),
+            num_vectors: self.num_vectors,
+            selectivity_threshold,
+            decision: OnceLock::new(),
+        }))
+    }
+}
+
+/// Lazily-chosen per-node evaluation strategy for [`AutoProvider`].
+enum AutoDecision {
+    /// Selective filter: dense match bitset, `O(1)` lookups.
+    Dense(Vec<u64>),
+    /// Broad filter: evaluate the predicate against the node's CSR row.
+    Csr,
+}
+
+/// A [`QueryLabelProvider`] that picks bitmap (selective) or CSR (broad) per query.
+struct AutoProvider {
+    encoded: EncodedFilterExpr,
+    offsets: Arc<[u32]>,
+    values: Arc<[u32]>,
+    posting: Arc<[RoaringBitmap]>,
+    num_vectors: u32,
+    selectivity_threshold: u64,
+    decision: OnceLock<AutoDecision>,
+}
+
+impl std::fmt::Debug for AutoProvider {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("AutoProvider").finish()
+    }
+}
+
+impl AutoProvider {
+    fn decide(&self) -> AutoDecision {
+        let result = eval_posting_to_roaring(
+            self.encoded.encoded_filter_expr(),
+            &self.posting,
+            self.num_vectors,
+        );
+        if result.len() <= self.selectivity_threshold {
+            AutoDecision::Dense(densify(&result, self.num_vectors))
+        } else {
+            AutoDecision::Csr
+        }
+    }
+}
+
+impl QueryLabelProvider<u32> for AutoProvider {
+    fn is_match(&self, vec_id: u32) -> bool {
+        if vec_id >= self.num_vectors {
+            return false;
+        }
+        match self.decision.get_or_init(|| self.decide()) {
+            AutoDecision::Dense(bits) => dense_contains(bits, vec_id),
+            AutoDecision::Csr => {
+                let idx = vec_id as usize;
+                let start = self.offsets[idx] as usize;
+                let end = self.offsets[idx + 1] as usize;
+                let evaluator = CsrRowEvaluator {
+                    row: &self.values[start..end],
+                };
+                evaluator.visit(self.encoded.encoded_filter_expr())
+            }
+        }
+    }
+}
+
+/// A bit-sliced live index: one dense bitset per attribute, built at [`Self::freeze`] (index time).
+/// `is_match` is one `O(1)` bit test per equality terminal, with **no** per-query build. Memory is
+/// `num_attributes * ceil(num_vectors / 64) * 8` bytes, so it is best when the label vocabulary is
+/// modest.
+pub struct InlineAttributeIndexBitslice {
+    attribute_map: AttributeEncoder,
+    posting: Vec<RoaringBitmap>,
+    num_vectors: u32,
+}
+
+impl Default for InlineAttributeIndexBitslice {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl InlineAttributeIndexBitslice {
+    /// Create an empty index.
+    pub fn new() -> Self {
+        Self {
+            attribute_map: AttributeEncoder::new(),
+            posting: Vec::new(),
+            num_vectors: 0,
+        }
+    }
+
+    /// Register a vector's attributes (same as the posting-list builder).
+    pub fn insert_document(&mut self, vec_id: u32, attributes: &[Attribute]) -> ANNResult<()> {
+        self.num_vectors = self.num_vectors.max(checked_vector_count(vec_id)?);
+        for attr in attributes {
+            let attr_id = self.attribute_map.insert(attr);
+            let attr_idx = usize::try_from(attr_id).map_err(|_| {
+                ANNError::message(
+                    ANNErrorKind::Opaque,
+                    "bit-slice filter supports at most usize::MAX distinct attributes",
+                )
+            })?;
+            if attr_idx >= self.posting.len() {
+                self.posting.resize_with(attr_idx + 1, RoaringBitmap::new);
+            }
+            self.posting[attr_idx].insert(vec_id);
+        }
+        Ok(())
+    }
+
+    /// Freeze into per-attribute dense bitsets.
+    pub fn freeze(self) -> FrozenAttributeIndexBitslice {
+        let bitsets: Vec<Box<[u64]>> = self
+            .posting
+            .iter()
+            .map(|rb| densify(rb, self.num_vectors).into_boxed_slice())
+            .collect();
+        FrozenAttributeIndexBitslice {
+            attribute_map: Arc::new(RwLock::new(self.attribute_map)),
+            bitsets: Arc::from(bitsets),
+            num_vectors: self.num_vectors,
+        }
+    }
+}
+
+/// A read-only, shareable bit-sliced index. See [`InlineAttributeIndexBitslice`].
+pub struct FrozenAttributeIndexBitslice {
+    attribute_map: Arc<RwLock<AttributeEncoder>>,
+    bitsets: Arc<[Box<[u64]>]>,
+    num_vectors: u32,
+}
+
+impl FrozenAttributeIndexBitslice {
+    /// Build a per-query [`QueryLabelProvider`] for `ast`.
+    ///
+    /// # Errors
+    /// Returns an error if the expression uses an unsupported operator, or references a field/value
+    /// absent from the dataset.
+    pub fn make_provider(&self, ast: &ASTExpr) -> ANNResult<Arc<dyn QueryLabelProvider<u32>>> {
+        ensure_and_or_only(ast)?;
+        let encoded = EncodedFilterExpr::new(ast, self.attribute_map.clone())?;
+        Ok(Arc::new(BitsliceProvider {
+            encoded,
+            bitsets: self.bitsets.clone(),
+            num_vectors: self.num_vectors,
+        }))
+    }
+}
+
+/// A [`QueryLabelProvider`] that evaluates the predicate as one `O(1)` bit test per terminal against
+/// the per-attribute dense bitsets. No per-query build.
+struct BitsliceProvider {
+    encoded: EncodedFilterExpr,
+    bitsets: Arc<[Box<[u64]>]>,
+    num_vectors: u32,
+}
+
+impl std::fmt::Debug for BitsliceProvider {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("BitsliceProvider").finish()
+    }
+}
+
+impl QueryLabelProvider<u32> for BitsliceProvider {
+    fn is_match(&self, vec_id: u32) -> bool {
+        if vec_id >= self.num_vectors {
+            return false;
+        }
+        let evaluator = BitsliceEvaluator {
+            vec_id,
+            bitsets: &self.bitsets,
+        };
+        evaluator.visit(self.encoded.encoded_filter_expr())
+    }
+}
+
+/// Evaluates an encoded `AND`/`OR` + equality predicate for one node via per-attribute bitsets.
+struct BitsliceEvaluator<'a> {
+    vec_id: u32,
+    bitsets: &'a [Box<[u64]>],
+}
+
+impl ASTIdExprVisitor<u64> for BitsliceEvaluator<'_> {
+    type Output = bool;
+
+    fn visit_and(&self, exprs: &[ASTIdExpr<u64>]) -> bool {
+        exprs.iter().all(|e| self.visit(e))
+    }
+
+    fn visit_or(&self, exprs: &[ASTIdExpr<u64>]) -> bool {
+        exprs.iter().any(|e| self.visit(e))
+    }
+
+    fn visit_not(&self, expr: &ASTIdExpr<u64>) -> bool {
+        // `NOT` is rejected at construction; handled for completeness.
+        !self.visit(expr)
+    }
+
+    fn visit_terminal(&self, id: &u64) -> bool {
+        usize::try_from(*id)
+            .ok()
+            .and_then(|i| self.bitsets.get(i))
+            .is_some_and(|bits| dense_contains(bits, self.vec_id))
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -511,4 +1028,154 @@ mod tests {
             assert_eq!(rp.is_match(id), cp.is_match(id), "mismatch at node {id}");
         }
     }
+
+    #[test]
+    fn posting_matches_roaring() {
+        // The materialized-bitmap provider must agree with the roaring provider on the same data
+        // and predicate, including an empty node and out-of-range ids.
+        let docs: [(u32, &[(&str, bool)]); 4] = [
+            (0, &[("A", true), ("B", true)]),
+            (1, &[("A", true)]),
+            (2, &[("C", true)]),
+            (3, &[]),
+        ];
+
+        let mut roaring = InlineAttributeIndex::new();
+        let mut posting = InlineAttributeIndexPosting::new();
+        for (id, labels) in docs {
+            let attrs: Vec<Attribute> = labels.iter().map(|(f, v)| attr(f, *v)).collect();
+            roaring.insert_document(id, &attrs).unwrap();
+            posting.insert_document(id, &attrs).unwrap();
+        }
+        let roaring = roaring.freeze();
+        let posting = posting.freeze();
+
+        for ast in [
+            ASTExpr::And(vec![eq_true("A"), eq_true("B")]),
+            ASTExpr::Or(vec![eq_true("A"), eq_true("C")]),
+        ] {
+            let rp = roaring.make_provider(&ast).unwrap();
+            let pp = posting.make_provider(&ast).unwrap();
+            for id in 0..6u32 {
+                assert_eq!(rp.is_match(id), pp.is_match(id), "mismatch at node {id}");
+            }
+        }
+    }
+
+    #[test]
+    fn posting_rejects_not_and_relational() {
+        let mut index = InlineAttributeIndexPosting::new();
+        index.insert_document(0, &[attr("A", true)]).unwrap();
+        let index = index.freeze();
+
+        assert!(index
+            .make_provider(&ASTExpr::Not(Box::new(eq_true("A"))))
+            .is_err());
+        let rel = ASTExpr::Compare {
+            field: "n".to_string(),
+            op: CompareOp::Gt(1.0),
+        };
+        assert!(index.make_provider(&rel).is_err());
+    }
+
+    #[test]
+    fn auto_dense_and_csr_branches_match_roaring() {
+        // 40 vectors -> auto selectivity threshold = 40/8 = 5. "COMMON" (on all) is broad -> CSR
+        // branch; "RARE" (on one) is selective -> Dense branch. Both must match the roaring result.
+        let n = 40u32;
+        let mut roaring = InlineAttributeIndex::new();
+        let mut auto = InlineAttributeIndexAuto::new();
+        for id in 0..n {
+            let mut labels = vec![attr("COMMON", true)];
+            if id == 7 {
+                labels.push(attr("RARE", true));
+            }
+            roaring.insert_document(id, &labels).unwrap();
+            auto.insert_document(id, &labels).unwrap();
+        }
+        let roaring = roaring.freeze();
+        let auto = auto.freeze();
+        for ast in [eq_true("COMMON"), eq_true("RARE")] {
+            let rp = roaring.make_provider(&ast).unwrap();
+            let ap = auto.make_provider(&ast).unwrap();
+            for id in 0..n {
+                assert_eq!(
+                    rp.is_match(id),
+                    ap.is_match(id),
+                    "auto mismatch at node {id}"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn all_live_providers_agree() {
+        let docs: [(u32, &[(&str, bool)]); 5] = [
+            (0, &[("A", true), ("B", true)]),
+            (1, &[("A", true)]),
+            (2, &[("C", true)]),
+            (3, &[]),
+            (4, &[("B", true), ("C", true)]),
+        ];
+        let mut roaring = InlineAttributeIndex::new();
+        let mut csr = InlineAttributeIndexCsr::new();
+        let mut posting = InlineAttributeIndexPosting::new();
+        let mut auto = InlineAttributeIndexAuto::new();
+        let mut bitslice = InlineAttributeIndexBitslice::new();
+        for (id, labels) in docs {
+            let attrs: Vec<Attribute> = labels.iter().map(|(f, v)| attr(f, *v)).collect();
+            roaring.insert_document(id, &attrs).unwrap();
+            csr.insert_document(id, &attrs).unwrap();
+            posting.insert_document(id, &attrs).unwrap();
+            auto.insert_document(id, &attrs).unwrap();
+            bitslice.insert_document(id, &attrs).unwrap();
+        }
+        let roaring = roaring.freeze();
+        let csr = csr.freeze();
+        let posting = posting.freeze();
+        let auto = auto.freeze();
+        let bitslice = bitslice.freeze();
+
+        let asts = [
+            eq_true("A"),
+            ASTExpr::And(vec![eq_true("A"), eq_true("B")]),
+            ASTExpr::Or(vec![eq_true("A"), eq_true("C")]),
+            ASTExpr::Or(vec![
+                ASTExpr::And(vec![eq_true("A"), eq_true("B")]),
+                eq_true("C"),
+            ]),
+        ];
+        for ast in &asts {
+            let rp = roaring.make_provider(ast).unwrap();
+            let others = [
+                csr.make_provider(ast).unwrap(),
+                posting.make_provider(ast).unwrap(),
+                auto.make_provider(ast).unwrap(),
+                bitslice.make_provider(ast).unwrap(),
+            ];
+            for id in 0..7u32 {
+                let expected = rp.is_match(id);
+                for p in &others {
+                    assert_eq!(p.is_match(id), expected, "disagreement at node {id}");
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn dense_live_providers_reject_max_vector_id() {
+        let attrs = [attr("A", true)];
+
+        let mut csr = InlineAttributeIndexCsr::new();
+        assert!(csr.insert_document(u32::MAX, &attrs).is_err());
+
+        let mut posting = InlineAttributeIndexPosting::new();
+        assert!(posting.insert_document(u32::MAX, &attrs).is_err());
+
+        let mut auto = InlineAttributeIndexAuto::new();
+        assert!(auto.insert_document(u32::MAX, &attrs).is_err());
+
+        let mut bitslice = InlineAttributeIndexBitslice::new();
+        assert!(bitslice.insert_document(u32::MAX, &attrs).is_err());
+    }
 }

From dff4a454a26e4dd976e264117016aef18738ec77 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Tue, 28 Jul 2026 19:32:13 +0800
Subject: [PATCH 08/25] diskann-benchmark: wire optimized live filter searches

Expose bitmap, adaptive, and bit-sliced multihop search modes. Recreate lazy providers for every repetition and search-L run so materialization remains part of measured query latency.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../src/backend/index/benchmarks.rs           | 173 +++++++++++++++++-
 .../src/backend/index/search/knn.rs           |  59 ++++++
 .../src/backend/index/search/plugins.rs       |  38 ++++
 diskann-benchmark/src/inputs/graph_index.rs   |  53 ++++++
 diskann-benchmark/src/utils/filters.rs        | 158 +++++++++++++++-
 5 files changed, 476 insertions(+), 5 deletions(-)

diff --git a/diskann-benchmark/src/backend/index/benchmarks.rs b/diskann-benchmark/src/backend/index/benchmarks.rs
index a2e9f3b14a..ffab2eec1b 100644
--- a/diskann-benchmark/src/backend/index/benchmarks.rs
+++ b/diskann-benchmark/src/backend/index/benchmarks.rs
@@ -78,7 +78,10 @@ pub(super) fn register_benchmarks(registry: &mut Registry) -> anyhow::Result<()>
             .search(plugins::TopkBetaFilter)
             .search(plugins::TopkMultihopFilter)
             .search(plugins::TopkMultihopLiveFilter)
-            .search(plugins::TopkMultihopLiveFilterCsr),
+            .search(plugins::TopkMultihopLiveFilterCsr)
+            .search(plugins::TopkMultihopLiveFilterBitmap)
+            .search(plugins::TopkMultihopLiveFilterAuto)
+            .search(plugins::TopkMultihopLiveFilterBitslice),
     )?;
 
     registry.register(
@@ -747,6 +750,174 @@ where
         Ok(AggregatedSearchResults::Topk(result))
     }
 }
+
+//-----------------------------//
+// MultihopLiveFilter (Bitmap)  //
+//-----------------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>> for plugins::TopkMultihopLiveFilterBitmap
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<DP, &'a [DP::Element]> + Clone + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        let multihop = phase.as_topk_multihop_live_filter_bitmap()?;
+
+        let queries: Arc<Matrix<DP::Element>> = Arc::new(datafiles::load_dataset(
+            datafiles::BinFile(&multihop.queries),
+        )?);
+
+        let groundtruth =
+            datafiles::load_range_groundtruth(datafiles::BinFile(&multihop.groundtruth))?;
+
+        let steps =
+            search::knn::SearchSteps::new(multihop.reps, &multihop.num_threads, &multihop.runs);
+
+        // Build the posting-list index once. Fresh providers are constructed for every benchmark
+        // repetition/search-L so lazy match-set materialization is charged to each query execution.
+        let attribute_index =
+            utils::filters::build_inline_attribute_index_posting(&multihop.data_labels)?;
+        let make_multihop = || {
+            let providers = utils::filters::make_live_providers_posting(
+                &attribute_index,
+                &multihop.query_predicates,
+            )?;
+            benchmark_core::search::graph::MultiHop::new(
+                index.clone(),
+                queries.clone(),
+                benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
+                providers.into(),
+            )
+        };
+
+        let result = search::knn::run_fresh_multihop(make_multihop, &groundtruth, steps)?;
+        Ok(AggregatedSearchResults::Topk(result))
+    }
+}
+
+//---------------------------//
+// MultihopLiveFilter (Auto)  //
+//---------------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>> for plugins::TopkMultihopLiveFilterAuto
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<DP, &'a [DP::Element]> + Clone + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        let multihop = phase.as_topk_multihop_live_filter_auto()?;
+
+        let queries: Arc<Matrix<DP::Element>> = Arc::new(datafiles::load_dataset(
+            datafiles::BinFile(&multihop.queries),
+        )?);
+
+        let groundtruth =
+            datafiles::load_range_groundtruth(datafiles::BinFile(&multihop.groundtruth))?;
+
+        let steps =
+            search::knn::SearchSteps::new(multihop.reps, &multihop.num_threads, &multihop.runs);
+
+        let attribute_index =
+            utils::filters::build_inline_attribute_index_auto(&multihop.data_labels)?;
+        // Recreate providers for every repetition/search-L so the lazy strategy decision and any
+        // dense materialization cannot be amortized across benchmark executions.
+        let make_multihop = || {
+            let providers = utils::filters::make_live_providers_auto(
+                &attribute_index,
+                &multihop.query_predicates,
+            )?;
+            benchmark_core::search::graph::MultiHop::new(
+                index.clone(),
+                queries.clone(),
+                benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
+                providers.into(),
+            )
+        };
+
+        let result = search::knn::run_fresh_multihop(make_multihop, &groundtruth, steps)?;
+        Ok(AggregatedSearchResults::Topk(result))
+    }
+}
+
+//--------------------------------//
+// MultihopLiveFilter (Bitslice)   //
+//--------------------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>> for plugins::TopkMultihopLiveFilterBitslice
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<DP, &'a [DP::Element]> + Clone + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        let multihop = phase.as_topk_multihop_live_filter_bitslice()?;
+
+        let queries: Arc<Matrix<DP::Element>> = Arc::new(datafiles::load_dataset(
+            datafiles::BinFile(&multihop.queries),
+        )?);
+
+        let groundtruth =
+            datafiles::load_range_groundtruth(datafiles::BinFile(&multihop.groundtruth))?;
+
+        let steps =
+            search::knn::SearchSteps::new(multihop.reps, &multihop.num_threads, &multihop.runs);
+
+        let attribute_index =
+            utils::filters::build_inline_attribute_index_bitslice(&multihop.data_labels)?;
+        let providers = utils::filters::make_live_providers_bitslice(
+            &attribute_index,
+            &multihop.query_predicates,
+        )?;
+
+        let multihop = benchmark_core::search::graph::MultiHop::new(
+            index,
+            queries,
+            benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
+            providers.into(),
+        )?;
+
+        let result = search::knn::run(&multihop, &groundtruth, steps)?;
+        Ok(AggregatedSearchResults::Topk(result))
+    }
+}
 /// The stack looks like this:
 ///
 /// - Bottom: [`FullPrecisionStream`]: The core streaming index implementation.
diff --git a/diskann-benchmark/src/backend/index/search/knn.rs b/diskann-benchmark/src/backend/index/search/knn.rs
index 7385f4c307..4a399aae41 100644
--- a/diskann-benchmark/src/backend/index/search/knn.rs
+++ b/diskann-benchmark/src/backend/index/search/knn.rs
@@ -6,6 +6,7 @@
 use std::{num::NonZeroUsize, sync::Arc};
 
 use diskann_benchmark_core::recall::GroundTruthMode;
+use diskann_benchmark_core::search::Aggregate;
 use diskann_benchmark_core::{self as benchmark_core, search as core_search};
 
 use crate::{backend::index::result::SearchResults, inputs::graph_index::GraphSearch};
@@ -64,6 +65,64 @@ pub(crate) fn run<I>(
     Ok(all)
 }
 
+/// Run multi-hop searches with a freshly constructed searcher for every repetition and parameter.
+///
+/// This is required for query providers with lazy per-query state: reusing one `MultiHop`
+/// searcher would amortize that state across repetitions and search-L values.
+pub(crate) fn run_fresh_multihop<I, S, F>(
+    mut make_runner: F,
+    groundtruth: &dyn benchmark_core::recall::Rows<I>,
+    steps: SearchSteps<'_>,
+) -> anyhow::Result<Vec<SearchResults>>
+where
+    I: benchmark_core::recall::RecallCompatible,
+    S: core_search::Search<
+        Id = I,
+        Parameters = diskann::graph::search::Knn,
+        Output = core_search::graph::knn::Metrics,
+    >,
+    F: FnMut() -> anyhow::Result<Arc<S>>,
+{
+    let mut all = Vec::new();
+
+    for threads in steps.num_tasks.iter() {
+        for run in steps.runs.iter() {
+            for search_l in &run.search_l {
+                let parameters =
+                    diskann::graph::search::Knn::new(run.search_n, *search_l, None).unwrap();
+                let setup = core_search::Setup {
+                    threads: *threads,
+                    tasks: *threads,
+                    reps: steps.reps,
+                };
+                let runtime = benchmark_core::tokio::runtime((*threads).into())?;
+                let mut raw = Vec::with_capacity(steps.reps.get());
+
+                for _ in 0..steps.reps.get() {
+                    raw.push(core_search::search(
+                        make_runner()?,
+                        parameters,
+                        *threads,
+                        &runtime,
+                    )?);
+                }
+
+                let mut aggregator = core_search::graph::knn::Aggregator::new(
+                    groundtruth,
+                    run.recall_k,
+                    run.search_n,
+                    GroundTruthMode::Flexible,
+                );
+                let summary =
+                    aggregator.aggregate(core_search::Run::new(parameters, setup), raw)?;
+                all.push(SearchResults::new(summary));
+            }
+        }
+    }
+
+    Ok(all)
+}
+
 type Run = core_search::Run<diskann::graph::search::Knn>;
 pub(crate) trait Knn<I> {
     fn search_all(
diff --git a/diskann-benchmark/src/backend/index/search/plugins.rs b/diskann-benchmark/src/backend/index/search/plugins.rs
index 30f16cd460..339a3add84 100644
--- a/diskann-benchmark/src/backend/index/search/plugins.rs
+++ b/diskann-benchmark/src/backend/index/search/plugins.rs
@@ -208,3 +208,41 @@ impl TopkMultihopLiveFilterCsr {
         SearchPhaseKind::TopkMultihopLiveFilterCsr
     }
 }
+
+/// A multi-hop live-filter plugin that materializes the query's whole match set once (via roaring
+/// set-algebra over per-attribute posting lists) into a dense bitset, then answers each per-node
+/// match with an O(1) bit test. The materialization is timed as part of the query.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkMultihopLiveFilterBitmap;
+
+impl TopkMultihopLiveFilterBitmap {
+    /// Returns [`SearchPhaseKind::TopkMultihopLiveFilterBitmap`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkMultihopLiveFilterBitmap
+    }
+}
+
+/// A multi-hop live-filter plugin that adapts per query: it materializes the match set's roaring
+/// bitmap once, and (by cardinality) either densifies to a bitset (selective) or falls back to the
+/// CSR row-scan (broad) — aiming to win across all selectivities.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkMultihopLiveFilterAuto;
+
+impl TopkMultihopLiveFilterAuto {
+    /// Returns [`SearchPhaseKind::TopkMultihopLiveFilterAuto`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkMultihopLiveFilterAuto
+    }
+}
+
+/// A multi-hop live-filter plugin backed by per-attribute dense bitsets (bit-sliced), built at
+/// index time: `is_match` is one O(1) bit test per terminal with no per-query build.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkMultihopLiveFilterBitslice;
+
+impl TopkMultihopLiveFilterBitslice {
+    /// Returns [`SearchPhaseKind::TopkMultihopLiveFilterBitslice`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkMultihopLiveFilterBitslice
+    }
+}
diff --git a/diskann-benchmark/src/inputs/graph_index.rs b/diskann-benchmark/src/inputs/graph_index.rs
index dbbbe1b62c..0d83ff3f54 100644
--- a/diskann-benchmark/src/inputs/graph_index.rs
+++ b/diskann-benchmark/src/inputs/graph_index.rs
@@ -316,6 +316,9 @@ pub(crate) enum SearchPhase {
     TopkMultihopFilter(MultiHopSearchPhase),
     TopkMultihopLiveFilter(MultiHopSearchPhase),
     TopkMultihopLiveFilterCsr(MultiHopSearchPhase),
+    TopkMultihopLiveFilterBitmap(MultiHopSearchPhase),
+    TopkMultihopLiveFilterAuto(MultiHopSearchPhase),
+    TopkMultihopLiveFilterBitslice(MultiHopSearchPhase),
 }
 
 #[derive(Debug, Error)]
@@ -344,6 +347,11 @@ impl SearchPhase {
             Self::TopkMultihopFilter(_) => SearchPhaseKind::TopkMultihopFilter,
             Self::TopkMultihopLiveFilter(_) => SearchPhaseKind::TopkMultihopLiveFilter,
             Self::TopkMultihopLiveFilterCsr(_) => SearchPhaseKind::TopkMultihopLiveFilterCsr,
+            Self::TopkMultihopLiveFilterBitmap(_) => SearchPhaseKind::TopkMultihopLiveFilterBitmap,
+            Self::TopkMultihopLiveFilterAuto(_) => SearchPhaseKind::TopkMultihopLiveFilterAuto,
+            Self::TopkMultihopLiveFilterBitslice(_) => {
+                SearchPhaseKind::TopkMultihopLiveFilterBitslice
+            }
         }
     }
 
@@ -412,6 +420,42 @@ impl SearchPhase {
             )),
         }
     }
+
+    pub(crate) fn as_topk_multihop_live_filter_bitmap(
+        &self,
+    ) -> Result<&MultiHopSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkMultihopLiveFilterBitmap(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkMultihopLiveFilterBitmap,
+                self.kind(),
+            )),
+        }
+    }
+
+    pub(crate) fn as_topk_multihop_live_filter_auto(
+        &self,
+    ) -> Result<&MultiHopSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkMultihopLiveFilterAuto(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkMultihopLiveFilterAuto,
+                self.kind(),
+            )),
+        }
+    }
+
+    pub(crate) fn as_topk_multihop_live_filter_bitslice(
+        &self,
+    ) -> Result<&MultiHopSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkMultihopLiveFilterBitslice(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkMultihopLiveFilterBitslice,
+                self.kind(),
+            )),
+        }
+    }
 }
 
 impl SearchPhase {
@@ -423,6 +467,9 @@ impl SearchPhase {
             SearchPhase::TopkMultihopFilter(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopLiveFilter(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopLiveFilterCsr(phase) => phase.validate(checker),
+            SearchPhase::TopkMultihopLiveFilterBitmap(phase) => phase.validate(checker),
+            SearchPhase::TopkMultihopLiveFilterAuto(phase) => phase.validate(checker),
+            SearchPhase::TopkMultihopLiveFilterBitslice(phase) => phase.validate(checker),
         }
     }
 }
@@ -435,6 +482,9 @@ pub(crate) enum SearchPhaseKind {
     TopkMultihopFilter,
     TopkMultihopLiveFilter,
     TopkMultihopLiveFilterCsr,
+    TopkMultihopLiveFilterBitmap,
+    TopkMultihopLiveFilterAuto,
+    TopkMultihopLiveFilterBitslice,
 }
 
 impl SearchPhaseKind {
@@ -446,6 +496,9 @@ impl SearchPhaseKind {
             Self::TopkMultihopFilter => "topk-multihop-filter",
             Self::TopkMultihopLiveFilter => "topk-multihop-live-filter",
             Self::TopkMultihopLiveFilterCsr => "topk-multihop-live-filter-csr",
+            Self::TopkMultihopLiveFilterBitmap => "topk-multihop-live-filter-bitmap",
+            Self::TopkMultihopLiveFilterAuto => "topk-multihop-live-filter-auto",
+            Self::TopkMultihopLiveFilterBitslice => "topk-multihop-live-filter-bitslice",
         }
     }
 }
diff --git a/diskann-benchmark/src/utils/filters.rs b/diskann-benchmark/src/utils/filters.rs
index bf6240b5ed..51b2e057e5 100644
--- a/diskann-benchmark/src/utils/filters.rs
+++ b/diskann-benchmark/src/utils/filters.rs
@@ -24,8 +24,10 @@ use std::sync::Arc;
 
 use diskann_label_filter::attribute::Attribute;
 use diskann_label_filter::{
-    read_and_parse_queries, read_baselabels, FrozenAttributeIndex, FrozenAttributeIndexCsr,
-    InlineAttributeIndex, InlineAttributeIndexCsr,
+    read_and_parse_queries, read_baselabels, FrozenAttributeIndex, FrozenAttributeIndexAuto,
+    FrozenAttributeIndexBitslice, FrozenAttributeIndexCsr, FrozenAttributeIndexPosting,
+    InlineAttributeIndex, InlineAttributeIndexAuto, InlineAttributeIndexBitslice,
+    InlineAttributeIndexCsr, InlineAttributeIndexPosting,
 };
 
 pub struct QueryBitmapEvaluator {
@@ -122,6 +124,11 @@ pub(crate) fn as_query_label_provider(set: BitSet) -> Arc<dyn QueryLabelProvider
     Arc::new(BitmapFilter(set))
 }
 
+fn checked_doc_id(doc_id: usize) -> anyhow::Result<u32> {
+    u32::try_from(doc_id)
+        .map_err(|_| anyhow::anyhow!("document id {doc_id} exceeds the u32 graph-id range"))
+}
+
 /// Build an in-memory inline attribute index from a jsonl label file (one document per line).
 ///
 /// Each document's flattened `(field, value)` pairs are encoded to integer attribute-ids and
@@ -143,8 +150,9 @@ pub(crate) fn build_inline_attribute_index(
                 })?);
             }
         }
+        let doc_id = checked_doc_id(doc.doc_id)?;
         index
-            .insert_document(doc.doc_id as u32, &attrs)
+            .insert_document(doc_id, &attrs)
             .map_err(|e| anyhow::anyhow!("failed to insert document {}: {e:?}", doc.doc_id))?;
     }
     Ok(Arc::new(index.freeze()))
@@ -191,8 +199,9 @@ pub(crate) fn build_inline_attribute_index_csr(
                 })?);
             }
         }
+        let doc_id = checked_doc_id(doc.doc_id)?;
         index
-            .insert_document(doc.doc_id as u32, &attrs)
+            .insert_document(doc_id, &attrs)
             .map_err(|e| anyhow::anyhow!("failed to insert document {}: {e:?}", doc.doc_id))?;
     }
     Ok(Arc::new(index.freeze()))
@@ -217,6 +226,138 @@ pub(crate) fn make_live_providers_csr(
     Ok(providers)
 }
 
+/// Build an in-memory posting-list attribute index (one `RoaringBitmap` of vector-ids per
+/// attribute) from a jsonl label file. Same inputs/encoding as [`build_inline_attribute_index`];
+/// used by the materialized-bitmap live provider.
+pub(crate) fn build_inline_attribute_index_posting(
+    data_labels: &InputFile,
+) -> anyhow::Result<Arc<FrozenAttributeIndexPosting>> {
+    let docs = read_baselabels(data_labels.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to read base labels: {e}"))?;
+    let mut index = InlineAttributeIndexPosting::new();
+    let mut attrs: Vec<Attribute> = Vec::new();
+    for doc in &docs {
+        attrs.clear();
+        if let Some(obj) = doc.label.as_object() {
+            for (field, value) in obj {
+                attrs.push(Attribute::from_json_value(field, value).map_err(|e| {
+                    anyhow::anyhow!("attribute conversion failed for field '{field}': {e:?}")
+                })?);
+            }
+        }
+        let doc_id = checked_doc_id(doc.doc_id)?;
+        index
+            .insert_document(doc_id, &attrs)
+            .map_err(|e| anyhow::anyhow!("failed to insert document {}: {e:?}", doc.doc_id))?;
+    }
+    Ok(Arc::new(index.freeze()))
+}
+
+/// Parse per-query predicates and build one materialized-bitmap [`QueryLabelProvider`] per query,
+/// all sharing the same posting `index`. Mirrors [`make_live_providers`].
+pub(crate) fn make_live_providers_posting(
+    index: &FrozenAttributeIndexPosting,
+    query_predicates: &InputFile,
+) -> anyhow::Result<Vec<Arc<dyn QueryLabelProvider<u32>>>> {
+    let parsed = read_and_parse_queries(query_predicates.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to parse query predicates: {e}"))?;
+    let mut providers = Vec::with_capacity(parsed.len());
+    for (_query_id, ast) in parsed {
+        providers.push(
+            index
+                .make_provider(&ast)
+                .map_err(|e| anyhow::anyhow!("failed to build live provider: {e:?}"))?,
+        );
+    }
+    Ok(providers)
+}
+
+/// Build an in-memory adaptive (auto) attribute index (CSR + posting lists) from a jsonl label file.
+pub(crate) fn build_inline_attribute_index_auto(
+    data_labels: &InputFile,
+) -> anyhow::Result<Arc<FrozenAttributeIndexAuto>> {
+    let docs = read_baselabels(data_labels.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to read base labels: {e}"))?;
+    let mut index = InlineAttributeIndexAuto::new();
+    let mut attrs: Vec<Attribute> = Vec::new();
+    for doc in &docs {
+        attrs.clear();
+        if let Some(obj) = doc.label.as_object() {
+            for (field, value) in obj {
+                attrs.push(Attribute::from_json_value(field, value).map_err(|e| {
+                    anyhow::anyhow!("attribute conversion failed for field '{field}': {e:?}")
+                })?);
+            }
+        }
+        let doc_id = checked_doc_id(doc.doc_id)?;
+        index
+            .insert_document(doc_id, &attrs)
+            .map_err(|e| anyhow::anyhow!("failed to insert document {}: {e:?}", doc.doc_id))?;
+    }
+    Ok(Arc::new(index.freeze()))
+}
+
+/// Build one adaptive (auto) [`QueryLabelProvider`] per query. Mirrors [`make_live_providers`].
+pub(crate) fn make_live_providers_auto(
+    index: &FrozenAttributeIndexAuto,
+    query_predicates: &InputFile,
+) -> anyhow::Result<Vec<Arc<dyn QueryLabelProvider<u32>>>> {
+    let parsed = read_and_parse_queries(query_predicates.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to parse query predicates: {e}"))?;
+    let mut providers = Vec::with_capacity(parsed.len());
+    for (_query_id, ast) in parsed {
+        providers.push(
+            index
+                .make_provider(&ast)
+                .map_err(|e| anyhow::anyhow!("failed to build live provider: {e:?}"))?,
+        );
+    }
+    Ok(providers)
+}
+
+/// Build an in-memory bit-sliced attribute index (one dense bitset per attribute) from a jsonl file.
+pub(crate) fn build_inline_attribute_index_bitslice(
+    data_labels: &InputFile,
+) -> anyhow::Result<Arc<FrozenAttributeIndexBitslice>> {
+    let docs = read_baselabels(data_labels.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to read base labels: {e}"))?;
+    let mut index = InlineAttributeIndexBitslice::new();
+    let mut attrs: Vec<Attribute> = Vec::new();
+    for doc in &docs {
+        attrs.clear();
+        if let Some(obj) = doc.label.as_object() {
+            for (field, value) in obj {
+                attrs.push(Attribute::from_json_value(field, value).map_err(|e| {
+                    anyhow::anyhow!("attribute conversion failed for field '{field}': {e:?}")
+                })?);
+            }
+        }
+        let doc_id = checked_doc_id(doc.doc_id)?;
+        index
+            .insert_document(doc_id, &attrs)
+            .map_err(|e| anyhow::anyhow!("failed to insert document {}: {e:?}", doc.doc_id))?;
+    }
+    Ok(Arc::new(index.freeze()))
+}
+
+/// Build one bit-sliced [`QueryLabelProvider`] per query. Mirrors [`make_live_providers`].
+pub(crate) fn make_live_providers_bitslice(
+    index: &FrozenAttributeIndexBitslice,
+    query_predicates: &InputFile,
+) -> anyhow::Result<Vec<Arc<dyn QueryLabelProvider<u32>>>> {
+    let parsed = read_and_parse_queries(query_predicates.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to parse query predicates: {e}"))?;
+    let mut providers = Vec::with_capacity(parsed.len());
+    for (_query_id, ast) in parsed {
+        providers.push(
+            index
+                .make_provider(&ast)
+                .map_err(|e| anyhow::anyhow!("failed to build live provider: {e:?}"))?,
+        );
+    }
+    Ok(providers)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -252,4 +393,13 @@ mod tests {
         assert!(filter.is_match(1000u32));
         assert!(!filter.is_match(999u32));
     }
+
+    #[test]
+    fn test_checked_doc_id() {
+        assert_eq!(checked_doc_id(42).unwrap(), 42);
+        assert_eq!(checked_doc_id(u32::MAX as usize).unwrap(), u32::MAX);
+        if let Some(too_large) = (u32::MAX as usize).checked_add(1) {
+            assert!(checked_doc_id(too_large).is_err());
+        }
+    }
 }

From 6b102785f5ff9675cdc7680c4ad368c107cd5f07 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Tue, 28 Jul 2026 19:32:21 +0800
Subject: [PATCH 09/25] docs: compare optimized live filter strategies

Document the posting bitmap crossover and the adaptive and bit-sliced results, including latency, selectivity, and memory tradeoffs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../multiple_filter_test_report.md            | 45 +++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/diskann-benchmark/multiple_filter_test_report.md b/diskann-benchmark/multiple_filter_test_report.md
index 314e189b16..4cdcf2bb6d 100644
--- a/diskann-benchmark/multiple_filter_test_report.md
+++ b/diskann-benchmark/multiple_filter_test_report.md
@@ -226,6 +226,49 @@ A CSR-backed provider (`InlineAttributeIndexCsr` / `FrozenAttributeIndexCsr`) wa
 
 CSR gives a **3.4x (S1) - 4.4x (S4)** end-to-end latency/QPS improvement at equal recall, closing ~82-85% of the live-vs-precomputed-bitmap gap from section 8 while still evaluating the predicate live per node. The end-to-end factor is smaller than the ~15-20x on `is_match` alone because the ~13k vector-distance comparisons per query are unchanged and now dominate the remaining latency.
 
+## 8.2 Posting-list + materialized bitmap, and the selectivity crossover
+
+CSR still evaluates the predicate per visited node. The Lucene/Milvus/FAISS approach instead builds the query's whole match set **once** (roaring `AND`/`OR` over per-attribute posting lists) into a dense bitset, then answers each node with an `O(1)` bit test. `topk-multihop-live-filter-bitmap` (`InlineAttributeIndexPosting` / `MaterializedBitmapProvider`) implements this **live** — the match-set materialization is done lazily on the first `is_match`, so its cost is counted in query latency, not an offline pass. The benchmark reconstructs these lazy providers for every repetition and search-L run, preventing the materialized state from being reused across measurements.
+
+Three-way live comparison (same index, k=150, L=150, single thread, 1000 queries; recall identical within each case):
+
+| Case (sel.) | avg hops | live (roaring) | live-csr | live-bitmap |
+|---|---:|---:|---:|---:|
+| S1 (66.4%) | 1087 | 21.99 ms | **6.70 ms** | 51.44 ms |
+| S4 (10.0%) | 2492 | 79.74 ms | 17.98 ms | **17.18 ms** |
+| S8 (1.17%) | 4439 | 93.45 ms | 21.90 ms | **7.05 ms** |
+
+(p99, ms: S1 100.0 / 28.5 / 74.0; S4 207.6 / 47.4 / 26.5; S8 135.5 / 32.1 / 10.2.)
+
+There is a clean **selectivity crossover**:
+
+- The bitmap's per-query cost is dominated by **materializing the match set** (proportional to the number of matching ids). For a broad filter (S1, ~6.6M matches) this densify dominates and bitmap is the **worst** option (51 ms); for a selective filter (S8, ~117k matches) it is cheap and the `O(1)` per-node test wins decisively (**7.05 ms — 3.1x faster than CSR, 13x faster than roaring**).
+- Selective filters also **traverse more** (S8 avg hops 4439 vs S1 1087), so `is_match` is called far more often, further rewarding the bitmap's `O(1)` test / CSR's cheap row-scan and penalizing the roaring path.
+- CSR has **no per-query build** and a tiny per-node cost, so it is the **robust default**: 3.3-4.4x over roaring at every selectivity, best for broad, ~tied for mid.
+
+**Takeaway for live query latency:** no single per-node representation wins everywhere. A **selectivity-adaptive** provider is best — the posting-list index already knows `|match set|` cheaply (roaring cardinality, before any densify), so it can pick **bitmap when selective, CSR when broad**, yielding the best cell of each row (S1→CSR 6.70, S4/S8→bitmap 17.18/7.05 ms): up to **13x** over the roaring baseline for selective filters and **3.3x** for broad, all live.
+
+_Caveat: the bitmap build is per distinct query predicate. In this benchmark all queries share one predicate, so a system that caches the match set per predicate would amortize the broad-filter build; the numbers above are the honest cost for a unique-per-query predicate._
+
+## 8.3 Two "win everywhere" methods: adaptive (auto) and bit-sliced
+
+Section 8.2's bitmap/CSR winner flips with selectivity. Two methods remove that weakness. `topk-multihop-live-filter-auto` (`InlineAttributeIndexAuto`) builds the cheap roaring match set once, reads its cardinality for free, then densifies to a bitset when selective or falls back to the CSR row-scan when broad. `topk-multihop-live-filter-bitslice` (`InlineAttributeIndexBitslice`) precomputes **one dense bitset per attribute at index time**, so `is_match` is one `O(1)` bit test per equality terminal with **no** per-query build.
+
+Full live comparison (same index, k=150, L=150, single thread, 1000 queries; recall identical per case). live-roaring from section 8.2 shown for reference:
+
+| Case (sel.) | avg hops | roaring | csr | bitmap | auto | bitslice |
+|---|---:|---:|---:|---:|---:|---:|
+| S1 (66.4%) | 1087 | 21.99 | 5.64 | 49.39 | 6.27 | **3.18** |
+| S4 (10.0%) | 2492 | 79.74 | 18.38 | 17.38 | 17.36 | **6.61** |
+| S8 (1.17%) | 4439 | 93.45 | 22.45 | 7.08 | 7.06 | **6.39** |
+
+(mean ms; p99 ms — S1: csr 21.6 / bitmap 56.9 / auto 24.6 / bitslice 11.5; S4: 46.9 / 22.9 / 22.9 / 17.7; S8: 32.3 / 10.5 / 9.9 / 9.5.)
+
+- **Bit-sliced wins outright in every case** (3.18 / 6.61 / 6.39 ms): 1.8-3.5x over CSR and 6.9-14.6x over roaring, fastest mean *and* p99. Because the per-attribute bitsets are built once at index time, a single-term filter costs exactly one `O(1)` bit test per node — it even edges the section-8 precomputed-bitmap "ideal", built legitimately and amortized over all queries. Its cost is **memory**: `num_attributes * ceil(N/64) * 8` bytes (~14 MB for the 11 labels here, ~745 MB for the full 596-label vocabulary, infeasible for high-cardinality labels).
+- **Auto is the robust, memory-light alternative**: it dispatched S1->CSR, S4/S8->bitmap and thus **matched the better of {csr, bitmap} in every case** (never the worst) using the free match-set cardinality — no per-attribute bitset matrix required.
+
+**Bottom line for live query latency:** if the label vocabulary is modest, **bit-sliced per-attribute bitsets win across all selectivities**; otherwise **auto** (adaptive bitmap<->CSR) reliably takes the better of the two base methods. Both keep recall identical and evaluate the filter fully live.
+
 ## 9. Artifacts (`Q:\test6\filtered_test2\bench\full\`)
 
 - Labels: `data_labels_set.jsonl` (596 labels, general), `data_labels_min.jsonl` (11, fast)
@@ -236,6 +279,8 @@ CSR gives a **3.4x (S1) - 4.4x (S4)** end-to-end latency/QPS improvement at equa
 - Encoders: `gen_setmembership.py` (full), `gen_setmin.py` (minimal)
 - Live-filter code: `diskann-label-filter/src/live_filter.rs` (InlineAttributeIndex / FrozenAttributeIndex + QueryLabelProvider); benchmark search-type `topk-multihop-live-filter`
 - CSR live-filter code (section 8.1): `InlineAttributeIndexCsr` / `FrozenAttributeIndexCsr` in the same module; benchmark search-type `topk-multihop-live-filter-csr`; is_match microbenchmark `diskann-label-filter/benches/benchmarks/live_filter_bench.rs`
+- Posting-list + materialized-bitmap live code (section 8.2): `InlineAttributeIndexPosting` / `FrozenAttributeIndexPosting` / `MaterializedBitmapProvider`; benchmark search-type `topk-multihop-live-filter-bitmap`
+- Adaptive + bit-sliced live code (section 8.3): `InlineAttributeIndexAuto` (search-type `topk-multihop-live-filter-auto`) and `InlineAttributeIndexBitslice` (search-type `topk-multihop-live-filter-bitslice`)
 - Index (reused): `idxsave_full`(+`.data`)
 
 _Note: an earlier version of this report used a single-valued `geo` string field; it is superseded by the set-membership results above._
\ No newline at end of file

From 8eb344cdd2d890ab2e61740155138d3f33c149f8 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Thu, 6 Aug 2026 18:03:50 +0800
Subject: [PATCH 10/25] diskann-label-filter: add flat bitslice DNF evaluation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../benches/benchmarks/live_filter_bench.rs   |  59 ++++-
 diskann-label-filter/src/live_filter.rs       | 212 ++++++++++++++++++
 2 files changed, 268 insertions(+), 3 deletions(-)

diff --git a/diskann-label-filter/benches/benchmarks/live_filter_bench.rs b/diskann-label-filter/benches/benchmarks/live_filter_bench.rs
index b2ae4b0e13..d01810f7b0 100644
--- a/diskann-label-filter/benches/benchmarks/live_filter_bench.rs
+++ b/diskann-label-filter/benches/benchmarks/live_filter_bench.rs
@@ -5,7 +5,7 @@
 
 //! Microbenchmark isolating the per-node `is_match` cost of live filter matching.
 //!
-//! It compares three representations of the *same* corpus of per-document attribute
+//! It compares multiple representations of the *same* corpus of per-document attribute
 //! sets, evaluating the *same* predicate over the *same* probed node ids:
 //!
 //! * `treemap`  — the current production path: [`InlineAttributeIndex`]
@@ -16,7 +16,7 @@
 //! * `posting`  — one `RoaringBitmap` per attribute id (the doc-ids carrying it):
 //!   a match is an `AND`/`OR` of `posting[term].contains(node)`.
 //!
-//! Before timing, all three are asserted to agree on every probe, so the benchmark
+//! Before timing, all representations are asserted to agree on every probe, so the benchmark
 //! measures only *how* the match decision is computed, not *what* it decides.
 //!
 //! Tunables (env): `LF_BENCH_N` corpus size (default 1_000_000),
@@ -25,7 +25,9 @@
 use criterion::{criterion_group, Criterion, Throughput};
 use diskann::graph::index::QueryLabelProvider;
 use diskann_label_filter::attribute::Attribute;
-use diskann_label_filter::{ASTExpr, CompareOp, InlineAttributeIndex};
+use diskann_label_filter::{
+    ASTExpr, CompareOp, InlineAttributeIndex, InlineAttributeIndexBitslice,
+};
 use rand::rngs::StdRng;
 use rand::{Rng, SeedableRng};
 use roaring::RoaringBitmap;
@@ -138,6 +140,20 @@ fn build_treemap(corpus: &[Vec<u16>]) -> InlineAttributeIndex {
     index
 }
 
+fn build_bitslice(corpus: &[Vec<u16>]) -> InlineAttributeIndexBitslice {
+    let attr_cache: Vec<Attribute> = (0..VOCAB)
+        .map(|id| Attribute::from_json_value(&format!("L{id}"), &json!(true)).unwrap())
+        .collect();
+    let mut index = InlineAttributeIndexBitslice::new();
+    let mut scratch: Vec<Attribute> = Vec::new();
+    for (doc, attrs) in corpus.iter().enumerate() {
+        scratch.clear();
+        scratch.extend(attrs.iter().map(|&id| attr_cache[id as usize].clone()));
+        index.insert_document(doc as u32, &scratch).unwrap();
+    }
+    index
+}
+
 fn bench_live_filter(c: &mut Criterion) {
     let n: usize = std::env::var("LF_BENCH_N")
         .ok()
@@ -153,6 +169,7 @@ fn bench_live_filter(c: &mut Criterion) {
     let (offsets, values) = build_csr(&corpus);
     let posting = build_posting(&corpus);
     let frozen = build_treemap(&corpus).freeze();
+    let frozen_bitslice = build_bitslice(&corpus).freeze();
 
     // Random node ids mimic the data-dependent traversal order (defeats prefetching).
     let probes: Vec<u32> = (0..num_probes)
@@ -174,11 +191,15 @@ fn bench_live_filter(c: &mut Criterion) {
     for (name, pred) in &predicates {
         let ast = pred.to_ast();
         let provider: Arc<dyn QueryLabelProvider<u32>> = frozen.make_provider(&ast).unwrap();
+        let bitslice_recursive = frozen_bitslice.make_provider(&ast).unwrap();
+        let bitslice_dnf = frozen_bitslice.make_dnf_provider(&ast).unwrap();
 
         // Correctness gate: all three representations must agree on every probe.
         let mut match_count = 0usize;
         for &node in &probes {
             let treemap_hit = provider.is_match(node);
+            let recursive_hit = bitslice_recursive.is_match(node);
+            let dnf_hit = bitslice_dnf.is_match(node);
             let start = offsets[node as usize] as usize;
             let end = offsets[node as usize + 1] as usize;
             let csr_hit = pred.eval_csr(&values[start..end]);
@@ -191,6 +212,14 @@ fn bench_live_filter(c: &mut Criterion) {
                 treemap_hit, posting_hit,
                 "treemap vs posting disagree ({name}, node {node})"
             );
+            assert_eq!(
+                treemap_hit, recursive_hit,
+                "treemap vs recursive bitslice disagree ({name}, node {node})"
+            );
+            assert_eq!(
+                treemap_hit, dnf_hit,
+                "treemap vs DNF bitslice disagree ({name}, node {node})"
+            );
             if treemap_hit {
                 match_count += 1;
             }
@@ -242,6 +271,30 @@ fn bench_live_filter(c: &mut Criterion) {
             })
         });
 
+        group.bench_function(format!("bitslice_recursive[{sel_tag}]"), |b| {
+            b.iter(|| {
+                let mut hits = 0u64;
+                for &node in &probes {
+                    if bitslice_recursive.is_match(black_box(node)) {
+                        hits += 1;
+                    }
+                }
+                black_box(hits)
+            })
+        });
+
+        group.bench_function(format!("bitslice_dnf[{sel_tag}]"), |b| {
+            b.iter(|| {
+                let mut hits = 0u64;
+                for &node in &probes {
+                    if bitslice_dnf.is_match(black_box(node)) {
+                        hits += 1;
+                    }
+                }
+                black_box(hits)
+            })
+        });
+
         group.finish();
     }
 }
diff --git a/diskann-label-filter/src/live_filter.rs b/diskann-label-filter/src/live_filter.rs
index ced737e70e..040b8f13b5 100644
--- a/diskann-label-filter/src/live_filter.rs
+++ b/diskann-label-filter/src/live_filter.rs
@@ -820,6 +820,36 @@ impl FrozenAttributeIndexBitslice {
             num_vectors: self.num_vectors,
         }))
     }
+
+    /// Build a provider using a flat disjunctive-normal-form representation.
+    ///
+    /// Accepted expressions are a terminal, an AND of terminals, or an OR whose children are
+    /// terminals or ANDs of terminals. Associatively nested AND and OR groups are flattened.
+    /// Expressions such as `(A OR B) AND (C OR D)` must be normalized before provider
+    /// construction.
+    ///
+    /// # Errors
+    /// Returns an error if the expression is unsupported, references an unknown attribute, or is
+    /// not already in the accepted DNF shape.
+    pub fn make_dnf_provider(&self, ast: &ASTExpr) -> ANNResult<Arc<dyn QueryLabelProvider<u32>>> {
+        ensure_and_or_only(ast)?;
+        let encoded = EncodedFilterExpr::new(ast, self.attribute_map.clone())?;
+        let dnf = EncodedDnf::new(encoded.encoded_filter_expr(), self.bitsets.len())?;
+
+        if let Some(attribute_id) = dnf.single_attribute() {
+            Ok(Arc::new(BitsliceSingleProvider {
+                attribute_id,
+                bitsets: self.bitsets.clone(),
+                num_vectors: self.num_vectors,
+            }))
+        } else {
+            Ok(Arc::new(BitsliceDnfProvider {
+                dnf,
+                bitsets: self.bitsets.clone(),
+                num_vectors: self.num_vectors,
+            }))
+        }
+    }
 }
 
 /// A [`QueryLabelProvider`] that evaluates the predicate as one `O(1)` bit test per terminal against
@@ -879,6 +909,159 @@ impl ASTIdExprVisitor<u64> for BitsliceEvaluator<'_> {
     }
 }
 
+/// A flat OR-of-ANDs expression.
+///
+/// Clause `i` occupies `attributes[clause_offsets[i]..clause_offsets[i + 1]]`.
+struct EncodedDnf {
+    clause_offsets: Box<[usize]>,
+    attributes: Box<[usize]>,
+}
+
+impl EncodedDnf {
+    fn new(expr: &ASTIdExpr<u64>, num_attributes: usize) -> ANNResult<Self> {
+        let mut clause_offsets = vec![0usize];
+        let mut attributes = Vec::new();
+
+        Self::append_disjunction(expr, num_attributes, &mut clause_offsets, &mut attributes)?;
+
+        Ok(Self {
+            clause_offsets: clause_offsets.into_boxed_slice(),
+            attributes: attributes.into_boxed_slice(),
+        })
+    }
+
+    fn append_disjunction(
+        expr: &ASTIdExpr<u64>,
+        num_attributes: usize,
+        clause_offsets: &mut Vec<usize>,
+        attributes: &mut Vec<usize>,
+    ) -> ANNResult<()> {
+        match expr {
+            ASTIdExpr::Terminal(_) | ASTIdExpr::And(_) => {
+                let start = attributes.len();
+                Self::append_conjunction(expr, num_attributes, attributes)?;
+                if attributes.len() == start {
+                    return Err(Self::shape_error());
+                }
+                clause_offsets.push(attributes.len());
+            }
+            ASTIdExpr::Or(clauses) => {
+                if clauses.is_empty() {
+                    return Err(Self::shape_error());
+                }
+                for clause in clauses {
+                    Self::append_disjunction(clause, num_attributes, clause_offsets, attributes)?;
+                }
+            }
+            ASTIdExpr::Not(_) => return Err(Self::shape_error()),
+        }
+
+        Ok(())
+    }
+
+    fn append_conjunction(
+        expr: &ASTIdExpr<u64>,
+        num_attributes: usize,
+        attributes: &mut Vec<usize>,
+    ) -> ANNResult<()> {
+        match expr {
+            ASTIdExpr::Terminal(id) => {
+                attributes.push(Self::attribute_index(*id, num_attributes)?);
+            }
+            ASTIdExpr::And(terms) => {
+                if terms.is_empty() {
+                    return Err(Self::shape_error());
+                }
+                for term in terms {
+                    Self::append_conjunction(term, num_attributes, attributes)?;
+                }
+            }
+            ASTIdExpr::Or(_) | ASTIdExpr::Not(_) => return Err(Self::shape_error()),
+        }
+
+        Ok(())
+    }
+
+    fn attribute_index(id: u64, num_attributes: usize) -> ANNResult<usize> {
+        let index = usize::try_from(id).map_err(|_| Self::shape_error())?;
+        if index >= num_attributes {
+            return Err(ANNError::message(
+                ANNErrorKind::Opaque,
+                format!("encoded attribute id {id} is outside the bit-slice index"),
+            ));
+        }
+        Ok(index)
+    }
+
+    fn single_attribute(&self) -> Option<usize> {
+        (self.clause_offsets.len() == 2 && self.attributes.len() == 1).then_some(self.attributes[0])
+    }
+
+    fn shape_error() -> ANNError {
+        ANNError::message(
+            ANNErrorKind::Opaque,
+            "bit-slice DNF requires a terminal, an AND of terminals, or an OR of terminal/AND clauses",
+        )
+    }
+}
+
+/// Specialized query provider for the common single-terminal predicate.
+struct BitsliceSingleProvider {
+    attribute_id: usize,
+    bitsets: Arc<[Box<[u64]>]>,
+    num_vectors: u32,
+}
+
+impl std::fmt::Debug for BitsliceSingleProvider {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("BitsliceSingleProvider").finish()
+    }
+}
+
+impl QueryLabelProvider<u32> for BitsliceSingleProvider {
+    fn is_match(&self, vec_id: u32) -> bool {
+        vec_id < self.num_vectors && dense_contains(&self.bitsets[self.attribute_id], vec_id)
+    }
+}
+
+/// Query provider that evaluates a flat OR of AND clauses without recursive AST traversal.
+struct BitsliceDnfProvider {
+    dnf: EncodedDnf,
+    bitsets: Arc<[Box<[u64]>]>,
+    num_vectors: u32,
+}
+
+impl std::fmt::Debug for BitsliceDnfProvider {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("BitsliceDnfProvider").finish()
+    }
+}
+
+impl QueryLabelProvider<u32> for BitsliceDnfProvider {
+    fn is_match(&self, vec_id: u32) -> bool {
+        if vec_id >= self.num_vectors {
+            return false;
+        }
+
+        let bit_index = vec_id as usize;
+        let word_index = bit_index / 64;
+        let mask = 1u64 << (bit_index % 64);
+
+        for clause in self.dnf.clause_offsets.windows(2) {
+            let start = clause[0];
+            let end = clause[1];
+            let matches = self.dnf.attributes[start..end]
+                .iter()
+                .all(|&attribute_id| self.bitsets[attribute_id][word_index] & mask != 0);
+            if matches {
+                return true;
+            }
+        }
+
+        false
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1144,6 +1327,10 @@ mod tests {
                 ASTExpr::And(vec![eq_true("A"), eq_true("B")]),
                 eq_true("C"),
             ]),
+            ASTExpr::Or(vec![
+                ASTExpr::And(vec![eq_true("A"), ASTExpr::And(vec![eq_true("B")])]),
+                ASTExpr::Or(vec![eq_true("C")]),
+            ]),
         ];
         for ast in &asts {
             let rp = roaring.make_provider(ast).unwrap();
@@ -1152,6 +1339,7 @@ mod tests {
                 posting.make_provider(ast).unwrap(),
                 auto.make_provider(ast).unwrap(),
                 bitslice.make_provider(ast).unwrap(),
+                bitslice.make_dnf_provider(ast).unwrap(),
             ];
             for id in 0..7u32 {
                 let expected = rp.is_match(id);
@@ -1178,4 +1366,28 @@ mod tests {
         let mut bitslice = InlineAttributeIndexBitslice::new();
         assert!(bitslice.insert_document(u32::MAX, &attrs).is_err());
     }
+
+    #[test]
+    fn bitslice_dnf_rejects_and_of_or_clauses() {
+        let mut index = InlineAttributeIndexBitslice::new();
+        index
+            .insert_document(
+                0,
+                &[
+                    attr("A", true),
+                    attr("B", true),
+                    attr("C", true),
+                    attr("D", true),
+                ],
+            )
+            .unwrap();
+        let index = index.freeze();
+        let ast = ASTExpr::And(vec![
+            ASTExpr::Or(vec![eq_true("A"), eq_true("B")]),
+            ASTExpr::Or(vec![eq_true("C"), eq_true("D")]),
+        ]);
+
+        assert!(index.make_provider(&ast).is_ok());
+        assert!(index.make_dnf_provider(&ast).is_err());
+    }
 }

From 9b77d7ee6b55a93ed3b6acb20a1ba9ce8417959f Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Thu, 6 Aug 2026 18:04:02 +0800
Subject: [PATCH 11/25] diskann-benchmark: add bitslice DNF search mode

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../src/backend/index/benchmarks.rs           | 59 ++++++++++++++++++-
 .../src/backend/index/search/plugins.rs       | 11 ++++
 diskann-benchmark/src/inputs/graph_index.rs   | 19 ++++++
 diskann-benchmark/src/utils/filters.rs        | 19 ++++++
 4 files changed, 107 insertions(+), 1 deletion(-)

diff --git a/diskann-benchmark/src/backend/index/benchmarks.rs b/diskann-benchmark/src/backend/index/benchmarks.rs
index ffab2eec1b..7d9673b889 100644
--- a/diskann-benchmark/src/backend/index/benchmarks.rs
+++ b/diskann-benchmark/src/backend/index/benchmarks.rs
@@ -81,7 +81,8 @@ pub(super) fn register_benchmarks(registry: &mut Registry) -> anyhow::Result<()>
             .search(plugins::TopkMultihopLiveFilterCsr)
             .search(plugins::TopkMultihopLiveFilterBitmap)
             .search(plugins::TopkMultihopLiveFilterAuto)
-            .search(plugins::TopkMultihopLiveFilterBitslice),
+            .search(plugins::TopkMultihopLiveFilterBitslice)
+            .search(plugins::TopkMultihopLiveFilterBitsliceDnf),
     )?;
 
     registry.register(
@@ -918,6 +919,62 @@ where
         Ok(AggregatedSearchResults::Topk(result))
     }
 }
+
+//------------------------------------//
+// MultihopLiveFilter (Bitslice DNF)   //
+//------------------------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>>
+    for plugins::TopkMultihopLiveFilterBitsliceDnf
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<DP, &'a [DP::Element]> + Clone + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        let multihop = phase.as_topk_multihop_live_filter_bitslice_dnf()?;
+
+        let queries: Arc<Matrix<DP::Element>> = Arc::new(datafiles::load_dataset(
+            datafiles::BinFile(&multihop.queries),
+        )?);
+
+        let groundtruth =
+            datafiles::load_range_groundtruth(datafiles::BinFile(&multihop.groundtruth))?;
+
+        let steps =
+            search::knn::SearchSteps::new(multihop.reps, &multihop.num_threads, &multihop.runs);
+
+        let attribute_index =
+            utils::filters::build_inline_attribute_index_bitslice(&multihop.data_labels)?;
+        let providers = utils::filters::make_live_providers_bitslice_dnf(
+            &attribute_index,
+            &multihop.query_predicates,
+        )?;
+
+        let multihop = benchmark_core::search::graph::MultiHop::new(
+            index,
+            queries,
+            benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
+            providers.into(),
+        )?;
+
+        let result = search::knn::run(&multihop, &groundtruth, steps)?;
+        Ok(AggregatedSearchResults::Topk(result))
+    }
+}
+
 /// The stack looks like this:
 ///
 /// - Bottom: [`FullPrecisionStream`]: The core streaming index implementation.
diff --git a/diskann-benchmark/src/backend/index/search/plugins.rs b/diskann-benchmark/src/backend/index/search/plugins.rs
index 339a3add84..6edbfcee2d 100644
--- a/diskann-benchmark/src/backend/index/search/plugins.rs
+++ b/diskann-benchmark/src/backend/index/search/plugins.rs
@@ -246,3 +246,14 @@ impl TopkMultihopLiveFilterBitslice {
         SearchPhaseKind::TopkMultihopLiveFilterBitslice
     }
 }
+
+/// A multi-hop live-filter plugin backed by bit slices and a flat OR-of-AND query plan.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkMultihopLiveFilterBitsliceDnf;
+
+impl TopkMultihopLiveFilterBitsliceDnf {
+    /// Returns [`SearchPhaseKind::TopkMultihopLiveFilterBitsliceDnf`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkMultihopLiveFilterBitsliceDnf
+    }
+}
diff --git a/diskann-benchmark/src/inputs/graph_index.rs b/diskann-benchmark/src/inputs/graph_index.rs
index 0d83ff3f54..1997120649 100644
--- a/diskann-benchmark/src/inputs/graph_index.rs
+++ b/diskann-benchmark/src/inputs/graph_index.rs
@@ -319,6 +319,7 @@ pub(crate) enum SearchPhase {
     TopkMultihopLiveFilterBitmap(MultiHopSearchPhase),
     TopkMultihopLiveFilterAuto(MultiHopSearchPhase),
     TopkMultihopLiveFilterBitslice(MultiHopSearchPhase),
+    TopkMultihopLiveFilterBitsliceDnf(MultiHopSearchPhase),
 }
 
 #[derive(Debug, Error)]
@@ -352,6 +353,9 @@ impl SearchPhase {
             Self::TopkMultihopLiveFilterBitslice(_) => {
                 SearchPhaseKind::TopkMultihopLiveFilterBitslice
             }
+            Self::TopkMultihopLiveFilterBitsliceDnf(_) => {
+                SearchPhaseKind::TopkMultihopLiveFilterBitsliceDnf
+            }
         }
     }
 
@@ -456,6 +460,18 @@ impl SearchPhase {
             )),
         }
     }
+
+    pub(crate) fn as_topk_multihop_live_filter_bitslice_dnf(
+        &self,
+    ) -> Result<&MultiHopSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkMultihopLiveFilterBitsliceDnf(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkMultihopLiveFilterBitsliceDnf,
+                self.kind(),
+            )),
+        }
+    }
 }
 
 impl SearchPhase {
@@ -470,6 +486,7 @@ impl SearchPhase {
             SearchPhase::TopkMultihopLiveFilterBitmap(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopLiveFilterAuto(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopLiveFilterBitslice(phase) => phase.validate(checker),
+            SearchPhase::TopkMultihopLiveFilterBitsliceDnf(phase) => phase.validate(checker),
         }
     }
 }
@@ -485,6 +502,7 @@ pub(crate) enum SearchPhaseKind {
     TopkMultihopLiveFilterBitmap,
     TopkMultihopLiveFilterAuto,
     TopkMultihopLiveFilterBitslice,
+    TopkMultihopLiveFilterBitsliceDnf,
 }
 
 impl SearchPhaseKind {
@@ -499,6 +517,7 @@ impl SearchPhaseKind {
             Self::TopkMultihopLiveFilterBitmap => "topk-multihop-live-filter-bitmap",
             Self::TopkMultihopLiveFilterAuto => "topk-multihop-live-filter-auto",
             Self::TopkMultihopLiveFilterBitslice => "topk-multihop-live-filter-bitslice",
+            Self::TopkMultihopLiveFilterBitsliceDnf => "topk-multihop-live-filter-bitslice-dnf",
         }
     }
 }
diff --git a/diskann-benchmark/src/utils/filters.rs b/diskann-benchmark/src/utils/filters.rs
index 51b2e057e5..c50eaa10d9 100644
--- a/diskann-benchmark/src/utils/filters.rs
+++ b/diskann-benchmark/src/utils/filters.rs
@@ -337,6 +337,7 @@ pub(crate) fn build_inline_attribute_index_bitslice(
             .insert_document(doc_id, &attrs)
             .map_err(|e| anyhow::anyhow!("failed to insert document {}: {e:?}", doc.doc_id))?;
     }
+    drop(docs);
     Ok(Arc::new(index.freeze()))
 }
 
@@ -358,6 +359,24 @@ pub(crate) fn make_live_providers_bitslice(
     Ok(providers)
 }
 
+/// Build one flat-DNF bit-sliced [`QueryLabelProvider`] per query.
+pub(crate) fn make_live_providers_bitslice_dnf(
+    index: &FrozenAttributeIndexBitslice,
+    query_predicates: &InputFile,
+) -> anyhow::Result<Vec<Arc<dyn QueryLabelProvider<u32>>>> {
+    let parsed = read_and_parse_queries(query_predicates.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to parse query predicates: {e}"))?;
+    let mut providers = Vec::with_capacity(parsed.len());
+    for (_query_id, ast) in parsed {
+        providers.push(
+            index
+                .make_dnf_provider(&ast)
+                .map_err(|e| anyhow::anyhow!("failed to build DNF live provider: {e:?}"))?,
+        );
+    }
+    Ok(providers)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

From f4b0b33a60cd18970303776fbfd2b9bb270bf973 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Thu, 6 Aug 2026 18:04:12 +0800
Subject: [PATCH 12/25] diskann: reuse scratch in multihop expansion

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../provider/async_/inmem/full_precision.rs   | 17 ++++++-
 diskann/src/graph/glue.rs                     | 48 +++++++++++++++++--
 diskann/src/graph/search/multihop_search.rs   | 17 ++++---
 3 files changed, 72 insertions(+), 10 deletions(-)

diff --git a/diskann-providers/src/model/graph/provider/async_/inmem/full_precision.rs b/diskann-providers/src/model/graph/provider/async_/inmem/full_precision.rs
index e72f323efb..1598fcb393 100644
--- a/diskann-providers/src/model/graph/provider/async_/inmem/full_precision.rs
+++ b/diskann-providers/src/model/graph/provider/async_/inmem/full_precision.rs
@@ -10,7 +10,7 @@ use diskann::{
     ANNError, ANNResult,
     error::Infallible,
     graph::{
-        SearchOutputBuffer,
+        AdjacencyList, SearchOutputBuffer,
         glue::{
             self, DefaultPostProcessor, ExpandBeam, InplaceDeleteStrategy, InsertStrategy,
             PruneStrategy, SearchExt, SearchStrategy,
@@ -314,6 +314,21 @@ where
     D: AsyncFriendly,
     Ctx: ExecutionContext,
 {
+    fn expand_beam_with_scratch<Itr, P, F>(
+        &mut self,
+        ids: Itr,
+        computer: &Self::QueryComputer,
+        neighbors: &mut AdjacencyList<Self::Id>,
+        pred: P,
+        on_neighbors: F,
+    ) -> impl Future<Output = ANNResult<()>> + Send
+    where
+        Itr: Iterator<Item = Self::Id> + Send,
+        P: glue::HybridPredicate<Self::Id> + Send + Sync,
+        F: FnMut(f32, Self::Id) + Send,
+    {
+        self.expand_beam_default_with_scratch(ids, computer, neighbors, pred, on_neighbors)
+    }
 }
 
 //-------------------//
diff --git a/diskann/src/graph/glue.rs b/diskann/src/graph/glue.rs
index 5e691d515b..6e41fe71bf 100644
--- a/diskann/src/graph/glue.rs
+++ b/diskann/src/graph/glue.rs
@@ -252,10 +252,12 @@ impl<T> HybridPredicate<T> for NotInMut<'_, T> where T: Clone + Eq + std::hash::
 ///
 /// Transient errors yielded by `distances_unordered` are acknowledged and not escalated.
 pub trait ExpandBeam<T>: BuildQueryComputer<T> + AsNeighbor + Sized {
-    fn expand_beam<Itr, P, F>(
+    /// Run the provided beam-expansion implementation with a reusable adjacency-list buffer.
+    fn expand_beam_default_with_scratch<Itr, P, F>(
         &mut self,
         ids: Itr,
         computer: &Self::QueryComputer,
+        neighbors: &mut AdjacencyList<Self::Id>,
         mut pred: P,
         mut on_neighbors: F,
     ) -> impl std::future::Future<Output = ANNResult<()>> + Send
@@ -265,9 +267,8 @@ pub trait ExpandBeam<T>: BuildQueryComputer<T> + AsNeighbor + Sized {
         F: FnMut(f32, Self::Id) + Send,
     {
         async move {
-            let mut neighbors = AdjacencyList::new();
             for id in ids {
-                self.get_neighbors(id, &mut neighbors).send().await?;
+                self.get_neighbors(id, neighbors).send().await?;
                 neighbors.retain(|i| pred.eval(i));
 
                 self.distances_unordered(neighbors.iter().copied(), computer, |distance, id| {
@@ -283,6 +284,47 @@ pub trait ExpandBeam<T>: BuildQueryComputer<T> + AsNeighbor + Sized {
             Ok(())
         }
     }
+
+    /// Expand a beam while allowing the caller to provide reusable scratch storage.
+    ///
+    /// The default delegates to [`Self::expand_beam`] so specialized provider overrides retain
+    /// their I/O, batching, and accounting semantics. Providers using the default implementation
+    /// may override this method and call [`Self::expand_beam_default_with_scratch`] to reuse
+    /// `neighbors`.
+    fn expand_beam_with_scratch<Itr, P, F>(
+        &mut self,
+        ids: Itr,
+        computer: &Self::QueryComputer,
+        _neighbors: &mut AdjacencyList<Self::Id>,
+        pred: P,
+        on_neighbors: F,
+    ) -> impl std::future::Future<Output = ANNResult<()>> + Send
+    where
+        Itr: Iterator<Item = Self::Id> + Send,
+        P: HybridPredicate<Self::Id> + Send + Sync,
+        F: FnMut(f32, Self::Id) + Send,
+    {
+        async move { self.expand_beam(ids, computer, pred, on_neighbors).await }
+    }
+
+    fn expand_beam<Itr, P, F>(
+        &mut self,
+        ids: Itr,
+        computer: &Self::QueryComputer,
+        pred: P,
+        on_neighbors: F,
+    ) -> impl std::future::Future<Output = ANNResult<()>> + Send
+    where
+        Itr: Iterator<Item = Self::Id> + Send,
+        P: HybridPredicate<Self::Id> + Send + Sync,
+        F: FnMut(f32, Self::Id) + Send,
+    {
+        async move {
+            let mut neighbors = AdjacencyList::new();
+            self.expand_beam_default_with_scratch(ids, computer, &mut neighbors, pred, on_neighbors)
+                .await
+        }
+    }
 }
 
 /// A search strategy for query objects of type `T`.
diff --git a/diskann/src/graph/search/multihop_search.rs b/diskann/src/graph/search/multihop_search.rs
index 8ed36b53ce..52e0f0a959 100644
--- a/diskann/src/graph/search/multihop_search.rs
+++ b/diskann/src/graph/search/multihop_search.rs
@@ -15,6 +15,7 @@ use crate::{
     ANNResult,
     error::{ErrorExt, IntoANNResult},
     graph::{
+        AdjacencyList,
         glue::{
             self, ExpandBeam, HybridPredicate, Predicate, PredicateMut, SearchExt,
             SearchPostProcess, SearchStrategy,
@@ -214,6 +215,7 @@ where
     let mut one_hop_neighbors = Vec::with_capacity(max_degree_with_slack);
     let mut two_hop_neighbors = Vec::with_capacity(max_degree_with_slack);
     let mut candidates_two_hop_expansion = Vec::with_capacity(max_degree_with_slack);
+    let mut adjacency_scratch = AdjacencyList::with_capacity(max_degree_with_slack);
 
     while scratch.best.has_notvisited_node() && !accessor.terminate_early() {
         scratch.beam_nodes.clear();
@@ -232,9 +234,10 @@ where
 
         // compute distances from query to one-hop neighbors, and mark them visited
         accessor
-            .expand_beam(
+            .expand_beam_with_scratch(
                 scratch.beam_nodes.iter().copied(),
                 computer,
+                &mut adjacency_scratch,
                 glue::NotInMut::new(&mut scratch.visited),
                 |distance, id| one_hop_neighbors.push(Neighbor::new(id, distance)),
             )
@@ -274,13 +277,15 @@ where
         // Expand each two-hop candidate: if its neighbor is a match, compute its distance
         // to the query and insert into `scratch.visited`
         // If it is not a match, do nothing
-        let two_hop_expansion_candidate_ids: Vec<I> =
-            candidates_two_hop_expansion.iter().map(|n| n.id).collect();
+        let two_hop_expansion_count = candidates_two_hop_expansion.len();
 
         accessor
-            .expand_beam(
-                two_hop_expansion_candidate_ids.iter().copied(),
+            .expand_beam_with_scratch(
+                candidates_two_hop_expansion
+                    .iter()
+                    .map(|neighbor| neighbor.id),
                 computer,
+                &mut adjacency_scratch,
                 NotInMutWithLabelCheck::new(&mut scratch.visited, query_label_evaluator),
                 |distance, id| {
                     two_hop_neighbors.push(Neighbor::new(id, distance));
@@ -294,7 +299,7 @@ where
             .for_each(|neighbor| scratch.best.insert(*neighbor));
 
         scratch.cmps += two_hop_neighbors.len() as u32;
-        scratch.hops += two_hop_expansion_candidate_ids.len() as u32;
+        scratch.hops += two_hop_expansion_count as u32;
     }
 
     Ok(make_stats(scratch))

From aede0d13b5fed912c4ee9f3fab54ba67ae31d0aa Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Thu, 6 Aug 2026 18:04:19 +0800
Subject: [PATCH 13/25] docs: record filtered search optimizations

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../multiple_filter_test_report.md            | 204 +++++++++++++++++-
 1 file changed, 201 insertions(+), 3 deletions(-)

diff --git a/diskann-benchmark/multiple_filter_test_report.md b/diskann-benchmark/multiple_filter_test_report.md
index 4cdcf2bb6d..1812165db1 100644
--- a/diskann-benchmark/multiple_filter_test_report.md
+++ b/diskann-benchmark/multiple_filter_test_report.md
@@ -38,8 +38,8 @@ float32, distance squared_l2, max_degree 64, l_build 100, alpha 1.2, medoid star
 ## 3. Methodology
 
 - **Labels (set-membership):** each line token -> boolean field `{"doc_id":i,"GeoLocationID_190":true,"EN-US":true,...}`. A label matches regardless of position. Predicates use `{"<label>":{"$eq":true}}` composed with `$and`/`$or`.
-- Full-vocabulary file `data_labels_set.jsonl` (all 596 labels) supports *any* query. For the 9 test cases the referenced-label subset `data_labels_min.jsonl` (11 labels) yields **identical** match-sets/recall/latency and is used here for speed.
-- **Filtered groundtruth** via `compute_groundtruth` (shared evaluator with the benchmark), true top-150 among matching docs, `recall_at=150`.
+- Full-vocabulary file `data_labels_set.jsonl` (all 596 labels) is the authoritative source. For the 9 test cases, `data_labels_min.jsonl` is an exact 11-field projection and remains available only as a setup-speed optimization.
+- **Filtered groundtruth** via `compute_groundtruth` (shared evaluator with the benchmark), true top-150 among matching docs, `recall_at=150`. The canonical `gtset_S1..S9.bin` files were regenerated from `data_labels_set.jsonl`; all nine are byte-identical to the earlier `gtmin` files.
 - **Search:** k=150, L in {150,200,300,500,1000}, 3 reps, single thread. Beta uses `beta=0.1`. Recall = recall@150 vs the same filtered GT for both methods.
 
 ## 4. Filter cases & (corrected) selectivity
@@ -269,11 +269,208 @@ Full live comparison (same index, k=150, L=150, single thread, 1000 queries; rec
 
 **Bottom line for live query latency:** if the label vocabulary is modest, **bit-sliced per-attribute bitsets win across all selectivities**; otherwise **auto** (adaptive bitmap<->CSR) reliably takes the better of the two base methods. Both keep recall identical and evaluate the filter fully live.
 
+## 8.4 Bit-sliced layout and flat DNF query evaluation
+
+### 8.4.1 Attribute-major bit-sliced index
+
+`InlineAttributeIndexBitslice` builds one dense vector-id bitmap for every encoded
+attribute. If `a` is an attribute id and `v` is a vector id, the membership test is:
+
+```text
+word = bitsets[a][v / 64]
+matches = ((word >> (v % 64)) & 1) != 0
+```
+
+The storage is therefore an attribute-major Boolean matrix:
+
+```text
+attribute 0: [bit for node 0, bit for node 1, ...]
+attribute 1: [bit for node 0, bit for node 1, ...]
+...
+```
+
+Each equality terminal requires one indexed `u64` load plus a shift/mask. The immutable
+bitsets are shared by every query provider through `Arc`; there is no per-query result bitmap,
+lock, or allocation in `is_match`. Storage is:
+
+```text
+num_attributes * ceil(num_vectors / 64) * 8 bytes
+```
+
+For 9,996,160 vectors and all 596 labels this is 744,713,920 bytes (710.21 MiB). A
+single-attribute query touches only one 1.19 MiB slice even though the complete matrix is much
+larger.
+
+### 8.4.2 Recursive encoded AST
+
+The original Bitslice provider encodes each comparison to an integer terminal, but preserves the
+recursive query tree:
+
+```text
+ASTIdExpr =
+    Terminal(attribute_id)
+  | And(Vec<ASTIdExpr>)
+  | Or(Vec<ASTIdExpr>)
+```
+
+For every visited node, an `ASTIdExprVisitor` recursively dispatches on each node in the tree.
+`AND` and `OR` short-circuit through `all()` and `any()`, but every terminal still repeats enum
+dispatch, attribute-array lookup, and vector-id word/mask calculation.
+
+### 8.4.3 Flat DNF representation
+
+The optimized search type `topk-multihop-live-filter-bitslice-dnf` accepts expressions already in
+disjunctive normal form: an OR of AND clauses. A terminal is a one-term clause and a plain AND is
+a one-clause expression.
+
+```text
+(A AND B) OR (C AND D)
+
+clause_offsets = [0, 2, 4]
+attributes     = [A, B, C, D]
+```
+
+Clause `i` occupies
+`attributes[clause_offsets[i]..clause_offsets[i + 1]]`. The final hot-path query plan is stored
+in two contiguous boxed allocations regardless of clause count. The current prototype still
+builds the existing recursive encoded AST during query setup and then flattens it; the optimization
+targets repeated per-node evaluation rather than JSON/AST construction.
+
+At search time, the provider calculates the vector word and mask once, then loops over clauses:
+
+```text
+word_index = vector_id / 64
+mask = 1 << (vector_id % 64)
+
+for each AND clause:
+    if every bitsets[attribute][word_index] contains mask:
+        return true
+return false
+```
+
+The inner AND stops at its first missing attribute and the outer OR stops at its first matching
+clause. Single-terminal predicates use a dedicated provider that performs the bit test directly.
+Term order is intentionally preserved in this experiment; no cardinality-based reordering is
+included.
+
+The DNF compiler rejects trees such as `(A OR B) AND (C OR D)`. These must be normalized before
+ANN search, for example:
+
+```text
+(A OR B) AND (C OR D)
+  -> (A AND C) OR (A AND D) OR (B AND C) OR (B AND D)
+```
+
+Normalization belongs outside the hot search path and needs clause/terminal limits because
+unrestricted distribution can grow exponentially.
+
+Associatively nested groups such as `A OR (B OR C)` and `A AND (B AND C)` are flattened during
+query setup; they do not require distributive normalization.
+
+### 8.4.4 Isolated `is_match` result
+
+Criterion benchmark: 1M nodes, 596-label vocabulary, 50,000 random node probes per iteration.
+
+| Expression | Recursive Bitslice | Flat DNF | Speedup |
+|---|---:|---:|---:|
+| one terminal | 239.63 us | 118.31 us | **2.03x** |
+| `A AND B` | 529.57 us | 385.22 us | **1.37x** |
+| `(A AND B) OR (C AND D)` | 1,059.0 us | 553.62 us | **1.91x** |
+
+### 8.4.5 Full ANN result
+
+Full 596-label dataset, k=150, L=150, one thread, 1,000 queries. Latencies are milliseconds.
+Recall, comparisons, and hops are exactly identical between recursive and DNF providers.
+
+| Case | Terms | Recursive AVG | DNF AVG | Recursive P99 | DNF P99 | Recursive P99.9 | DNF P99.9 |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| S1 | 1 | 2.735 | **2.555** | 9.258 | **8.850** | **14.228** | 14.342 |
+| S2 | 2 | 4.906 | **4.386** | 10.837 | **9.137** | 18.209 | **10.697** |
+| S3 | 2 | 4.841 | **4.354** | 12.130 | **10.613** | 13.986 | **13.443** |
+| S4 | 4 | 6.789 | **5.148** | 17.297 | **13.269** | 20.875 | **15.500** |
+| S5 | 1 | 3.223 | **2.985** | 9.903 | **8.618** | 14.714 | **13.835** |
+| S6 | 1 | 5.563 | **4.969** | 10.030 | **8.486** | 12.275 | **10.374** |
+| S7 | 1 | 6.362 | **5.660** | 9.969 | **9.057** | 12.544 | **11.061** |
+| S8 | 1 | 6.600 | **5.816** | 9.590 | **8.555** | 12.954 | **10.704** |
+| S9 | 2 | 4.905 | **4.612** | 8.988 | **8.776** | **11.895** | 12.150 |
+
+Across S1-S9, flat DNF improves mean latency by **1.125x geometric mean** (6.0-24.2%)
+and P99 by **1.137x geometric mean**. The four-terminal S4 expression benefits most:
+24.2% lower mean and 23.3% lower P99. P99.9 improves in seven cases; the small S1/S9
+regressions are within single-run tail noise.
+
+The uniform-random single-attribute workload also improves from 3.300 to 2.856 ms mean
+(13.45%), 10.242 to 9.112 ms P99 (11.03%), and 13.187 to 11.312 ms P99.9 (14.22%).
+
+## 8.5 Exact-semantics multihop allocation reuse
+
+After optimizing filter evaluation, the current multihop implementation still created temporary
+graph-traversal storage repeatedly:
+
+- every `expand_beam` call constructed a new adjacency-list buffer;
+- each search iteration copied the selected two-hop routing IDs into a new `Vec`.
+
+The optimized implementation adds `expand_beam_with_scratch`, allowing the in-memory full-precision
+provider to reuse one adjacency list, preallocated to the graph's maximum degree, for all one-hop
+and two-hop expansions in a query. Providers with specialized `expand_beam` implementations keep
+their original I/O, batching, and accounting behavior. The two-hop call now consumes an iterator
+over the already sorted `Neighbor` list instead of allocating a second ID vector.
+
+This change does not alter predicate order, candidate order, distance calculations, queue
+operations, or traversal limits. A fresh controlled benchmark compared matched old and optimized
+binaries using the same DNF provider, full 596-label dataset, and **three repetitions per S1-S9
+case**. Recall, comparisons, and hops were exactly identical.
+
+All values below are milliseconds and are the mean of the three repetitions.
+
+| Case | Old AVG | Optimized AVG | AVG gain | Old P99 | Optimized P99 | P99 gain | Old P99.9 | Optimized P99.9 | P99.9 gain |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| S1 | 2.527 | **2.350** | 7.02% | 8.423 | **7.985** | 5.20% | 11.729 | **11.180** | 4.68% |
+| S2 | 4.296 | **4.280** | 0.39% | **9.070** | 9.253 | -2.02% | **11.903** | 21.286 | -78.83% |
+| S3 | 4.236 | **4.101** | 3.18% | 10.304 | **10.141** | 1.58% | 13.183 | **11.758** | 10.81% |
+| S4 | 5.020 | **4.940** | 1.60% | 12.571 | **12.383** | 1.50% | **17.176** | 21.160 | -23.20% |
+| S5 | 3.001 | **2.765** | 7.84% | 9.489 | **8.469** | 10.75% | 12.923 | **11.643** | 9.91% |
+| S6 | 4.871 | **4.714** | 3.22% | 8.388 | **8.336** | 0.62% | 10.307 | **9.315** | 9.63% |
+| S7 | 5.547 | **5.413** | 2.42% | 9.126 | **8.796** | 3.61% | 13.213 | **10.430** | 21.06% |
+| S8 | 5.588 | **5.467** | 2.15% | **8.179** | 8.236 | -0.70% | 13.912 | **12.383** | 10.99% |
+| S9 | 4.438 | **4.254** | 4.16% | 8.510 | **8.032** | 5.62% | 11.920 | **10.219** | 14.27% |
+
+The fresh geometric-mean speedups are **1.0372x** for AVG (3.72%), **1.0307x** for
+P99 (3.07%), and **1.0095x** for P99.9 (0.95%). P99.9 is intrinsically noisy with
+1,000 queries: the S2 and S4 optimized means are dominated by one repetition at
+39.489 ms and 31.415 ms respectively. The repeatable signal is the AVG improvement,
+with P99 also improving in seven of nine cases. This is a useful low-risk improvement,
+but the larger remaining ceiling is avoiding duplicated predicate checks and unnecessary
+distance work rather than removing additional small allocations.
+
+## 8.6 Backlog: ACORN-style filter-first traversal
+
+ACORN-1 is deferred for later investigation. It changes traversal semantics rather than only
+optimizing predicate evaluation, so it is not expected to return the exact same neighbor IDs as
+the current multihop implementation. The goal would be competitive recall at lower latency and
+fewer distance comparisons.
+
+The proposed experiment would retain rejected nodes as unscored routing connectors, expand
+bounded multi-hop neighborhoods, and compute vector distances only for matching nodes. Evaluation
+must compare recall-versus-latency curves rather than result parity:
+
+- keep the existing multihop search as the baseline;
+- add ACORN as a separate search type over the same graph;
+- sweep L and routing depth/budget across S1-S9;
+- require every returned node to satisfy the hard DNF predicate;
+- compare latency and distance comparisons at equal recall;
+- preserve an exact/current-search fallback if fewer than k matches are found.
+
+This work is intentionally postponed. The immediate priority is exact-semantics optimization of
+the current multihop implementation, including allocation reuse and removal of duplicated work,
+before changing its traversal policy.
+
 ## 9. Artifacts (`Q:\test6\filtered_test2\bench\full\`)
 
 - Labels: `data_labels_set.jsonl` (596 labels, general), `data_labels_min.jsonl` (11, fast)
 - Predicates: `predmin_S1..S9.jsonl` (also `predset_S1..S9.jsonl`)
-- Groundtruth: `gtmin_S1..S9.bin`
+- Groundtruth: `gtset_S1..S9.bin` (canonical, regenerated from all 596 labels); `gtmin_S1..S9.bin` are verified byte-identical projections
+- Full-label Bitslice-DNF runbook: `runbook_bitslice_dnf_set.json`
 - Runbooks: `runbook_setmin.json` (multihop), `runbook_beta_setmin.json` (beta), `runbook_livefilter.json` (live per-node)
 - Outputs: `out_setmin.json`, `out_beta_setmin.json`, `out_livefilter.json` (+ `out_live_S8.json`, `out_live_S9.json`)
 - Encoders: `gen_setmembership.py` (full), `gen_setmin.py` (minimal)
@@ -281,6 +478,7 @@ Full live comparison (same index, k=150, L=150, single thread, 1000 queries; rec
 - CSR live-filter code (section 8.1): `InlineAttributeIndexCsr` / `FrozenAttributeIndexCsr` in the same module; benchmark search-type `topk-multihop-live-filter-csr`; is_match microbenchmark `diskann-label-filter/benches/benchmarks/live_filter_bench.rs`
 - Posting-list + materialized-bitmap live code (section 8.2): `InlineAttributeIndexPosting` / `FrozenAttributeIndexPosting` / `MaterializedBitmapProvider`; benchmark search-type `topk-multihop-live-filter-bitmap`
 - Adaptive + bit-sliced live code (section 8.3): `InlineAttributeIndexAuto` (search-type `topk-multihop-live-filter-auto`) and `InlineAttributeIndexBitslice` (search-type `topk-multihop-live-filter-bitslice`)
+- Flat DNF Bitslice code (section 8.4): `EncodedDnf`, `BitsliceSingleProvider`, and `BitsliceDnfProvider`; benchmark search-type `topk-multihop-live-filter-bitslice-dnf`; microbenchmark `diskann-label-filter/benches/benchmarks/live_filter_bench.rs`
 - Index (reused): `idxsave_full`(+`.data`)
 
 _Note: an earlier version of this report used a single-valued `geo` string field; it is superseded by the set-membership results above._
\ No newline at end of file

From 0893c676a95929cff0f95b744391d984f7fa46d5 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Fri, 7 Aug 2026 15:47:17 +0800
Subject: [PATCH 14/25] diskann-benchmark: add inline Bitslice DNF search

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 diskann-benchmark/src/index/benchmarks.rs     | 67 +++++++++++++++++++
 diskann-benchmark/src/index/search/plugins.rs | 11 +++
 diskann-benchmark/src/inputs/graph_index.rs   | 19 ++++++
 3 files changed, 97 insertions(+)

diff --git a/diskann-benchmark/src/index/benchmarks.rs b/diskann-benchmark/src/index/benchmarks.rs
index 7b35c2173f..a51d8abad6 100644
--- a/diskann-benchmark/src/index/benchmarks.rs
+++ b/diskann-benchmark/src/index/benchmarks.rs
@@ -84,6 +84,7 @@ pub(crate) fn register_benchmarks(registry: &mut Registry) -> anyhow::Result<()>
             .search(plugins::TopkMultihopLiveFilterAuto)
             .search(plugins::TopkMultihopLiveFilterBitslice)
             .search(plugins::TopkMultihopLiveFilterBitsliceDnf)
+            .search(plugins::TopkInlineLiveFilterBitsliceDnf)
             .search(plugins::TopkInlineFilter)
             .search(plugins::DeterminantDiversity),
     )?;
@@ -1088,6 +1089,72 @@ where
     }
 }
 
+//---------------------------------//
+// InlineFilter (Bitslice DNF)      //
+//---------------------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>>
+    for plugins::TopkInlineLiveFilterBitsliceDnf
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<
+            'a,
+            DP,
+            &'a [DP::Element],
+            SearchAccessor: glue::SearchAccessor,
+        > + Clone
+        + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        let inline = phase.as_topk_inline_live_filter_bitslice_dnf()?;
+
+        let queries: Arc<Matrix<DP::Element>> = Arc::new(datafiles::load_dataset(
+            datafiles::BinFile(&inline.queries),
+        )?);
+
+        let groundtruth =
+            datafiles::load_range_groundtruth(datafiles::BinFile(&inline.groundtruth))?;
+
+        let steps = search::knn::SearchSteps::new(
+            inline.reps,
+            &inline.num_threads,
+            &inline.runs,
+            GroundTruthMode::Flexible,
+        );
+
+        let attribute_index =
+            utils::filters::build_inline_attribute_index_bitslice(&inline.data_labels)?;
+        let providers = utils::filters::make_live_providers_bitslice_dnf(
+            &attribute_index,
+            &inline.query_predicates,
+        )?;
+
+        let inline = benchmark_core::search::graph::InlineFilterSearch::new(
+            index,
+            queries,
+            benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
+            providers.into(),
+            inline.adaptive_l()?,
+        )?;
+
+        let result = search::knn::run(&inline, &groundtruth, steps)?;
+        Ok(AggregatedSearchResults::Topk(result))
+    }
+}
+
 //--------------//
 // InlineFilter //
 //--------------//
diff --git a/diskann-benchmark/src/index/search/plugins.rs b/diskann-benchmark/src/index/search/plugins.rs
index 0b452fb7db..db74ceebb2 100644
--- a/diskann-benchmark/src/index/search/plugins.rs
+++ b/diskann-benchmark/src/index/search/plugins.rs
@@ -307,3 +307,14 @@ impl TopkMultihopLiveFilterBitsliceDnf {
         SearchPhaseKind::TopkMultihopLiveFilterBitsliceDnf
     }
 }
+
+/// An inline-filtered search plugin backed by bit slices and a flat OR-of-AND query plan.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkInlineLiveFilterBitsliceDnf;
+
+impl TopkInlineLiveFilterBitsliceDnf {
+    /// Returns [`SearchPhaseKind::TopkInlineLiveFilterBitsliceDnf`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkInlineLiveFilterBitsliceDnf
+    }
+}
diff --git a/diskann-benchmark/src/inputs/graph_index.rs b/diskann-benchmark/src/inputs/graph_index.rs
index e81c66f1e5..2d592b5fae 100644
--- a/diskann-benchmark/src/inputs/graph_index.rs
+++ b/diskann-benchmark/src/inputs/graph_index.rs
@@ -414,6 +414,7 @@ pub(crate) enum SearchPhase {
     TopkMultihopLiveFilterAuto(MultihopFilterSearchPhase),
     TopkMultihopLiveFilterBitslice(MultihopFilterSearchPhase),
     TopkMultihopLiveFilterBitsliceDnf(MultihopFilterSearchPhase),
+    TopkInlineLiveFilterBitsliceDnf(InlineFilterSearchPhase),
     TopkInlineFilter(InlineFilterSearchPhase),
     TopkDeterminantDiversity(TopkDeterminantDiversityPhase),
 }
@@ -452,6 +453,9 @@ impl SearchPhase {
             Self::TopkMultihopLiveFilterBitsliceDnf(_) => {
                 SearchPhaseKind::TopkMultihopLiveFilterBitsliceDnf
             }
+            Self::TopkInlineLiveFilterBitsliceDnf(_) => {
+                SearchPhaseKind::TopkInlineLiveFilterBitsliceDnf
+            }
             Self::TopkInlineFilter(_) => SearchPhaseKind::TopkInlineFilter,
             Self::TopkDeterminantDiversity(_) => SearchPhaseKind::TopkDeterminantDiversity,
         }
@@ -583,6 +587,18 @@ impl SearchPhase {
         }
     }
 
+    pub(crate) fn as_topk_inline_live_filter_bitslice_dnf(
+        &self,
+    ) -> Result<&InlineFilterSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkInlineLiveFilterBitsliceDnf(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkInlineLiveFilterBitsliceDnf,
+                self.kind(),
+            )),
+        }
+    }
+
     pub(crate) fn as_topk_determinant_diversity(
         &self,
     ) -> Result<&TopkDeterminantDiversityPhase, WrongSearchPhaseKind> {
@@ -609,6 +625,7 @@ impl SearchPhase {
             SearchPhase::TopkMultihopLiveFilterAuto(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopLiveFilterBitslice(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopLiveFilterBitsliceDnf(phase) => phase.validate(checker),
+            SearchPhase::TopkInlineLiveFilterBitsliceDnf(phase) => phase.validate(checker),
             SearchPhase::TopkInlineFilter(phase) => phase.validate(checker),
             SearchPhase::TopkDeterminantDiversity(phase) => phase.validate(checker),
         }
@@ -627,6 +644,7 @@ pub(crate) enum SearchPhaseKind {
     TopkMultihopLiveFilterAuto,
     TopkMultihopLiveFilterBitslice,
     TopkMultihopLiveFilterBitsliceDnf,
+    TopkInlineLiveFilterBitsliceDnf,
     TopkInlineFilter,
     TopkDeterminantDiversity,
 }
@@ -644,6 +662,7 @@ impl SearchPhaseKind {
             Self::TopkMultihopLiveFilterAuto => "topk-multihop-live-filter-auto",
             Self::TopkMultihopLiveFilterBitslice => "topk-multihop-live-filter-bitslice",
             Self::TopkMultihopLiveFilterBitsliceDnf => "topk-multihop-live-filter-bitslice-dnf",
+            Self::TopkInlineLiveFilterBitsliceDnf => "topk-inline-live-filter-bitslice-dnf",
             Self::TopkInlineFilter => "topk-inline-filter",
             Self::TopkDeterminantDiversity => "topk-determinant-diversity",
         }

From 03225957a3fa7980d7a37751e528845bcbd16eac Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Fri, 7 Aug 2026 15:47:18 +0800
Subject: [PATCH 15/25] docs: compare filtered search strategies

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../multiple_filter_test_report.md            | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/diskann-benchmark/multiple_filter_test_report.md b/diskann-benchmark/multiple_filter_test_report.md
index 1812165db1..187548c82d 100644
--- a/diskann-benchmark/multiple_filter_test_report.md
+++ b/diskann-benchmark/multiple_filter_test_report.md
@@ -402,6 +402,65 @@ regressions are within single-run tail noise.
 The uniform-random single-attribute workload also improves from 3.300 to 2.856 ms mean
 (13.45%), 10.242 to 9.112 ms P99 (11.03%), and 13.187 to 11.312 ms P99.9 (14.22%).
 
+### 8.4.6 Fresh Roaring-materialized bitmap versus Bitslice-DNF
+
+After merging `origin/main`, both providers were rerun in one counterbalanced S1-S9 runbook using
+the full 596-label dataset, canonical `gtset` ground truth, k=150, L=150, one thread, 1,000
+queries, and three repetitions. Values are milliseconds averaged across the three repetitions.
+`topk-multihop-live-filter-bitmap` rebuilt fresh query providers for every repetition and L; its
+lazy Roaring set algebra and dense result-bitmap construction were therefore included in query
+latency, with no cross-query result cache.
+
+| Case | Bitmap AVG | DNF AVG | AVG speedup | Bitmap P99 | DNF P99 | P99 speedup | Bitmap P99.9 | DNF P99.9 | P99.9 speedup |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| S1 | 50.914 | **2.130** | 23.91x | 60.307 | **7.321** | 8.24x | 76.567 | **11.090** | 6.90x |
+| S2 | 11.109 | **4.121** | 2.70x | 14.936 | **8.976** | 1.66x | 18.371 | **10.849** | 1.69x |
+| S3 | 16.508 | **4.221** | 3.91x | 22.508 | **10.410** | 2.16x | 30.520 | **13.176** | 2.32x |
+| S4 | 17.757 | **5.205** | 3.41x | 23.850 | **13.216** | 1.80x | 34.291 | **17.202** | 1.99x |
+| S5 | 48.190 | **2.723** | 17.70x | 58.693 | **8.262** | 7.10x | 73.576 | **10.871** | 6.77x |
+| S6 | 15.432 | **4.468** | 3.45x | 19.774 | **7.996** | 2.47x | 29.565 | **10.705** | 2.76x |
+| S7 | 8.757 | **5.206** | 1.68x | 12.453 | **8.317** | 1.50x | 20.782 | **10.945** | 1.90x |
+| S8 | 6.361 | **5.135** | 1.24x | 9.002 | **7.698** | 1.17x | 11.031 | **8.704** | 1.27x |
+| S9 | 9.580 | **4.311** | 2.22x | 13.963 | **7.895** | 1.77x | 17.651 | **9.942** | 1.78x |
+
+Recall, comparisons, and hops were exactly identical for every pair. Bitslice-DNF won all 27
+latency comparisons. Its geometric-mean speedups were **3.967x AVG**, **2.426x P99**, and
+**2.534x P99.9**. The largest gaps were the broad single-terminal S1 and S5 cases, where iterating
+millions of Roaring matches during densification dominates. The closest case was selective S8,
+where cheap materialization plus frequent membership tests narrowed the DNF advantage to 1.24x
+AVG.
+
+### 8.4.7 Fixed-L InlineFilterSearch versus multihop with Bitslice-DNF
+
+A dedicated `topk-inline-live-filter-bitslice-dnf` benchmark mode was added so InlineFilterSearch
+and multihop can use the exact same attribute index, encoded DNF providers, queries, and ground
+truth. The initial comparison intentionally disabled Adaptive-L and used the same fixed k=150,
+L=150, one thread, 1,000 queries, full 596-label metadata, canonical `gtset` ground truth, and
+three repetitions. Values are milliseconds averaged across repetitions.
+
+| Case | Inline AVG | Multi AVG | Speedup | Inline P99 | Multi P99 | Inline P99.9 | Multi P99.9 | Inline recall | Multi recall | Recall delta |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| S1 | **0.432** | 2.324 | 5.38x | **1.189** | 7.921 | **1.547** | 11.730 | 0.76114 | **0.97104** | -0.20990 |
+| S2 | **0.466** | 4.390 | 9.42x | **1.210** | 9.492 | **1.536** | 12.295 | 0.41239 | **0.94577** | -0.53338 |
+| S3 | **0.465** | 4.400 | 9.45x | **1.207** | 10.703 | **1.609** | 12.488 | 0.48748 | **0.95031** | -0.46283 |
+| S4 | **0.554** | 5.606 | 10.11x | **1.564** | 14.346 | **1.830** | 19.392 | 0.44256 | **0.95338** | -0.51082 |
+| S5 | **0.443** | 2.842 | 6.41x | **1.152** | 8.687 | **2.426** | 11.842 | 0.70740 | **0.97237** | -0.26497 |
+| S6 | **0.399** | 4.406 | 11.05x | **1.205** | 7.716 | **2.213** | 9.134 | 0.16844 | **0.87069** | -0.70225 |
+| S7 | **0.415** | 5.229 | 12.60x | **1.052** | 8.445 | **1.887** | 10.107 | 0.11883 | **0.88348** | -0.76465 |
+| S8 | **0.385** | 5.192 | 13.50x | **0.965** | 7.893 | **1.451** | 9.811 | 0.05506 | **0.83374** | -0.77868 |
+| S9 | **0.418** | 4.559 | 10.91x | **1.052** | 8.498 | **1.358** | 10.378 | 0.21855 | **0.91891** | -0.70035 |
+
+Fixed-L Inline was **9.512x faster in AVG**, **7.815x in P99**, and **6.717x in P99.9**
+by geometric mean, but it was not recall-competitive. Mean recall was only **0.37465**, versus
+**0.92219** for multihop, a -0.54754 absolute difference. Inline performed the same
+filter-independent traversal in every case (2,330.738 comparisons and 156.407 hops), while
+multihop spent 11.9K-18.4K comparisons and 1.1K-4.4K hops routing through rejected nodes to recover
+matching neighbors.
+
+The latency advantage therefore represents a different recall point, not an algorithmic win at
+equal quality. Adaptive-L or an L sweep is required to compare recall-versus-latency curves and
+determine whether Inline can match multihop recall efficiently.
+
 ## 8.5 Exact-semantics multihop allocation reuse
 
 After optimizing filter evaluation, the current multihop implementation still created temporary
@@ -465,6 +524,33 @@ This work is intentionally postponed. The immediate priority is exact-semantics
 the current multihop implementation, including allocation reuse and removal of duplicated work,
 before changing its traversal policy.
 
+## 8.7 Backlog: SIMD whole-query bitmap materialization
+
+A no-cache SIMD materialization path is worth testing as the strongest whole-query-bitmap
+alternative to live DNF Bitslice evaluation. It would reuse the existing attribute-major dense
+bitsets, but evaluate the complete predicate over all `ceil(N / 64)` words using AVX2 or AVX-512:
+AND the terminal bitsets within each DNF clause, OR the clause results, and write one dense
+query-result bitmap. ANN traversal would then perform one bit lookup per visited node.
+
+This differs from `topk-multihop-live-filter-bitmap`, which currently performs Roaring posting-list
+set algebra and then iterates the matching IDs to densify the result. The SIMD experiment should
+not use a cross-query result cache: construct a fresh result bitmap for each query execution and
+charge all allocation, initialization, Boolean operations, and writes to query latency.
+
+The comparison should include:
+
+- current Roaring materialization, SIMD dense materialization, and live Bitslice-DNF;
+- one-, two-, four-, and larger-terminal DNF expressions with controlled short-circuit behavior;
+- total filter evaluations relative to `N / 64`, including all nodes visited during the query;
+- selective and broad results, plus different terminal/clause orderings;
+- separate materialization, ANN traversal, and end-to-end latency;
+- exact recall, comparison, hop, and filter-result parity;
+- memory bandwidth, output-bitmap allocation/zeroing, and cache-pollution measurements.
+
+The expected opportunity is complex predicates with weak live short-circuiting and enough visited
+nodes to amortize a sequential SIMD pass. Live Bitslice-DNF should remain favored for small
+one-off searches and well-ordered selective predicates.
+
 ## 9. Artifacts (`Q:\test6\filtered_test2\bench\full\`)
 
 - Labels: `data_labels_set.jsonl` (596 labels, general), `data_labels_min.jsonl` (11, fast)
@@ -479,6 +565,7 @@ before changing its traversal policy.
 - Posting-list + materialized-bitmap live code (section 8.2): `InlineAttributeIndexPosting` / `FrozenAttributeIndexPosting` / `MaterializedBitmapProvider`; benchmark search-type `topk-multihop-live-filter-bitmap`
 - Adaptive + bit-sliced live code (section 8.3): `InlineAttributeIndexAuto` (search-type `topk-multihop-live-filter-auto`) and `InlineAttributeIndexBitslice` (search-type `topk-multihop-live-filter-bitslice`)
 - Flat DNF Bitslice code (section 8.4): `EncodedDnf`, `BitsliceSingleProvider`, and `BitsliceDnfProvider`; benchmark search-type `topk-multihop-live-filter-bitslice-dnf`; microbenchmark `diskann-label-filter/benches/benchmarks/live_filter_bench.rs`
+- Inline Bitslice-DNF comparison (section 8.4.7): benchmark search-type `topk-inline-live-filter-bitslice-dnf`, using the same `InlineAttributeIndexBitslice` and DNF providers with `InlineFilterSearch`
 - Index (reused): `idxsave_full`(+`.data`)
 
 _Note: an earlier version of this report used a single-valued `geo` string field; it is superseded by the set-membership results above._
\ No newline at end of file

From 17b2be39c5cfa009b6ae92a40fc8285798d7c1d0 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Fri, 7 Aug 2026 17:28:31 +0800
Subject: [PATCH 16/25] diskann-label-filter: add encoded label indexes

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 Cargo.lock                                    |    2 +-
 Cargo.toml                                    |    2 +-
 diskann-label-filter/Cargo.toml               |    2 +-
 .../src/encoded_label_index.rs                | 1150 +++++++++++++++++
 diskann-label-filter/src/lib.rs               |    5 +
 5 files changed, 1158 insertions(+), 3 deletions(-)
 create mode 100644 diskann-label-filter/src/encoded_label_index.rs

diff --git a/Cargo.lock b/Cargo.lock
index b28f10fe42..b91d7e4801 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -645,7 +645,7 @@ dependencies = [
 
 [[package]]
 name = "diskann-label-filter"
-version = "0.55.0"
+version = "0.55.1-pre.1"
 dependencies = [
  "anyhow",
  "bf-tree",
diff --git a/Cargo.toml b/Cargo.toml
index 6394a7d319..359ad79ee1 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -63,7 +63,7 @@ diskann = { path = "diskann", version = "0.55.0" }
 diskann-providers = { path = "diskann-providers", default-features = false, version = "0.55.0" }
 diskann-inmem = { path = "diskann-inmem", default-features = false, version = "0.55.0" }
 diskann-disk = { path = "diskann-disk", version = "0.55.0" }
-diskann-label-filter = { path = "diskann-label-filter", version = "0.55.0" }
+diskann-label-filter = { path = "diskann-label-filter", version = "0.55.1-pre.1" }
 # Infra
 diskann-benchmark-runner = { path = "diskann-benchmark-runner", version = "0.55.0" }
 diskann-benchmark-core = { path = "diskann-benchmark-core", version = "0.55.0" }
diff --git a/diskann-label-filter/Cargo.toml b/diskann-label-filter/Cargo.toml
index 14102411ec..dbe2449ca1 100644
--- a/diskann-label-filter/Cargo.toml
+++ b/diskann-label-filter/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "diskann-label-filter"
-version.workspace = true
+version = "0.55.1-pre.1"
 description.workspace = true
 authors.workspace = true
 repository.workspace = true
diff --git a/diskann-label-filter/src/encoded_label_index.rs b/diskann-label-filter/src/encoded_label_index.rs
new file mode 100644
index 0000000000..ec2affdf2e
--- /dev/null
+++ b/diskann-label-filter/src/encoded_label_index.rs
@@ -0,0 +1,1150 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+
+//! Versioned on-disk label-index encoding, loading, and query evaluation.
+
+use diskann::graph::ext::labeled::QueryLabelProvider;
+use roaring::RoaringBitmap;
+use serde_json::{Map, Value};
+use std::{
+    collections::{HashMap, HashSet},
+    fs::File,
+    io::{self, BufRead, BufReader, BufWriter, Read, Seek, Write},
+    path::Path,
+};
+use thiserror::Error;
+
+const LABEL_INDEX_MAGIC: [u8; 8] = *b"DANLBL01";
+const LABEL_INDEX_VERSION: u32 = 1;
+const MAX_LABEL_COUNT: usize = 1_000_000;
+const MAX_LABEL_LENGTH: usize = 1 << 20;
+const MAX_POSTING_BYTES: usize = 512 << 20;
+const MAX_DENSE_BITMAP_BYTES: usize = 256 << 20;
+const MAX_BITMAP_VECTORS: u64 = (MAX_DENSE_BITMAP_BYTES as u64) * 8;
+
+/// The persisted label-index storage format.
+#[repr(u32)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LabelIndexFormat {
+    /// One contiguous dense bit slice per encoded label.
+    Bitslice = 0,
+    /// One serialized Roaring posting list per encoded label.
+    Bitmap = 1,
+}
+
+/// The outer Boolean structure of a clause list passed to [`EncodedLabelIndex::query`].
+#[allow(clippy::upper_case_acronyms)]
+#[repr(u32)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FilterExpressionType {
+    /// Outer OR with `&`-separated labels inside each string:
+    /// `["A&B", "C&D"]` means `(A AND B) OR (C AND D)`.
+    ORMajor = 0,
+    /// Outer AND with `|`-separated labels inside each string:
+    /// `["A|B", "C|D"]` means `(A OR B) AND (C OR D)`.
+    ANDMajor = 1,
+}
+
+#[derive(Debug, Error)]
+pub enum EncodedLabelIndexError {
+    #[error(transparent)]
+    Io(#[from] io::Error),
+    #[error(transparent)]
+    Json(#[from] serde_json::Error),
+    #[error("{0}")]
+    Invalid(String),
+}
+
+enum LabelStorage {
+    Bitslice {
+        words_per_label: usize,
+        bits: Box<[u64]>,
+    },
+    Bitmap {
+        postings: Box<[RoaringBitmap]>,
+    },
+}
+
+/// An immutable encoded label index loaded from a versioned label-index file.
+pub struct EncodedLabelIndex {
+    labels: Box<[String]>,
+    label_ids: HashMap<String, u32>,
+    num_vectors: u32,
+    storage: LabelStorage,
+}
+
+impl std::fmt::Debug for EncodedLabelIndex {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("EncodedLabelIndex")
+            .field("num_labels", &self.labels.len())
+            .field("num_vectors", &self.num_vectors)
+            .field("format", &self.format())
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+enum PlanKind {
+    OrMajor,
+    AndMajor,
+}
+
+impl From<FilterExpressionType> for PlanKind {
+    fn from(value: FilterExpressionType) -> Self {
+        match value {
+            FilterExpressionType::ORMajor => Self::OrMajor,
+            FilterExpressionType::ANDMajor => Self::AndMajor,
+        }
+    }
+}
+
+#[derive(Debug)]
+struct CompiledPlan {
+    kind: PlanKind,
+    clause_offsets: Box<[usize]>,
+    label_ids: Box<[Option<u32>]>,
+}
+
+enum QueryStorage<'a> {
+    Bitslice {
+        words_per_label: usize,
+        bits: &'a [u64],
+        plan: CompiledPlan,
+    },
+    DenseBitmap {
+        bits: Box<[u64]>,
+    },
+}
+
+/// Query-scoped label provider backed by an [`EncodedLabelIndex`].
+pub struct EncodedLabelQuery<'a> {
+    num_vectors: u32,
+    storage: QueryStorage<'a>,
+}
+
+impl std::fmt::Debug for EncodedLabelQuery<'_> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("EncodedLabelQuery")
+            .field("num_vectors", &self.num_vectors)
+            .finish()
+    }
+}
+
+impl QueryLabelProvider<u32> for EncodedLabelQuery<'_> {
+    fn is_match(&self, vec_id: u32) -> bool {
+        if vec_id >= self.num_vectors {
+            return false;
+        }
+
+        match &self.storage {
+            QueryStorage::Bitslice {
+                words_per_label,
+                bits,
+                plan,
+            } => plan.matches_bitslice(*words_per_label, bits, vec_id),
+            QueryStorage::DenseBitmap { bits } => dense_contains(bits, vec_id),
+        }
+    }
+}
+
+impl CompiledPlan {
+    fn matches_bitslice(&self, words_per_label: usize, bits: &[u64], vec_id: u32) -> bool {
+        let terminal_matches = |label_id: Option<u32>| {
+            label_id.is_some_and(|label_id| {
+                let label_id = label_id as usize;
+                let vec_id = vec_id as usize;
+                let word = bits[label_id * words_per_label + vec_id / 64];
+                word & (1u64 << (vec_id % 64)) != 0
+            })
+        };
+
+        match self.kind {
+            PlanKind::OrMajor => self.clause_offsets.windows(2).any(|clause| {
+                self.label_ids[clause[0]..clause[1]]
+                    .iter()
+                    .copied()
+                    .all(terminal_matches)
+            }),
+            PlanKind::AndMajor => self.clause_offsets.windows(2).all(|clause| {
+                self.label_ids[clause[0]..clause[1]]
+                    .iter()
+                    .copied()
+                    .any(terminal_matches)
+            }),
+        }
+    }
+}
+
+impl EncodedLabelIndex {
+    pub fn load(path: impl AsRef<Path>) -> Result<Self, EncodedLabelIndexError> {
+        let file = File::open(path)?;
+        let file_len = file.metadata()?.len();
+        let mut reader = BufReader::new(file);
+
+        let mut magic = [0u8; LABEL_INDEX_MAGIC.len()];
+        reader.read_exact(&mut magic)?;
+        if magic != LABEL_INDEX_MAGIC {
+            return Err(EncodedLabelIndexError::Invalid(
+                "invalid label-index file magic".to_string(),
+            ));
+        }
+
+        let version = read_u32(&mut reader)?;
+        if version != LABEL_INDEX_VERSION {
+            return Err(EncodedLabelIndexError::Invalid(format!(
+                "unsupported label-index version {version}"
+            )));
+        }
+
+        let format = match read_u32(&mut reader)? {
+            0 => LabelIndexFormat::Bitslice,
+            1 => LabelIndexFormat::Bitmap,
+            value => {
+                return Err(EncodedLabelIndexError::Invalid(format!(
+                    "unsupported label-index format {value}"
+                )));
+            }
+        };
+        let num_vectors = u32::try_from(read_u64(&mut reader)?).map_err(|_| {
+            EncodedLabelIndexError::Invalid("label-index vector count exceeds u32".to_string())
+        })?;
+        if num_vectors == 0 {
+            return Err(EncodedLabelIndexError::Invalid(
+                "label-index vector count cannot be zero".to_string(),
+            ));
+        }
+        if format == LabelIndexFormat::Bitmap && u64::from(num_vectors) > MAX_BITMAP_VECTORS {
+            return Err(EncodedLabelIndexError::Invalid(format!(
+                "bitmap vector count {num_vectors} exceeds limit {MAX_BITMAP_VECTORS}"
+            )));
+        }
+
+        let num_labels = usize::try_from(read_u64(&mut reader)?).map_err(|_| {
+            EncodedLabelIndexError::Invalid("label-index label count exceeds usize".to_string())
+        })?;
+        if num_labels > MAX_LABEL_COUNT {
+            return Err(EncodedLabelIndexError::Invalid(format!(
+                "label-index label count {num_labels} exceeds limit {MAX_LABEL_COUNT}"
+            )));
+        }
+        let minimum_dictionary_bytes = num_labels.checked_mul(4).ok_or_else(|| {
+            EncodedLabelIndexError::Invalid("label dictionary size overflow".to_string())
+        })?;
+        ensure_remaining(
+            &mut reader,
+            file_len,
+            minimum_dictionary_bytes,
+            "label dictionary",
+        )?;
+
+        let mut labels = Vec::new();
+        labels.try_reserve_exact(num_labels).map_err(|_| {
+            EncodedLabelIndexError::Invalid("cannot reserve label dictionary".to_string())
+        })?;
+
+        let mut label_ids = HashMap::new();
+        label_ids.try_reserve(num_labels).map_err(|_| {
+            EncodedLabelIndexError::Invalid("cannot reserve label lookup map".to_string())
+        })?;
+
+        for id in 0..num_labels {
+            let len = usize::try_from(read_u32(&mut reader)?).map_err(|_| {
+                EncodedLabelIndexError::Invalid("label length exceeds usize".to_string())
+            })?;
+            if len > MAX_LABEL_LENGTH {
+                return Err(EncodedLabelIndexError::Invalid(format!(
+                    "label length {len} exceeds limit {MAX_LABEL_LENGTH}"
+                )));
+            }
+            ensure_remaining(&mut reader, file_len, len, "label bytes")?;
+            let mut bytes = Vec::new();
+            bytes.try_reserve_exact(len).map_err(|_| {
+                EncodedLabelIndexError::Invalid("cannot reserve label bytes".to_string())
+            })?;
+            bytes.resize(len, 0);
+            reader.read_exact(&mut bytes)?;
+
+            let label = String::from_utf8(bytes).map_err(|_| {
+                EncodedLabelIndexError::Invalid("label-index contains invalid UTF-8".to_string())
+            })?;
+            validate_label(&label)?;
+
+            let id = u32::try_from(id).map_err(|_| {
+                EncodedLabelIndexError::Invalid("label count exceeds u32".to_string())
+            })?;
+            if label_ids.insert(label.clone(), id).is_some() {
+                return Err(EncodedLabelIndexError::Invalid(format!(
+                    "duplicate label '{label}' in label-index"
+                )));
+            }
+            labels.push(label);
+        }
+
+        let storage = match format {
+            LabelIndexFormat::Bitslice => {
+                let words_per_label = usize::try_from(read_u64(&mut reader)?).map_err(|_| {
+                    EncodedLabelIndexError::Invalid("bitslice row length exceeds usize".to_string())
+                })?;
+                let expected_words = (num_vectors as usize).div_ceil(64);
+                if words_per_label != expected_words {
+                    return Err(EncodedLabelIndexError::Invalid(format!(
+                        "bitslice row has {words_per_label} words; expected {expected_words}"
+                    )));
+                }
+                let total_words = num_labels.checked_mul(words_per_label).ok_or_else(|| {
+                    EncodedLabelIndexError::Invalid("bitslice allocation size overflow".to_string())
+                })?;
+                let payload_bytes = total_words.checked_mul(8).ok_or_else(|| {
+                    EncodedLabelIndexError::Invalid("bitslice byte size overflow".to_string())
+                })?;
+                ensure_remaining(&mut reader, file_len, payload_bytes, "bitslice payload")?;
+
+                let mut bits = Vec::new();
+                bits.try_reserve_exact(total_words).map_err(|_| {
+                    EncodedLabelIndexError::Invalid("cannot reserve bitslice payload".to_string())
+                })?;
+                for _ in 0..total_words {
+                    bits.push(read_u64(&mut reader)?);
+                }
+                validate_bitslice_padding(&bits, num_labels, words_per_label, num_vectors)?;
+
+                LabelStorage::Bitslice {
+                    words_per_label,
+                    bits: bits.into_boxed_slice(),
+                }
+            }
+            LabelIndexFormat::Bitmap => {
+                let mut postings = Vec::new();
+                postings.try_reserve_exact(num_labels).map_err(|_| {
+                    EncodedLabelIndexError::Invalid("cannot reserve posting list table".to_string())
+                })?;
+                for _ in 0..num_labels {
+                    let len = usize::try_from(read_u64(&mut reader)?).map_err(|_| {
+                        EncodedLabelIndexError::Invalid(
+                            "serialized posting length exceeds usize".to_string(),
+                        )
+                    })?;
+                    if len > MAX_POSTING_BYTES {
+                        return Err(EncodedLabelIndexError::Invalid(format!(
+                            "serialized posting length {len} exceeds limit {MAX_POSTING_BYTES}"
+                        )));
+                    }
+                    ensure_remaining(&mut reader, file_len, len, "serialized posting")?;
+
+                    let mut limited = reader.by_ref().take(len as u64);
+                    let posting = RoaringBitmap::deserialize_from(&mut limited)?;
+                    if limited.limit() != 0 {
+                        return Err(EncodedLabelIndexError::Invalid(
+                            "serialized posting length does not match payload".to_string(),
+                        ));
+                    }
+                    if posting.max().is_some_and(|max| max >= num_vectors) {
+                        return Err(EncodedLabelIndexError::Invalid(
+                            "serialized posting contains an out-of-range vector ID".to_string(),
+                        ));
+                    }
+                    postings.push(posting);
+                }
+
+                LabelStorage::Bitmap {
+                    postings: postings.into_boxed_slice(),
+                }
+            }
+        };
+
+        if reader.read(&mut [0u8; 1])? != 0 {
+            return Err(EncodedLabelIndexError::Invalid(
+                "label-index contains trailing bytes".to_string(),
+            ));
+        }
+
+        Ok(Self {
+            labels: labels.into_boxed_slice(),
+            label_ids,
+            num_vectors,
+            storage,
+        })
+    }
+
+    pub fn query<S>(
+        &self,
+        clauses: &[S],
+        expression_type: FilterExpressionType,
+    ) -> Result<EncodedLabelQuery<'_>, EncodedLabelIndexError>
+    where
+        S: AsRef<str>,
+    {
+        let plan = compile_plan(clauses, expression_type.into(), &self.label_ids)?;
+
+        let storage = match &self.storage {
+            LabelStorage::Bitslice {
+                words_per_label,
+                bits,
+            } => QueryStorage::Bitslice {
+                words_per_label: *words_per_label,
+                bits,
+                plan,
+            },
+            LabelStorage::Bitmap { postings } => QueryStorage::DenseBitmap {
+                bits: materialize_bitmap(&plan, postings, self.num_vectors)?.into_boxed_slice(),
+            },
+        };
+
+        Ok(EncodedLabelQuery {
+            num_vectors: self.num_vectors,
+            storage,
+        })
+    }
+
+    fn format(&self) -> LabelIndexFormat {
+        match &self.storage {
+            LabelStorage::Bitslice { .. } => LabelIndexFormat::Bitslice,
+            LabelStorage::Bitmap { .. } => LabelIndexFormat::Bitmap,
+        }
+    }
+}
+
+/// Encode a JSONL label file into a versioned Bitslice or Roaring-bitmap label index.
+///
+/// Supported JSONL rows are:
+///
+/// - objects with optional `doc_id`; `true` fields use the field name, other scalar values use
+///   `field=value`;
+/// - objects with a `labels` string array;
+/// - a raw string or string array, using the line number as the document ID.
+pub fn encode_label_index_jsonl(
+    input_path: impl AsRef<Path>,
+    output_path: impl AsRef<Path>,
+    format: LabelIndexFormat,
+) -> Result<(), EncodedLabelIndexError> {
+    encode_jsonl(input_path, output_path, format)
+}
+
+fn compile_plan<S: AsRef<str>>(
+    clauses: &[S],
+    kind: PlanKind,
+    label_ids: &HashMap<String, u32>,
+) -> Result<CompiledPlan, EncodedLabelIndexError> {
+    if clauses.is_empty() {
+        return Err(EncodedLabelIndexError::Invalid(
+            "filter must contain at least one clause".to_string(),
+        ));
+    }
+
+    let delimiter = match kind {
+        PlanKind::OrMajor => '&',
+        PlanKind::AndMajor => '|',
+    };
+    let mut clause_offsets = vec![0usize];
+    let mut encoded = Vec::new();
+
+    for clause in clauses {
+        let mut terminal_count = 0usize;
+        for terminal in clause.as_ref().split(delimiter) {
+            let terminal = terminal.trim();
+            validate_label(terminal)?;
+            encoded.push(label_ids.get(terminal).copied());
+            terminal_count += 1;
+        }
+        if terminal_count == 0 {
+            return Err(EncodedLabelIndexError::Invalid(
+                "filter clauses cannot be empty".to_string(),
+            ));
+        }
+        clause_offsets.push(encoded.len());
+    }
+
+    Ok(CompiledPlan {
+        kind,
+        clause_offsets: clause_offsets.into_boxed_slice(),
+        label_ids: encoded.into_boxed_slice(),
+    })
+}
+
+fn materialize_bitmap(
+    plan: &CompiledPlan,
+    postings: &[RoaringBitmap],
+    num_vectors: u32,
+) -> Result<Vec<u64>, EncodedLabelIndexError> {
+    let result = match plan.kind {
+        PlanKind::OrMajor => {
+            let mut result = RoaringBitmap::new();
+            for clause in plan.clause_offsets.windows(2) {
+                let labels = &plan.label_ids[clause[0]..clause[1]];
+                if labels.iter().any(Option::is_none) {
+                    continue;
+                }
+                let mut labels = labels.iter().filter_map(|label| *label);
+                let Some(first) = labels.next() else {
+                    continue;
+                };
+                let mut clause_result = postings[first as usize].clone();
+                for label in labels {
+                    clause_result &= &postings[label as usize];
+                    if clause_result.is_empty() {
+                        break;
+                    }
+                }
+                result |= clause_result;
+            }
+            result
+        }
+        PlanKind::AndMajor => {
+            let mut result: Option<RoaringBitmap> = None;
+            for clause in plan.clause_offsets.windows(2) {
+                let mut clause_result = RoaringBitmap::new();
+                for label in plan.label_ids[clause[0]..clause[1]]
+                    .iter()
+                    .filter_map(|label| *label)
+                {
+                    clause_result |= &postings[label as usize];
+                }
+                result = Some(match result {
+                    None => clause_result,
+                    Some(mut result) => {
+                        result &= clause_result;
+                        result
+                    }
+                });
+                if result.as_ref().is_some_and(RoaringBitmap::is_empty) {
+                    break;
+                }
+            }
+            result.unwrap_or_default()
+        }
+    };
+
+    densify(&result, num_vectors)
+}
+
+fn dense_contains(bits: &[u64], vec_id: u32) -> bool {
+    let vec_id = vec_id as usize;
+    bits[vec_id / 64] & (1u64 << (vec_id % 64)) != 0
+}
+
+fn densify(result: &RoaringBitmap, num_vectors: u32) -> Result<Vec<u64>, EncodedLabelIndexError> {
+    let words = (num_vectors as usize).div_ceil(64);
+    let bytes = words.checked_mul(8).ok_or_else(|| {
+        EncodedLabelIndexError::Invalid("dense bitmap byte size overflow".to_string())
+    })?;
+    if bytes > MAX_DENSE_BITMAP_BYTES {
+        return Err(EncodedLabelIndexError::Invalid(format!(
+            "dense query bitmap requires {bytes} bytes; limit is {MAX_DENSE_BITMAP_BYTES}"
+        )));
+    }
+    let mut bits = Vec::new();
+    bits.try_reserve_exact(words).map_err(|_| {
+        EncodedLabelIndexError::Invalid("cannot reserve dense query bitmap".to_string())
+    })?;
+    bits.resize(words, 0);
+    for vec_id in result {
+        let vec_id = vec_id as usize;
+        bits[vec_id / 64] |= 1u64 << (vec_id % 64);
+    }
+    Ok(bits)
+}
+
+fn encode_jsonl(
+    input_path: impl AsRef<Path>,
+    output_path: impl AsRef<Path>,
+    format: LabelIndexFormat,
+) -> Result<(), EncodedLabelIndexError> {
+    let reader = BufReader::new(File::open(input_path)?);
+    let mut labels = Vec::<String>::new();
+    let mut label_ids = HashMap::<String, u32>::new();
+    let mut postings = Vec::<RoaringBitmap>::new();
+    let mut max_doc_id = None::<u32>;
+    let mut seen_doc_ids = HashSet::<u32>::new();
+
+    let mut record_number = 0u32;
+    for line in reader.lines() {
+        let line = line?;
+        if line.trim().is_empty() {
+            continue;
+        }
+        let default_doc_id = record_number;
+        record_number = record_number.checked_add(1).ok_or_else(|| {
+            EncodedLabelIndexError::Invalid("JSONL record count exceeds u32".to_string())
+        })?;
+        let (doc_id, document_labels) = parse_document(&line, default_doc_id)?;
+        if !seen_doc_ids.insert(doc_id) {
+            return Err(EncodedLabelIndexError::Invalid(format!(
+                "duplicate doc_id {doc_id} in label JSONL"
+            )));
+        }
+        max_doc_id = Some(max_doc_id.map_or(doc_id, |current| current.max(doc_id)));
+
+        for label in document_labels {
+            let label_id = if let Some(&label_id) = label_ids.get(&label) {
+                label_id
+            } else {
+                if labels.len() >= MAX_LABEL_COUNT {
+                    return Err(EncodedLabelIndexError::Invalid(format!(
+                        "label count exceeds limit {MAX_LABEL_COUNT}"
+                    )));
+                }
+                let label_id = u32::try_from(labels.len()).map_err(|_| {
+                    EncodedLabelIndexError::Invalid("label count exceeds u32".to_string())
+                })?;
+                label_ids.insert(label.clone(), label_id);
+                labels.push(label);
+                postings.push(RoaringBitmap::new());
+                label_id
+            };
+            postings[label_id as usize].insert(doc_id);
+        }
+    }
+
+    let num_vectors = max_doc_id
+        .and_then(|doc_id| doc_id.checked_add(1))
+        .ok_or_else(|| {
+            EncodedLabelIndexError::Invalid("label JSONL contains no documents".to_string())
+        })?;
+    write_label_index(output_path, format, num_vectors, &labels, &postings)
+}
+
+fn parse_document(
+    line: &str,
+    default_doc_id: u32,
+) -> Result<(u32, Vec<String>), EncodedLabelIndexError> {
+    let value: Value = serde_json::from_str(line)?;
+    match value {
+        Value::String(label) => {
+            validate_label(&label)?;
+            Ok((default_doc_id, vec![label]))
+        }
+        Value::Array(labels) => Ok((
+            default_doc_id,
+            parse_direct_label_array(&labels, "root label array")?,
+        )),
+        Value::Object(fields) => parse_object_document(fields, default_doc_id),
+        _ => Err(EncodedLabelIndexError::Invalid(
+            "each JSONL line must be an object, string, or string array".to_string(),
+        )),
+    }
+}
+
+fn parse_object_document(
+    fields: Map<String, Value>,
+    default_doc_id: u32,
+) -> Result<(u32, Vec<String>), EncodedLabelIndexError> {
+    let doc_id = match fields.get("doc_id") {
+        Some(value) => {
+            let value = value.as_u64().ok_or_else(|| {
+                EncodedLabelIndexError::Invalid("doc_id must be a non-negative integer".to_string())
+            })?;
+            u32::try_from(value)
+                .map_err(|_| EncodedLabelIndexError::Invalid("doc_id exceeds u32".to_string()))?
+        }
+        None => default_doc_id,
+    };
+
+    let mut labels = Vec::new();
+    for (field, value) in fields {
+        if field == "doc_id" {
+            continue;
+        }
+        if field == "labels" {
+            if let Value::Array(values) = &value {
+                labels.extend(parse_direct_label_array(values, "labels field")?);
+                continue;
+            }
+        }
+
+        let label = match value {
+            Value::Bool(true) => field,
+            Value::Bool(false) => format!("{field}=false"),
+            Value::Number(value) => format!("{field}={value}"),
+            Value::String(value) => format!("{field}={value}"),
+            Value::Null => format!("{field}=null"),
+            Value::Array(_) | Value::Object(_) => {
+                return Err(EncodedLabelIndexError::Invalid(format!(
+                    "field '{field}' must contain a scalar value"
+                )));
+            }
+        };
+        validate_label(&label)?;
+        labels.push(label);
+    }
+
+    Ok((doc_id, labels))
+}
+
+fn parse_direct_label_array(
+    values: &[Value],
+    context: &str,
+) -> Result<Vec<String>, EncodedLabelIndexError> {
+    values
+        .iter()
+        .map(|value| {
+            let label = value.as_str().ok_or_else(|| {
+                EncodedLabelIndexError::Invalid(format!("{context} must contain only strings"))
+            })?;
+            validate_label(label)?;
+            Ok(label.to_string())
+        })
+        .collect()
+}
+
+fn validate_label(label: &str) -> Result<(), EncodedLabelIndexError> {
+    if label.is_empty() {
+        return Err(EncodedLabelIndexError::Invalid(
+            "labels cannot be empty".to_string(),
+        ));
+    }
+    if label.contains(['&', '|']) {
+        return Err(EncodedLabelIndexError::Invalid(format!(
+            "label '{label}' contains a reserved filter delimiter"
+        )));
+    }
+    if label.as_bytes().contains(&0) {
+        return Err(EncodedLabelIndexError::Invalid(
+            "labels cannot contain embedded NUL bytes".to_string(),
+        ));
+    }
+    if label.len() > MAX_LABEL_LENGTH {
+        return Err(EncodedLabelIndexError::Invalid(format!(
+            "label length {} exceeds limit {MAX_LABEL_LENGTH}",
+            label.len()
+        )));
+    }
+    if label.trim() != label {
+        return Err(EncodedLabelIndexError::Invalid(
+            "labels cannot have leading or trailing whitespace".to_string(),
+        ));
+    }
+    Ok(())
+}
+
+fn validate_bitslice_padding(
+    bits: &[u64],
+    num_labels: usize,
+    words_per_label: usize,
+    num_vectors: u32,
+) -> Result<(), EncodedLabelIndexError> {
+    let remainder = (num_vectors as usize) % 64;
+    if remainder == 0 || words_per_label == 0 {
+        return Ok(());
+    }
+
+    let valid_mask = (1u64 << remainder) - 1;
+    for label_id in 0..num_labels {
+        let last_word = bits[(label_id + 1) * words_per_label - 1];
+        if last_word & !valid_mask != 0 {
+            return Err(EncodedLabelIndexError::Invalid(
+                "bitslice padding contains out-of-range vector IDs".to_string(),
+            ));
+        }
+    }
+    Ok(())
+}
+
+fn write_label_index(
+    path: impl AsRef<Path>,
+    format: LabelIndexFormat,
+    num_vectors: u32,
+    labels: &[String],
+    postings: &[RoaringBitmap],
+) -> Result<(), EncodedLabelIndexError> {
+    if labels.len() > MAX_LABEL_COUNT {
+        return Err(EncodedLabelIndexError::Invalid(format!(
+            "label count {} exceeds limit {MAX_LABEL_COUNT}",
+            labels.len()
+        )));
+    }
+    if labels.len() != postings.len() {
+        return Err(EncodedLabelIndexError::Invalid(
+            "label dictionary and posting counts differ".to_string(),
+        ));
+    }
+    if num_vectors == 0 {
+        return Err(EncodedLabelIndexError::Invalid(
+            "label-index vector count cannot be zero".to_string(),
+        ));
+    }
+    if format == LabelIndexFormat::Bitmap && u64::from(num_vectors) > MAX_BITMAP_VECTORS {
+        return Err(EncodedLabelIndexError::Invalid(format!(
+            "bitmap vector count {num_vectors} exceeds limit {MAX_BITMAP_VECTORS}"
+        )));
+    }
+
+    let mut writer = BufWriter::new(File::create(path)?);
+    writer.write_all(&LABEL_INDEX_MAGIC)?;
+    write_u32(&mut writer, LABEL_INDEX_VERSION)?;
+    write_u32(&mut writer, format as u32)?;
+    write_u64(&mut writer, u64::from(num_vectors))?;
+    write_u64(&mut writer, labels.len() as u64)?;
+
+    for label in labels {
+        validate_label(label)?;
+        let bytes = label.as_bytes();
+        let len = u32::try_from(bytes.len()).map_err(|_| {
+            EncodedLabelIndexError::Invalid(format!("label '{label}' is too long to encode"))
+        })?;
+        write_u32(&mut writer, len)?;
+        writer.write_all(bytes)?;
+    }
+
+    match format {
+        LabelIndexFormat::Bitslice => {
+            let words_per_label = (num_vectors as usize).div_ceil(64);
+            write_u64(&mut writer, words_per_label as u64)?;
+
+            let total_words = labels.len().checked_mul(words_per_label).ok_or_else(|| {
+                EncodedLabelIndexError::Invalid("bitslice output size overflow".to_string())
+            })?;
+            let mut bits = Vec::new();
+            bits.try_reserve_exact(total_words).map_err(|_| {
+                EncodedLabelIndexError::Invalid("cannot reserve bitslice output".to_string())
+            })?;
+            bits.resize(total_words, 0);
+
+            for (label_id, posting) in postings.iter().enumerate() {
+                let row = &mut bits[label_id * words_per_label..(label_id + 1) * words_per_label];
+                for vec_id in posting {
+                    let vec_id = vec_id as usize;
+                    row[vec_id / 64] |= 1u64 << (vec_id % 64);
+                }
+            }
+
+            for word in bits {
+                write_u64(&mut writer, word)?;
+            }
+        }
+        LabelIndexFormat::Bitmap => {
+            for posting in postings {
+                let serialized_size = posting.serialized_size();
+                if serialized_size > MAX_POSTING_BYTES {
+                    return Err(EncodedLabelIndexError::Invalid(format!(
+                        "serialized posting length {serialized_size} exceeds limit {MAX_POSTING_BYTES}"
+                    )));
+                }
+
+                let mut bytes = Vec::new();
+                bytes.try_reserve_exact(serialized_size).map_err(|_| {
+                    EncodedLabelIndexError::Invalid("cannot reserve serialized posting".to_string())
+                })?;
+                posting.serialize_into(&mut bytes)?;
+                write_u64(&mut writer, bytes.len() as u64)?;
+                writer.write_all(&bytes)?;
+            }
+        }
+    }
+
+    writer.flush()?;
+    Ok(())
+}
+
+fn write_u32(writer: &mut impl Write, value: u32) -> io::Result<()> {
+    writer.write_all(&value.to_le_bytes())
+}
+
+fn write_u64(writer: &mut impl Write, value: u64) -> io::Result<()> {
+    writer.write_all(&value.to_le_bytes())
+}
+
+fn read_u32(reader: &mut impl Read) -> io::Result<u32> {
+    let mut bytes = [0u8; 4];
+    reader.read_exact(&mut bytes)?;
+    Ok(u32::from_le_bytes(bytes))
+}
+
+fn read_u64(reader: &mut impl Read) -> io::Result<u64> {
+    let mut bytes = [0u8; 8];
+    reader.read_exact(&mut bytes)?;
+    Ok(u64::from_le_bytes(bytes))
+}
+
+fn ensure_remaining(
+    reader: &mut BufReader<File>,
+    file_len: u64,
+    required: usize,
+    context: &str,
+) -> Result<(), EncodedLabelIndexError> {
+    let position = reader.stream_position()?;
+    let remaining = file_len.checked_sub(position).ok_or_else(|| {
+        EncodedLabelIndexError::Invalid("reader position exceeds file length".to_string())
+    })?;
+    if required as u64 > remaining {
+        return Err(EncodedLabelIndexError::Invalid(format!(
+            "{context} requires {required} bytes but only {remaining} remain"
+        )));
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs::OpenOptions;
+
+    fn sample_jsonl() -> &'static str {
+        concat!(
+            "{\"doc_id\":0,\"A\":true,\"group\":\"x\"}\n",
+            "{\"doc_id\":1,\"B\":true,\"group\":\"x\"}\n",
+            "{\"doc_id\":2,\"A\":true,\"B\":true,\"score\":2}\n",
+            "{\"doc_id\":3,\"labels\":[\"C\",\"D\"]}\n",
+        )
+    }
+
+    fn compile<'a>(
+        index: &'a EncodedLabelIndex,
+        clauses: &[&str],
+        expression_type: FilterExpressionType,
+    ) -> EncodedLabelQuery<'a> {
+        index.query(clauses, expression_type).unwrap()
+    }
+
+    fn round_trip(format: LabelIndexFormat) -> EncodedLabelIndex {
+        let dir = tempfile::tempdir().unwrap();
+        let input = dir.path().join("labels.jsonl");
+        let output = dir.path().join("labels.bin");
+        std::fs::write(&input, sample_jsonl()).unwrap();
+        encode_label_index_jsonl(&input, &output, format).unwrap();
+        EncodedLabelIndex::load(output).unwrap()
+    }
+
+    #[test]
+    fn bitslice_and_bitmap_match_for_or_major() {
+        for format in [LabelIndexFormat::Bitslice, LabelIndexFormat::Bitmap] {
+            let index = round_trip(format);
+            let query = compile(&index, &["A&B", "C&D"], FilterExpressionType::ORMajor);
+            assert!(!query.is_match(0));
+            assert!(!query.is_match(1));
+            assert!(query.is_match(2));
+            assert!(query.is_match(3));
+        }
+    }
+
+    #[test]
+    fn bitslice_and_bitmap_match_for_and_major() {
+        for format in [LabelIndexFormat::Bitslice, LabelIndexFormat::Bitmap] {
+            let index = round_trip(format);
+            let query = compile(
+                &index,
+                &["A|B", "group=x|score=2"],
+                FilterExpressionType::ANDMajor,
+            );
+            assert!(query.is_match(0));
+            assert!(query.is_match(1));
+            assert!(query.is_match(2));
+            assert!(!query.is_match(3));
+        }
+    }
+
+    #[test]
+    fn query_accepts_owned_strings() {
+        let index = round_trip(LabelIndexFormat::Bitmap);
+        let clauses = vec!["A&B".to_string(), "C&D".to_string()];
+        let query = index
+            .query(&clauses, FilterExpressionType::ORMajor)
+            .unwrap();
+        assert!(!query.is_match(0));
+        assert!(query.is_match(2));
+        assert!(query.is_match(3));
+    }
+
+    #[test]
+    fn unknown_labels_are_non_matches() {
+        let index = round_trip(LabelIndexFormat::Bitslice);
+        let query = compile(&index, &["missing"], FilterExpressionType::ORMajor);
+        for id in 0..4 {
+            assert!(!query.is_match(id));
+        }
+    }
+
+    #[test]
+    fn raw_and_object_jsonl_forms_are_supported() {
+        let dir = tempfile::tempdir().unwrap();
+        let input = dir.path().join("labels.jsonl");
+        let output = dir.path().join("labels.bin");
+        std::fs::write(
+            &input,
+            concat!(
+                "\"solo\"\n",
+                "[\"left\",\"right\"]\n",
+                "{\"doc_id\":4,\"enabled\":true,\"group\":\"g\",\"count\":2,\"deleted\":false,\"labels\":[\"inline\"]}\n",
+            ),
+        )
+        .unwrap();
+
+        encode_label_index_jsonl(&input, &output, LabelIndexFormat::Bitslice).unwrap();
+        let index = EncodedLabelIndex::load(output).unwrap();
+
+        let raw = compile(&index, &["solo"], FilterExpressionType::ORMajor);
+        assert!(raw.is_match(0));
+        assert!(!raw.is_match(1));
+
+        let array = compile(&index, &["left&right"], FilterExpressionType::ORMajor);
+        assert!(array.is_match(1));
+        assert!(!array.is_match(0));
+
+        let object = compile(
+            &index,
+            &["enabled&group=g&count=2&deleted=false&inline"],
+            FilterExpressionType::ORMajor,
+        );
+        assert!(object.is_match(4));
+        assert!(!object.is_match(3));
+    }
+
+    #[test]
+    fn blank_lines_do_not_shift_implicit_document_ids() {
+        let dir = tempfile::tempdir().unwrap();
+        let input = dir.path().join("labels.jsonl");
+        let output = dir.path().join("labels.bin");
+        std::fs::write(&input, "\n\"A\"\n\n\"B\"\n").unwrap();
+        encode_label_index_jsonl(&input, &output, LabelIndexFormat::Bitslice).unwrap();
+        let index = EncodedLabelIndex::load(output).unwrap();
+
+        let a = compile(&index, &["A"], FilterExpressionType::ORMajor);
+        let b = compile(&index, &["B"], FilterExpressionType::ORMajor);
+        assert!(a.is_match(0));
+        assert!(!a.is_match(1));
+        assert!(!b.is_match(0));
+        assert!(b.is_match(1));
+    }
+
+    #[test]
+    fn reserved_delimiters_are_rejected_in_label_files() {
+        let dir = tempfile::tempdir().unwrap();
+        let input = dir.path().join("labels.jsonl");
+        let output = dir.path().join("labels.bin");
+        std::fs::write(&input, "{\"doc_id\":0,\"labels\":[\"A&B\"]}\n").unwrap();
+        assert!(encode_label_index_jsonl(&input, &output, LabelIndexFormat::Bitslice).is_err());
+    }
+
+    #[test]
+    fn embedded_nul_labels_are_rejected() {
+        let dir = tempfile::tempdir().unwrap();
+        let input = dir.path().join("labels.jsonl");
+        let output = dir.path().join("labels.bin");
+        std::fs::write(&input, "{\"doc_id\":0,\"labels\":[\"A\\u0000B\"]}\n").unwrap();
+        assert!(encode_label_index_jsonl(&input, &output, LabelIndexFormat::Bitslice).is_err());
+    }
+
+    #[test]
+    fn labels_with_outer_whitespace_are_rejected() {
+        let dir = tempfile::tempdir().unwrap();
+        let input = dir.path().join("labels.jsonl");
+        let output = dir.path().join("labels.bin");
+        std::fs::write(&input, "{\"doc_id\":0,\"labels\":[\" A\"]}\n").unwrap();
+        assert!(encode_label_index_jsonl(&input, &output, LabelIndexFormat::Bitslice).is_err());
+    }
+
+    #[test]
+    fn duplicate_document_ids_are_rejected() {
+        let dir = tempfile::tempdir().unwrap();
+        let input = dir.path().join("labels.jsonl");
+        let output = dir.path().join("labels.bin");
+        std::fs::write(
+            &input,
+            "{\"doc_id\":0,\"A\":true}\n{\"doc_id\":0,\"B\":true}\n",
+        )
+        .unwrap();
+        assert!(encode_label_index_jsonl(&input, &output, LabelIndexFormat::Bitslice).is_err());
+    }
+
+    #[test]
+    fn load_rejects_invalid_magic() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("labels.bin");
+        std::fs::write(&path, b"not-an-index").unwrap();
+        assert!(EncodedLabelIndex::load(path).is_err());
+    }
+
+    #[test]
+    fn load_rejects_out_of_range_posting_ids() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("labels.bin");
+        let mut posting = RoaringBitmap::new();
+        posting.insert(1);
+        write_label_index(
+            &path,
+            LabelIndexFormat::Bitmap,
+            1,
+            &["A".to_string()],
+            &[posting],
+        )
+        .unwrap();
+        assert!(EncodedLabelIndex::load(path).is_err());
+    }
+
+    #[test]
+    fn load_rejects_excessive_label_count_before_allocation() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("labels.bin");
+        let mut writer = BufWriter::new(File::create(&path).unwrap());
+        writer.write_all(&LABEL_INDEX_MAGIC).unwrap();
+        write_u32(&mut writer, LABEL_INDEX_VERSION).unwrap();
+        write_u32(&mut writer, LabelIndexFormat::Bitslice as u32).unwrap();
+        write_u64(&mut writer, 1).unwrap();
+        write_u64(&mut writer, (MAX_LABEL_COUNT as u64) + 1).unwrap();
+        writer.flush().unwrap();
+        assert!(EncodedLabelIndex::load(path).is_err());
+    }
+
+    #[test]
+    fn load_rejects_set_bits_in_bitslice_padding() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("labels.bin");
+        let mut writer = BufWriter::new(File::create(&path).unwrap());
+        writer.write_all(&LABEL_INDEX_MAGIC).unwrap();
+        write_u32(&mut writer, LABEL_INDEX_VERSION).unwrap();
+        write_u32(&mut writer, LabelIndexFormat::Bitslice as u32).unwrap();
+        write_u64(&mut writer, 1).unwrap();
+        write_u64(&mut writer, 1).unwrap();
+        write_u32(&mut writer, 1).unwrap();
+        writer.write_all(b"A").unwrap();
+        write_u64(&mut writer, 1).unwrap();
+        write_u64(&mut writer, 1u64 << 1).unwrap();
+        writer.flush().unwrap();
+        assert!(EncodedLabelIndex::load(path).is_err());
+    }
+
+    #[test]
+    fn load_rejects_oversized_bitmap_index() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("labels.bin");
+        let oversized_vectors = u32::try_from((MAX_DENSE_BITMAP_BYTES / 8) * 64 + 1).unwrap();
+        let mut writer = BufWriter::new(File::create(&path).unwrap());
+        writer.write_all(&LABEL_INDEX_MAGIC).unwrap();
+        write_u32(&mut writer, LABEL_INDEX_VERSION).unwrap();
+        write_u32(&mut writer, LabelIndexFormat::Bitmap as u32).unwrap();
+        write_u64(&mut writer, u64::from(oversized_vectors)).unwrap();
+        write_u64(&mut writer, 0).unwrap();
+        writer.flush().unwrap();
+
+        assert!(EncodedLabelIndex::load(path).is_err());
+    }
+
+    #[test]
+    fn load_rejects_trailing_bytes() {
+        let dir = tempfile::tempdir().unwrap();
+        let input = dir.path().join("labels.jsonl");
+        let output = dir.path().join("labels.bin");
+        std::fs::write(&input, sample_jsonl()).unwrap();
+        encode_label_index_jsonl(&input, &output, LabelIndexFormat::Bitmap).unwrap();
+
+        let mut file = OpenOptions::new().append(true).open(&output).unwrap();
+        file.write_all(&[0]).unwrap();
+        drop(file);
+
+        assert!(EncodedLabelIndex::load(output).is_err());
+    }
+
+    #[test]
+    fn load_rejects_zero_vector_count() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("labels.bin");
+        let mut writer = BufWriter::new(File::create(&path).unwrap());
+        writer.write_all(&LABEL_INDEX_MAGIC).unwrap();
+        write_u32(&mut writer, LABEL_INDEX_VERSION).unwrap();
+        write_u32(&mut writer, LabelIndexFormat::Bitslice as u32).unwrap();
+        write_u64(&mut writer, 0).unwrap();
+        writer.flush().unwrap();
+        assert!(EncodedLabelIndex::load(path).is_err());
+    }
+}
diff --git a/diskann-label-filter/src/lib.rs b/diskann-label-filter/src/lib.rs
index 5ee39f0d1a..9df157fa1d 100644
--- a/diskann-label-filter/src/lib.rs
+++ b/diskann-label-filter/src/lib.rs
@@ -57,6 +57,7 @@ pub mod tests {
 
 pub mod attribute;
 pub mod document;
+pub mod encoded_label_index;
 pub mod live_filter;
 pub mod query;
 pub mod set;
@@ -68,6 +69,10 @@ pub mod kv_index;
 pub mod stores;
 
 // Re-exports for convenience
+pub use encoded_label_index::{
+    encode_label_index_jsonl, EncodedLabelIndex, EncodedLabelIndexError, EncodedLabelQuery,
+    FilterExpressionType, LabelIndexFormat,
+};
 pub use live_filter::{
     FrozenAttributeIndex, FrozenAttributeIndexAuto, FrozenAttributeIndexBitslice,
     FrozenAttributeIndexCsr, FrozenAttributeIndexPosting, InlineAttributeIndex,

From f3944247faf3e3f32fe9e05b9db8934b618436a6 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Fri, 7 Aug 2026 17:32:03 +0800
Subject: [PATCH 17/25] diskann-label-index: isolate encoded label storage

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 Cargo.lock                                    | 13 +++++++++++-
 Cargo.toml                                    |  4 +++-
 diskann-label-filter/Cargo.toml               |  2 +-
 diskann-label-filter/src/lib.rs               |  5 -----
 diskann-label-index/Cargo.toml                | 21 +++++++++++++++++++
 .../src/lib.rs                                |  2 +-
 6 files changed, 38 insertions(+), 9 deletions(-)
 create mode 100644 diskann-label-index/Cargo.toml
 rename diskann-label-filter/src/encoded_label_index.rs => diskann-label-index/src/lib.rs (99%)

diff --git a/Cargo.lock b/Cargo.lock
index b91d7e4801..c8973a14c6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -645,7 +645,7 @@ dependencies = [
 
 [[package]]
 name = "diskann-label-filter"
-version = "0.55.1-pre.1"
+version = "0.55.0"
 dependencies = [
  "anyhow",
  "bf-tree",
@@ -666,6 +666,17 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "diskann-label-index"
+version = "0.55.1-pre.1"
+dependencies = [
+ "diskann",
+ "roaring",
+ "serde_json",
+ "tempfile",
+ "thiserror 2.0.17",
+]
+
 [[package]]
 name = "diskann-linalg"
 version = "0.55.0"
diff --git a/Cargo.toml b/Cargo.toml
index 359ad79ee1..df3ad50a4f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -17,6 +17,7 @@ members = [
     "diskann-providers",
     "diskann-disk",
     "diskann-label-filter",
+    "diskann-label-index",
     "diskann-garnet",
     "diskann-inmem",
     # Infrastructure
@@ -63,7 +64,8 @@ diskann = { path = "diskann", version = "0.55.0" }
 diskann-providers = { path = "diskann-providers", default-features = false, version = "0.55.0" }
 diskann-inmem = { path = "diskann-inmem", default-features = false, version = "0.55.0" }
 diskann-disk = { path = "diskann-disk", version = "0.55.0" }
-diskann-label-filter = { path = "diskann-label-filter", version = "0.55.1-pre.1" }
+diskann-label-filter = { path = "diskann-label-filter", version = "0.55.0" }
+diskann-label-index = { path = "diskann-label-index", version = "0.55.1-pre.1" }
 # Infra
 diskann-benchmark-runner = { path = "diskann-benchmark-runner", version = "0.55.0" }
 diskann-benchmark-core = { path = "diskann-benchmark-core", version = "0.55.0" }
diff --git a/diskann-label-filter/Cargo.toml b/diskann-label-filter/Cargo.toml
index dbe2449ca1..14102411ec 100644
--- a/diskann-label-filter/Cargo.toml
+++ b/diskann-label-filter/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "diskann-label-filter"
-version = "0.55.1-pre.1"
+version.workspace = true
 description.workspace = true
 authors.workspace = true
 repository.workspace = true
diff --git a/diskann-label-filter/src/lib.rs b/diskann-label-filter/src/lib.rs
index 9df157fa1d..5ee39f0d1a 100644
--- a/diskann-label-filter/src/lib.rs
+++ b/diskann-label-filter/src/lib.rs
@@ -57,7 +57,6 @@ pub mod tests {
 
 pub mod attribute;
 pub mod document;
-pub mod encoded_label_index;
 pub mod live_filter;
 pub mod query;
 pub mod set;
@@ -69,10 +68,6 @@ pub mod kv_index;
 pub mod stores;
 
 // Re-exports for convenience
-pub use encoded_label_index::{
-    encode_label_index_jsonl, EncodedLabelIndex, EncodedLabelIndexError, EncodedLabelQuery,
-    FilterExpressionType, LabelIndexFormat,
-};
 pub use live_filter::{
     FrozenAttributeIndex, FrozenAttributeIndexAuto, FrozenAttributeIndexBitslice,
     FrozenAttributeIndexCsr, FrozenAttributeIndexPosting, InlineAttributeIndex,
diff --git a/diskann-label-index/Cargo.toml b/diskann-label-index/Cargo.toml
new file mode 100644
index 0000000000..a2e85b790f
--- /dev/null
+++ b/diskann-label-index/Cargo.toml
@@ -0,0 +1,21 @@
+[package]
+name = "diskann-label-index"
+version = "0.55.1-pre.1"
+description.workspace = true
+authors.workspace = true
+repository.workspace = true
+license.workspace = true
+edition.workspace = true
+
+[lints]
+clippy.undocumented_unsafe_blocks = "warn"
+clippy.uninlined_format_args = "allow"
+
+[dependencies]
+diskann.workspace = true
+roaring.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
diff --git a/diskann-label-filter/src/encoded_label_index.rs b/diskann-label-index/src/lib.rs
similarity index 99%
rename from diskann-label-filter/src/encoded_label_index.rs
rename to diskann-label-index/src/lib.rs
index ec2affdf2e..58cda63894 100644
--- a/diskann-label-filter/src/encoded_label_index.rs
+++ b/diskann-label-index/src/lib.rs
@@ -3,7 +3,7 @@
  * Licensed under the MIT license.
  */
 
-//! Versioned on-disk label-index encoding, loading, and query evaluation.
+//! Versioned on-disk label-index encoding, loading, and query evaluation for DiskANN.
 
 use diskann::graph::ext::labeled::QueryLabelProvider;
 use roaring::RoaringBitmap;

From 7b51f7ebc04242689c11c2ab2078b43181c81751 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Fri, 7 Aug 2026 18:00:38 +0800
Subject: [PATCH 18/25] diskann-label-index: decouple query storage

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 Cargo.lock                     | 1 -
 diskann-label-index/Cargo.toml | 1 -
 diskann-label-index/src/lib.rs | 6 +++---
 3 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index c8973a14c6..2d34ff849e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -670,7 +670,6 @@ dependencies = [
 name = "diskann-label-index"
 version = "0.55.1-pre.1"
 dependencies = [
- "diskann",
  "roaring",
  "serde_json",
  "tempfile",
diff --git a/diskann-label-index/Cargo.toml b/diskann-label-index/Cargo.toml
index a2e85b790f..d6c18722b9 100644
--- a/diskann-label-index/Cargo.toml
+++ b/diskann-label-index/Cargo.toml
@@ -12,7 +12,6 @@ clippy.undocumented_unsafe_blocks = "warn"
 clippy.uninlined_format_args = "allow"
 
 [dependencies]
-diskann.workspace = true
 roaring.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
diff --git a/diskann-label-index/src/lib.rs b/diskann-label-index/src/lib.rs
index 58cda63894..e6166c490d 100644
--- a/diskann-label-index/src/lib.rs
+++ b/diskann-label-index/src/lib.rs
@@ -5,7 +5,6 @@
 
 //! Versioned on-disk label-index encoding, loading, and query evaluation for DiskANN.
 
-use diskann::graph::ext::labeled::QueryLabelProvider;
 use roaring::RoaringBitmap;
 use serde_json::{Map, Value};
 use std::{
@@ -132,8 +131,9 @@ impl std::fmt::Debug for EncodedLabelQuery<'_> {
     }
 }
 
-impl QueryLabelProvider<u32> for EncodedLabelQuery<'_> {
-    fn is_match(&self, vec_id: u32) -> bool {
+impl EncodedLabelQuery<'_> {
+    /// Return whether `vec_id` satisfies this compiled label query.
+    pub fn is_match(&self, vec_id: u32) -> bool {
         if vec_id >= self.num_vectors {
             return false;
         }

From a6451b847375cdf0dbb140f5a64c6c3eac62b229 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Sun, 9 Aug 2026 16:01:29 +0800
Subject: [PATCH 19/25] diskann-label-index: add AST query expressions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 Cargo.lock                     |   1 +
 diskann-label-index/Cargo.toml |   1 +
 diskann-label-index/src/lib.rs | 695 +++++++++++++++++++++++++++++++--
 3 files changed, 655 insertions(+), 42 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 2d34ff849e..e90f11a2c8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -671,6 +671,7 @@ name = "diskann-label-index"
 version = "0.55.1-pre.1"
 dependencies = [
  "roaring",
+ "serde",
  "serde_json",
  "tempfile",
  "thiserror 2.0.17",
diff --git a/diskann-label-index/Cargo.toml b/diskann-label-index/Cargo.toml
index d6c18722b9..7ebe73cf90 100644
--- a/diskann-label-index/Cargo.toml
+++ b/diskann-label-index/Cargo.toml
@@ -13,6 +13,7 @@ clippy.uninlined_format_args = "allow"
 
 [dependencies]
 roaring.workspace = true
+serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
 
diff --git a/diskann-label-index/src/lib.rs b/diskann-label-index/src/lib.rs
index e6166c490d..d5566735fa 100644
--- a/diskann-label-index/src/lib.rs
+++ b/diskann-label-index/src/lib.rs
@@ -6,6 +6,7 @@
 //! Versioned on-disk label-index encoding, loading, and query evaluation for DiskANN.
 
 use roaring::RoaringBitmap;
+use serde::de::{self, DeserializeSeed, Deserializer, MapAccess, SeqAccess, Visitor};
 use serde_json::{Map, Value};
 use std::{
     collections::{HashMap, HashSet},
@@ -22,6 +23,8 @@ const MAX_LABEL_LENGTH: usize = 1 << 20;
 const MAX_POSTING_BYTES: usize = 512 << 20;
 const MAX_DENSE_BITMAP_BYTES: usize = 256 << 20;
 const MAX_BITMAP_VECTORS: u64 = (MAX_DENSE_BITMAP_BYTES as u64) * 8;
+const MAX_LABEL_EXPRESSION_DEPTH: usize = 64;
+const MAX_LABEL_EXPRESSION_NODES: usize = 4096;
 
 /// The persisted label-index storage format.
 #[repr(u32)]
@@ -40,10 +43,233 @@ pub enum LabelIndexFormat {
 pub enum FilterExpressionType {
     /// Outer OR with `&`-separated labels inside each string:
     /// `["A&B", "C&D"]` means `(A AND B) OR (C AND D)`.
-    ORMajor = 0,
+    DNF = 0,
     /// Outer AND with `|`-separated labels inside each string:
     /// `["A|B", "C|D"]` means `(A OR B) AND (C OR D)`.
-    ANDMajor = 1,
+    CNF = 1,
+    /// Exactly one JSON string containing a recursive abstract syntax tree.
+    AST = 2,
+}
+
+impl FilterExpressionType {
+    /// Backward-compatible alias for [`FilterExpressionType::DNF`].
+    #[allow(non_upper_case_globals)]
+    pub const ORMajor: Self = Self::DNF;
+
+    /// Backward-compatible alias for [`FilterExpressionType::CNF`].
+    #[allow(non_upper_case_globals)]
+    pub const ANDMajor: Self = Self::CNF;
+}
+
+/// A crate-owned Boolean label expression tree.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LabelExpression {
+    /// A terminal label.
+    Label(String),
+    /// A conjunction of child expressions.
+    And(Vec<LabelExpression>),
+    /// A disjunction of child expressions.
+    Or(Vec<LabelExpression>),
+    /// A negated child expression.
+    Not(Box<LabelExpression>),
+}
+
+struct LabelExpressionBudget {
+    remaining_nodes: usize,
+}
+
+impl LabelExpressionBudget {
+    fn new() -> Self {
+        Self {
+            remaining_nodes: MAX_LABEL_EXPRESSION_NODES,
+        }
+    }
+
+    fn reserve<E>(&mut self, depth: usize) -> Result<(), E>
+    where
+        E: de::Error,
+    {
+        if depth > MAX_LABEL_EXPRESSION_DEPTH {
+            return Err(E::custom(format!(
+                "label expression depth {depth} exceeds limit {MAX_LABEL_EXPRESSION_DEPTH}"
+            )));
+        }
+
+        if self.remaining_nodes == 0 {
+            let node_count = MAX_LABEL_EXPRESSION_NODES + 1;
+            return Err(E::custom(format!(
+                "label expression node count {node_count} exceeds limit {MAX_LABEL_EXPRESSION_NODES}"
+            )));
+        }
+
+        self.remaining_nodes -= 1;
+        Ok(())
+    }
+}
+
+struct LabelExpressionSeed<'a> {
+    budget: &'a mut LabelExpressionBudget,
+    depth: usize,
+}
+
+impl<'a, 'de> DeserializeSeed<'de> for LabelExpressionSeed<'a> {
+    type Value = LabelExpression;
+
+    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        deserializer.deserialize_any(LabelExpressionVisitor {
+            budget: self.budget,
+            depth: self.depth,
+        })
+    }
+}
+
+struct LabelExpressionVisitor<'a> {
+    budget: &'a mut LabelExpressionBudget,
+    depth: usize,
+}
+
+impl<'de> Visitor<'de> for LabelExpressionVisitor<'_> {
+    type Value = LabelExpression;
+
+    fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str("a label string or a one-key and/or/not object")
+    }
+
+    fn visit_borrowed_str<E>(self, value: &'de str) -> Result<Self::Value, E>
+    where
+        E: de::Error,
+    {
+        self.visit_str(value)
+    }
+
+    fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
+    where
+        E: de::Error,
+    {
+        self.budget.reserve::<E>(self.depth)?;
+        validate_label(value).map_err(E::custom)?;
+        Ok(LabelExpression::Label(value.to_string()))
+    }
+
+    fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
+    where
+        E: de::Error,
+    {
+        self.budget.reserve::<E>(self.depth)?;
+        validate_label(&value).map_err(E::custom)?;
+        Ok(LabelExpression::Label(value))
+    }
+
+    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
+    where
+        A: MapAccess<'de>,
+    {
+        let LabelExpressionVisitor { budget, depth } = self;
+        budget.reserve::<A::Error>(depth)?;
+
+        let Some(operator) = map.next_key::<String>()? else {
+            return Err(de::Error::custom(
+                "label expression objects must contain exactly one operator",
+            ));
+        };
+
+        let child_depth = depth + 1;
+        let expression = match operator.as_str() {
+            "and" | "$and" => {
+                LabelExpression::And(map.next_value_seed(LabelExpressionArraySeed {
+                    budget,
+                    depth: child_depth,
+                    operator: "and",
+                })?)
+            }
+            "or" | "$or" => LabelExpression::Or(map.next_value_seed(LabelExpressionArraySeed {
+                budget,
+                depth: child_depth,
+                operator: "or",
+            })?),
+            "not" | "$not" => {
+                LabelExpression::Not(Box::new(map.next_value_seed(LabelExpressionSeed {
+                    budget,
+                    depth: child_depth,
+                })?))
+            }
+            _ => {
+                return Err(de::Error::custom(format!(
+                    "unsupported label expression operator '{operator}'"
+                )));
+            }
+        };
+
+        if map.next_key::<String>()?.is_some() {
+            return Err(de::Error::custom(
+                "label expression objects must contain exactly one operator",
+            ));
+        }
+
+        Ok(expression)
+    }
+}
+
+struct LabelExpressionArraySeed<'a> {
+    budget: &'a mut LabelExpressionBudget,
+    depth: usize,
+    operator: &'static str,
+}
+
+impl<'a, 'de> DeserializeSeed<'de> for LabelExpressionArraySeed<'a> {
+    type Value = Vec<LabelExpression>;
+
+    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        deserializer.deserialize_seq(LabelExpressionArrayVisitor {
+            budget: self.budget,
+            depth: self.depth,
+            operator: self.operator,
+        })
+    }
+}
+
+struct LabelExpressionArrayVisitor<'a> {
+    budget: &'a mut LabelExpressionBudget,
+    depth: usize,
+    operator: &'static str,
+}
+
+impl<'de> Visitor<'de> for LabelExpressionArrayVisitor<'_> {
+    type Value = Vec<LabelExpression>;
+
+    fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str("a non-empty array of label expressions")
+    }
+
+    fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
+    where
+        A: SeqAccess<'de>,
+    {
+        let LabelExpressionArrayVisitor {
+            budget,
+            depth,
+            operator,
+        } = self;
+        let Some(first) = seq.next_element_seed(LabelExpressionSeed { budget, depth })? else {
+            return Err(de::Error::custom(format!(
+                "label expression '{}' array cannot be empty",
+                operator
+            )));
+        };
+
+        let mut children = vec![first];
+        while let Some(child) = seq.next_element_seed(LabelExpressionSeed { budget, depth })? {
+            children.push(child);
+        }
+
+        Ok(children)
+    }
 }
 
 #[derive(Debug, Error)]
@@ -86,17 +312,8 @@ impl std::fmt::Debug for EncodedLabelIndex {
 
 #[derive(Debug, Clone, Copy)]
 enum PlanKind {
-    OrMajor,
-    AndMajor,
-}
-
-impl From<FilterExpressionType> for PlanKind {
-    fn from(value: FilterExpressionType) -> Self {
-        match value {
-            FilterExpressionType::ORMajor => Self::OrMajor,
-            FilterExpressionType::ANDMajor => Self::AndMajor,
-        }
-    }
+    Dnf,
+    Cnf,
 }
 
 #[derive(Debug)]
@@ -106,11 +323,20 @@ struct CompiledPlan {
     label_ids: Box<[Option<u32>]>,
 }
 
+#[derive(Debug)]
+enum CompiledExpression {
+    Flat(CompiledPlan),
+    Label(Option<u32>),
+    And(Box<[CompiledExpression]>),
+    Or(Box<[CompiledExpression]>),
+    Not(Box<CompiledExpression>),
+}
+
 enum QueryStorage<'a> {
     Bitslice {
         words_per_label: usize,
         bits: &'a [u64],
-        plan: CompiledPlan,
+        expression: CompiledExpression,
     },
     DenseBitmap {
         bits: Box<[u64]>,
@@ -142,8 +368,8 @@ impl EncodedLabelQuery<'_> {
             QueryStorage::Bitslice {
                 words_per_label,
                 bits,
-                plan,
-            } => plan.matches_bitslice(*words_per_label, bits, vec_id),
+                expression,
+            } => expression.matches_bitslice(*words_per_label, bits, vec_id),
             QueryStorage::DenseBitmap { bits } => dense_contains(bits, vec_id),
         }
     }
@@ -161,13 +387,13 @@ impl CompiledPlan {
         };
 
         match self.kind {
-            PlanKind::OrMajor => self.clause_offsets.windows(2).any(|clause| {
+            PlanKind::Dnf => self.clause_offsets.windows(2).any(|clause| {
                 self.label_ids[clause[0]..clause[1]]
                     .iter()
                     .copied()
                     .all(terminal_matches)
             }),
-            PlanKind::AndMajor => self.clause_offsets.windows(2).all(|clause| {
+            PlanKind::Cnf => self.clause_offsets.windows(2).all(|clause| {
                 self.label_ids[clause[0]..clause[1]]
                     .iter()
                     .copied()
@@ -177,6 +403,27 @@ impl CompiledPlan {
     }
 }
 
+impl CompiledExpression {
+    fn matches_bitslice(&self, words_per_label: usize, bits: &[u64], vec_id: u32) -> bool {
+        match self {
+            Self::Flat(plan) => plan.matches_bitslice(words_per_label, bits, vec_id),
+            Self::Label(label_id) => label_id.is_some_and(|label_id| {
+                let label_id = label_id as usize;
+                let vec_id = vec_id as usize;
+                let word = bits[label_id * words_per_label + vec_id / 64];
+                word & (1u64 << (vec_id % 64)) != 0
+            }),
+            Self::And(children) => children
+                .iter()
+                .all(|child| child.matches_bitslice(words_per_label, bits, vec_id)),
+            Self::Or(children) => children
+                .iter()
+                .any(|child| child.matches_bitslice(words_per_label, bits, vec_id)),
+            Self::Not(child) => !child.matches_bitslice(words_per_label, bits, vec_id),
+        }
+    }
+}
+
 impl EncodedLabelIndex {
     pub fn load(path: impl AsRef<Path>) -> Result<Self, EncodedLabelIndexError> {
         let file = File::open(path)?;
@@ -376,8 +623,48 @@ impl EncodedLabelIndex {
     where
         S: AsRef<str>,
     {
-        let plan = compile_plan(clauses, expression_type.into(), &self.label_ids)?;
+        let expression = match expression_type {
+            FilterExpressionType::DNF => {
+                CompiledExpression::Flat(compile_plan(clauses, PlanKind::Dnf, &self.label_ids)?)
+            }
+            FilterExpressionType::CNF => {
+                CompiledExpression::Flat(compile_plan(clauses, PlanKind::Cnf, &self.label_ids)?)
+            }
+            FilterExpressionType::AST => {
+                if clauses.len() != 1 {
+                    return Err(EncodedLabelIndexError::Invalid(
+                        "AST filters must contain exactly one JSON expression string".to_string(),
+                    ));
+                }
+                let expression = parse_label_expression_json(clauses[0].as_ref())?;
+                compile_label_expression(&expression, &self.label_ids)?
+            }
+        };
+
+        self.build_query(expression)
+    }
+
+    /// Compile a query from a recursive label expression.
+    pub fn query_expression(
+        &self,
+        expression: &LabelExpression,
+    ) -> Result<EncodedLabelQuery<'_>, EncodedLabelIndexError> {
+        self.build_query(compile_label_expression(expression, &self.label_ids)?)
+    }
+
+    /// Compile a query from a JSON-encoded recursive label expression.
+    pub fn query_ast_json(
+        &self,
+        expression_json: &str,
+    ) -> Result<EncodedLabelQuery<'_>, EncodedLabelIndexError> {
+        let expression = parse_label_expression_json(expression_json)?;
+        self.query_expression(&expression)
+    }
 
+    fn build_query(
+        &self,
+        expression: CompiledExpression,
+    ) -> Result<EncodedLabelQuery<'_>, EncodedLabelIndexError> {
         let storage = match &self.storage {
             LabelStorage::Bitslice {
                 words_per_label,
@@ -385,10 +672,11 @@ impl EncodedLabelIndex {
             } => QueryStorage::Bitslice {
                 words_per_label: *words_per_label,
                 bits,
-                plan,
+                expression,
             },
             LabelStorage::Bitmap { postings } => QueryStorage::DenseBitmap {
-                bits: materialize_bitmap(&plan, postings, self.num_vectors)?.into_boxed_slice(),
+                bits: materialize_bitmap(&expression, postings, self.num_vectors)?
+                    .into_boxed_slice(),
             },
         };
 
@@ -422,6 +710,22 @@ pub fn encode_label_index_jsonl(
     encode_jsonl(input_path, output_path, format)
 }
 
+/// Parse a JSON-encoded recursive label expression.
+pub fn parse_label_expression_json(
+    expression_json: &str,
+) -> Result<LabelExpression, EncodedLabelIndexError> {
+    let mut deserializer = serde_json::Deserializer::from_str(expression_json);
+    let mut budget = LabelExpressionBudget::new();
+    let expression = LabelExpressionSeed {
+        budget: &mut budget,
+        depth: 1,
+    }
+    .deserialize(&mut deserializer)?;
+    deserializer.end()?;
+    validate_label_expression(&expression)?;
+    Ok(expression)
+}
+
 fn compile_plan<S: AsRef<str>>(
     clauses: &[S],
     kind: PlanKind,
@@ -434,8 +738,8 @@ fn compile_plan<S: AsRef<str>>(
     }
 
     let delimiter = match kind {
-        PlanKind::OrMajor => '&',
-        PlanKind::AndMajor => '|',
+        PlanKind::Dnf => '&',
+        PlanKind::Cnf => '|',
     };
     let mut clause_offsets = vec![0usize];
     let mut encoded = Vec::new();
@@ -463,13 +767,139 @@ fn compile_plan<S: AsRef<str>>(
     })
 }
 
+fn compile_label_expression(
+    expression: &LabelExpression,
+    label_ids: &HashMap<String, u32>,
+) -> Result<CompiledExpression, EncodedLabelIndexError> {
+    validate_label_expression(expression)?;
+    Ok(compile_label_expression_inner(expression, label_ids))
+}
+
+fn compile_label_expression_inner(
+    expression: &LabelExpression,
+    label_ids: &HashMap<String, u32>,
+) -> CompiledExpression {
+    match expression {
+        LabelExpression::Label(label) => CompiledExpression::Label(label_ids.get(label).copied()),
+        LabelExpression::And(children) => CompiledExpression::And(
+            children
+                .iter()
+                .map(|child| compile_label_expression_inner(child, label_ids))
+                .collect::<Vec<_>>()
+                .into_boxed_slice(),
+        ),
+        LabelExpression::Or(children) => CompiledExpression::Or(
+            children
+                .iter()
+                .map(|child| compile_label_expression_inner(child, label_ids))
+                .collect::<Vec<_>>()
+                .into_boxed_slice(),
+        ),
+        LabelExpression::Not(child) => {
+            CompiledExpression::Not(Box::new(compile_label_expression_inner(child, label_ids)))
+        }
+    }
+}
+
+fn validate_label_expression(expression: &LabelExpression) -> Result<(), EncodedLabelIndexError> {
+    let mut node_count = 0usize;
+    let mut stack = vec![(expression, 1usize)];
+
+    while let Some((expression, depth)) = stack.pop() {
+        if depth > MAX_LABEL_EXPRESSION_DEPTH {
+            return Err(EncodedLabelIndexError::Invalid(format!(
+                "label expression depth {depth} exceeds limit {MAX_LABEL_EXPRESSION_DEPTH}"
+            )));
+        }
+
+        node_count += 1;
+        if node_count > MAX_LABEL_EXPRESSION_NODES {
+            return Err(EncodedLabelIndexError::Invalid(format!(
+                "label expression node count {node_count} exceeds limit {MAX_LABEL_EXPRESSION_NODES}"
+            )));
+        }
+
+        match expression {
+            LabelExpression::Label(label) => validate_label(label)?,
+            LabelExpression::And(children) => {
+                if children.is_empty() {
+                    return Err(EncodedLabelIndexError::Invalid(
+                        "label expression 'and' array cannot be empty".to_string(),
+                    ));
+                }
+                stack.extend(children.iter().rev().map(|child| (child, depth + 1)));
+            }
+            LabelExpression::Or(children) => {
+                if children.is_empty() {
+                    return Err(EncodedLabelIndexError::Invalid(
+                        "label expression 'or' array cannot be empty".to_string(),
+                    ));
+                }
+                stack.extend(children.iter().rev().map(|child| (child, depth + 1)));
+            }
+            LabelExpression::Not(child) => stack.push((child.as_ref(), depth + 1)),
+        }
+    }
+
+    Ok(())
+}
+
 fn materialize_bitmap(
-    plan: &CompiledPlan,
+    expression: &CompiledExpression,
     postings: &[RoaringBitmap],
     num_vectors: u32,
 ) -> Result<Vec<u64>, EncodedLabelIndexError> {
-    let result = match plan.kind {
-        PlanKind::OrMajor => {
+    let result = materialize_bitmap_expression(expression, postings, num_vectors)?;
+    densify(&result, num_vectors)
+}
+
+fn materialize_bitmap_expression(
+    expression: &CompiledExpression,
+    postings: &[RoaringBitmap],
+    num_vectors: u32,
+) -> Result<RoaringBitmap, EncodedLabelIndexError> {
+    match expression {
+        CompiledExpression::Flat(plan) => Ok(materialize_bitmap_plan(plan, postings)),
+        CompiledExpression::Label(Some(label_id)) => Ok(postings[*label_id as usize].clone()),
+        CompiledExpression::Label(None) => Ok(RoaringBitmap::new()),
+        CompiledExpression::And(children) => {
+            let Some((first, rest)) = children.split_first() else {
+                return Err(EncodedLabelIndexError::Invalid(
+                    "label expression 'and' array cannot be empty".to_string(),
+                ));
+            };
+            let mut result = materialize_bitmap_expression(first, postings, num_vectors)?;
+            for child in rest {
+                result &= materialize_bitmap_expression(child, postings, num_vectors)?;
+                if result.is_empty() {
+                    break;
+                }
+            }
+            Ok(result)
+        }
+        CompiledExpression::Or(children) => {
+            if children.is_empty() {
+                return Err(EncodedLabelIndexError::Invalid(
+                    "label expression 'or' array cannot be empty".to_string(),
+                ));
+            }
+            let mut result = RoaringBitmap::new();
+            for child in children.iter() {
+                result |= materialize_bitmap_expression(child, postings, num_vectors)?;
+            }
+            Ok(result)
+        }
+        CompiledExpression::Not(child) => {
+            let mut result = full_bitmap(num_vectors);
+            result -= materialize_bitmap_expression(child, postings, num_vectors)?;
+            Ok(result)
+        }
+    }
+}
+
+fn materialize_bitmap_plan(plan: &CompiledPlan, postings: &[RoaringBitmap]) -> RoaringBitmap {
+    match plan.kind {
+        PlanKind::Dnf => {
             let mut result = RoaringBitmap::new();
             for clause in plan.clause_offsets.windows(2) {
                 let labels = &plan.label_ids[clause[0]..clause[1]];
@@ -491,7 +921,7 @@ fn materialize_bitmap(
             }
             result
         }
-        PlanKind::AndMajor => {
+        PlanKind::Cnf => {
             let mut result: Option<RoaringBitmap> = None;
             for clause in plan.clause_offsets.windows(2) {
                 let mut clause_result = RoaringBitmap::new();
@@ -514,9 +944,13 @@ fn materialize_bitmap(
             }
             result.unwrap_or_default()
         }
-    };
+    }
+}
 
-    densify(&result, num_vectors)
+fn full_bitmap(num_vectors: u32) -> RoaringBitmap {
+    let mut result = RoaringBitmap::new();
+    result.insert_range(0..num_vectors);
+    result
 }
 
 fn dense_contains(bits: &[u64], vec_id: u32) -> bool {
@@ -897,6 +1331,12 @@ mod tests {
         index.query(clauses, expression_type).unwrap()
     }
 
+    fn matching_ids(query: &EncodedLabelQuery<'_>, num_vectors: u32) -> Vec<u32> {
+        (0..num_vectors)
+            .filter(|&vec_id| query.is_match(vec_id))
+            .collect()
+    }
+
     fn round_trip(format: LabelIndexFormat) -> EncodedLabelIndex {
         let dir = tempfile::tempdir().unwrap();
         let input = dir.path().join("labels.jsonl");
@@ -906,11 +1346,27 @@ mod tests {
         EncodedLabelIndex::load(output).unwrap()
     }
 
+    fn nested_not_expression(wrappings: usize) -> LabelExpression {
+        let mut expression = LabelExpression::Label("A".to_string());
+        for _ in 0..wrappings {
+            expression = LabelExpression::Not(Box::new(expression));
+        }
+        expression
+    }
+
+    fn nested_not_json(wrappings: usize) -> String {
+        let mut expression_json = "\"A\"".to_string();
+        for _ in 0..wrappings {
+            expression_json = format!(r#"{{"not":{expression_json}}}"#);
+        }
+        expression_json
+    }
+
     #[test]
-    fn bitslice_and_bitmap_match_for_or_major() {
+    fn bitslice_and_bitmap_match_for_dnf() {
         for format in [LabelIndexFormat::Bitslice, LabelIndexFormat::Bitmap] {
             let index = round_trip(format);
-            let query = compile(&index, &["A&B", "C&D"], FilterExpressionType::ORMajor);
+            let query = compile(&index, &["A&B", "C&D"], FilterExpressionType::DNF);
             assert!(!query.is_match(0));
             assert!(!query.is_match(1));
             assert!(query.is_match(2));
@@ -919,13 +1375,13 @@ mod tests {
     }
 
     #[test]
-    fn bitslice_and_bitmap_match_for_and_major() {
+    fn bitslice_and_bitmap_match_for_cnf() {
         for format in [LabelIndexFormat::Bitslice, LabelIndexFormat::Bitmap] {
             let index = round_trip(format);
             let query = compile(
                 &index,
                 &["A|B", "group=x|score=2"],
-                FilterExpressionType::ANDMajor,
+                FilterExpressionType::CNF,
             );
             assert!(query.is_match(0));
             assert!(query.is_match(1));
@@ -938,9 +1394,7 @@ mod tests {
     fn query_accepts_owned_strings() {
         let index = round_trip(LabelIndexFormat::Bitmap);
         let clauses = vec!["A&B".to_string(), "C&D".to_string()];
-        let query = index
-            .query(&clauses, FilterExpressionType::ORMajor)
-            .unwrap();
+        let query = index.query(&clauses, FilterExpressionType::DNF).unwrap();
         assert!(!query.is_match(0));
         assert!(query.is_match(2));
         assert!(query.is_match(3));
@@ -949,12 +1403,169 @@ mod tests {
     #[test]
     fn unknown_labels_are_non_matches() {
         let index = round_trip(LabelIndexFormat::Bitslice);
-        let query = compile(&index, &["missing"], FilterExpressionType::ORMajor);
+        let query = compile(&index, &["missing"], FilterExpressionType::DNF);
         for id in 0..4 {
             assert!(!query.is_match(id));
         }
     }
 
+    #[test]
+    fn ast_matches_nested_expression_for_bitslice_and_bitmap() {
+        let expression = r#"{"or":[{"and":["A","B"]},{"and":["C","D"]}]}"#;
+
+        for format in [LabelIndexFormat::Bitslice, LabelIndexFormat::Bitmap] {
+            let index = round_trip(format);
+            let query = index.query_ast_json(expression).unwrap();
+            assert_eq!(matching_ids(&query, index.num_vectors), vec![2, 3]);
+        }
+    }
+
+    #[test]
+    fn ast_matches_equivalent_dnf_and_cnf_queries() {
+        for format in [LabelIndexFormat::Bitslice, LabelIndexFormat::Bitmap] {
+            let index = round_trip(format);
+
+            let dnf = compile(&index, &["A&B", "C&D"], FilterExpressionType::DNF);
+            let ast_dnf = index
+                .query_ast_json(r#"{"or":[{"and":["A","B"]},{"and":["C","D"]}]}"#)
+                .unwrap();
+            assert_eq!(
+                matching_ids(&dnf, index.num_vectors),
+                matching_ids(&ast_dnf, index.num_vectors)
+            );
+
+            let cnf = compile(
+                &index,
+                &["A|B", "group=x|score=2"],
+                FilterExpressionType::CNF,
+            );
+            let ast_cnf = index
+                .query_expression(&LabelExpression::And(vec![
+                    LabelExpression::Or(vec![
+                        LabelExpression::Label("A".to_string()),
+                        LabelExpression::Label("B".to_string()),
+                    ]),
+                    LabelExpression::Or(vec![
+                        LabelExpression::Label("group=x".to_string()),
+                        LabelExpression::Label("score=2".to_string()),
+                    ]),
+                ]))
+                .unwrap();
+            assert_eq!(
+                matching_ids(&cnf, index.num_vectors),
+                matching_ids(&ast_cnf, index.num_vectors)
+            );
+        }
+    }
+
+    #[test]
+    fn ast_not_supports_known_and_unknown_labels() {
+        for format in [LabelIndexFormat::Bitslice, LabelIndexFormat::Bitmap] {
+            let index = round_trip(format);
+
+            let not_a = index.query_ast_json(r#"{"not":"A"}"#).unwrap();
+            assert_eq!(matching_ids(&not_a, index.num_vectors), vec![1, 3]);
+
+            let not_missing = index.query_ast_json(r#"{"not":"missing"}"#).unwrap();
+            assert_eq!(
+                matching_ids(&not_missing, index.num_vectors),
+                vec![0, 1, 2, 3]
+            );
+        }
+    }
+
+    #[test]
+    fn parse_label_expression_json_rejects_malformed_inputs() {
+        assert!(parse_label_expression_json("{").is_err());
+        assert!(parse_label_expression_json(r#"{"and":[]}"#).is_err());
+        assert!(parse_label_expression_json(r#"{"or":[]}"#).is_err());
+        assert!(parse_label_expression_json(r#"{"and":["A"],"or":["B"]}"#).is_err());
+        assert!(parse_label_expression_json(r#"{"and":["A"],"and":["B"]}"#).is_err());
+    }
+
+    #[test]
+    fn parse_label_expression_json_rejects_expressions_that_exceed_depth_limit() {
+        let error =
+            parse_label_expression_json(&nested_not_json(MAX_LABEL_EXPRESSION_DEPTH)).unwrap_err();
+        assert!(error
+            .to_string()
+            .contains("label expression depth 65 exceeds limit 64"));
+    }
+
+    #[test]
+    fn parse_label_expression_json_rejects_expressions_that_exceed_node_limit() {
+        let labels = std::iter::repeat_n(r#""A""#, MAX_LABEL_EXPRESSION_NODES)
+            .collect::<Vec<_>>()
+            .join(",");
+        let expression_json = format!(r#"{{"or":[{labels}]}}"#);
+        let error = parse_label_expression_json(&expression_json).unwrap_err();
+        assert!(error
+            .to_string()
+            .contains("label expression node count 4097 exceeds limit 4096"));
+    }
+
+    #[test]
+    fn parse_label_expression_json_rejects_unknown_operator_before_consuming_its_value() {
+        let error = parse_label_expression_json(r#"{"xor":"#).unwrap_err();
+        assert!(error
+            .to_string()
+            .contains("unsupported label expression operator 'xor'"));
+    }
+
+    #[test]
+    fn parse_label_expression_json_rejects_extra_keys_before_consuming_their_values() {
+        let error = parse_label_expression_json(r#"{"and":["A"],"or":"#).unwrap_err();
+        assert!(error
+            .to_string()
+            .contains("label expression objects must contain exactly one operator"));
+    }
+
+    #[test]
+    fn filter_expression_type_legacy_constants_match_current_variants() {
+        assert_eq!(FilterExpressionType::DNF as u32, 0);
+        assert_eq!(FilterExpressionType::CNF as u32, 1);
+        assert_eq!(FilterExpressionType::AST as u32, 2);
+        assert_eq!(FilterExpressionType::ORMajor, FilterExpressionType::DNF);
+        assert_eq!(FilterExpressionType::ANDMajor, FilterExpressionType::CNF);
+    }
+
+    #[test]
+    fn ast_query_requires_exactly_one_input_string() {
+        let index = round_trip(LabelIndexFormat::Bitslice);
+        assert!(index
+            .query(
+                &[r#"{"and":["A","B"]}"#, r#"{"and":["C","D"]}"#],
+                FilterExpressionType::AST,
+            )
+            .is_err());
+    }
+
+    #[test]
+    fn query_expression_rejects_invalid_programmatic_expressions() {
+        let index = round_trip(LabelIndexFormat::Bitslice);
+
+        assert!(index
+            .query_expression(&LabelExpression::Label(String::new()))
+            .is_err());
+        assert!(index
+            .query_expression(&LabelExpression::And(vec![]))
+            .is_err());
+        assert!(index
+            .query_expression(&LabelExpression::Or(vec![]))
+            .is_err());
+        assert!(index
+            .query_expression(&nested_not_expression(MAX_LABEL_EXPRESSION_DEPTH))
+            .is_err());
+        assert!(index
+            .query_expression(&LabelExpression::Or(vec![
+                LabelExpression::Label(
+                    "A".to_string()
+                );
+                MAX_LABEL_EXPRESSION_NODES
+            ]))
+            .is_err());
+    }
+
     #[test]
     fn raw_and_object_jsonl_forms_are_supported() {
         let dir = tempfile::tempdir().unwrap();
@@ -973,18 +1584,18 @@ mod tests {
         encode_label_index_jsonl(&input, &output, LabelIndexFormat::Bitslice).unwrap();
         let index = EncodedLabelIndex::load(output).unwrap();
 
-        let raw = compile(&index, &["solo"], FilterExpressionType::ORMajor);
+        let raw = compile(&index, &["solo"], FilterExpressionType::DNF);
         assert!(raw.is_match(0));
         assert!(!raw.is_match(1));
 
-        let array = compile(&index, &["left&right"], FilterExpressionType::ORMajor);
+        let array = compile(&index, &["left&right"], FilterExpressionType::DNF);
         assert!(array.is_match(1));
         assert!(!array.is_match(0));
 
         let object = compile(
             &index,
             &["enabled&group=g&count=2&deleted=false&inline"],
-            FilterExpressionType::ORMajor,
+            FilterExpressionType::DNF,
         );
         assert!(object.is_match(4));
         assert!(!object.is_match(3));
@@ -999,8 +1610,8 @@ mod tests {
         encode_label_index_jsonl(&input, &output, LabelIndexFormat::Bitslice).unwrap();
         let index = EncodedLabelIndex::load(output).unwrap();
 
-        let a = compile(&index, &["A"], FilterExpressionType::ORMajor);
-        let b = compile(&index, &["B"], FilterExpressionType::ORMajor);
+        let a = compile(&index, &["A"], FilterExpressionType::DNF);
+        let b = compile(&index, &["B"], FilterExpressionType::DNF);
         assert!(a.is_match(0));
         assert!(!a.is_match(1));
         assert!(!b.is_match(0));

From bae9e739e200ffa1c1ec1d74fc3a8a6ae9702565 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Sun, 9 Aug 2026 16:11:17 +0800
Subject: [PATCH 20/25] diskann-label-index: support recursive AST queries

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 diskann-label-index/src/lib.rs | 81 +++++++++++++++++++---------------
 1 file changed, 45 insertions(+), 36 deletions(-)

diff --git a/diskann-label-index/src/lib.rs b/diskann-label-index/src/lib.rs
index d5566735fa..785b389f83 100644
--- a/diskann-label-index/src/lib.rs
+++ b/diskann-label-index/src/lib.rs
@@ -41,24 +41,22 @@ pub enum LabelIndexFormat {
 #[repr(u32)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum FilterExpressionType {
-    /// Outer OR with `&`-separated labels inside each string:
+    /// Historical name for outer OR with `&`-separated labels inside each string:
     /// `["A&B", "C&D"]` means `(A AND B) OR (C AND D)`.
-    DNF = 0,
-    /// Outer AND with `|`-separated labels inside each string:
+    ORMajor = 0,
+    /// Historical name for outer AND with `|`-separated labels inside each string:
     /// `["A|B", "C|D"]` means `(A OR B) AND (C OR D)`.
-    CNF = 1,
-    /// Exactly one JSON string containing a recursive abstract syntax tree.
-    AST = 2,
+    ANDMajor = 1,
 }
 
 impl FilterExpressionType {
-    /// Backward-compatible alias for [`FilterExpressionType::DNF`].
-    #[allow(non_upper_case_globals)]
-    pub const ORMajor: Self = Self::DNF;
+    /// Preferred alias for [`FilterExpressionType::ORMajor`] using Boolean normal-form
+    /// terminology.
+    pub const DNF: Self = Self::ORMajor;
 
-    /// Backward-compatible alias for [`FilterExpressionType::CNF`].
-    #[allow(non_upper_case_globals)]
-    pub const ANDMajor: Self = Self::CNF;
+    /// Preferred alias for [`FilterExpressionType::ANDMajor`] using Boolean normal-form
+    /// terminology.
+    pub const CNF: Self = Self::ANDMajor;
 }
 
 /// A crate-owned Boolean label expression tree.
@@ -615,6 +613,11 @@ impl EncodedLabelIndex {
         })
     }
 
+    /// Compile a clause-list query using DNF/CNF semantics.
+    ///
+    /// Use [`FilterExpressionType::DNF`] or [`FilterExpressionType::CNF`] for the preferred
+    /// terminology. The legacy [`FilterExpressionType::ORMajor`] and
+    /// [`FilterExpressionType::ANDMajor`] variants remain supported for compatibility.
     pub fn query<S>(
         &self,
         clauses: &[S],
@@ -624,21 +627,12 @@ impl EncodedLabelIndex {
         S: AsRef<str>,
     {
         let expression = match expression_type {
-            FilterExpressionType::DNF => {
+            FilterExpressionType::ORMajor => {
                 CompiledExpression::Flat(compile_plan(clauses, PlanKind::Dnf, &self.label_ids)?)
             }
-            FilterExpressionType::CNF => {
+            FilterExpressionType::ANDMajor => {
                 CompiledExpression::Flat(compile_plan(clauses, PlanKind::Cnf, &self.label_ids)?)
             }
-            FilterExpressionType::AST => {
-                if clauses.len() != 1 {
-                    return Err(EncodedLabelIndexError::Invalid(
-                        "AST filters must contain exactly one JSON expression string".to_string(),
-                    ));
-                }
-                let expression = parse_label_expression_json(clauses[0].as_ref())?;
-                compile_label_expression(&expression, &self.label_ids)?
-            }
         };
 
         self.build_query(expression)
@@ -1521,23 +1515,38 @@ mod tests {
     }
 
     #[test]
-    fn filter_expression_type_legacy_constants_match_current_variants() {
-        assert_eq!(FilterExpressionType::DNF as u32, 0);
-        assert_eq!(FilterExpressionType::CNF as u32, 1);
-        assert_eq!(FilterExpressionType::AST as u32, 2);
-        assert_eq!(FilterExpressionType::ORMajor, FilterExpressionType::DNF);
-        assert_eq!(FilterExpressionType::ANDMajor, FilterExpressionType::CNF);
+    fn filter_expression_type_aliases_preserve_public_values() {
+        assert_eq!(FilterExpressionType::ORMajor as u32, 0);
+        assert_eq!(FilterExpressionType::ANDMajor as u32, 1);
+        assert_eq!(FilterExpressionType::DNF, FilterExpressionType::ORMajor);
+        assert_eq!(FilterExpressionType::CNF, FilterExpressionType::ANDMajor);
     }
 
     #[test]
-    fn ast_query_requires_exactly_one_input_string() {
+    fn query_supports_legacy_filter_expression_variant_names() {
         let index = round_trip(LabelIndexFormat::Bitslice);
-        assert!(index
-            .query(
-                &[r#"{"and":["A","B"]}"#, r#"{"and":["C","D"]}"#],
-                FilterExpressionType::AST,
-            )
-            .is_err());
+
+        let or_major = compile(&index, &["A&B", "C&D"], FilterExpressionType::ORMajor);
+        let dnf = compile(&index, &["A&B", "C&D"], FilterExpressionType::DNF);
+        assert_eq!(
+            matching_ids(&or_major, index.num_vectors),
+            matching_ids(&dnf, index.num_vectors)
+        );
+
+        let and_major = compile(
+            &index,
+            &["A|B", "group=x|score=2"],
+            FilterExpressionType::ANDMajor,
+        );
+        let cnf = compile(
+            &index,
+            &["A|B", "group=x|score=2"],
+            FilterExpressionType::CNF,
+        );
+        assert_eq!(
+            matching_ids(&and_major, index.num_vectors),
+            matching_ids(&cnf, index.num_vectors)
+        );
     }
 
     #[test]

From a5de3b6c39d456de0b58e1127f91d0c06c8857e5 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Sun, 9 Aug 2026 18:06:12 +0800
Subject: [PATCH 21/25] diskann-benchmark: compare encoded filter expressions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 Cargo.lock                                    |   1 +
 diskann-benchmark/Cargo.toml                  |   1 +
 diskann-benchmark/src/index/benchmarks.rs     | 182 ++++++++-
 diskann-benchmark/src/index/search/plugins.rs |  36 ++
 diskann-benchmark/src/inputs/graph_index.rs   |  61 +++
 diskann-benchmark/src/utils/filters.rs        | 347 +++++++++++++++++-
 diskann-label-index/src/lib.rs                |  75 ++--
 7 files changed, 678 insertions(+), 25 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index e90f11a2c8..c0d1929684 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -472,6 +472,7 @@ dependencies = [
  "diskann-disk",
  "diskann-inmem",
  "diskann-label-filter",
+ "diskann-label-index",
  "diskann-providers",
  "diskann-quantization",
  "diskann-tools",
diff --git a/diskann-benchmark/Cargo.toml b/diskann-benchmark/Cargo.toml
index 31739244c9..a6a2722967 100644
--- a/diskann-benchmark/Cargo.toml
+++ b/diskann-benchmark/Cargo.toml
@@ -29,6 +29,7 @@ tokio = { workspace = true, features = ["rt-multi-thread"] }
 diskann-vector.workspace = true
 diskann-wide.workspace = true
 diskann-label-filter.workspace = true
+diskann-label-index.workspace = true
 diskann-tools = { workspace = true }
 diskann-disk = { workspace = true, optional = true }
 diskann-bftree = { workspace = true, optional = true }
diff --git a/diskann-benchmark/src/index/benchmarks.rs b/diskann-benchmark/src/index/benchmarks.rs
index a51d8abad6..12c4fc4072 100644
--- a/diskann-benchmark/src/index/benchmarks.rs
+++ b/diskann-benchmark/src/index/benchmarks.rs
@@ -46,7 +46,10 @@ use crate::{
         search::plugins,
         streaming::{self, managed, stats::StreamStats, FullPrecisionStream, Managed},
     },
-    inputs::graph_index::{DynamicIndexRun, IndexBuild, IndexOperation, IndexSource, SearchPhase},
+    inputs::graph_index::{
+        DynamicIndexRun, IndexBuild, IndexOperation, IndexSource, MultihopFilterSearchPhase,
+        SearchPhase,
+    },
     utils::{
         self,
         datafiles::{self},
@@ -84,6 +87,9 @@ pub(crate) fn register_benchmarks(registry: &mut Registry) -> anyhow::Result<()>
             .search(plugins::TopkMultihopLiveFilterAuto)
             .search(plugins::TopkMultihopLiveFilterBitslice)
             .search(plugins::TopkMultihopLiveFilterBitsliceDnf)
+            .search(plugins::TopkMultihopEncodedBitsliceDnf)
+            .search(plugins::TopkMultihopEncodedBitsliceAst)
+            .search(plugins::TopkMultihopEncodedBitmapAst)
             .search(plugins::TopkInlineLiveFilterBitsliceDnf)
             .search(plugins::TopkInlineFilter)
             .search(plugins::DeterminantDiversity),
@@ -416,6 +422,63 @@ impl<S> Strategy<S> {
     }
 }
 
+fn run_multihop_encoded<DP, S>(
+    index: Arc<DiskANNIndex<DP>>,
+    phase: &MultihopFilterSearchPhase,
+    strategy: &Strategy<S>,
+    mode: utils::filters::EncodedQueryMode,
+    expected_format: diskann_label_index::LabelIndexFormat,
+) -> anyhow::Result<AggregatedSearchResults>
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<
+            'a,
+            DP,
+            &'a [DP::Element],
+            SearchAccessor: glue::SearchAccessor,
+        > + Clone
+        + AsyncFriendly,
+{
+    let queries: Arc<Matrix<DP::Element>> =
+        Arc::new(datafiles::load_dataset(datafiles::BinFile(&phase.queries))?);
+
+    let groundtruth = datafiles::load_range_groundtruth(datafiles::BinFile(&phase.groundtruth))?;
+
+    let steps = search::knn::SearchSteps::new(
+        phase.reps,
+        &phase.num_threads,
+        &phase.runs,
+        GroundTruthMode::Flexible,
+    );
+
+    // For the encoded-label-index search phases, `data_labels` intentionally points at the
+    // pre-encoded label-index file, not the raw labels JSONL. Query compilation/materialization
+    // (including bitmap densification for the bitmap-AST mode) happens once here during benchmark
+    // setup so the timed ANN search measures only the shared multi-hop traversal with membership
+    // checks against the compiled providers.
+    let label_index = utils::filters::load_encoded_label_index(&phase.data_labels)?;
+    if label_index.format() != expected_format {
+        anyhow::bail!(
+            "encoded search mode expected {:?} label storage, but {} contains {:?}",
+            expected_format,
+            phase.data_labels.display(),
+            label_index.format()
+        );
+    }
+    let providers =
+        utils::filters::make_encoded_query_providers(&label_index, &phase.query_predicates, mode)?;
+
+    let multihop = benchmark_core::search::graph::MultiHop::new(
+        index,
+        queries,
+        benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
+        providers.into(),
+    )?;
+
+    let result = search::knn::run(&multihop, &groundtruth, steps)?;
+    Ok(AggregatedSearchResults::Topk(result))
+}
+
 //------//
 // Topk //
 //------//
@@ -1089,6 +1152,123 @@ where
     }
 }
 
+//--------------------------------------//
+// MultihopEncodedFilter (Bitslice DNF) //
+//--------------------------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>> for plugins::TopkMultihopEncodedBitsliceDnf
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<
+            'a,
+            DP,
+            &'a [DP::Element],
+            SearchAccessor: glue::SearchAccessor,
+        > + Clone
+        + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        run_multihop_encoded(
+            index,
+            phase.as_topk_multihop_encoded_bitslice_dnf()?,
+            strategy,
+            utils::filters::EncodedQueryMode::Dnf,
+            diskann_label_index::LabelIndexFormat::Bitslice,
+        )
+    }
+}
+
+//--------------------------------------//
+// MultihopEncodedFilter (Bitslice AST) //
+//--------------------------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>> for plugins::TopkMultihopEncodedBitsliceAst
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<
+            'a,
+            DP,
+            &'a [DP::Element],
+            SearchAccessor: glue::SearchAccessor,
+        > + Clone
+        + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        run_multihop_encoded(
+            index,
+            phase.as_topk_multihop_encoded_bitslice_ast()?,
+            strategy,
+            utils::filters::EncodedQueryMode::Ast,
+            diskann_label_index::LabelIndexFormat::Bitslice,
+        )
+    }
+}
+
+//------------------------------------//
+// MultihopEncodedFilter (Bitmap AST) //
+//------------------------------------//
+
+impl<DP, S> search::Plugin<DP, SearchPhase, Strategy<S>> for plugins::TopkMultihopEncodedBitmapAst
+where
+    DP: DataProvider<Context: Default, InternalId = u32, ExternalId = u32> + QueryType,
+    S: for<'a> glue::DefaultSearchStrategy<
+            'a,
+            DP,
+            &'a [DP::Element],
+            SearchAccessor: glue::SearchAccessor,
+        > + Clone
+        + AsyncFriendly,
+{
+    fn is_match(&self, phase: &SearchPhase) -> bool {
+        Self::kind() == phase.kind()
+    }
+
+    fn kind(&self) -> &'static str {
+        Self::kind().as_str()
+    }
+
+    fn run(
+        &self,
+        index: Arc<DiskANNIndex<DP>>,
+        phase: &SearchPhase,
+        strategy: &Strategy<S>,
+    ) -> anyhow::Result<AggregatedSearchResults> {
+        run_multihop_encoded(
+            index,
+            phase.as_topk_multihop_encoded_bitmap_ast()?,
+            strategy,
+            utils::filters::EncodedQueryMode::Ast,
+            diskann_label_index::LabelIndexFormat::Bitmap,
+        )
+    }
+}
+
 //---------------------------------//
 // InlineFilter (Bitslice DNF)      //
 //---------------------------------//
diff --git a/diskann-benchmark/src/index/search/plugins.rs b/diskann-benchmark/src/index/search/plugins.rs
index db74ceebb2..0edeb0a23d 100644
--- a/diskann-benchmark/src/index/search/plugins.rs
+++ b/diskann-benchmark/src/index/search/plugins.rs
@@ -308,6 +308,42 @@ impl TopkMultihopLiveFilterBitsliceDnf {
     }
 }
 
+/// A multi-hop encoded-filter plugin backed by a pre-encoded bitslice label index and a flat
+/// OR-of-AND query plan compiled during benchmark setup.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkMultihopEncodedBitsliceDnf;
+
+impl TopkMultihopEncodedBitsliceDnf {
+    /// Returns [`SearchPhaseKind::TopkMultihopEncodedBitsliceDnf`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkMultihopEncodedBitsliceDnf
+    }
+}
+
+/// A multi-hop encoded-filter plugin backed by a pre-encoded bitslice label index and a recursive
+/// AST query compiled during benchmark setup.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkMultihopEncodedBitsliceAst;
+
+impl TopkMultihopEncodedBitsliceAst {
+    /// Returns [`SearchPhaseKind::TopkMultihopEncodedBitsliceAst`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkMultihopEncodedBitsliceAst
+    }
+}
+
+/// A multi-hop encoded-filter plugin backed by a pre-encoded roaring-postings label index whose
+/// recursive AST query is materialized to a dense bitmap during benchmark setup.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct TopkMultihopEncodedBitmapAst;
+
+impl TopkMultihopEncodedBitmapAst {
+    /// Returns [`SearchPhaseKind::TopkMultihopEncodedBitmapAst`].
+    pub(crate) fn kind() -> SearchPhaseKind {
+        SearchPhaseKind::TopkMultihopEncodedBitmapAst
+    }
+}
+
 /// An inline-filtered search plugin backed by bit slices and a flat OR-of-AND query plan.
 #[derive(Debug, Clone, Copy)]
 pub(crate) struct TopkInlineLiveFilterBitsliceDnf;
diff --git a/diskann-benchmark/src/inputs/graph_index.rs b/diskann-benchmark/src/inputs/graph_index.rs
index 2d592b5fae..899345370a 100644
--- a/diskann-benchmark/src/inputs/graph_index.rs
+++ b/diskann-benchmark/src/inputs/graph_index.rs
@@ -414,6 +414,15 @@ pub(crate) enum SearchPhase {
     TopkMultihopLiveFilterAuto(MultihopFilterSearchPhase),
     TopkMultihopLiveFilterBitslice(MultihopFilterSearchPhase),
     TopkMultihopLiveFilterBitsliceDnf(MultihopFilterSearchPhase),
+    /// For these encoded-label-index modes, `data_labels` points at a pre-encoded
+    /// `diskann-label-index` artifact instead of the raw labels JSONL.
+    TopkMultihopEncodedBitsliceDnf(MultihopFilterSearchPhase),
+    /// For these encoded-label-index modes, `data_labels` points at a pre-encoded
+    /// `diskann-label-index` artifact instead of the raw labels JSONL.
+    TopkMultihopEncodedBitsliceAst(MultihopFilterSearchPhase),
+    /// For these encoded-label-index modes, `data_labels` points at a pre-encoded
+    /// `diskann-label-index` artifact instead of the raw labels JSONL.
+    TopkMultihopEncodedBitmapAst(MultihopFilterSearchPhase),
     TopkInlineLiveFilterBitsliceDnf(InlineFilterSearchPhase),
     TopkInlineFilter(InlineFilterSearchPhase),
     TopkDeterminantDiversity(TopkDeterminantDiversityPhase),
@@ -453,6 +462,13 @@ impl SearchPhase {
             Self::TopkMultihopLiveFilterBitsliceDnf(_) => {
                 SearchPhaseKind::TopkMultihopLiveFilterBitsliceDnf
             }
+            Self::TopkMultihopEncodedBitsliceDnf(_) => {
+                SearchPhaseKind::TopkMultihopEncodedBitsliceDnf
+            }
+            Self::TopkMultihopEncodedBitsliceAst(_) => {
+                SearchPhaseKind::TopkMultihopEncodedBitsliceAst
+            }
+            Self::TopkMultihopEncodedBitmapAst(_) => SearchPhaseKind::TopkMultihopEncodedBitmapAst,
             Self::TopkInlineLiveFilterBitsliceDnf(_) => {
                 SearchPhaseKind::TopkInlineLiveFilterBitsliceDnf
             }
@@ -575,6 +591,42 @@ impl SearchPhase {
         }
     }
 
+    pub(crate) fn as_topk_multihop_encoded_bitslice_dnf(
+        &self,
+    ) -> Result<&MultihopFilterSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkMultihopEncodedBitsliceDnf(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkMultihopEncodedBitsliceDnf,
+                self.kind(),
+            )),
+        }
+    }
+
+    pub(crate) fn as_topk_multihop_encoded_bitslice_ast(
+        &self,
+    ) -> Result<&MultihopFilterSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkMultihopEncodedBitsliceAst(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkMultihopEncodedBitsliceAst,
+                self.kind(),
+            )),
+        }
+    }
+
+    pub(crate) fn as_topk_multihop_encoded_bitmap_ast(
+        &self,
+    ) -> Result<&MultihopFilterSearchPhase, WrongSearchPhaseKind> {
+        match self {
+            Self::TopkMultihopEncodedBitmapAst(phase) => Ok(phase),
+            _ => Err(WrongSearchPhaseKind::new(
+                SearchPhaseKind::TopkMultihopEncodedBitmapAst,
+                self.kind(),
+            )),
+        }
+    }
+
     pub(crate) fn as_topk_inline_filter(
         &self,
     ) -> Result<&InlineFilterSearchPhase, WrongSearchPhaseKind> {
@@ -625,6 +677,9 @@ impl SearchPhase {
             SearchPhase::TopkMultihopLiveFilterAuto(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopLiveFilterBitslice(phase) => phase.validate(checker),
             SearchPhase::TopkMultihopLiveFilterBitsliceDnf(phase) => phase.validate(checker),
+            SearchPhase::TopkMultihopEncodedBitsliceDnf(phase) => phase.validate(checker),
+            SearchPhase::TopkMultihopEncodedBitsliceAst(phase) => phase.validate(checker),
+            SearchPhase::TopkMultihopEncodedBitmapAst(phase) => phase.validate(checker),
             SearchPhase::TopkInlineLiveFilterBitsliceDnf(phase) => phase.validate(checker),
             SearchPhase::TopkInlineFilter(phase) => phase.validate(checker),
             SearchPhase::TopkDeterminantDiversity(phase) => phase.validate(checker),
@@ -644,6 +699,9 @@ pub(crate) enum SearchPhaseKind {
     TopkMultihopLiveFilterAuto,
     TopkMultihopLiveFilterBitslice,
     TopkMultihopLiveFilterBitsliceDnf,
+    TopkMultihopEncodedBitsliceDnf,
+    TopkMultihopEncodedBitsliceAst,
+    TopkMultihopEncodedBitmapAst,
     TopkInlineLiveFilterBitsliceDnf,
     TopkInlineFilter,
     TopkDeterminantDiversity,
@@ -662,6 +720,9 @@ impl SearchPhaseKind {
             Self::TopkMultihopLiveFilterAuto => "topk-multihop-live-filter-auto",
             Self::TopkMultihopLiveFilterBitslice => "topk-multihop-live-filter-bitslice",
             Self::TopkMultihopLiveFilterBitsliceDnf => "topk-multihop-live-filter-bitslice-dnf",
+            Self::TopkMultihopEncodedBitsliceDnf => "topk-multihop-encoded-bitslice-dnf",
+            Self::TopkMultihopEncodedBitsliceAst => "topk-multihop-encoded-bitslice-ast",
+            Self::TopkMultihopEncodedBitmapAst => "topk-multihop-encoded-bitmap-ast",
             Self::TopkInlineLiveFilterBitsliceDnf => "topk-inline-live-filter-bitslice-dnf",
             Self::TopkInlineFilter => "topk-inline-filter",
             Self::TopkDeterminantDiversity => "topk-determinant-diversity",
diff --git a/diskann-benchmark/src/utils/filters.rs b/diskann-benchmark/src/utils/filters.rs
index 26e4ee3064..01c557fef9 100644
--- a/diskann-benchmark/src/utils/filters.rs
+++ b/diskann-benchmark/src/utils/filters.rs
@@ -5,6 +5,7 @@
 
 use bit_set::BitSet;
 use std::fmt::Debug;
+use std::sync::Arc;
 
 use diskann::{
     graph::ext::labeled::QueryLabelProvider,
@@ -18,12 +19,14 @@ use diskann_label_filter::{
         posting_list_trait::{PostingList, RoaringPostingList},
         query_evaluator::QueryEvaluator,
     },
-    ASTExpr, DefaultKeyCodec,
+    ASTExpr, CompareOp, DefaultKeyCodec,
+};
+use diskann_label_index::{
+    EncodedLabelIndex, EncodedLabelQuery, FilterExpressionType, LabelExpression,
 };
 use diskann_providers::model::graph::provider::layers::BetaFilter;
 
 use diskann_tools::utils::ground_truth::read_labels_and_compute_bitmap;
-use std::sync::Arc;
 
 use diskann_label_filter::attribute::Attribute;
 use diskann_label_filter::{
@@ -32,6 +35,7 @@ use diskann_label_filter::{
     InlineAttributeIndex, InlineAttributeIndexAuto, InlineAttributeIndexBitslice,
     InlineAttributeIndexCsr, InlineAttributeIndexPosting,
 };
+use serde_json::Value;
 
 pub struct QueryBitmapEvaluator {
     pub ast_expr: ASTExpr,
@@ -92,6 +96,21 @@ where
     }
 }
 
+#[derive(Debug)]
+struct EncodedQueryProvider(EncodedLabelQuery<'static>);
+
+impl QueryLabelProvider<u32> for EncodedQueryProvider {
+    fn is_match(&self, vec_id: u32) -> bool {
+        self.0.is_match(vec_id)
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum EncodedQueryMode {
+    Dnf,
+    Ast,
+}
+
 pub(crate) fn generate_bitmaps(
     query_predicates: &InputFile,
     data_labels: &InputFile,
@@ -127,11 +146,186 @@ pub(crate) fn as_query_label_provider(set: BitSet) -> Arc<dyn QueryLabelProvider
     Arc::new(BitmapFilter(set))
 }
 
+pub(crate) fn load_encoded_label_index(
+    data_labels: &InputFile,
+) -> anyhow::Result<EncodedLabelIndex> {
+    EncodedLabelIndex::load(&**data_labels).map_err(|e| {
+        anyhow::anyhow!(
+            "failed to load encoded label index {}: {e}",
+            data_labels.display()
+        )
+    })
+}
+
+pub(crate) fn make_encoded_query_providers(
+    index: &EncodedLabelIndex,
+    query_predicates: &InputFile,
+    mode: EncodedQueryMode,
+) -> anyhow::Result<Vec<Arc<dyn QueryLabelProvider<u32>>>> {
+    let parsed = read_and_parse_queries(query_predicates.to_str().unwrap())
+        .map_err(|e| anyhow::anyhow!("failed to parse query predicates: {e}"))?;
+    parsed
+        .into_iter()
+        .map(|(_query_id, ast)| {
+            let label_expression = ast_to_label_expression(&ast)?;
+            validate_encoded_benchmark_labels(index, &label_expression)?;
+            let query = match mode {
+                EncodedQueryMode::Dnf => {
+                    let clauses = flatten_dnf_clauses(&label_expression)?;
+                    index.query(&clauses, FilterExpressionType::DNF)
+                }
+                EncodedQueryMode::Ast => index.query_expression(&label_expression),
+            }
+            .map_err(|e| anyhow::anyhow!("failed to compile encoded label query: {e}"))?;
+            Ok(Arc::new(EncodedQueryProvider(query)) as Arc<dyn QueryLabelProvider<u32>>)
+        })
+        .collect()
+}
+
 fn checked_doc_id(doc_id: usize) -> anyhow::Result<u32> {
     u32::try_from(doc_id)
         .map_err(|_| anyhow::anyhow!("document id {doc_id} exceeds the u32 graph-id range"))
 }
 
+fn validate_encoded_benchmark_labels(
+    index: &EncodedLabelIndex,
+    expression: &LabelExpression,
+) -> anyhow::Result<()> {
+    let mut stack = vec![expression];
+    while let Some(expression) = stack.pop() {
+        match expression {
+            LabelExpression::Label(label) => {
+                if !index.contains_label(label) {
+                    anyhow::bail!(
+                        "encoded benchmark query references label '{label}' absent from the label index"
+                    );
+                }
+            }
+            LabelExpression::And(children) | LabelExpression::Or(children) => {
+                stack.extend(children);
+            }
+            LabelExpression::Not(child) => stack.push(child),
+        }
+    }
+    Ok(())
+}
+
+fn ast_to_label_expression(ast: &ASTExpr) -> anyhow::Result<LabelExpression> {
+    match ast {
+        ASTExpr::And(exprs) => Ok(LabelExpression::And(
+            exprs
+                .iter()
+                .map(ast_to_label_expression)
+                .collect::<anyhow::Result<Vec<_>>>()?,
+        )),
+        ASTExpr::Or(exprs) => Ok(LabelExpression::Or(
+            exprs
+                .iter()
+                .map(ast_to_label_expression)
+                .collect::<anyhow::Result<Vec<_>>>()?,
+        )),
+        ASTExpr::Not(expr) => Ok(LabelExpression::Not(Box::new(ast_to_label_expression(
+            expr,
+        )?))),
+        ASTExpr::Compare { field, op } => compare_to_label_expression(field, op),
+    }
+}
+
+fn compare_to_label_expression(field: &str, op: &CompareOp) -> anyhow::Result<LabelExpression> {
+    match op {
+        CompareOp::Eq(value) => eq_value_to_label_expression(field, value),
+        CompareOp::Ne(_)
+        | CompareOp::Lt(_)
+        | CompareOp::Lte(_)
+        | CompareOp::Gt(_)
+        | CompareOp::Gte(_) => Err(anyhow::anyhow!(
+            "encoded label-index queries only support equality/set-membership predicates; field '{field}' used unsupported operator {op}"
+        )),
+    }
+}
+
+fn eq_value_to_label_expression(field: &str, value: &Value) -> anyhow::Result<LabelExpression> {
+    match value {
+        Value::Bool(true) => Ok(LabelExpression::Label(field.to_string())),
+        Value::Bool(false) | Value::Number(_) | Value::String(_) => {
+            Ok(LabelExpression::Label(format!("{field}={}", value_repr(value))))
+        }
+        Value::Null => Err(anyhow::anyhow!(
+            "encoded benchmark equality predicates do not support null for field '{field}'"
+        )),
+        Value::Array(_) => Err(anyhow::anyhow!(
+            "encoded label-index equality predicates do not support array values for field '{field}'"
+        )),
+        Value::Object(_) => Err(anyhow::anyhow!(
+            "encoded label-index equality predicates require scalar or array values; field '{field}' used an object"
+        )),
+    }
+}
+
+fn value_repr(value: &Value) -> String {
+    match value {
+        Value::Bool(value) => value.to_string(),
+        Value::Number(value) => value.to_string(),
+        Value::String(value) => value.clone(),
+        Value::Null => "null".to_string(),
+        Value::Array(_) | Value::Object(_) => {
+            unreachable!("handled by eq_value_to_label_expression")
+        }
+    }
+}
+
+fn flatten_dnf_clauses(expression: &LabelExpression) -> anyhow::Result<Vec<String>> {
+    let mut clauses = Vec::new();
+    collect_dnf_clauses(expression, &mut clauses)?;
+    Ok(clauses)
+}
+
+fn collect_dnf_clauses(
+    expression: &LabelExpression,
+    clauses: &mut Vec<String>,
+) -> anyhow::Result<()> {
+    match expression {
+        LabelExpression::Label(label) => clauses.push(label.clone()),
+        LabelExpression::And(children) => {
+            let mut terminals = Vec::new();
+            for child in children {
+                collect_dnf_conjunction(child, &mut terminals)?;
+            }
+            clauses.push(terminals.join("&"));
+        }
+        LabelExpression::Or(children) => {
+            for child in children {
+                collect_dnf_clauses(child, clauses)?;
+            }
+        }
+        LabelExpression::Not(_) => {
+            anyhow::bail!("encoded DNF queries require an OR-of-AND predicate shape; NOT expressions are unsupported")
+        }
+    }
+    Ok(())
+}
+
+fn collect_dnf_conjunction(
+    expression: &LabelExpression,
+    terminals: &mut Vec<String>,
+) -> anyhow::Result<()> {
+    match expression {
+        LabelExpression::Label(label) => terminals.push(label.clone()),
+        LabelExpression::And(children) => {
+            for child in children {
+                collect_dnf_conjunction(child, terminals)?;
+            }
+        }
+        LabelExpression::Or(_) => {
+            anyhow::bail!("encoded DNF queries require an OR-of-AND predicate shape; OR expressions cannot appear inside a conjunction")
+        }
+        LabelExpression::Not(_) => {
+            anyhow::bail!("encoded DNF queries require an OR-of-AND predicate shape; NOT expressions are unsupported")
+        }
+    }
+    Ok(())
+}
+
 /// Build an in-memory inline attribute index from a jsonl label file (one document per line).
 ///
 /// Each document's flattened `(field, value)` pairs are encoded to integer attribute-ids and
@@ -383,6 +577,27 @@ pub(crate) fn make_live_providers_bitslice_dnf(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::{fs::File, io::Write};
+
+    use diskann_label_index::{encode_label_index_jsonl, LabelIndexFormat};
+    use serde_json::json;
+    use tempfile::tempdir;
+
+    fn write_lines(path: &std::path::Path, lines: &[&str]) {
+        let mut file = File::create(path).unwrap();
+        for line in lines {
+            writeln!(file, "{line}").unwrap();
+        }
+    }
+
+    fn test_query_matches(
+        provider: &Arc<dyn QueryLabelProvider<u32>>,
+        num_vectors: u32,
+    ) -> Vec<u32> {
+        (0..num_vectors)
+            .filter(|&vec_id| provider.is_match(vec_id))
+            .collect()
+    }
 
     #[test]
     fn test_bitmap_filter_match() {
@@ -424,4 +639,132 @@ mod tests {
             assert!(checked_doc_id(too_large).is_err());
         }
     }
+
+    #[test]
+    fn test_encoded_providers_agree_for_dnf_and_ast() {
+        let dir = tempdir().unwrap();
+        let labels_jsonl = dir.path().join("labels.jsonl");
+        let bitslice_index = dir.path().join("labels.bitslice");
+        let bitmap_index = dir.path().join("labels.bitmap");
+        let queries_jsonl = dir.path().join("queries.jsonl");
+
+        write_lines(
+            &labels_jsonl,
+            &[
+                r#"{"doc_id":0,"brand":"A","color":"red","promo":true,"active":false,"score":2,"missing":null}"#,
+                r#"{"doc_id":1,"brand":"A","color":"blue","promo":false,"active":false,"score":3,"missing":"value"}"#,
+                r#"{"doc_id":2,"brand":"B","color":"red","promo":false,"active":true,"score":2,"missing":null}"#,
+                r#"{"doc_id":3,"brand":"C","color":"green","promo":true,"active":false,"score":5,"missing":null}"#,
+            ],
+        );
+        write_lines(
+            &queries_jsonl,
+            &[
+                r#"{"query_id":0,"filter":{"$or":[{"$and":[{"brand":{"$eq":"A"}},{"color":{"$eq":"red"}}]},{"promo":{"$eq":true}}]}}"#,
+                r#"{"query_id":1,"filter":{"active":{"$eq":false},"score":{"$eq":2}}}"#,
+                r#"{"query_id":2,"filter":{"$or":[{"brand":{"$eq":"B"}},{"color":{"$eq":"green"}}]}}"#,
+            ],
+        );
+
+        encode_label_index_jsonl(&labels_jsonl, &bitslice_index, LabelIndexFormat::Bitslice)
+            .unwrap();
+        encode_label_index_jsonl(&labels_jsonl, &bitmap_index, LabelIndexFormat::Bitmap).unwrap();
+
+        let bitslice_index = load_encoded_label_index(&InputFile::new(bitslice_index)).unwrap();
+        let bitmap_index = load_encoded_label_index(&InputFile::new(bitmap_index)).unwrap();
+        let query_file = InputFile::new(queries_jsonl);
+
+        let dnf = make_encoded_query_providers(&bitslice_index, &query_file, EncodedQueryMode::Dnf)
+            .unwrap();
+        let bitslice_ast =
+            make_encoded_query_providers(&bitslice_index, &query_file, EncodedQueryMode::Ast)
+                .unwrap();
+        let bitmap_ast =
+            make_encoded_query_providers(&bitmap_index, &query_file, EncodedQueryMode::Ast)
+                .unwrap();
+
+        assert_eq!(dnf.len(), bitslice_ast.len());
+        assert_eq!(dnf.len(), bitmap_ast.len());
+        for ((dnf, bitslice_ast), bitmap_ast) in dnf.iter().zip(&bitslice_ast).zip(&bitmap_ast) {
+            assert_eq!(
+                test_query_matches(dnf, 4),
+                test_query_matches(bitslice_ast, 4)
+            );
+            assert_eq!(
+                test_query_matches(dnf, 4),
+                test_query_matches(bitmap_ast, 4)
+            );
+        }
+    }
+
+    #[test]
+    fn test_encoded_query_rejects_unsupported_relational_operator() {
+        let error = ast_to_label_expression(&ASTExpr::Compare {
+            field: "score".to_string(),
+            op: CompareOp::Gt(2.0),
+        })
+        .unwrap_err();
+        assert!(error.to_string().contains("unsupported operator >"));
+    }
+
+    #[test]
+    fn test_encoded_dnf_rejects_non_dnf_shape() {
+        let expression = ast_to_label_expression(&ASTExpr::And(vec![
+            ASTExpr::Compare {
+                field: "brand".to_string(),
+                op: CompareOp::Eq(json!("A")),
+            },
+            ASTExpr::Or(vec![
+                ASTExpr::Compare {
+                    field: "color".to_string(),
+                    op: CompareOp::Eq(json!("red")),
+                },
+                ASTExpr::Compare {
+                    field: "color".to_string(),
+                    op: CompareOp::Eq(json!("blue")),
+                },
+            ]),
+        ]))
+        .unwrap();
+
+        let error = flatten_dnf_clauses(&expression).unwrap_err();
+        assert!(error
+            .to_string()
+            .contains("OR expressions cannot appear inside a conjunction"));
+    }
+
+    #[test]
+    fn test_encoded_dnf_rejects_array_equality_explicitly() {
+        let error = ast_to_label_expression(&ASTExpr::Compare {
+            field: "brand".to_string(),
+            op: CompareOp::Eq(json!(["A", "B"])),
+        })
+        .unwrap_err();
+        assert!(error.to_string().contains("do not support array values"));
+    }
+
+    #[test]
+    fn test_encoded_query_rejects_null_equality() {
+        let error = ast_to_label_expression(&ASTExpr::Compare {
+            field: "missing".to_string(),
+            op: CompareOp::Eq(Value::Null),
+        })
+        .unwrap_err();
+        assert!(error.to_string().contains("do not support null"));
+    }
+
+    #[test]
+    fn test_encoded_benchmark_rejects_unknown_labels() {
+        let dir = tempdir().unwrap();
+        let labels_jsonl = dir.path().join("labels.jsonl");
+        let bitslice_index = dir.path().join("labels.bitslice");
+        write_lines(&labels_jsonl, &[r#"{"doc_id":0,"A":true}"#]);
+        encode_label_index_jsonl(&labels_jsonl, &bitslice_index, LabelIndexFormat::Bitslice)
+            .unwrap();
+        let index = load_encoded_label_index(&InputFile::new(bitslice_index)).unwrap();
+        let error =
+            validate_encoded_benchmark_labels(&index, &LabelExpression::Label("missing".into()))
+                .unwrap_err();
+        assert!(error.to_string().contains("absent from the label index"));
+    }
 }
diff --git a/diskann-label-index/src/lib.rs b/diskann-label-index/src/lib.rs
index 785b389f83..372a42f9f0 100644
--- a/diskann-label-index/src/lib.rs
+++ b/diskann-label-index/src/lib.rs
@@ -12,7 +12,9 @@ use std::{
     collections::{HashMap, HashSet},
     fs::File,
     io::{self, BufRead, BufReader, BufWriter, Read, Seek, Write},
+    marker::PhantomData,
     path::Path,
+    sync::Arc,
 };
 use thiserror::Error;
 
@@ -283,10 +285,10 @@ pub enum EncodedLabelIndexError {
 enum LabelStorage {
     Bitslice {
         words_per_label: usize,
-        bits: Box<[u64]>,
+        bits: Arc<[u64]>,
     },
     Bitmap {
-        postings: Box<[RoaringBitmap]>,
+        postings: Arc<[RoaringBitmap]>,
     },
 }
 
@@ -330,10 +332,10 @@ enum CompiledExpression {
     Not(Box<CompiledExpression>),
 }
 
-enum QueryStorage<'a> {
+enum QueryStorage {
     Bitslice {
         words_per_label: usize,
-        bits: &'a [u64],
+        bits: Arc<[u64]>,
         expression: CompiledExpression,
     },
     DenseBitmap {
@@ -341,10 +343,14 @@ enum QueryStorage<'a> {
     },
 }
 
-/// Query-scoped label provider backed by an [`EncodedLabelIndex`].
+/// Query-scoped evaluator compiled from an [`EncodedLabelIndex`].
+///
+/// Bitslice queries share the index payload through [`Arc`] so the compiled query remains usable
+/// after the source [`EncodedLabelIndex`] is dropped.
 pub struct EncodedLabelQuery<'a> {
     num_vectors: u32,
-    storage: QueryStorage<'a>,
+    storage: QueryStorage,
+    _lifetime: PhantomData<&'a ()>,
 }
 
 impl std::fmt::Debug for EncodedLabelQuery<'_> {
@@ -423,6 +429,11 @@ impl CompiledExpression {
 }
 
 impl EncodedLabelIndex {
+    /// Return whether this index contains an encoded label.
+    pub fn contains_label(&self, label: &str) -> bool {
+        self.label_ids.contains_key(label)
+    }
+
     pub fn load(path: impl AsRef<Path>) -> Result<Self, EncodedLabelIndexError> {
         let file = File::open(path)?;
         let file_len = file.metadata()?.len();
@@ -557,7 +568,7 @@ impl EncodedLabelIndex {
 
                 LabelStorage::Bitslice {
                     words_per_label,
-                    bits: bits.into_boxed_slice(),
+                    bits: Arc::from(bits),
                 }
             }
             LabelIndexFormat::Bitmap => {
@@ -594,7 +605,7 @@ impl EncodedLabelIndex {
                 }
 
                 LabelStorage::Bitmap {
-                    postings: postings.into_boxed_slice(),
+                    postings: Arc::from(postings),
                 }
             }
         };
@@ -617,12 +628,13 @@ impl EncodedLabelIndex {
     ///
     /// Use [`FilterExpressionType::DNF`] or [`FilterExpressionType::CNF`] for the preferred
     /// terminology. The legacy [`FilterExpressionType::ORMajor`] and
-    /// [`FilterExpressionType::ANDMajor`] variants remain supported for compatibility.
+    /// [`FilterExpressionType::ANDMajor`] variants remain supported for compatibility. The
+    /// returned [`EncodedLabelQuery`] owns its compiled expression and any shared storage handles.
     pub fn query<S>(
         &self,
         clauses: &[S],
         expression_type: FilterExpressionType,
-    ) -> Result<EncodedLabelQuery<'_>, EncodedLabelIndexError>
+    ) -> Result<EncodedLabelQuery<'static>, EncodedLabelIndexError>
     where
         S: AsRef<str>,
     {
@@ -638,19 +650,19 @@ impl EncodedLabelIndex {
         self.build_query(expression)
     }
 
-    /// Compile a query from a recursive label expression.
+    /// Compile an owned query from a recursive label expression.
     pub fn query_expression(
         &self,
         expression: &LabelExpression,
-    ) -> Result<EncodedLabelQuery<'_>, EncodedLabelIndexError> {
+    ) -> Result<EncodedLabelQuery<'static>, EncodedLabelIndexError> {
         self.build_query(compile_label_expression(expression, &self.label_ids)?)
     }
 
-    /// Compile a query from a JSON-encoded recursive label expression.
+    /// Compile an owned query from a JSON-encoded recursive label expression.
     pub fn query_ast_json(
         &self,
         expression_json: &str,
-    ) -> Result<EncodedLabelQuery<'_>, EncodedLabelIndexError> {
+    ) -> Result<EncodedLabelQuery<'static>, EncodedLabelIndexError> {
         let expression = parse_label_expression_json(expression_json)?;
         self.query_expression(&expression)
     }
@@ -658,14 +670,14 @@ impl EncodedLabelIndex {
     fn build_query(
         &self,
         expression: CompiledExpression,
-    ) -> Result<EncodedLabelQuery<'_>, EncodedLabelIndexError> {
+    ) -> Result<EncodedLabelQuery<'static>, EncodedLabelIndexError> {
         let storage = match &self.storage {
             LabelStorage::Bitslice {
                 words_per_label,
                 bits,
             } => QueryStorage::Bitslice {
                 words_per_label: *words_per_label,
-                bits,
+                bits: Arc::clone(bits),
                 expression,
             },
             LabelStorage::Bitmap { postings } => QueryStorage::DenseBitmap {
@@ -677,10 +689,12 @@ impl EncodedLabelIndex {
         Ok(EncodedLabelQuery {
             num_vectors: self.num_vectors,
             storage,
+            _lifetime: PhantomData,
         })
     }
 
-    fn format(&self) -> LabelIndexFormat {
+    /// Return the persisted storage format backing this index.
+    pub fn format(&self) -> LabelIndexFormat {
         match &self.storage {
             LabelStorage::Bitslice { .. } => LabelIndexFormat::Bitslice,
             LabelStorage::Bitmap { .. } => LabelIndexFormat::Bitmap,
@@ -1317,20 +1331,22 @@ mod tests {
         )
     }
 
-    fn compile<'a>(
-        index: &'a EncodedLabelIndex,
+    fn compile(
+        index: &EncodedLabelIndex,
         clauses: &[&str],
         expression_type: FilterExpressionType,
-    ) -> EncodedLabelQuery<'a> {
+    ) -> EncodedLabelQuery<'static> {
         index.query(clauses, expression_type).unwrap()
     }
 
-    fn matching_ids(query: &EncodedLabelQuery<'_>, num_vectors: u32) -> Vec<u32> {
+    fn matching_ids(query: &EncodedLabelQuery, num_vectors: u32) -> Vec<u32> {
         (0..num_vectors)
             .filter(|&vec_id| query.is_match(vec_id))
             .collect()
     }
 
+    fn assert_send_sync_static<T: Send + Sync + 'static>(_: &T) {}
+
     fn round_trip(format: LabelIndexFormat) -> EncodedLabelIndex {
         let dir = tempfile::tempdir().unwrap();
         let input = dir.path().join("labels.jsonl");
@@ -1456,7 +1472,6 @@ mod tests {
     fn ast_not_supports_known_and_unknown_labels() {
         for format in [LabelIndexFormat::Bitslice, LabelIndexFormat::Bitmap] {
             let index = round_trip(format);
-
             let not_a = index.query_ast_json(r#"{"not":"A"}"#).unwrap();
             assert_eq!(matching_ids(&not_a, index.num_vectors), vec![1, 3]);
 
@@ -1468,6 +1483,22 @@ mod tests {
         }
     }
 
+    #[test]
+    fn compiled_queries_remain_usable_after_index_drop() {
+        for format in [LabelIndexFormat::Bitslice, LabelIndexFormat::Bitmap] {
+            let query = {
+                let index = round_trip(format);
+                Arc::new(
+                    index
+                        .query_ast_json(r#"{"or":[{"and":["A","B"]},{"and":["C","D"]}]}"#)
+                        .unwrap(),
+                )
+            };
+            assert_send_sync_static(query.as_ref());
+            assert_eq!(matching_ids(&query, 4), vec![2, 3]);
+        }
+    }
+
     #[test]
     fn parse_label_expression_json_rejects_malformed_inputs() {
         assert!(parse_label_expression_json("{").is_err());

From 4c58e96fae449c0eac156a2bc93cb6065a9b6040 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Sun, 9 Aug 2026 18:06:13 +0800
Subject: [PATCH 22/25] docs: record encoded expression benchmarks

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../multiple_filter_test_report.md            | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/diskann-benchmark/multiple_filter_test_report.md b/diskann-benchmark/multiple_filter_test_report.md
index 187548c82d..5b96a9acc6 100644
--- a/diskann-benchmark/multiple_filter_test_report.md
+++ b/diskann-benchmark/multiple_filter_test_report.md
@@ -461,6 +461,49 @@ The latency advantage therefore represents a different recall point, not an algo
 equal quality. Adaptive-L or an L sweep is required to compare recall-versus-latency curves and
 determine whether Inline can match multihop recall efficiently.
 
+### 8.4.8 Encoded-label library: DNF, AST, and precomputed AST
+
+The new `diskann-label-index` crate was benchmarked directly through three multihop modes:
+
+- `topk-multihop-encoded-bitslice-dnf`: contiguous Bitslice storage plus the flat DNF plan;
+- `topk-multihop-encoded-bitslice-ast`: the same Bitslice storage plus recursive AST evaluation;
+- `topk-multihop-encoded-bitmap-ast`: Roaring postings plus recursive AST materialization into one
+  dense query-result bitmap before timed ANN search.
+
+The full 596-label JSONL was encoded once into a 744,726,578-byte Bitslice file and a
+61,892,560-byte Roaring file. One counterbalanced 27-job runbook then covered S1-S9, k=150, L=150,
+one thread, 1,000 queries, and three repetitions. Values are milliseconds averaged across
+repetitions.
+
+| Case | Bitslice DNF AVG | Bitslice AST AVG | Precomputed AST AVG | DNF P99 | AST P99 | Pre P99 | DNF P99.9 | AST P99.9 | Pre P99.9 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| S1 | 2.616 | 2.499 | **2.435** | 9.200 | 8.665 | **7.816** | 14.442 | **11.585** | 19.243 |
+| S2 | 4.222 | 4.929 | **3.503** | 9.505 | 10.978 | **6.829** | 11.965 | 31.797 | **10.894** |
+| S3 | 4.497 | 4.904 | **3.503** | 11.440 | 12.349 | **8.099** | 17.361 | 15.686 | **9.759** |
+| S4 | 6.119 | 7.217 | **3.670** | 16.167 | 18.997 | **8.277** | 26.944 | 26.378 | **10.222** |
+| S5 | 3.009 | 3.049 | **2.882** | 9.364 | 9.773 | **8.411** | **12.126** | 14.358 | 10.654 |
+| S6 | 5.435 | 5.003 | **4.697** | 10.343 | 9.232 | **7.913** | 18.581 | 13.521 | **9.619** |
+| S7 | 7.486 | 6.673 | **5.259** | 12.626 | 11.813 | **8.569** | 16.570 | 39.672 | **11.013** |
+| S8 | 8.572 | 8.442 | **5.567** | 13.796 | 20.945 | **8.610** | 18.575 | 36.382 | **11.214** |
+| S9 | 5.004 | 4.789 | **3.616** | 9.496 | 9.225 | **6.404** | 28.355 | 16.517 | **13.191** |
+
+Recall, comparisons, and hops were exactly identical across all three modes for every case.
+Bitslice AST versus flat DNF had a **1.013x AVG latency ratio** (1.3% slower geometric mean), a
+**1.066x P99 ratio**, and a **1.180x P99.9 ratio**. This confirms that recursive AST evaluation is
+mean-latency competitive for the current one-to-four-terminal workload, while its tail is noisier;
+the S2/S7/S8 P99.9 values are dominated by isolated outliers.
+
+Precomputed AST was **1.294x faster in AVG**, **1.417x in P99**, and **1.528x in P99.9** versus
+Bitslice DNF by geometric mean. This is the expected warm/precomputed result: Roaring AST
+evaluation and dense bitmap construction occur during benchmark setup, so timed traversal pays
+only one membership lookup per visited node. Its 2.435-5.567 ms means are in the same range as the
+earlier precomputed-bitmap results in section 8.
+
+The new encoded Bitslice-DNF means were 1.218x slower by geometric mean than the immediately prior
+Bitslice-DNF rerun in section 8.4.6. Because traversal statistics are identical, this is
+run-to-run/system drift plus the new generic provider layer rather than a semantic difference;
+the matched within-run AST/DNF/precomputed comparisons are the authoritative result.
+
 ## 8.5 Exact-semantics multihop allocation reuse
 
 After optimizing filter evaluation, the current multihop implementation still created temporary
@@ -566,6 +609,7 @@ one-off searches and well-ordered selective predicates.
 - Adaptive + bit-sliced live code (section 8.3): `InlineAttributeIndexAuto` (search-type `topk-multihop-live-filter-auto`) and `InlineAttributeIndexBitslice` (search-type `topk-multihop-live-filter-bitslice`)
 - Flat DNF Bitslice code (section 8.4): `EncodedDnf`, `BitsliceSingleProvider`, and `BitsliceDnfProvider`; benchmark search-type `topk-multihop-live-filter-bitslice-dnf`; microbenchmark `diskann-label-filter/benches/benchmarks/live_filter_bench.rs`
 - Inline Bitslice-DNF comparison (section 8.4.7): benchmark search-type `topk-inline-live-filter-bitslice-dnf`, using the same `InlineAttributeIndexBitslice` and DNF providers with `InlineFilterSearch`
+- Encoded-label library comparison (section 8.4.8): `diskann-label-index`; benchmark search-types `topk-multihop-encoded-bitslice-dnf`, `topk-multihop-encoded-bitslice-ast`, and `topk-multihop-encoded-bitmap-ast`; local encoded files `data_labels_set.bitslice.bin` and `data_labels_set.bitmap.bin`
 - Index (reused): `idxsave_full`(+`.data`)
 
 _Note: an earlier version of this report used a single-valued `geo` string field; it is superseded by the set-membership results above._
\ No newline at end of file

From 5eadb21997307d83799e329631554fcc7a4215ec Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Sun, 9 Aug 2026 19:35:45 +0800
Subject: [PATCH 23/25] diskann-benchmark: include encoded query costs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 diskann-benchmark/src/index/benchmarks.rs |  35 +-
 diskann-benchmark/src/utils/filters.rs    | 407 ++++++++++++++++++----
 2 files changed, 355 insertions(+), 87 deletions(-)

diff --git a/diskann-benchmark/src/index/benchmarks.rs b/diskann-benchmark/src/index/benchmarks.rs
index 12c4fc4072..752f99dfad 100644
--- a/diskann-benchmark/src/index/benchmarks.rs
+++ b/diskann-benchmark/src/index/benchmarks.rs
@@ -451,11 +451,12 @@ where
         GroundTruthMode::Flexible,
     );
 
-    // For the encoded-label-index search phases, `data_labels` intentionally points at the
-    // pre-encoded label-index file, not the raw labels JSONL. Query compilation/materialization
-    // (including bitmap densification for the bitmap-AST mode) happens once here during benchmark
-    // setup so the timed ANN search measures only the shared multi-hop traversal with membership
-    // checks against the compiled providers.
+    // For encoded-label-index search phases, `data_labels` intentionally points at the persisted
+    // encoded label-index file, not the raw labels JSONL. Loading that index and parsing/validating
+    // the predicate JSONL (including ASTExpr -> LabelExpression conversion plus AST-JSON or DNF
+    // source preparation) stay outside timing. Each timed repetition/search-L rebuilds fresh lazy
+    // providers so the first `is_match` includes `EncodedLabelIndex::{query, query_ast_json}`,
+    // label-id lookup, AST parsing/compilation, and bitmap AST dense materialization.
     let label_index = utils::filters::load_encoded_label_index(&phase.data_labels)?;
     if label_index.format() != expected_format {
         anyhow::bail!(
@@ -465,17 +466,23 @@ where
             label_index.format()
         );
     }
-    let providers =
-        utils::filters::make_encoded_query_providers(&label_index, &phase.query_predicates, mode)?;
-
-    let multihop = benchmark_core::search::graph::MultiHop::new(
-        index,
-        queries,
-        benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
-        providers.into(),
+    let query_sources = utils::filters::prepare_encoded_query_sources(
+        label_index.as_ref(),
+        &phase.query_predicates,
+        mode,
     )?;
+    let make_multihop = || {
+        let providers =
+            utils::filters::make_encoded_query_providers(label_index.clone(), &query_sources);
+        benchmark_core::search::graph::MultiHop::new(
+            index.clone(),
+            queries.clone(),
+            benchmark_core::search::graph::Strategy::broadcast(strategy.inner()),
+            providers.into(),
+        )
+    };
 
-    let result = search::knn::run(&multihop, &groundtruth, steps)?;
+    let result = search::knn::run_fresh_multihop(make_multihop, &groundtruth, steps)?;
     Ok(AggregatedSearchResults::Topk(result))
 }
 
diff --git a/diskann-benchmark/src/utils/filters.rs b/diskann-benchmark/src/utils/filters.rs
index 01c557fef9..1ff37cc53b 100644
--- a/diskann-benchmark/src/utils/filters.rs
+++ b/diskann-benchmark/src/utils/filters.rs
@@ -4,8 +4,13 @@
  */
 
 use bit_set::BitSet;
-use std::fmt::Debug;
-use std::sync::Arc;
+use std::{
+    fmt::{self, Debug},
+    sync::{Arc, OnceLock},
+};
+
+#[cfg(test)]
+use std::sync::atomic::{AtomicUsize, Ordering};
 
 use diskann::{
     graph::ext::labeled::QueryLabelProvider,
@@ -22,7 +27,8 @@ use diskann_label_filter::{
     ASTExpr, CompareOp, DefaultKeyCodec,
 };
 use diskann_label_index::{
-    EncodedLabelIndex, EncodedLabelQuery, FilterExpressionType, LabelExpression,
+    parse_label_expression_json, EncodedLabelIndex, EncodedLabelQuery, FilterExpressionType,
+    LabelExpression,
 };
 use diskann_providers::model::graph::provider::layers::BetaFilter;
 
@@ -35,7 +41,7 @@ use diskann_label_filter::{
     InlineAttributeIndex, InlineAttributeIndexAuto, InlineAttributeIndexBitslice,
     InlineAttributeIndexCsr, InlineAttributeIndexPosting,
 };
-use serde_json::Value;
+use serde_json::{json, Value};
 
 pub struct QueryBitmapEvaluator {
     pub ast_expr: ASTExpr,
@@ -96,21 +102,80 @@ where
     }
 }
 
-#[derive(Debug)]
-struct EncodedQueryProvider(EncodedLabelQuery<'static>);
-
-impl QueryLabelProvider<u32> for EncodedQueryProvider {
-    fn is_match(&self, vec_id: u32) -> bool {
-        self.0.is_match(vec_id)
-    }
-}
-
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum EncodedQueryMode {
     Dnf,
     Ast,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum ValidatedEncodedQuerySource {
+    Dnf(Box<[String]>),
+    AstJson(String),
+}
+
+/// Per-query lazy encoded-label provider used by the encoded multihop benchmarks.
+///
+/// Outside timed search we only parse query JSONL, convert/validate the predicate shape, and store
+/// either validated DNF clauses or the recursive AST JSON string. The first `is_match` call inside
+/// timed ANN search performs the actual `EncodedLabelIndex::{query, query_ast_json}` compilation
+/// (plus bitmap AST materialization for bitmap-backed indexes); later probes reuse the cached
+/// [`EncodedLabelQuery`] for that one query row only.
+struct LazyEncodedQueryProvider {
+    index: Arc<EncodedLabelIndex>,
+    source: ValidatedEncodedQuerySource,
+    compiled: OnceLock<EncodedLabelQuery<'static>>,
+    #[cfg(test)]
+    compile_count: AtomicUsize,
+}
+
+impl LazyEncodedQueryProvider {
+    fn new(index: Arc<EncodedLabelIndex>, source: ValidatedEncodedQuerySource) -> Self {
+        Self {
+            index,
+            source,
+            compiled: OnceLock::new(),
+            #[cfg(test)]
+            compile_count: AtomicUsize::new(0),
+        }
+    }
+
+    fn compile(&self) -> EncodedLabelQuery<'static> {
+        #[cfg(test)]
+        self.compile_count.fetch_add(1, Ordering::Relaxed);
+
+        compile_encoded_query(self.index.as_ref(), &self.source).unwrap_or_else(|e| {
+            panic!(
+                "validated encoded benchmark query failed lazy compilation for {:?}: {e}",
+                self.source
+            )
+        })
+    }
+
+    #[cfg(test)]
+    fn compile_count(&self) -> usize {
+        self.compile_count.load(Ordering::Relaxed)
+    }
+}
+
+impl fmt::Debug for LazyEncodedQueryProvider {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("LazyEncodedQueryProvider")
+            .field("format", &self.index.format())
+            .field("source", &self.source)
+            .field("compiled", &self.compiled.get().is_some())
+            .finish()
+    }
+}
+
+impl QueryLabelProvider<u32> for LazyEncodedQueryProvider {
+    fn is_match(&self, vec_id: u32) -> bool {
+        self.compiled
+            .get_or_init(|| self.compile())
+            .is_match(vec_id)
+    }
+}
+
 pub(crate) fn generate_bitmaps(
     query_predicates: &InputFile,
     data_labels: &InputFile,
@@ -148,20 +213,28 @@ pub(crate) fn as_query_label_provider(set: BitSet) -> Arc<dyn QueryLabelProvider
 
 pub(crate) fn load_encoded_label_index(
     data_labels: &InputFile,
-) -> anyhow::Result<EncodedLabelIndex> {
-    EncodedLabelIndex::load(&**data_labels).map_err(|e| {
-        anyhow::anyhow!(
-            "failed to load encoded label index {}: {e}",
-            data_labels.display()
-        )
-    })
+) -> anyhow::Result<Arc<EncodedLabelIndex>> {
+    EncodedLabelIndex::load(&**data_labels)
+        .map(Arc::new)
+        .map_err(|e| {
+            anyhow::anyhow!(
+                "failed to load encoded label index {}: {e}",
+                data_labels.display()
+            )
+        })
 }
 
-pub(crate) fn make_encoded_query_providers(
+/// Parse/validate the benchmark predicate JSONL outside timed ANN search.
+///
+/// Setup still includes JSONL parsing, AST-to-`LabelExpression` conversion, supported-operator
+/// checks, null/unknown-label rejection, DNF-shape validation, and benchmark-local AST JSON
+/// serialization. Timed search begins only when the lazy provider first calls back into
+/// `EncodedLabelIndex::{query, query_ast_json}`.
+pub(crate) fn prepare_encoded_query_sources(
     index: &EncodedLabelIndex,
     query_predicates: &InputFile,
     mode: EncodedQueryMode,
-) -> anyhow::Result<Vec<Arc<dyn QueryLabelProvider<u32>>>> {
+) -> anyhow::Result<Vec<ValidatedEncodedQuerySource>> {
     let parsed = read_and_parse_queries(query_predicates.to_str().unwrap())
         .map_err(|e| anyhow::anyhow!("failed to parse query predicates: {e}"))?;
     parsed
@@ -169,19 +242,86 @@ pub(crate) fn make_encoded_query_providers(
         .map(|(_query_id, ast)| {
             let label_expression = ast_to_label_expression(&ast)?;
             validate_encoded_benchmark_labels(index, &label_expression)?;
-            let query = match mode {
-                EncodedQueryMode::Dnf => {
-                    let clauses = flatten_dnf_clauses(&label_expression)?;
-                    index.query(&clauses, FilterExpressionType::DNF)
-                }
-                EncodedQueryMode::Ast => index.query_expression(&label_expression),
-            }
-            .map_err(|e| anyhow::anyhow!("failed to compile encoded label query: {e}"))?;
-            Ok(Arc::new(EncodedQueryProvider(query)) as Arc<dyn QueryLabelProvider<u32>>)
+            encoded_query_source_from_expression(&label_expression, mode)
         })
         .collect()
 }
 
+/// Instantiate one independent lazy provider per query row.
+///
+/// Each provider receives its own [`OnceLock`], so filter compilation is never shared across query
+/// rows or across repeated benchmark executions.
+pub(crate) fn make_encoded_query_providers(
+    index: Arc<EncodedLabelIndex>,
+    query_sources: &[ValidatedEncodedQuerySource],
+) -> Vec<Arc<dyn QueryLabelProvider<u32>>> {
+    query_sources
+        .iter()
+        .cloned()
+        .map(|source| {
+            Arc::new(LazyEncodedQueryProvider::new(index.clone(), source))
+                as Arc<dyn QueryLabelProvider<u32>>
+        })
+        .collect()
+}
+
+fn encoded_query_source_from_expression(
+    expression: &LabelExpression,
+    mode: EncodedQueryMode,
+) -> anyhow::Result<ValidatedEncodedQuerySource> {
+    match mode {
+        EncodedQueryMode::Dnf => Ok(ValidatedEncodedQuerySource::Dnf(
+            flatten_dnf_clauses(expression)?.into_boxed_slice(),
+        )),
+        EncodedQueryMode::Ast => {
+            let expression_json = label_expression_to_ast_json(expression)?;
+            parse_label_expression_json(&expression_json)
+                .map_err(|e| anyhow::anyhow!("encoded AST source failed validation: {e}"))?;
+            Ok(ValidatedEncodedQuerySource::AstJson(expression_json))
+        }
+    }
+}
+
+fn compile_encoded_query(
+    index: &EncodedLabelIndex,
+    source: &ValidatedEncodedQuerySource,
+) -> anyhow::Result<EncodedLabelQuery<'static>> {
+    match source {
+        ValidatedEncodedQuerySource::Dnf(clauses) => index
+            .query(clauses.as_ref(), FilterExpressionType::DNF)
+            .map_err(|e| anyhow::anyhow!("failed to compile encoded DNF query: {e}")),
+        ValidatedEncodedQuerySource::AstJson(expression_json) => index
+            .query_ast_json(expression_json)
+            .map_err(|e| anyhow::anyhow!("failed to compile encoded AST query: {e}")),
+    }
+}
+
+fn label_expression_to_ast_json(expression: &LabelExpression) -> anyhow::Result<String> {
+    serde_json::to_string(&label_expression_to_ast_value(expression))
+        .map_err(|e| anyhow::anyhow!("failed to serialize encoded AST query: {e}"))
+}
+
+fn label_expression_to_ast_value(expression: &LabelExpression) -> Value {
+    match expression {
+        LabelExpression::Label(label) => Value::String(label.clone()),
+        LabelExpression::And(children) => json!({
+            "and": children
+                .iter()
+                .map(label_expression_to_ast_value)
+                .collect::<Vec<_>>()
+        }),
+        LabelExpression::Or(children) => json!({
+            "or": children
+                .iter()
+                .map(label_expression_to_ast_value)
+                .collect::<Vec<_>>()
+        }),
+        LabelExpression::Not(child) => json!({
+            "not": label_expression_to_ast_value(child)
+        }),
+    }
+}
+
 fn checked_doc_id(doc_id: usize) -> anyhow::Result<u32> {
     u32::try_from(doc_id)
         .map_err(|_| anyhow::anyhow!("document id {doc_id} exceeds the u32 graph-id range"))
@@ -599,6 +739,63 @@ mod tests {
             .collect()
     }
 
+    fn test_compiled_query_matches(query: &EncodedLabelQuery<'_>, num_vectors: u32) -> Vec<u32> {
+        (0..num_vectors)
+            .filter(|&vec_id| query.is_match(vec_id))
+            .collect()
+    }
+
+    fn encoded_fixture() -> (
+        tempfile::TempDir,
+        Arc<EncodedLabelIndex>,
+        Arc<EncodedLabelIndex>,
+        InputFile,
+    ) {
+        let dir = tempdir().unwrap();
+        let labels_jsonl = dir.path().join("labels.jsonl");
+        let bitslice_index = dir.path().join("labels.bitslice");
+        let bitmap_index = dir.path().join("labels.bitmap");
+        let queries_jsonl = dir.path().join("queries.jsonl");
+
+        write_lines(
+            &labels_jsonl,
+            &[
+                r#"{"doc_id":0,"brand":"A","color":"red","promo":true,"active":false,"score":2,"missing":null}"#,
+                r#"{"doc_id":1,"brand":"A","color":"blue","promo":false,"active":false,"score":3,"missing":"value"}"#,
+                r#"{"doc_id":2,"brand":"B","color":"red","promo":false,"active":true,"score":2,"missing":null}"#,
+                r#"{"doc_id":3,"brand":"C","color":"green","promo":true,"active":false,"score":5,"missing":null}"#,
+            ],
+        );
+        write_lines(
+            &queries_jsonl,
+            &[
+                r#"{"query_id":0,"filter":{"$or":[{"$and":[{"brand":{"$eq":"A"}},{"color":{"$eq":"red"}}]},{"promo":{"$eq":true}}]}}"#,
+                r#"{"query_id":1,"filter":{"active":{"$eq":false},"score":{"$eq":2}}}"#,
+                r#"{"query_id":2,"filter":{"$or":[{"brand":{"$eq":"B"}},{"color":{"$eq":"green"}}]}}"#,
+            ],
+        );
+
+        encode_label_index_jsonl(&labels_jsonl, &bitslice_index, LabelIndexFormat::Bitslice)
+            .unwrap();
+        encode_label_index_jsonl(&labels_jsonl, &bitmap_index, LabelIndexFormat::Bitmap).unwrap();
+
+        (
+            dir,
+            load_encoded_label_index(&InputFile::new(bitslice_index)).unwrap(),
+            load_encoded_label_index(&InputFile::new(bitmap_index)).unwrap(),
+            InputFile::new(queries_jsonl),
+        )
+    }
+
+    fn eager_encoded_matches(
+        index: &EncodedLabelIndex,
+        source: &ValidatedEncodedQuerySource,
+        num_vectors: u32,
+    ) -> Vec<u32> {
+        let query = compile_encoded_query(index, source).unwrap();
+        test_compiled_query_matches(&query, num_vectors)
+    }
+
     #[test]
     fn test_bitmap_filter_match() {
         let mut bitset = BitSet::new();
@@ -641,60 +838,124 @@ mod tests {
     }
 
     #[test]
-    fn test_encoded_providers_agree_for_dnf_and_ast() {
+    fn test_lazy_encoded_dnf_provider_matches_eager_query() {
+        let (_dir, bitslice_index, _bitmap_index, query_file) = encoded_fixture();
+        let sources = prepare_encoded_query_sources(
+            bitslice_index.as_ref(),
+            &query_file,
+            EncodedQueryMode::Dnf,
+        )
+        .unwrap();
+        let providers = make_encoded_query_providers(bitslice_index.clone(), &sources);
+
+        assert_eq!(providers.len(), sources.len());
+        for (provider, source) in providers.iter().zip(&sources) {
+            assert_eq!(
+                test_query_matches(provider, 4),
+                eager_encoded_matches(bitslice_index.as_ref(), source, 4)
+            );
+        }
+    }
+
+    #[test]
+    fn test_lazy_encoded_ast_provider_matches_eager_query_for_bitslice_and_bitmap() {
+        let (_dir, bitslice_index, bitmap_index, query_file) = encoded_fixture();
+        let bitslice_sources = prepare_encoded_query_sources(
+            bitslice_index.as_ref(),
+            &query_file,
+            EncodedQueryMode::Ast,
+        )
+        .unwrap();
+        let bitmap_sources = prepare_encoded_query_sources(
+            bitmap_index.as_ref(),
+            &query_file,
+            EncodedQueryMode::Ast,
+        )
+        .unwrap();
+        let bitslice_providers =
+            make_encoded_query_providers(bitslice_index.clone(), &bitslice_sources);
+        let bitmap_providers = make_encoded_query_providers(bitmap_index.clone(), &bitmap_sources);
+
+        assert_eq!(bitslice_providers.len(), bitslice_sources.len());
+        assert_eq!(bitmap_providers.len(), bitmap_sources.len());
+        for ((bitslice_provider, bitslice_source), (bitmap_provider, bitmap_source)) in
+            bitslice_providers
+                .iter()
+                .zip(&bitslice_sources)
+                .zip(bitmap_providers.iter().zip(&bitmap_sources))
+        {
+            assert_eq!(
+                test_query_matches(bitslice_provider, 4),
+                eager_encoded_matches(bitslice_index.as_ref(), bitslice_source, 4)
+            );
+            assert_eq!(
+                test_query_matches(bitmap_provider, 4),
+                eager_encoded_matches(bitmap_index.as_ref(), bitmap_source, 4)
+            );
+        }
+    }
+
+    #[test]
+    fn test_encoded_ast_source_json_shape() {
+        let expression = LabelExpression::Or(vec![
+            LabelExpression::And(vec![
+                LabelExpression::Label("brand=A".into()),
+                LabelExpression::Not(Box::new(LabelExpression::Label("promo".into()))),
+            ]),
+            LabelExpression::Label("color=red".into()),
+        ]);
+        let source =
+            encoded_query_source_from_expression(&expression, EncodedQueryMode::Ast).unwrap();
+        let ValidatedEncodedQuerySource::AstJson(expression_json) = source else {
+            panic!("expected AST JSON source");
+        };
+
+        assert_eq!(
+            serde_json::from_str::<Value>(&expression_json).unwrap(),
+            json!({
+                "or": [
+                    {
+                        "and": [
+                            "brand=A",
+                            { "not": "promo" }
+                        ]
+                    },
+                    "color=red"
+                ]
+            })
+        );
+    }
+
+    #[test]
+    fn test_lazy_encoded_provider_reuses_compilation_per_instance() {
         let dir = tempdir().unwrap();
         let labels_jsonl = dir.path().join("labels.jsonl");
         let bitslice_index = dir.path().join("labels.bitslice");
-        let bitmap_index = dir.path().join("labels.bitmap");
-        let queries_jsonl = dir.path().join("queries.jsonl");
-
         write_lines(
             &labels_jsonl,
             &[
-                r#"{"doc_id":0,"brand":"A","color":"red","promo":true,"active":false,"score":2,"missing":null}"#,
-                r#"{"doc_id":1,"brand":"A","color":"blue","promo":false,"active":false,"score":3,"missing":"value"}"#,
-                r#"{"doc_id":2,"brand":"B","color":"red","promo":false,"active":true,"score":2,"missing":null}"#,
-                r#"{"doc_id":3,"brand":"C","color":"green","promo":true,"active":false,"score":5,"missing":null}"#,
-            ],
-        );
-        write_lines(
-            &queries_jsonl,
-            &[
-                r#"{"query_id":0,"filter":{"$or":[{"$and":[{"brand":{"$eq":"A"}},{"color":{"$eq":"red"}}]},{"promo":{"$eq":true}}]}}"#,
-                r#"{"query_id":1,"filter":{"active":{"$eq":false},"score":{"$eq":2}}}"#,
-                r#"{"query_id":2,"filter":{"$or":[{"brand":{"$eq":"B"}},{"color":{"$eq":"green"}}]}}"#,
+                r#"{"doc_id":0,"A":true,"B":true}"#,
+                r#"{"doc_id":1,"A":false,"B":true}"#,
             ],
         );
-
         encode_label_index_jsonl(&labels_jsonl, &bitslice_index, LabelIndexFormat::Bitslice)
             .unwrap();
-        encode_label_index_jsonl(&labels_jsonl, &bitmap_index, LabelIndexFormat::Bitmap).unwrap();
+        let index = load_encoded_label_index(&InputFile::new(bitslice_index)).unwrap();
+        let source = ValidatedEncodedQuerySource::AstJson(r#"{"and":["A","B"]}"#.to_string());
+        let provider_a = Arc::new(LazyEncodedQueryProvider::new(index.clone(), source.clone()));
+        let provider_b = Arc::new(LazyEncodedQueryProvider::new(index, source));
 
-        let bitslice_index = load_encoded_label_index(&InputFile::new(bitslice_index)).unwrap();
-        let bitmap_index = load_encoded_label_index(&InputFile::new(bitmap_index)).unwrap();
-        let query_file = InputFile::new(queries_jsonl);
+        assert_eq!(provider_a.compile_count(), 0);
+        assert_eq!(provider_b.compile_count(), 0);
+        assert!(provider_a.is_match(0));
+        assert!(!provider_a.is_match(1));
+        assert!(provider_a.is_match(0));
+        assert_eq!(provider_a.compile_count(), 1);
+        assert_eq!(provider_b.compile_count(), 0);
 
-        let dnf = make_encoded_query_providers(&bitslice_index, &query_file, EncodedQueryMode::Dnf)
-            .unwrap();
-        let bitslice_ast =
-            make_encoded_query_providers(&bitslice_index, &query_file, EncodedQueryMode::Ast)
-                .unwrap();
-        let bitmap_ast =
-            make_encoded_query_providers(&bitmap_index, &query_file, EncodedQueryMode::Ast)
-                .unwrap();
-
-        assert_eq!(dnf.len(), bitslice_ast.len());
-        assert_eq!(dnf.len(), bitmap_ast.len());
-        for ((dnf, bitslice_ast), bitmap_ast) in dnf.iter().zip(&bitslice_ast).zip(&bitmap_ast) {
-            assert_eq!(
-                test_query_matches(dnf, 4),
-                test_query_matches(bitslice_ast, 4)
-            );
-            assert_eq!(
-                test_query_matches(dnf, 4),
-                test_query_matches(bitmap_ast, 4)
-            );
-        }
+        assert!(provider_b.is_match(0));
+        assert_eq!(provider_b.compile_count(), 1);
+        assert_eq!(provider_a.compile_count(), 1);
     }
 
     #[test]

From fa256c1e8e48ce1826119f1580d20f1aea6bdba4 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Sun, 9 Aug 2026 19:35:46 +0800
Subject: [PATCH 24/25] docs: report query-inclusive filter latency

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../multiple_filter_test_report.md            | 41 +++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/diskann-benchmark/multiple_filter_test_report.md b/diskann-benchmark/multiple_filter_test_report.md
index 5b96a9acc6..c9cb5b90e8 100644
--- a/diskann-benchmark/multiple_filter_test_report.md
+++ b/diskann-benchmark/multiple_filter_test_report.md
@@ -504,6 +504,47 @@ Bitslice-DNF rerun in section 8.4.6. Because traversal statistics are identical,
 run-to-run/system drift plus the new generic provider layer rather than a semantic difference;
 the matched within-run AST/DNF/precomputed comparisons are the authoritative result.
 
+### 8.4.9 Including per-query encoding and materialization
+
+The encoded benchmark providers were then changed to compile lazily on their first `is_match`
+inside timed ANN search. Each query row owns an independent `OnceLock`, and fresh providers are
+created for every repetition and search-L. The timed path therefore includes:
+
+- DNF: label-string lookup and flat clause-plan compilation;
+- Bitslice AST: JSON AST parsing, validation, label lookup, and recursive-plan compilation;
+- Bitmap AST: all AST costs plus Roaring set algebra, dense allocation/zeroing, and result
+  materialization.
+
+The persisted Bitslice/Roaring index load and benchmark predicate-file parsing remain index/setup
+costs outside query latency. The same counterbalanced S1-S9 configuration was rerun.
+
+| Case | DNF AVG | AST AVG | Bitmap AST AVG | DNF P99 | AST P99 | Bitmap P99 | DNF P99.9 | AST P99.9 | Bitmap P99.9 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| S1 | 2.698 | 2.651 | 46.479 | 9.836 | 9.470 | 57.984 | 13.368 | 12.521 | 76.905 |
+| S2 | 4.448 | 4.913 | 9.944 | 10.057 | 11.263 | 13.580 | 12.969 | 29.329 | 16.460 |
+| S3 | 4.561 | 4.781 | 14.694 | 11.687 | 11.945 | 20.159 | 17.175 | 15.934 | 24.612 |
+| S4 | 5.135 | 7.659 | 16.351 | 12.650 | 20.666 | 22.637 | 18.467 | 41.756 | 43.390 |
+| S5 | 3.145 | 2.796 | 43.062 | 9.698 | 8.590 | 54.658 | 14.802 | 11.736 | 76.852 |
+| S6 | 5.535 | 4.978 | 14.109 | 9.812 | 9.164 | 19.467 | 13.161 | 13.473 | 26.372 |
+| S7 | 6.675 | 5.837 | 7.771 | 10.772 | 9.471 | 11.038 | 33.984 | 14.685 | 16.343 |
+| S8 | 6.824 | 6.044 | **6.153** | 10.699 | 9.027 | 9.774 | 15.958 | 23.023 | **13.200** |
+| S9 | 4.338 | 4.677 | 8.646 | 8.158 | 8.846 | 12.546 | 9.367 | 11.445 | 15.766 |
+
+Recall, comparisons, and hops again matched exactly. Query-inclusive Bitslice AST remained almost
+tied with DNF: its geometric-mean AVG ratio was **1.014x**. The DNF/AST compilation costs are small
+relative to traversal and system noise; several query-inclusive means are lower than the
+setup-excluded run, so subtracting the independent runs is not a reliable microsecond estimate.
+
+Bitmap AST became **3.130x slower than DNF** by geometric-mean AVG once its per-query materialization
+was charged. The approximate setup-excluded-to-inclusive mean increase ranged from 0.585 ms for
+selective S8 to 44.043 ms for broad S1, averaging 14.675 ms across S1-S9. Its broad-filter
+S1/S5 means returned to 46.479/43.062 ms, while selective S8 remained competitive at 6.153 ms.
+
+These results reproduce the previous no-cache Roaring-materialized benchmark: the new Bitmap AST
+means are within the same range as section 8.4.6 and are 0.909x its geometric mean. The conclusion
+is unchanged: live Bitslice DNF/AST is normally preferable for unique queries, while
+materialization can compete for sufficiently selective filters or when its result is reused.
+
 ## 8.5 Exact-semantics multihop allocation reuse
 
 After optimizing filter evaluation, the current multihop implementation still created temporary

From 0aadf5519285b5501f0575b5f8760f8b5ce93928 Mon Sep 17 00:00:00 2001
From: Sanhaoji2 <jegao@microsoft.com>
Date: Tue, 11 Aug 2026 17:32:38 +0800
Subject: [PATCH 25/25] docs: summarize multi-filter ANN optimization

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../multiple_filter_optimization_summary.md   | 393 ++++++++++++++++++
 1 file changed, 393 insertions(+)
 create mode 100644 diskann-benchmark/multiple_filter_optimization_summary.md

diff --git a/diskann-benchmark/multiple_filter_optimization_summary.md b/diskann-benchmark/multiple_filter_optimization_summary.md
new file mode 100644
index 0000000000..f06cdd629e
--- /dev/null
+++ b/diskann-benchmark/multiple_filter_optimization_summary.md
@@ -0,0 +1,393 @@
+# Multi-Filter ANN Optimization Summary
+
+## Executive summary
+
+The objective was to keep the high recall of Rust multihop filtered search while reducing the
+query-time cost of evaluating multi-label filters.
+
+The original Rust benchmark used an **Abstract Syntax Tree (AST)** to precompute the complete
+matching-document bitmap before ANN traversal. This made each traversal-time membership check
+cheap, but the reported **3.15-6.84 ms** mean latency at `L=150` excluded the expensive per-query
+bitmap construction.
+
+The final implementation keeps the same multihop traversal and replaces query-result
+materialization with:
+
+1. a persisted, attribute-major **Bitslice** label index; and
+2. a flat **Disjunctive Normal Form (DNF)** query plan evaluated directly against the Bitslice data.
+
+In the query-inclusive comparison, Bitmap+AST required **6.15-46.48 ms**, while Bitslice+DNF
+required **2.70-6.82 ms**. Bitslice+DNF was **3.13x faster by geometric-mean average latency**.
+Recall, distance comparisons, and graph hops were identical, so this was a filter-evaluation
+improvement rather than a quality trade-off.
+
+## Test scope
+
+| Item | Configuration |
+|---|---|
+| Dataset | 9,996,160 PMax vectors |
+| Vector type | 64-dimensional float32 benchmark data |
+| Label vocabulary | 596 labels |
+| Queries | 1,000 |
+| Filter workload | 9 single-label and multi-label predicates |
+| Selectivity | 1.17% to 66.40% |
+| Search | `k=150`, `L=150`, one thread, three repetitions |
+| Correctness | Exact filtered ground truth; identical recall/comparisons/hops across compared providers |
+
+## Original Rust implementation: precomputed Bitmap + AST
+
+The original implementation separated filter evaluation from graph traversal. Before search, it
+parsed the query into a recursive Boolean predicate, combined the label posting lists, and
+materialized the complete set of matching vector IDs. The ANN multihop traversal then checked each
+visited vector against that prebuilt bitmap. Once the complete match set was available, each
+membership check was cheap.
+
+### Precomputed Roaring label map
+
+The persistent index is an inverted map from labels to vector IDs. It is built once with the ANN
+index rather than rebuilt for every query:
+
+| Component | Structure | Purpose |
+|---|---|---|
+| Label dictionary | Ordered label strings | Gives every distinct label a stable numeric ID |
+| Label lookup | Label string to numeric ID | Resolves each terminal in the query expression |
+| Posting table | One Roaring bitmap at each label-ID position | Stores every vector ID carrying that label |
+| Vector count | Total number of addressable vector IDs | Defines the universe used by `NOT` and the final dense bitmap |
+
+#### Worked Roaring map example
+
+Assume ten vectors have the following labels:
+
+| Vector ID | Assigned labels |
+|---:|---|
+| 0 | C, D |
+| 1 | A |
+| 2 | A, B |
+| 3 | None |
+| 4 | D |
+| 5 | A, B, C |
+| 6 | None |
+| 7 | B |
+| 8 | A |
+| 9 | C |
+
+The encoder inverts those vector rows into a dictionary and a posting array:
+
+```text
+labels      = ["A", "B", "C", "D"]
+label_ids   = {"A": 0, "B": 1, "C": 2, "D": 3}
+
+postings[0] = Roaring{1, 2, 5, 8}  // vectors carrying A
+postings[1] = Roaring{2, 5, 7}     // vectors carrying B
+postings[2] = Roaring{0, 5, 9}     // vectors carrying C
+postings[3] = Roaring{0, 4}        // vectors carrying D
+
+num_vectors = 10
+```
+
+The two arrays are aligned by numeric label ID. A query terminal `C` therefore performs
+`label_ids["C"] -> 2 -> postings[2]`; the posting itself stores only vector IDs, not another copy of
+the string `C`. For `A AND C`, the evaluator intersects `postings[0]` and `postings[2]` and obtains
+`{5}`. The same postings are reused in the AST example below.
+
+Each posting is a compressed, ordered set of 32-bit vector IDs. Roaring partitions the ID space by
+the upper 16 bits, creating one container for each populated 65,536-ID range. All IDs in the small
+example are in range 0, so the A posting is one sparse container:
+
+```text
+postings[0] for A
+  container key 0 -> offsets [1, 2, 5, 8]
+```
+
+If A also appeared on vector 65,538, Roaring would place offset 2 in a second container because
+`65,538 = 1 * 65,536 + 2`:
+
+```text
+postings[0] for A
+  container key 0 -> offsets [1, 2, 5, 8]
+  container key 1 -> offsets [2]
+```
+
+Sparse ranges retain compact sorted offsets, while dense ranges use bitmaps. Union, intersection,
+and subtraction operate on matching containers rather than scanning all 9,996,160 vectors. This is
+why the persisted Roaring index is only **59.0 MiB** for PMax, far smaller than one dense
+vector-length bit slice for every label. The posting table is immutable after loading and is shared
+across queries.
+
+On disk, the index contains a small format header, the label dictionary, and one length-prefixed
+serialized Roaring posting per label. At load time, the dictionary is reconstructed into the
+label-to-ID lookup and the postings become a numeric-ID-indexed array. Therefore a query terminal
+requires one label lookup followed by direct access to its posting bitmap.
+
+### How the AST produces a query bitmap
+
+The query is parsed into a tree whose leaves are labels and whose internal nodes are Boolean
+operators. Label strings are first replaced with their numeric IDs; a label absent from the index
+represents an empty posting.
+
+The evaluator uses a depth-first, post-order traversal. It enters at the root, recursively descends
+to a leaf, returns that leaf's posting bitmap to its parent, and combines child results while
+unwinding back up the tree. An operator is therefore entered before its children but produces its
+result only after the required children have returned. The root is the last node to produce a
+bitmap, and that bitmap is the final query result.
+
+| AST node | Bitmap evaluation |
+|---|---|
+| Label | Copy that label's precomputed Roaring posting |
+| `AND` | Intersect the child results; stop as soon as the intermediate result is empty |
+| `OR` | Union the child results into an initially empty bitmap |
+| `NOT` | Start with the full vector-ID universe and subtract the child result |
+
+For a small example, assume A maps to `{1, 2, 5, 8}`, B to `{2, 5, 7}`, C to `{0, 5, 9}`, and D
+to `{0, 4}`. The expression `(A AND B) OR (C AND NOT D)` produces this AST:
+
+```mermaid
+flowchart TD
+    Root["OR<br/>result: {2, 5, 9}"]
+    LeftAnd["AND<br/>result: {2, 5}"]
+    A["A<br/>{1, 2, 5, 8}"]
+    B["B<br/>{2, 5, 7}"]
+    RightAnd["AND<br/>result: {5, 9}"]
+    C["C<br/>{0, 5, 9}"]
+    NotD["NOT<br/>result: U - {0, 4}"]
+    D["D<br/>{0, 4}"]
+
+    Root -->|"left child"| LeftAnd
+    Root -->|"right child"| RightAnd
+    LeftAnd --> A
+    LeftAnd --> B
+    RightAnd --> C
+    RightAnd --> NotD
+    NotD --> D
+```
+
+`U` is the full valid vector-ID universe. The evaluator walks the tree as follows:
+
+1. Enter the root `OR`, then descend into its left `AND` subtree.
+2. Visit leaf A and return `{1, 2, 5, 8}`; visit leaf B and return `{2, 5, 7}`.
+3. The left `AND` intersects those child results and returns `{2, 5}` to the root.
+4. Descend into the right `AND`. Leaf C returns `{0, 5, 9}`. The `NOT` node descends to D,
+   receives `{0, 4}`, subtracts it from `U`, and returns `U - {0, 4}`.
+5. The right `AND` intersects `{0, 5, 9}` with `U - {0, 4}` and returns `{5, 9}`.
+6. After both subtrees have returned, the root `OR` unions `{2, 5}` with `{5, 9}` and produces
+   the final match set `{2, 5, 9}`.
+
+Each internal node can create or modify an intermediate Roaring bitmap. After the root is evaluated,
+the final Roaring result is converted into a dense array of 64-bit words with one bit per vector.
+For 9,996,160 PMax vectors, this final query bitmap is about **1.19 MiB**. Multihop search then tests
+a candidate by loading one word and checking the candidate's bit; it no longer walks the AST during
+graph traversal.
+
+This design deliberately moves work out of the traversal hot path. Its cost is paid once for each
+new predicate: resolve the AST terminals, clone and combine Roaring postings, allocate and zero the
+dense result, and enumerate every matching ID to set its bit. Broad predicates create large
+intermediate and final sets, which explains why query-inclusive Bitmap+AST latency grows sharply
+even though its later per-node membership checks are inexpensive.
+
+This approach has two different performance views:
+
+| Measurement | Mean latency | Meaning |
+|---|---:|---|
+| Original search-only benchmark | 3.15-6.84 ms | Bitmap already existed; AST evaluation and materialization were outside search timing |
+| Query-inclusive Bitmap+AST | 6.15-46.48 ms | Includes AST compilation, Roaring set operations, dense allocation/zeroing, and materialization |
+
+The search-only result is useful as a warm-cache ideal, but it is not the end-to-end latency of a
+new filter predicate. Broad predicates are especially expensive because millions of matching IDs
+must be enumerated and copied into the query bitmap.
+
+## How multihop traverses the graph compared with normal ANN
+
+Normal ANN performs a greedy beam search. It repeatedly expands the closest unvisited node and adds
+its promising neighbors to a bounded search list. Labels do not affect this traversal, so every
+discovered node is eligible to remain in the list, be expanded later, and become a result.
+
+Multihop makes two important changes for newly discovered neighbors:
+
+1. **Only nodes that pass the filter enter the search list.** A failed node cannot consume a search
+   list slot, be selected as a normal frontier node, or become a result.
+2. **A selected failed one-hop neighbor can still expose its children.** Multihop inspects that
+   failed node's adjacency list once. Passing grandchildren enter the search list; failed
+   grandchildren are discarded, so the routing path does not continue through them.
+
+The following local graph is shown as a traversal tree. `PASS` and `FAIL` describe the filter
+result, and `d` is distance to the query. Assume beam width 1 and a search list large enough to hold
+all nodes in the example.
+
+```mermaid
+flowchart TB
+    A["A: current frontier<br/>PASS"]
+    A -->|"one hop"| B["B: PASS<br/>d = 0.18"]
+    A -. "rejected; routing only" .-> C["C: FAIL<br/>d = 0.12"]
+    A -->|"one hop"| D["D: PASS<br/>d = 0.25"]
+    C -. "one extra hop" .-> E["E: PASS<br/>d = 0.08"]
+    C -. "one extra hop" .-> F["F: FAIL<br/>d = 0.30"]
+
+    classDef frontier fill:#dbeafe,stroke:#2563eb,color:#111827;
+    classDef match fill:#dcfce7,stroke:#16a34a,color:#111827;
+    classDef reject fill:#fee2e2,stroke:#dc2626,color:#111827;
+    class A frontier;
+    class B,D,E match;
+    class C,F reject;
+```
+
+The table shows only the **unexpanded frontier** of the search list, ordered by query distance.
+Normal ANN ignores the displayed filter status; it is included only to make the comparison visible.
+
+| Stage | Normal ANN search-list frontier | Multihop search-list frontier |
+|---|---|---|
+| Seed | `[A]` | `[A]` |
+| Expand `A` | `[C FAIL 0.12, B PASS 0.18, D PASS 0.25]` | `[B PASS 0.18, D PASS 0.25]`; `C` is kept only as a temporary routing choice |
+| Handle `C` | `C` is the closest candidate, so normal ANN expands it and gets `[E PASS 0.08, B PASS 0.18, D PASS 0.25, F FAIL 0.30]` | Without inserting `C`, multihop inspects its children once: `E` passes and enters the list, while `F` fails and is dropped, producing `[E PASS 0.08, B PASS 0.18, D PASS 0.25]` |
+| Select the next frontier | Expand `E` | Expand `E` |
+
+The key list transitions are therefore:
+
+- Normal ANN: `[A] -> [C, B, D] -> [E, B, D, F]`
+- Multihop: `[A] -> [B, D] -> [E, B, D]`
+
+`C` never occupies the multihop search list, but it still reveals matching grandchild `E`. `F` also
+fails, so it is neither inserted nor expanded; multihop does not take a third hop through it. Once
+`E` enters the list, it behaves like any other passing candidate and can continue normal graph
+traversal in later iterations.
+
+This routing is selective rather than an unrestricted deeper graph walk. For each frontier
+expansion, multihop sorts failed one-hop neighbors by query distance, keeps only the closest subset
+up to half the graph degree, and examines exactly one additional hop through them. A rejected graph
+entry point is the one special case: it may seed traversal, but it is excluded from returned
+results.
+
+Compared with a hard filter, this strategy performs extra routing work, but it prevents the filter
+from turning a useful bridge into a hard traversal boundary. Compared with normal ANN, it retains
+the same greedy candidate search while changing non-matching nodes from result candidates into
+short-lived connectors. In the original *L*=150 benchmark, multihop achieved **0.834-0.972
+recall@150** across filters ranging from 1.17% to 66.40% selectivity.
+
+## Final implementation: Bitslice + flat DNF
+
+### 1. Pre-encode labels as attribute-major Bitslices
+
+The label index stores one dense vector-ID bitset per label. Each bit position corresponds to one
+vector, so a set bit means that the vector has that label. Checking whether a vector has a label
+requires reading the machine word containing that vector's bit and testing only that bit.
+
+#### Worked Bitslice example
+
+Reuse the ten-vector label assignment from the Roaring example. Instead of storing a compressed set
+of vector IDs for each label, the Bitslice representation allocates one dense row of bits per label:
+
+| Label row | Vector 0 | Vector 1 | Vector 2 | Vector 3 | Vector 4 | Vector 5 | Vector 6 | Vector 7 | Vector 8 | Vector 9 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| A, label ID 0 | 0 | 1 | 1 | 0 | 0 | 1 | 0 | 0 | 1 | 0 |
+| B, label ID 1 | 0 | 0 | 1 | 0 | 0 | 1 | 0 | 1 | 0 | 0 |
+| C, label ID 2 | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 1 |
+| D, label ID 3 | 1 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 |
+
+Bits are packed into 64-bit words, with vector 0 using the least-significant bit. Ten vectors require
+`ceil(10 / 64) = 1` word per label, so the four rows above become:
+
+| Flat word position | Label | Set bit positions | Packed 64-bit word |
+|---:|---|---|---:|
+| 0 | A | 1, 2, 5, 8 | `0x0000000000000126` |
+| 1 | B | 2, 5, 7 | `0x00000000000000A4` |
+| 2 | C | 0, 5, 9 | `0x0000000000000221` |
+| 3 | D | 0, 4 | `0x0000000000000011` |
+
+All label rows are stored consecutively in one flat array. For a larger index,
+`words_per_label = ceil(vector_count / 64)`, and a lookup uses the word at
+`label_id * words_per_label + floor(vector_id / 64)`. It then tests the mask
+`1 << (vector_id % 64)`.
+
+For example, testing whether vector 5 has label C selects label row 2, reads word
+`0x0000000000000221`, and tests mask `0x20`. The result is nonzero, so C is present. Testing the
+same vector for D reads row 3; `0x0000000000000011 & 0x20` is zero, so D is absent.
+
+For the DNF query `(A AND B) OR (C AND D)`, vector 5 reads the same bit position from the A and B
+rows. Both bits are set, so the first `AND` clause succeeds and the outer `OR` stops without
+checking C or D. This label-major layout is why a visited graph node can be evaluated directly:
+the search reads only the relevant bits for that vector and never constructs a query-wide result
+bitmap.
+
+The index is built once and shared by all queries. After the one-time label-ID and DNF-plan
+compilation, each node check avoids query-result bitmap allocation and posting-list iteration.
+
+### 2. Compile the query into a flat DNF plan
+
+Queries are normalized to an `OR` of `AND` clauses. For example, a query can require both labels A
+and B, or both labels C and D. The compiled plan stores the clause boundaries and label IDs in
+contiguous arrays rather than retaining the recursive query tree.
+
+The hot path iterates contiguous label IDs instead of recursively walking an AST. Each `AND`
+clause stops at its first missing label, and the outer `OR` stops at its first matching clause.
+
+This removes recursive enum dispatch and repeated tree navigation. In the isolated predicate
+benchmark, flat DNF was:
+
+| Predicate | DNF evaluator speedup vs recursive Bitslice AST |
+|---|---:|
+| One label | 2.03x |
+| Two-label `AND` | 1.37x |
+| Four-label OR-of-AND | 1.91x |
+
+In the controlled full ANN benchmark, DNF improved average latency by **1.125x** and P99 by
+**1.137x** over the recursive Bitslice AST, with identical search results. The larger end-to-end
+gain versus Bitmap+AST comes primarily from eliminating per-query match-set materialization; DNF
+then reduces the remaining per-node evaluation overhead.
+
+### 3. Reuse multihop scratch storage
+
+The final search also reuses adjacency buffers across one-hop and two-hop expansions and iterates
+the selected routing neighbors without allocating another ID vector. This preserved exact search
+semantics and added a further **3.72% average-latency** and **3.07% P99** improvement.
+
+## End-to-end performance comparison
+
+The tables below use the fair query-inclusive encoded-label benchmark. Both methods include query
+compilation; Bitmap+AST also includes Roaring AST evaluation and dense bitmap materialization.
+
+| Representative case | Selectivity | Bitmap+AST AVG | Bitslice+DNF AVG | Speedup |
+|---|---:|---:|---:|---:|
+| S1: broad single label | 66.40% | 46.479 ms | 2.698 ms | **17.23x** |
+| S4: four-label OR-of-AND | 10.03% | 16.351 ms | 5.135 ms | **3.18x** |
+| S6: medium-selectivity single label | 12.58% | 14.109 ms | 5.535 ms | **2.55x** |
+| S8: very selective single label | 1.17% | **6.153 ms** | 6.824 ms | 0.90x |
+| S9: two-label AND | 5.67% | 8.646 ms | 4.338 ms | **1.99x** |
+| **S1-S9 geometric mean** | 1.17%-66.40% | - | - | **3.13x** |
+
+Tail latency, where P999 is the 99.9th percentile:
+
+| Representative case | Bitmap+AST P99 | Bitslice+DNF P99 | P99 speedup | Bitmap+AST P999 | Bitslice+DNF P999 | P999 speedup |
+|---|---:|---:|---:|---:|---:|---:|
+| S1: broad single label | 57.984 ms | **9.836 ms** | **5.90x** | 76.905 ms | **13.368 ms** | **5.75x** |
+| S4: four-label OR-of-AND | 22.637 ms | **12.650 ms** | **1.79x** | 43.390 ms | **18.467 ms** | **2.35x** |
+| S6: medium-selectivity single label | 19.467 ms | **9.812 ms** | **1.98x** | 26.372 ms | **13.161 ms** | **2.00x** |
+| S8: very selective single label | **9.774 ms** | 10.699 ms | 0.91x | **13.200 ms** | 15.958 ms | 0.83x |
+| S9: two-label AND | 12.546 ms | **8.158 ms** | **1.54x** | 15.766 ms | **9.367 ms** | **1.68x** |
+| **S1-S9 geometric mean** | - | - | **1.94x** | - | - | **1.77x** |
+
+Bitmap materialization can remain competitive for a very selective predicate because its result
+set is small. Bitslice+DNF provides the stronger overall result and avoids the severe broad-filter
+latency spikes. Across S1-S9, it improves geometric-mean P99 by **1.94x** and P999 by **1.77x**.
+
+## Trade-offs and recommendation
+
+| Area | Bitmap+AST | Bitslice+DNF |
+|---|---|---|
+| Persisted label-index size | 59.0 MiB | 710.2 MiB |
+| Query-time setup | AST set algebra plus result materialization | Label-ID lookup plus compact DNF plan |
+| Per-node check | One result-bitmap lookup | One direct bit test per visited DNF terminal |
+| Broad-filter latency | High when materialization is charged | Stable; no result-set construction |
+| Best fit | Very high-cardinality labels, selective filters, or reusable cached predicates | Bounded label vocabulary and unique/dynamic predicates |
+
+For the PMax workload with 596 labels, the recommended implementation is
+`topk-multihop-encoded-bitslice-dnf`. It preserves the proven multihop recall behavior and delivers
+the best overall query-time latency. Bitslice memory grows linearly with
+`label_count * vector_count`, so high-cardinality datasets should retain Bitmap+AST or use an
+adaptive representation rather than allocating a dense slice for every label.
+
+## Main implementation locations
+
+- `diskann/src/graph/search/multihop_filter_search.rs`: two-hop filtered graph traversal.
+- `diskann-label-index/src/lib.rs`: persisted Bitmap/Bitslice formats and AST/DNF query compilation.
+- `diskann-label-filter/src/live_filter.rs`: specialized Bitslice and flat-DNF evaluation.
+- `diskann-benchmark/src/index/benchmarks.rs`: query-inclusive encoded-label benchmark wiring.
+- `diskann-benchmark/src/index/search/plugins.rs`: `topk-multihop-encoded-bitslice-dnf` plugin.