feat: split VectorIndexResolver into peek/resolve/ensure_loaded

Split the resolver trait to match DataFusion's sync/async pipeline:
- peek(key) — sync, cheap: returns VectorIndexMeta (metric, schema)
  for the optimizer rule to validate ANN rewrites without loading
- resolve(key) — sync: returns loaded RegisteredTable from cache
- ensure_loaded(key) — async: loads index on cache miss, called by
  the physical planner before building execution plans

The optimizer rule uses peek (sync, no I/O).
The planner calls ensure_loaded (async) then resolve.
The executor uses resolve (sync, cache only).

This enables catalog-backed resolution where ensure_loaded downloads
and loads index files on demand, while the optimizer stays sync and fast.

Author: anoop-narang

src/lib.rs

@@ -75,7 +75,7 @@ pub use lookup::{HashKeyProvider, PointLookupProvider};
 pub use node::{DistanceType, USearchNode};
 pub use planner::{USearchExec, USearchExecPlanner, USearchQueryPlanner};
 pub use registry::{
-    RegisteredTable, USearchIndexConfig, USearchRegistry, USearchTableConfig,
+    RegisteredTable, USearchIndexConfig, USearchRegistry, USearchTableConfig, VectorIndexMeta,
     VectorIndexResolver,
 };
 pub use rule::USearchRule;

src/planner.rs

@@ -140,12 +140,14 @@ impl ExtensionPlanner for USearchExecPlanner {
             None => return Ok(None),
         };
 
-        // Cheap validation: RwLock read + HashMap lookup — no I/O.
+        // Async: ensure the index is loaded (downloads on cache miss).
+        self.registry.ensure_loaded(&node.table_name).await?;
+
         let registered = match self.registry.resolve(&node.table_name) {
             Some(r) => r,
             None => {
                 return Err(DataFusionError::Execution(format!(
-                    "USearchExecPlanner: table '{}' not in registry",
+                    "USearchExecPlanner: table '{}' not available after ensure_loaded",
                     node.table_name
                 )));
             }

src/registry.rs

@@ -216,19 +216,44 @@ pub struct RegisteredTable {
 
 // ── VectorIndexResolver ───────────────────────────────────────────────────────
 
+/// Lightweight metadata returned by the sync `peek` check.
+/// Contains enough info for the optimizer to validate the ANN rewrite
+/// and build the logical plan node, without needing the loaded index objects.
+#[derive(Debug, Clone)]
+pub struct VectorIndexMeta {
+    pub metric: MetricKind,
+    pub scalar_kind: ScalarKind,
+    pub schema: SchemaRef,
+    pub key_col: String,
+    pub config: USearchTableConfig,
+}
+
 /// Trait for resolving vector index entries by name.
 ///
-/// The optimizer rule, physical planner, and executor all call `resolve()` to
-/// obtain the loaded index, providers, and metadata needed for ANN execution.
+/// Split into two operations to accommodate DataFusion's mixed sync/async pipeline:
+/// - `peek()` — sync, cheap: used by the optimizer rule to decide if ANN rewrite applies
+/// - `resolve()` — sync: returns fully loaded entry from cache (for executor hot path)
+/// - `ensure_loaded()` — async: loads the index on cache miss (for planner/executor)
 ///
-/// The built-in [`USearchRegistry`] implements this as a direct hashmap lookup.
-/// Production systems can implement a catalog-backed resolver that treats the
-/// in-memory index as a cache and reloads from storage on miss or staleness.
+/// The built-in [`USearchRegistry`] implements all three as direct hashmap lookups
+/// (always cached). Production systems can implement catalog-backed loading in
+/// `ensure_loaded`.
+#[async_trait::async_trait]
 pub trait VectorIndexResolver: Send + Sync + std::fmt::Debug {
-    /// Look up a registered table by its key (e.g., `"catalog::schema::table::col"`).
-    ///
-    /// Returns `None` if the key is not found or the index is not available.
+    /// Sync, cheap: check if a vector index exists and return its metadata.
+    /// Used by the optimizer rule to decide if the ANN rewrite should apply.
+    /// Must NOT do I/O — only check local cache or lightweight state.
+    fn peek(&self, name: &str) -> Option<VectorIndexMeta>;
+
+    /// Sync: return a fully loaded entry from cache.
+    /// Returns `None` on cache miss — the caller should call `ensure_loaded` first.
     fn resolve(&self, name: &str) -> Option<Arc<RegisteredTable>>;
+
+    /// Async: ensure the index is loaded and available in cache.
+    /// On cache miss or stale entry, downloads files and loads the index.
+    /// On cache hit with current generation, returns immediately.
+    /// Called from the async physical planner before building the execution plan.
+    async fn ensure_loaded(&self, name: &str) -> datafusion::common::Result<()>;
 }
 
 // ── USearchRegistry ───────────────────────────────────────────────────────────
@@ -397,10 +422,26 @@ impl USearchRegistry {
     }
 }
 
+#[async_trait::async_trait]
 impl VectorIndexResolver for USearchRegistry {
+    fn peek(&self, name: &str) -> Option<VectorIndexMeta> {
+        self.get(name).map(|r| VectorIndexMeta {
+            metric: r.metric,
+            scalar_kind: r.scalar_kind,
+            schema: r.schema.clone(),
+            key_col: r.key_col.clone(),
+            config: r.config.clone(),
+        })
+    }
+
     fn resolve(&self, name: &str) -> Option<Arc<RegisteredTable>> {
         self.get(name)
     }
+
+    async fn ensure_loaded(&self, _name: &str) -> datafusion::common::Result<()> {
+        // USearchRegistry is always fully cached — nothing to load.
+        Ok(())
+    }
 }
 
 impl Default for USearchRegistry {

src/rule.rs

@@ -104,8 +104,8 @@ impl USearchRule {
         // Registry key: "catalog::schema::table::col" (or fewer parts for bare refs).
         let reg_key = format!("{}::{}", table_ref_full, vec_col);
 
-        // Table must be registered for vector search.
-        let registered = self.registry.resolve(&reg_key)?;
+        // Sync check: does a vector index exist for this key?
+        let meta = self.registry.peek(&reg_key)?;
 
         let dist_type = match udf_name.as_str() {
             "l2_distance" => DistanceType::L2,
@@ -116,14 +116,14 @@ impl USearchRule {
 
         // Guard: the SQL distance UDF must match the metric the index was built
         // with. Mismatch → return None so DataFusion falls back to exact scan.
-        if !dist_type_matches_metric(&dist_type, registered.metric) {
+        if !dist_type_matches_metric(&dist_type, meta.metric) {
             return None;
         }
 
         // Build USearchNode schema: base fields qualified with the original table
         // reference (Full/Partial/Bare) so qualifiers match the original plan's schema.
         let table_ref = scan_table_ref.clone();
-        let qualified_fields: Vec<(Option<TableReference>, Arc<arrow_schema::Field>)> = registered
+        let qualified_fields: Vec<(Option<TableReference>, Arc<arrow_schema::Field>)> = meta
             .schema
             .fields()
             .iter()