Struct MetadataIndex 

pub struct MetadataIndex<K> { /* private fields */ }

An opt-in, per-field inverted index over record metadata.

K is the caller’s row key — a storage index, an iqdb_types::VectorId, or any Clone + Eq + Hash handle. Build one with build; it is immutable thereafter (rebuild to reflect new data). See candidates for the resolution rules and the superset contract.

Implementations

impl<K> MetadataIndex<K>

where K: Clone + Eq + Hash,

pub fn build<'a, I>(fields: &[&str], records: I) -> Self

where I: IntoIterator<Item = (K, Option<&'a Metadata>)>,

Builds an index over fields from records.

fields is the explicit opt-in list — only these fields are indexed. records yields (key, metadata) pairs; a record with None metadata (or one missing an indexed field) still counts toward the total but contributes no postings. A field named in fields that no record carries simply has an empty posting set.

Examples

use iqdb_filter::MetadataIndex;
use iqdb_types::{Metadata, Value};

let rows = [(0_u64, [("k".to_string(), Value::Int(1))].into_iter().collect::<Metadata>())];
let index = MetadataIndex::build(&["k"], rows.iter().map(|(k, m)| (*k, Some(m))));
assert_eq!(index.len(), 1);
assert!(index.is_indexed("k"));

pub fn len(&self) -> usize

The number of records the index was built from.

pub fn is_empty(&self) -> bool

Whether the index was built from zero records.

pub fn is_indexed(&self, field: &str) -> bool

Whether field is one of the indexed fields.

pub fn indexed_fields(&self) -> impl Iterator<Item = &str>

The set of indexed field names, in unspecified order.

pub fn candidates(&self, evaluator: &FilterEvaluator) -> Option<Vec<K>>

Resolves evaluator’s filter to a candidate key set, or None if the index cannot bound it (scan everything in that case).

When this returns Some(keys), keys is a superset of the records the evaluator accepts — re-run evaluate over them for the exact result. The keys are unique and in unspecified order.

Takes a validated FilterEvaluator, so the recursive walk is bounded by MAX_FILTER_DEPTH.

Examples

use iqdb_filter::{FilterEvaluator, MetadataIndex};
use iqdb_types::{Filter, Metadata, Value};

let rows = [
    (0_usize, [("tier".to_string(), Value::Int(1))].into_iter().collect::<Metadata>()),
    (1, [("tier".to_string(), Value::Int(2))].into_iter().collect::<Metadata>()),
];
let index = MetadataIndex::build(&["tier"], rows.iter().map(|(k, m)| (*k, Some(m))));

// Indexed equality resolves.
let eq = FilterEvaluator::new(Filter::eq("tier", Value::Int(1)))?;
assert_eq!(index.candidates(&eq), Some(vec![0]));

// A range over an indexed field is left to a full scan.
let range = FilterEvaluator::new(Filter::gt("tier", Value::Int(1)))?;
assert_eq!(index.candidates(&range), None);

pub fn estimate_selectivity(&self, evaluator: &FilterEvaluator) -> f64

Estimates the fraction of records evaluator’s filter passes, in [0.0, 1.0], using real posting counts where the index can and the structural estimate_selectivity fallback elsewhere.

This is the data-backed counterpart to the structural estimate: an indexed Eq / In leaf contributes its actual matches / total fraction, so a selector backed by the index makes sharper pre/post decisions. With zero records it falls back entirely to the structural estimate.

Examples

use iqdb_filter::{FilterEvaluator, MetadataIndex};
use iqdb_types::{Filter, Metadata, Value};

// 1 of 4 rows has status == 1: the index knows the true 0.25.
let rows = [
    (0_usize, [("status".to_string(), Value::Int(1))].into_iter().collect::<Metadata>()),
    (1, [("status".to_string(), Value::Int(2))].into_iter().collect::<Metadata>()),
    (2, [("status".to_string(), Value::Int(2))].into_iter().collect::<Metadata>()),
    (3, [("status".to_string(), Value::Int(3))].into_iter().collect::<Metadata>()),
];
let index = MetadataIndex::build(&["status"], rows.iter().map(|(k, m)| (*k, Some(m))));

let eq = FilterEvaluator::new(Filter::eq("status", Value::Int(1)))?;
assert!((index.estimate_selectivity(&eq) - 0.25).abs() < 1e-9);

Trait Implementations

impl<K: Clone> Clone for MetadataIndex<K>

fn clone(&self) -> MetadataIndex<K>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K: Debug> Debug for MetadataIndex<K>

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

Formats the value using the given formatter.