core/vector_store/bench library

Reusable recall / latency benchmark harness for vector indexes.

The core primitive is benchIndex, which times a set of query batches against a candidate index, computes recall@k against a ground-truth SearchResult, and returns a BenchResult. A tiny CSV writer (writeBenchCsv) and a "sweep" helper (benchIndexSweep) are layered on top so callers can build recall-vs-latency tables with a few lines of glue.

This file intentionally has no CLI surface — see bin/bench_faiss.dart for a runnable frontend.

Classes

BenchOptions

Knobs for benchIndex. Sensible defaults are provided for one-off use; the sweep helpers reuse this class to keep argument lists sane.

BenchResult

Result of a single benchIndex run.

Functions

benchIndex({required Index index, required List<Float32List> queries, required int k, required SearchResult truth, String label = 'index', BenchOptions options = const BenchOptions()}) → BenchResult

Time index on queries and compute recall@k against truth.

benchIndexSweep<T>({required Index index, required List<Float32List> queries, required int k, required SearchResult truth, required List<T> values, required String configure(T value), BenchOptions options = const BenchOptions()}) → List<BenchResult>

Sweep an Index across a list of configurations. configure is called once per point with the raw value from values and should mutate the index in place (e.g. bump nprobe or efSearch); its return value is used as the point's label.

formatBenchTable(Iterable<BenchResult> rows) → String

Pretty-print a bench table to stdout-style text (fixed-width columns). Useful for CLI or test output.

paretoFrontier(Iterable<BenchResult> rows) → List<BenchResult>

Return the recall-vs-latency Pareto frontier of rows: the subset where no other row has both higher (or equal) recall AND lower (or equal) mean_us. The result is sorted by recall ascending; when two rows share the same recall, the one with the lower mean_us wins.

toBenchCsv(Iterable<BenchResult> rows) → String

Serialise a list of BenchResults to CSV. Column order: label,ntotal,nq,k,recall,mean_us,p50_us,p95_us,p99_us. The label column is CSV-escaped (commas / quotes / newlines) per RFC 4180.

toBenchMarkdown(Iterable<BenchResult> rows) → String

Render a list of BenchResults as a GitHub-flavoured Markdown table. Numeric columns are right-aligned via the --: header syntax; the label column is left-aligned. Pipe characters and backslashes in labels are escaped so pathological names cannot break the table.