perf(index): share resident buffers within query lifetimes

rust/lance-index/src/vector/bq/layered.rs

@@ -293,7 +293,8 @@ pub enum EntryColumns {
     All,
     /// Only the columns the index's resident store does not keep: the codes
     /// and the estimator bounds (see [`plane_entry_columns`]). Every read
-    /// attaches copies of the store's rows of the others, so the scored
+    /// attaches the store's rows of the others, views of the store for a
+    /// whole plane or partition and copies for gathered rows, so the scored
     /// batch is the one an `All` entry holds. Only an index whose small
     /// columns are resident keeps such entries.
     Codes,

rust/lance-index/src/vector/bq/layered_stats.rs

@@ -318,18 +318,42 @@ layered_lazy_counters! {
         /// built from codes stored packed and blocked, as the index builder
         /// writes them and cache entries keep them, rewrites nothing.
         storage_construct_repacks,
-        /// Batches assembled with copies of an index's resident rows: every
-        /// read of a plane or partition from the file that takes its small
-        /// columns from the resident store, and every read of a code-only
-        /// cache entry (`LANCE_RQ_ENTRY_COLUMNS=codes`), hits included.
+        /// Batches assembled with an index's resident rows, copied or shared:
+        /// every read of a plane or partition from the file that takes its
+        /// small columns from the resident store, and every read of a
+        /// code-only cache entry (`LANCE_RQ_ENTRY_COLUMNS=codes`), hits
+        /// included.
         resident_attach_calls,
         /// Rows those batches hold.
         resident_attach_rows,
-        /// Bytes of the resident rows copied into them: what a full entry
-        /// would have kept in the cache.
+        /// Bytes of the resident rows those batches hold, copied or shared,
+        /// each row at its columns' fixed widths: what a full entry would
+        /// have kept in the cache.
         resident_attach_bytes,
-        /// Time spent assembling them, copies included.
+        /// Time spent assembling them once their rows are resolved: the
+        /// copies (or views) of the resident rows, the other columns' clones
+        /// and the batch. Summed over every attach, including those of
+        /// partitions prepared at once, so it is CPU time rather than time
+        /// on a query's critical path.
         resident_attach_ns,
+        /// Of those batches, whole partitions and planes in which every
+        /// resident column shares the store's buffers.
+        resident_attach_shares,
+        /// Whole partitions and planes that copied a resident column: reads
+        /// that become cache entries (full entries, or partitions of a native
+        /// index with a graph), partitions streamed out of the index, and
+        /// columns a view cannot cover.
+        resident_attach_whole_copies,
+        /// Sparse gathers, whose rows are always copied.
+        resident_attach_gathers,
+        /// Bytes the whole copies and the gathers copied.
+        resident_attach_copied_bytes,
+        /// Storages of native partitions built from their code-only entry
+        /// (`LANCE_RQ_ENTRY_COLUMNS=codes`), once per read of the partition.
+        code_only_partition_builds,
+        /// Time those builds took: the attach of the resident rows and the
+        /// storage's construction, without a fallback load of the store.
+        code_only_partition_build_ns,
         /// Bytes of packed row columns that reads of plane-row IVF_RQ files
         /// unpacked into the column layout's fields.
         plane_rows_unpack_bytes,

rust/lance-index/src/vector/bq/partition_codes.rs

@@ -5,9 +5,10 @@
 //!
 //! A native IVF_RQ index with a flat sub-index whose small columns are
 //! resident caches a partition as its code columns alone
-//! (`EntryColumns::Codes`): every read attaches copies of the resident rows
-//! and builds the storage, so the cache holds no second copy of the row ids
-//! and factors the store already keeps. The codes are kept packed and
+//! (`EntryColumns::Codes`): every read attaches views of the resident rows
+//! and builds the storage for that read alone, so the cache holds no second
+//! copy of the row ids and
+//! factors the store already keeps. The codes are kept packed and
 //! blocked (see `normalize_entry_codes`), and persisted as a raw fixed-width
 //! body (see [`super::raw_body`]):
 //!