Diagnosing Quantized Vector Indexes

Quantization stores compact codes beside full-precision vectors. During a scan, ParadeDB filters candidates using per-row error bars, then reranks the surviving candidates exactly.

Inspect the Index

Use paradedb.vector_info to inspect configured quantization policy and actual storage per segment:

SELECT segno, vector_field, vector_format, quantized_storage,
       configured_quantized, configured_layers, configured_bytes_per_row, configured_format
FROM paradedb.vector_info('search_idx', 'embedding');

configured_layers lists the bit width of each quantization layer in scoring order. Vector fields with at least 64 dimensions use [1, 1] quantization by default; lower-dimensional fields remain unquantized. Set "quantization": false in a field’s vector_fields configuration to disable quantization explicitly. A field with no configured quantization reports configured_quantized = false and NULL for configured_layers, configured_bytes_per_row, and configured_format.

The configured_* columns describe field policy, not evidence that codes are stored. quantized_storage reports whether that specific segment has quantized slots. Small flat segments report false even when policy enables quantization; a mixed flat/IVF index can therefore contain both values. The other columns describe each segment’s actual vector and cluster layout.

Measure the Estimator

No query sample is needed for the first check:

SELECT *
FROM paradedb.vector_estimator_info('search_idx', 'embedding');

Example output:

 depth | bias  | spread | sample_rows | query_count | query_source
-------+-------+--------+-------------+-------------+--------------
     1 |  0.04 |   1.03 |        1000 |         100 | held_out
     2 | -0.01 |   0.99 |        1000 |         100 | held_out

With no query argument, the function samples stored vectors as pseudo-queries and reports query_source = 'held_out'. For a stronger check, pass 50–256 representative real queries. This is recommended when the query distribution differs from the indexed corpus, such as short queries against long passages or cross-modal queries:

SELECT *
FROM paradedb.vector_estimator_info(
    'search_idx',
    'embedding',
    ARRAY(
        SELECT embedding
        FROM representative_queries
        ORDER BY id
        LIMIT 100
    )
);

Provided queries report query_source = 'provided'. The function accepts at most 256 queries.

Measurement Interpretation
bias 0 means the estimator is centered. A healthy reading has |bias| ≤ 0.3. A larger magnitude indicates systematic mis-scoring for these queries and creates recall risk at the candidate filter.
spread 1.0 means the error model is exact. A value below 1.0 is conservative: it is safe but may do slightly more work. A healthy reading is at most 1.15; above that, the safety margin no longer covers the observed error and recall may drop at high probe fractions.

What the Measurement Covers

vector_estimator_info measures the honesty of the per-row estimator over an un-routed sample. It compares production quantized estimates with exact full-precision scores at every layer depth. It does not run a search: routing, candidate boundaries, reranking, and top-K are not involved. It therefore does not measure search recall; measuring recall requires queries with known ground-truth neighbors.

It reads the current snapshot, excludes deleted rows, selects samples deterministically, and writes nothing. The same index state and query input produce the same result.

The work is approximately 1,000 sampled rows times the query count for every layer depth. Expect seconds on a warm index, and do not call it for individual search requests.

When to Run It

Run the diagnostic:

  • after the initial index build;
  • after a bulk load from a different data source;
  • when vector recall appears incorrect.

Respond to an Unhealthy Reading

Raise paradedb.vector_cluster_max_probe so the scan considers more clusters, or rebuild the index with a quantization schedule that keeps more bits. There is no calibration knob, by design.

This function tells you whether the index is accurate on your data; it never changes how the index behaves.