Enum HnswIterativeScan 

pub enum HnswIterativeScan {
    Off,
    RelaxedOrder,
    StrictOrder,
}

How pgvector’s HNSW index behaves when a filter eliminates the candidates it handed up (#1116).

With pgvector’s own default — off — an HNSW scan produces one bounded candidate list and the filter is applied to it. Once the filter is selective the list is exhausted before k survivors exist, and the query succeeds with fewer rows: measured at 100 000 documents, k = 10 and a 1%-selective filter, three rows and a recall of 0.20, with nothing to distinguish that from “only three matched”. That is why FraiseQL names a value here instead of inheriting the server’s.

⚠ An invalid value is not an error. pgvector’s GUC is defined when its library loads, after the startup packet has been accepted, so a bad value produces WARNING: invalid value for parameter "hnsw.iterative_scan" and silently falls back to off — the failure this setting exists to prevent. Being an enum is what keeps an unrepresentable value from reaching the wire.

Variants

Off

pgvector’s own default: one bounded candidate list, no continuation. Filtered searches may silently return fewer than k rows.

RelaxedOrder

Continue scanning until k rows survive the filter, without buffering for exact ordering. Results may be slightly out of distance order.

StrictOrder

Continue scanning until k rows survive, preserving exact distance order.

The default, and the reason is the contract rather than the benchmark: nearest is documented to return rows most-similar-first, and a plan whose ordering comes from the index scan can only honour that if the scan is ordered. relaxed_order would trade #1116’s silent under-return for a quieter version of the same thing — a result that looks right and is subtly not.

The benchmark in benches/vector_filtered_ann.sql found the two indistinguishable in both recall and latency, so the guarantee is the only thing separating them there. An operator whose corpus disagrees can say so.

Implementations

impl HnswIterativeScan

pub const fn as_guc_value(self) -> &'static str

The value as pgvector spells it.

Trait Implementations

impl Clone for HnswIterativeScan

fn clone(&self) -> HnswIterativeScan

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for HnswIterativeScan

impl Debug for HnswIterativeScan

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for HnswIterativeScan

fn default() -> HnswIterativeScan

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for HnswIterativeScan

fn deserialize<__D>( __deserializer: __D, ) -> Result<HnswIterativeScan, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for HnswIterativeScan

impl PartialEq for HnswIterativeScan

fn eq(&self, other: &HnswIterativeScan) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for HnswIterativeScan

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for HnswIterativeScan