Skip to main content

surrealdb_idx/
lib.rs

1//! The SurrealDB index engines.
2//!
3//! Each engine here owns one index structure: the full-text index and its
4//! analyzer, the HNSW and DiskANN vector graphs, the count index, the
5//! unique/non-unique entry index, and the document-id mapping they share. An
6//! engine is reached downward — through a transaction and an [`env::IndexEnv`]
7//! handle — and answers from the keyspace alone.
8//!
9//! The pure computations those engines and the executor share — index key
10//! encoding and decoding, full-text term resolution and scoring, vector
11//! scoring — are [`kernels`]: functions over values and bytes that touch no
12//! storage, named in a registry. An executor that does its own reads hands
13//! what it read to them.
14//!
15//! Choosing an index for a query, and iterating one on behalf of a statement,
16//! is not here: that is the planner's job, and it lives above this crate with
17//! the executor that drives it.
18//!
19//! **This crate is an internal implementation detail of SurrealDB.** Its API is
20//! unstable and changes without notice.
21
22// This triggers because we have regex's in our Value type which have a unsafecell inside.
23#![allow(clippy::mutable_key_type)]
24// TODO: Remove once this crate no longer needs it; see `absolute_paths` in the workspace lints.
25#![allow(clippy::absolute_paths)]
26// Without `vector-index` the graph engine is left out, and without `fulltext`
27// no analyzer exists; the helpers and caches only they reach go unused.
28#![cfg_attr(not(all(feature = "vector-index", feature = "fulltext")), allow(dead_code))]
29#![recursion_limit = "256"]
30
31#[macro_use]
32mod mac;
33
34// The engines spell their neighbours the way core did — `catalog::X`,
35// `expr::X`, `val::X`, `key::X` — so the same aliases keep those paths valid
36// here.
37pub use surrealdb_catalog as catalog;
38pub use surrealdb_expr::{expr, val};
39
40/// The keyspace, and the storage layer's key contract, under one name.
41///
42/// The key types are generated from the layout declared in
43/// [`surrealdb_datastore::key::schema`]; the traits that generated code is
44/// written against are the storage layer's and live in [`surrealdb_kvs::key`].
45/// Naming both from here is how core spells them too, so a key type and the
46/// traits it implements are reached the same way from either side of the crate
47/// boundary.
48pub(crate) mod key {
49	pub(crate) use surrealdb_datastore::key::schema;
50	pub(crate) use surrealdb_kvs::key::{
51		KVKey, KVKeyDecode, KVRange, KVSubspace, RawRange, Resumable, TypedRange,
52	};
53	pub(crate) use surrealdb_kvs::value::KVValue;
54	pub(crate) use surrealdb_kvs::{Key, KeyRange};
55}
56
57pub mod adjacency;
58pub mod config;
59pub mod count;
60pub mod docids;
61pub mod entry;
62pub mod env;
63pub(crate) mod error;
64pub mod file;
65pub mod ft;
66pub mod index;
67pub mod inline_cache;
68pub mod kernels;
69pub(crate) mod parallel;
70pub mod places;
71pub mod spatial;
72#[cfg(test)]
73pub(crate) mod test_env;
74pub mod trees;
75
76use std::borrow::Cow;
77use std::fmt::{Debug, Display};
78use std::sync::Arc;
79
80use anyhow::Result;
81use roaring::RoaringTreemap;
82use surrealdb_datastore::pending_guard::{GuardedIndex, PendingGuardFamily};
83use surrealdb_datastore::values::fulltext::{
84	ChangeBatch, DocLengthAndCount, PostingBlock, TermDocsResidual,
85};
86use surrealdb_datastore::values::index_build::{
87	Appending, AppendingId, BatchId, BuildGeneration, BuildTicket, BuildTicketMutationSeq,
88	IndexBuildReservation, PrimaryAppendingTicket,
89};
90use surrealdb_datastore::{Transaction, storage_error};
91use surrealdb_kvs::Error as KvsError;
92use uuid::Uuid;
93
94pub use self::error::{Error, index_exists_record};
95
96/// Fails when this build left out the kernel an index of kind `index` needs.
97///
98/// Checked before an index is built, so a definition this build cannot serve
99/// is refused by the statement that defines it rather than accepted and left
100/// unbuildable.
101pub fn check_index_kernel(index: &catalog::Index) -> Result<()> {
102	match index {
103		#[cfg(not(feature = "vector-index"))]
104		catalog::Index::Hnsw(_) => Err(anyhow::Error::new(Error::FeatureDisabled {
105			feature: "vector-index",
106			what: "HNSW indexes",
107		})),
108		#[cfg(not(feature = "fulltext"))]
109		catalog::Index::FullText(_) => Err(anyhow::Error::new(Error::FeatureDisabled {
110			feature: "fulltext",
111			what: "Full-text indexes",
112		})),
113		_ => Ok(()),
114	}
115}
116use crate::catalog::{DatabaseId, IndexId, NamespaceId};
117use crate::docids::DocId;
118use crate::ft::{DocLength, TermFrequency};
119use crate::key::schema::{
120	BuildAppendGenerationPrefix, BuildAppendIxPrefix, BuildAppendKey, BuildAppendTicketPrefix,
121	BuildBarrierKey, BuildPrimaryGenerationPrefix, BuildPrimaryIxPrefix, BuildPrimaryKey,
122	BuildReservationGenerationPrefix, BuildReservationIxPrefix, BuildReservationKey, BuildStateKey,
123	BuildTicketIxPrefix, BuildTicketKey, DocCountKey, DocLengthKey, DocStatsBatchPrefix,
124	DocStatsKey, DocTermsKey, HnswDocElementsKey, HnswElementDocsKey, HnswElementHashedKey,
125	HnswElementKey, HnswGenerationKey, HnswLayerKey, HnswLayerLayerPrefix, HnswNodeKey,
126	HnswNodeLayerPrefix, HnswPendingLegacyPrefix, HnswRecordPendingKey, HnswRecordPendingPrefix,
127	HnswRecordPendingShardKey, HnswRecordPendingShardPrefix, HnswRecordPendingShardShardPrefix,
128	HnswStateKey, HnswVectorKey, IdxRoot, IndexAppendKey, IndexAppendPrefix, IndexCompactionKey,
129	IndexPrimaryKey, IndexVersionKey, TermBlockKey, TermBlockTermPrefix, TermBlocksKey,
130	TermChangeBatchPrefix, TermChangeBatchTermPrefix, TermChangeSetKey, TermChangesKey,
131	TermDocsKey, TermDocsResidualKey, TermDocsResidualPrefix, TermGenerationKey, TermPostingKey,
132};
133#[cfg(diskann)]
134use crate::key::schema::{
135	DiskannDocElementsKey, DiskannElementCodeKey, DiskannElementDocSetKey, DiskannElementDocsKey,
136	DiskannElementHashedKey, DiskannElementKey, DiskannGenerationKey, DiskannNodeKey,
137	DiskannPendingLegacyKey, DiskannPendingPrefix, DiskannPendingSummaryKey,
138	DiskannRecordPendingKey, DiskannRecordPendingPrefix, DiskannRecordPendingShardKey,
139	DiskannRecordPendingShardShardPrefix, DiskannStateKey,
140};
141use crate::key::{KVKey, KVSubspace, TypedRange};
142use crate::trees::hnsw::{ElementId, VectorPendingUpdate};
143use crate::trees::vector::SerializedVector;
144use crate::val::{IndexFormat, RecordIdKey, RecordIdentity, TableName};
145
146/// Reads a compaction generation key.
147///
148/// Missing generation keys are equivalent to generation `0`
149pub(crate) async fn read_compaction_generation<K>(tx: &Transaction, key: &K) -> Result<Option<u64>>
150where
151	K: KVKey<Value = u64> + Debug,
152{
153	tx.get_key(key, None).await
154}
155
156/// The generation a compaction advancing from `current` commits at.
157pub(crate) fn next_compaction_generation(current: Option<u64>) -> u64 {
158	current.unwrap_or(0).saturating_add(1)
159}
160
161/// Advances a compaction generation with a conditional write, to
162/// [`next_compaction_generation`] of `current`.
163///
164/// Returns `false` when the stored generation differs from `current`, so the
165/// caller can skip a plan built from an older snapshot.
166pub(crate) async fn bump_compaction_generation<K>(
167	tx: &Transaction,
168	key: &K,
169	current: Option<u64>,
170) -> Result<bool>
171where
172	K: KVKey<Value = u64> + Debug,
173{
174	let next = next_compaction_generation(current);
175	match tx.put_compare_key(key, &next, current.as_ref()).await {
176		Ok(()) => Ok(true),
177		Err(e) if is_transaction_condition_not_met(&e) => Ok(false),
178		Err(e) => Err(e),
179	}
180}
181
182/// Identifies the datastore error used for failed conditional writes/deletes.
183pub(crate) fn is_transaction_condition_not_met(e: &anyhow::Error) -> bool {
184	matches!(storage_error(e), Some(KvsError::TransactionConditionNotMet))
185}
186
187/// What applying one compaction plan did.
188///
189/// A plan records the compaction generation it read, and its apply advances it
190/// through [`bump_compaction_generation`], so of two plans read from one state
191/// at most one applies. The one that does not is reported apart from a plan
192/// that had nothing to apply: a caller that stops once there is nothing left to
193/// fold must not stop on a plan that was merely overtaken.
194#[derive(Clone, Copy, Debug, Eq, PartialEq)]
195pub enum CompactionApply {
196	/// The plan's writes were applied.
197	Applied,
198	/// The plan captured nothing to apply, so there is nothing to commit.
199	Empty,
200	/// The plan was stale when applied, so what it wrote must not commit:
201	/// another compactor advanced the compaction generation first, or an entry
202	/// the plan captured changed before the write.
203	LostRace,
204}
205
206impl CompactionApply {
207	/// Whether the plan's writes were applied.
208	pub fn applied(self) -> bool {
209		matches!(self, Self::Applied)
210	}
211}
212
213/// Clears everything an index has stored, and advances its compaction
214/// generation so that starting from empty does not unfence a compactor.
215///
216/// The generation key lives inside the subspace this clears. Deleting it would
217/// return the index to the state a never-compacted index is in, and a
218/// compaction plan prepared before the wipe expects exactly that state — so
219/// [`bump_compaction_generation`]'s conditional write would match again, and the
220/// guard whose whole purpose is to reject a stale plan would pass it. The
221/// per-key guards behind it are no help: whoever wipes an index goes on to
222/// re-index the same records, and a pending is derived wholly from the record
223/// and the graph state, carrying no writer identity, so the recreated entries
224/// can be byte-identical to the captured ones. Such a plan consumes the fresh
225/// pendings and folds them into a graph loaded from the pre-wipe snapshot,
226/// publishing an index that is `Online` and empty.
227///
228/// Writing the generation back one above what it was leaves every pre-wipe
229/// generation unmatchable, which is what keeps that guard able to do its job.
230/// Only the generations the index type actually keeps are touched.
231///
232/// The writes land after the delete within one transaction. That is well
233/// defined on every backend: `delr` enumerates the range and deletes key by
234/// key, so this is a later point write to the same key rather than a write
235/// racing a range tombstone.
236pub async fn wipe_index_data(
237	tx: &Transaction,
238	ikb: &IndexKeyBase,
239	index: &catalog::Index,
240) -> Result<()> {
241	/// Reads a generation and returns the value that must replace it.
242	async fn next<K>(tx: &Transaction, key: &K) -> Result<u64>
243	where
244		K: KVKey<Value = u64> + Debug,
245	{
246		Ok(read_compaction_generation(tx, key).await?.unwrap_or(0).saturating_add(1))
247	}
248
249	// Read the generations before the wipe removes them.
250	let mut hnsw = None;
251	let mut term = None;
252	let mut docs = None;
253	let mut count = None;
254	#[cfg(diskann)]
255	let mut diskann = None;
256	match index {
257		catalog::Index::Hnsw(_) => hnsw = Some(next(tx, &ikb.new_hg_key()).await?),
258		catalog::Index::FullText(_) => {
259			term = Some(next(tx, &ikb.new_tv_key()).await?);
260			docs = Some(next(tx, &ikb.new_dv_key()).await?);
261		}
262		catalog::Index::Count(_) => count = Some(next(tx, &ikb.new_iv_key()).await?),
263		#[cfg(diskann)]
264		catalog::Index::DiskAnn(_) => diskann = Some(next(tx, &ikb.new_dg_key()).await?),
265		#[cfg(not(diskann))]
266		catalog::Index::DiskAnn(_) => {}
267		// A b-tree or spatial index compacts nothing, so it keeps no generation.
268		catalog::Index::Idx | catalog::Index::Uniq | catalog::Index::Spatial => {}
269	}
270
271	tx.del_prefix_key(&ikb.new_idx_root()).await?;
272	// The wipe removes the pending-state guards and writer leases of an HNSW or
273	// DiskANN index too, so what this datastore knows of them is forgotten as the
274	// wipe commits.
275	match index {
276		catalog::Index::Hnsw(_) => {
277			tx.buffer_pending_guard_wipe(&ikb.guarded(PendingGuardFamily::Hnsw));
278		}
279		#[cfg(diskann)]
280		catalog::Index::DiskAnn(_) => {
281			tx.buffer_pending_guard_wipe(&ikb.guarded(PendingGuardFamily::DiskAnn));
282		}
283		_ => {}
284	}
285
286	if let Some(generation) = hnsw {
287		tx.set_key(&ikb.new_hg_key(), &generation).await?;
288	}
289	if let Some(generation) = term {
290		tx.set_key(&ikb.new_tv_key(), &generation).await?;
291	}
292	if let Some(generation) = docs {
293		tx.set_key(&ikb.new_dv_key(), &generation).await?;
294	}
295	if let Some(generation) = count {
296		tx.set_key(&ikb.new_iv_key(), &generation).await?;
297	}
298	#[cfg(diskann)]
299	if let Some(generation) = diskann {
300		tx.set_key(&ikb.new_dg_key(), &generation).await?;
301	}
302	Ok(())
303}
304
305/// Deletes, in `tx`, at most `limit` of the keys the index `ikb` names holds, other than the
306/// compaction generations [`wipe_index_data`] reads and writes back, and answers how many it
307/// deleted.
308///
309/// A wipe too large for one transaction runs this, a transaction at a time, until it answers
310/// zero, and then [`wipe_index_data`], which then has only the generations and what was written
311/// meanwhile left to delete. A deleted key stays deleted, so a caller that stops between pages
312/// resumes where the index's keys begin. A DiskANN index is not wiped this way: its wipe also
313/// forgets the pending-state guards its datastore knows of, which only [`wipe_index_data`] does.
314pub async fn wipe_index_page(tx: &Transaction, ikb: &IndexKeyBase, limit: u32) -> Result<usize> {
315	#[cfg_attr(not(diskann), allow(unused_mut))]
316	#[cfg_attr(not(diskann), allow(unused_mut))]
317	let mut kept = Vec::from([
318		ikb.new_hg_key().encode_key()?,
319		ikb.new_tv_key().encode_key()?,
320		ikb.new_dv_key().encode_key()?,
321		ikb.new_iv_key().encode_key()?,
322	]);
323	#[cfg(diskann)]
324	kept.push(ikb.new_dg_key().encode_key()?);
325	let keys = tx.keys_raw(ikb.new_idx_root().raw_range()?, limit, 0, None).await?;
326	let mut deleted = 0;
327	for key in keys.into_iter().filter(|key| !kept.iter().any(|k| k.as_slice() == key.as_slice())) {
328		tx.del(surrealdb_kvs::Key::from(key)).await?;
329		deleted += 1;
330	}
331	Ok(deleted)
332}
333
334/// A primary-appending marker's key as a previous release spelled it: the
335/// generation's prefix, then the record id under the index format.
336///
337/// No key this release declares has that layout, so the bytes are kept as
338/// built rather than encoded from fields.
339#[derive(Clone, Debug, PartialEq, Eq)]
340pub struct PreviousBuildPrimaryKey(Vec<u8>);
341
342impl PreviousBuildPrimaryKey {
343	/// The key's bytes.
344	pub fn as_bytes(&self) -> &[u8] {
345		&self.0
346	}
347}
348
349impl KVKey for PreviousBuildPrimaryKey {
350	type Value = PrimaryAppendingTicket;
351
352	fn encode_buffer(&self, buffer: &mut Vec<u8>) -> Result<()> {
353		buffer.extend_from_slice(&self.0);
354		Ok(())
355	}
356
357	fn value_context(&self) {}
358}
359
360/// A borrowed key reads the same marker, so a batch of keys can be read
361/// without being copied first.
362impl KVKey for &PreviousBuildPrimaryKey {
363	type Value = PrimaryAppendingTicket;
364
365	fn encode_buffer(&self, buffer: &mut Vec<u8>) -> Result<()> {
366		buffer.extend_from_slice(&self.0);
367		Ok(())
368	}
369
370	fn value_context(&self) {}
371}
372
373/// A previous release's primary-appending keys for one build generation,
374/// with the generation's prefix encoded once for however many records.
375pub struct PreviousBpSpelling(Vec<u8>);
376
377impl PreviousBpSpelling {
378	/// The key that release wrote `id`'s marker at, given `spelled`, the id's
379	/// bytes under this release's spelling, when the two keys differ.
380	///
381	/// That release spelled the id under the index format, which drops a nested
382	/// number's variant, so only an id holding a number has a key of its own
383	/// there. The key can be another record's under either spelling — `[1, NONE]`'s
384	/// is `[1]`'s under this release, and `[1]` and `[1dec]` share one — so a
385	/// marker found at it is `id`'s only when its queued mutation names `id`.
386	pub fn key(&self, id: &RecordIdKey, spelled: &[u8]) -> Result<Option<PreviousBuildPrimaryKey>> {
387		// An id the index format spells as this release does has no key of its
388		// own there, which `index_format_spells_alike` answers without an encode.
389		if id.index_format_spells_alike() {
390			return Ok(None);
391		}
392		let erased =
393			storekey::encode_vec_format::<IndexFormat, _>(id).map_err(anyhow::Error::from_boxed)?;
394		if erased == spelled {
395			return Ok(None);
396		}
397		let mut key = Vec::with_capacity(self.0.len() + erased.len());
398		key.extend_from_slice(&self.0);
399		key.extend_from_slice(&erased);
400		Ok(Some(PreviousBuildPrimaryKey(key)))
401	}
402}
403
404#[derive(Debug, Clone, Hash, PartialEq, Eq)]
405#[repr(transparent)]
406pub struct IndexKeyBase(Arc<Inner>);
407
408#[derive(Debug, Hash, PartialEq, Eq)]
409struct Inner {
410	ns: NamespaceId,
411	db: DatabaseId,
412	tb: TableName,
413	ix: IndexId,
414}
415
416impl Display for IndexKeyBase {
417	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
418		write!(f, "NS: {} - DB: {} - TB: {} - IX: {}", self.0.ns, self.0.db, self.0.tb, self.0.ix.0)
419	}
420}
421
422impl IndexKeyBase {
423	pub fn new(ns: NamespaceId, db: DatabaseId, tb: TableName, ix: IndexId) -> Self {
424		Self(Arc::new(Inner {
425			ns,
426			db,
427			tb,
428			ix,
429		}))
430	}
431
432	fn new_he_key(&self, element_id: ElementId) -> HnswVectorKey<'_> {
433		HnswVectorKey {
434			ns: self.0.ns,
435			db: self.0.db,
436			tb: Cow::Borrowed(&self.0.tb),
437			ix: self.0.ix,
438			element_id,
439		}
440	}
441
442	/// Range covering append-keyed HNSW pending updates.
443	pub fn new_hp_range(&self) -> Result<TypedRange<VectorPendingUpdate>> {
444		HnswPendingLegacyPrefix {
445			ns: self.0.ns,
446			db: self.0.db,
447			tb: Cow::Borrowed(&self.0.tb),
448			ix: self.0.ix,
449		}
450		.range()
451	}
452
453	/// Subspace covering everything this index has stored.
454	fn new_idx_root(&self) -> IdxRoot<'_> {
455		IdxRoot {
456			ns: self.0.ns,
457			db: self.0.db,
458			tb: Cow::Borrowed(&self.0.tb),
459			ix: self.0.ix,
460		}
461	}
462
463	/// Key storing the HNSW pending compaction generation.
464	fn new_hg_key(&self) -> HnswGenerationKey<'_> {
465		HnswGenerationKey {
466			ns: self.0.ns,
467			db: self.0.db,
468			tb: Cow::Borrowed(&self.0.tb),
469			ix: self.0.ix,
470		}
471	}
472
473	/// Key storing the pending HNSW update for one record.
474	fn new_hr_key<'a>(&'a self, id: &'a RecordIdKey) -> HnswRecordPendingKey<'a> {
475		HnswRecordPendingKey {
476			ns: self.0.ns,
477			db: self.0.db,
478			tb: Cow::Borrowed(&self.0.tb),
479			ix: self.0.ix,
480			id: Cow::Borrowed(id),
481		}
482	}
483
484	/// Range covering record-keyed HNSW pending updates.
485	pub fn new_hr_range(&self) -> Result<TypedRange<crate::trees::hnsw::HnswRecordPendingUpdate>> {
486		HnswRecordPendingPrefix {
487			ns: self.0.ns,
488			db: self.0.db,
489			tb: Cow::Borrowed(&self.0.tb),
490			ix: self.0.ix,
491		}
492		.range()
493	}
494
495	/// Key storing one shard's pending HNSW update (`!hw{shard}{id}`) for one
496	/// record, on an index that guards its pending updates.
497	///
498	/// `shard` is the record's pending-state shard (`pending_guard_shard`), so
499	/// compaction drains, and lookup scans, one shard at a time.
500	fn new_hw_key<'a>(&'a self, shard: u16, id: &'a RecordIdKey) -> HnswRecordPendingShardKey<'a> {
501		HnswRecordPendingShardKey {
502			ns: self.0.ns,
503			db: self.0.db,
504			tb: Cow::Borrowed(&self.0.tb),
505			ix: self.0.ix,
506			shard,
507			id: Cow::Borrowed(id),
508		}
509	}
510
511	/// Range covering one shard's `!hw` pending HNSW updates.
512	pub fn new_hw_shard_range(
513		&self,
514		shard: u16,
515	) -> Result<TypedRange<crate::trees::hnsw::HnswRecordPendingUpdate>> {
516		HnswRecordPendingShardShardPrefix {
517			ns: self.0.ns,
518			db: self.0.db,
519			tb: Cow::Borrowed(&self.0.tb),
520			ix: self.0.ix,
521			shard,
522		}
523		.range()
524	}
525
526	/// Range covering every shard's `!hw` pending HNSW updates.
527	pub fn new_hw_range(&self) -> Result<TypedRange<crate::trees::hnsw::HnswRecordPendingUpdate>> {
528		HnswRecordPendingShardPrefix {
529			ns: self.0.ns,
530			db: self.0.db,
531			tb: Cow::Borrowed(&self.0.tb),
532			ix: self.0.ix,
533		}
534		.range()
535	}
536
537	fn new_hl_key(&self, layer: u16, chunk: u32) -> HnswLayerKey<'_> {
538		HnswLayerKey {
539			ns: self.0.ns,
540			db: self.0.db,
541			tb: Cow::Borrowed(&self.0.tb),
542			ix: self.0.ix,
543			layer,
544			chunk,
545		}
546	}
547
548	/// Returns a key range covering all legacy `HnswLayerKey` chunk entries for the given HNSW
549	/// layer.
550	fn new_hl_layer_range(&self, layer: u16) -> Result<TypedRange<Vec<u8>>> {
551		HnswLayerLayerPrefix {
552			ns: self.0.ns,
553			db: self.0.db,
554			tb: Cow::Borrowed(&self.0.tb),
555			ix: self.0.ix,
556			layer,
557		}
558		.range()
559	}
560
561	/// Creates a per-node `Hn` key for storing a single node's edge list in an HNSW layer.
562	fn new_hn_key(&self, layer: u16, node: ElementId) -> HnswNodeKey<'_> {
563		HnswNodeKey {
564			ns: self.0.ns,
565			db: self.0.db,
566			tb: Cow::Borrowed(&self.0.tb),
567			ix: self.0.ix,
568			layer,
569			node,
570		}
571	}
572
573	/// Returns a key range covering all per-node `Hn` entries for the given HNSW layer.
574	fn new_hn_layer_range(&self, layer: u16) -> Result<TypedRange<Vec<u8>>> {
575		HnswNodeLayerPrefix {
576			ns: self.0.ns,
577			db: self.0.db,
578			tb: Cow::Borrowed(&self.0.tb),
579			ix: self.0.ix,
580			layer,
581		}
582		.range()
583	}
584
585	fn new_hv_key<'a>(&'a self, vec: &'a SerializedVector) -> HnswElementKey<'a> {
586		HnswElementKey {
587			ns: self.0.ns,
588			db: self.0.db,
589			tb: Cow::Borrowed(&self.0.tb),
590			ix: self.0.ix,
591			vec: Cow::Borrowed(vec),
592		}
593	}
594
595	/// Key mapping a document to the HNSW elements holding its vectors.
596	fn new_hk_key(&self, doc_id: DocId) -> HnswDocElementsKey<'_> {
597		HnswDocElementsKey {
598			ns: self.0.ns,
599			db: self.0.db,
600			tb: Cow::Borrowed(&self.0.tb),
601			ix: self.0.ix,
602			doc_id,
603		}
604	}
605
606	/// Key mapping an HNSW graph element to the doc-IDs whose vector it holds.
607	fn new_hm_key(&self, element_id: ElementId) -> HnswElementDocsKey<'_> {
608		HnswElementDocsKey {
609			ns: self.0.ns,
610			db: self.0.db,
611			tb: Cow::Borrowed(&self.0.tb),
612			ix: self.0.ix,
613			element_id,
614		}
615	}
616
617	/// Range covering every HNSW element's stored vector.
618	#[cfg(test)]
619	fn new_he_range(&self) -> Result<TypedRange<SerializedVector>> {
620		crate::key::schema::HnswVectorPrefix {
621			ns: self.0.ns,
622			db: self.0.db,
623			tb: Cow::Borrowed(&self.0.tb),
624			ix: self.0.ix,
625		}
626		.range()
627	}
628
629	/// Range covering every HNSW element's doc-ID set.
630	#[cfg(test)]
631	fn new_hm_range(&self) -> Result<TypedRange<crate::trees::knn::Ids64>> {
632		crate::key::schema::HnswElementDocsPrefix {
633			ns: self.0.ns,
634			db: self.0.db,
635			tb: Cow::Borrowed(&self.0.tb),
636			ix: self.0.ix,
637		}
638		.range()
639	}
640
641	fn new_hh_key(&self, hash: [u8; 32]) -> HnswElementHashedKey<'_> {
642		HnswElementHashedKey {
643			ns: self.0.ns,
644			db: self.0.db,
645			tb: Cow::Borrowed(&self.0.tb),
646			ix: self.0.ix,
647			hash,
648		}
649	}
650
651	pub fn new_hs_key(&self) -> HnswStateKey<'_> {
652		HnswStateKey {
653			ns: self.0.ns,
654			db: self.0.db,
655			tb: Cow::Borrowed(&self.0.tb),
656			ix: self.0.ix,
657		}
658	}
659
660	/// Key storing a DiskANN graph element vector/status payload.
661	#[cfg(diskann)]
662	fn new_de_key(&self, element_id: ElementId) -> DiskannElementKey<'_> {
663		DiskannElementKey {
664			ns: self.0.ns,
665			db: self.0.db,
666			tb: Cow::Borrowed(&self.0.tb),
667			ix: self.0.ix,
668			element_id,
669		}
670	}
671
672	/// Range covering all DiskANN graph element payloads.
673	#[cfg(diskann)]
674	pub fn new_de_range(&self) -> Result<TypedRange<crate::trees::diskann::DiskAnnElement>> {
675		use crate::key::schema::DiskannElementPrefix;
676
677		DiskannElementPrefix {
678			ns: self.0.ns,
679			db: self.0.db,
680			tb: Cow::Borrowed(&self.0.tb),
681			ix: self.0.ix,
682		}
683		.range()
684	}
685
686	/// Key storing the DiskANN pending compaction generation.
687	#[cfg(diskann)]
688	fn new_dg_key(&self) -> DiskannGenerationKey<'_> {
689		DiskannGenerationKey {
690			ns: self.0.ns,
691			db: self.0.db,
692			tb: Cow::Borrowed(&self.0.tb),
693			ix: self.0.ix,
694		}
695	}
696
697	/// Key mapping a document to the DiskANN elements holding its vectors.
698	#[cfg(diskann)]
699	fn new_dk_key(&self, doc_id: DocId) -> DiskannDocElementsKey<'_> {
700		DiskannDocElementsKey {
701			ns: self.0.ns,
702			db: self.0.db,
703			tb: Cow::Borrowed(&self.0.tb),
704			ix: self.0.ix,
705			doc_id,
706		}
707	}
708
709	/// Key mapping a vector hash to DiskANN hashed-vector document mappings.
710	#[cfg(diskann)]
711	fn new_dh_key(&self, hash: [u8; 32]) -> DiskannElementHashedKey<'_> {
712		DiskannElementHashedKey {
713			ns: self.0.ns,
714			db: self.0.db,
715			tb: Cow::Borrowed(&self.0.tb),
716			ix: self.0.ix,
717			hash,
718		}
719	}
720
721	/// Key storing one DiskANN graph adjacency list.
722	#[cfg(diskann)]
723	fn new_dn_key(&self, element_id: ElementId) -> DiskannNodeKey<'_> {
724		DiskannNodeKey {
725			ns: self.0.ns,
726			db: self.0.db,
727			tb: Cow::Borrowed(&self.0.tb),
728			ix: self.0.ix,
729			element_id,
730		}
731	}
732
733	/// Key storing one shard of the legacy DiskANN pending-state guard (tracks `!dr` records).
734	///
735	/// New code never constructs this — the sharded layout uses [`Self::new_dy_key`], and old nodes
736	/// own `!dp`. Retained for tests that simulate a pre-change node and for the legacy on-disk
737	/// family; hence `dead_code` in a non-test build.
738	#[cfg(diskann)]
739	#[allow(dead_code)]
740	fn new_dp_key(&self, shard: u16) -> DiskannPendingLegacyKey<'_> {
741		DiskannPendingLegacyKey {
742			ns: self.0.ns,
743			db: self.0.db,
744			tb: Cow::Borrowed(&self.0.tb),
745			ix: self.0.ix,
746			shard,
747		}
748	}
749
750	/// Key storing one shard of the sharded DiskANN pending-state guard (tracks `!dw` records).
751	///
752	/// Separate from `!dp` so a pre-change node's compactor — which only knows `!dp`/`!dr` — cannot
753	/// clear the guard for sharded data it can't see during a mixed-version rolling upgrade.
754	#[cfg(diskann)]
755	#[cfg(test)]
756	fn new_dy_key(&self, shard: u16) -> crate::key::schema::DiskannPendingKey<'_> {
757		crate::key::schema::DiskannPendingKey {
758			ns: self.0.ns,
759			db: self.0.db,
760			tb: Cow::Borrowed(&self.0.tb),
761			ix: self.0.ix,
762			shard,
763		}
764	}
765
766	/// Key storing the DiskANN pending-state summary (`!dY`), which reads `Empty` or is absent only
767	/// while every `!dy` guard reads `Empty` or is absent.
768	#[cfg(diskann)]
769	fn new_dy_summary_key(&self) -> DiskannPendingSummaryKey<'_> {
770		DiskannPendingSummaryKey {
771			ns: self.0.ns,
772			db: self.0.db,
773			tb: Cow::Borrowed(&self.0.tb),
774			ix: self.0.ix,
775		}
776	}
777
778	/// Range over every shard's DiskANN pending-state guard (`!dy`).
779	#[cfg(diskann)]
780	fn new_dy_range(&self) -> Result<TypedRange<crate::trees::diskann::DiskAnnPendingState>> {
781		DiskannPendingPrefix {
782			ns: self.0.ns,
783			db: self.0.db,
784			tb: Cow::Borrowed(&self.0.tb),
785			ix: self.0.ix,
786		}
787		.range()
788	}
789
790	/// Range covering every DiskANN element's 8-bit code.
791	#[cfg(all(test, diskann))]
792	fn new_da_range(&self) -> Result<TypedRange<crate::trees::diskann::DiskAnnElementCode>> {
793		crate::key::schema::DiskannElementCodePrefix {
794			ns: self.0.ns,
795			db: self.0.db,
796			tb: Cow::Borrowed(&self.0.tb),
797			ix: self.0.ix,
798		}
799		.range()
800	}
801
802	/// Key storing a DiskANN graph element's 8-bit code.
803	#[cfg(diskann)]
804	fn new_da_key(&self, element_id: ElementId) -> DiskannElementCodeKey<'_> {
805		DiskannElementCodeKey {
806			ns: self.0.ns,
807			db: self.0.db,
808			tb: Cow::Borrowed(&self.0.tb),
809			ix: self.0.ix,
810			element_id,
811		}
812	}
813
814	/// Key mapping a DiskANN graph element to the doc-IDs whose vector it holds.
815	#[cfg(diskann)]
816	fn new_dm_key(&self, element_id: ElementId) -> DiskannElementDocSetKey<'_> {
817		DiskannElementDocSetKey {
818			ns: self.0.ns,
819			db: self.0.db,
820			tb: Cow::Borrowed(&self.0.tb),
821			ix: self.0.ix,
822			element_id,
823		}
824	}
825
826	/// Range covering every DiskANN element's doc-ID set.
827	#[cfg(all(test, diskann))]
828	fn new_dm_range(&self) -> Result<TypedRange<crate::trees::knn::Ids64>> {
829		crate::key::schema::DiskannElementDocSetPrefix {
830			ns: self.0.ns,
831			db: self.0.db,
832			tb: Cow::Borrowed(&self.0.tb),
833			ix: self.0.ix,
834		}
835		.range()
836	}
837
838	/// Key mapping an exact serialized vector to its DiskANN document set.
839	#[cfg(diskann)]
840	fn new_dq_key<'a>(&'a self, vec: &'a SerializedVector) -> DiskannElementDocsKey<'a> {
841		DiskannElementDocsKey {
842			ns: self.0.ns,
843			db: self.0.db,
844			tb: Cow::Borrowed(&self.0.tb),
845			ix: self.0.ix,
846			vec: Cow::Borrowed(vec),
847		}
848	}
849
850	/// Key storing one shard's sharded pending DiskANN update (`!dw{shard}{id}`) for one record.
851	///
852	/// `shard` is the writer's pending-state shard (see `pending_guard_shard`); prefixing it lets
853	/// compaction drain — and lookup scan — one shard at a time. New writes always use this layout.
854	#[cfg(diskann)]
855	fn new_dw_key<'a>(
856		&'a self,
857		shard: u16,
858		id: &'a RecordIdKey,
859	) -> DiskannRecordPendingShardKey<'a> {
860		DiskannRecordPendingShardKey {
861			ns: self.0.ns,
862			db: self.0.db,
863			tb: Cow::Borrowed(&self.0.tb),
864			ix: self.0.ix,
865			shard,
866			id: Cow::Borrowed(id),
867		}
868	}
869
870	/// Range covering the sharded `!dw` pending updates for one shard.
871	#[cfg(diskann)]
872	pub fn new_dw_shard_range(
873		&self,
874		shard: u16,
875	) -> Result<TypedRange<crate::trees::diskann::DiskAnnRecordPendingUpdate>> {
876		DiskannRecordPendingShardShardPrefix {
877			ns: self.0.ns,
878			db: self.0.db,
879			tb: Cow::Borrowed(&self.0.tb),
880			ix: self.0.ix,
881			shard,
882		}
883		.range()
884	}
885
886	/// Key storing the legacy unsharded pending DiskANN update for one record.
887	///
888	/// New writes use the sharded `!dw` layout; this legacy key is read and deleted by the write
889	/// path's dual-read fold, and scanned/range-deleted by lookup and compaction, until the legacy
890	/// range drains empty.
891	#[cfg(diskann)]
892	fn new_dr_key<'a>(&'a self, id: &'a RecordIdKey) -> DiskannRecordPendingKey<'a> {
893		DiskannRecordPendingKey {
894			ns: self.0.ns,
895			db: self.0.db,
896			tb: Cow::Borrowed(&self.0.tb),
897			ix: self.0.ix,
898			id: Cow::Borrowed(id),
899		}
900	}
901
902	/// Range covering legacy unsharded record-keyed DiskANN pending updates.
903	#[cfg(diskann)]
904	fn new_dr_range(
905		&self,
906	) -> Result<TypedRange<crate::trees::diskann::DiskAnnRecordPendingUpdate>> {
907		DiskannRecordPendingPrefix {
908			ns: self.0.ns,
909			db: self.0.db,
910			tb: Cow::Borrowed(&self.0.tb),
911			ix: self.0.ix,
912		}
913		.range()
914	}
915
916	/// Key storing the DiskANN graph state.
917	#[cfg(diskann)]
918	fn new_ds_key(&self) -> DiskannStateKey<'_> {
919		DiskannStateKey {
920			ns: self.0.ns,
921			db: self.0.db,
922			tb: Cow::Borrowed(&self.0.tb),
923			ix: self.0.ix,
924		}
925	}
926
927	pub fn new_ig_key(&self, appending_id: AppendingId, batch_id: BatchId) -> IndexAppendKey<'_> {
928		IndexAppendKey {
929			ns: self.0.ns,
930			db: self.0.db,
931			tb: Cow::Borrowed(&self.0.tb),
932			ix: self.0.ix,
933			appending_id,
934			batch_id,
935		}
936	}
937
938	pub fn new_ig_range(&self) -> Result<TypedRange<Appending>> {
939		IndexAppendPrefix {
940			ns: self.0.ns,
941			db: self.0.db,
942			tb: Cow::Borrowed(&self.0.tb),
943			ix: self.0.ix,
944		}
945		.range()
946	}
947
948	pub fn new_ip_key(&self, id: RecordIdKey) -> IndexPrimaryKey<'_> {
949		IndexPrimaryKey {
950			ns: self.0.ns,
951			db: self.0.db,
952			tb: Cow::Borrowed(&self.0.tb),
953			ix: self.0.ix,
954			id,
955		}
956	}
957
958	/// Range covering every legacy `!ip` primary-appending marker of this
959	/// index, whatever record it names.
960	pub fn new_ip_raw_range(&self) -> Result<crate::key::RawRange> {
961		let mut prefix = self.new_idx_root().encode_bound()?.to_vec();
962		prefix.extend_from_slice(b"!ip");
963		Ok(self.new_idx_root().raw(surrealdb_kvs::Key::from(prefix).prefix_expect()))
964	}
965
966	/// Key storing durable build state for this table index.
967	pub fn new_bs_key(&self) -> BuildStateKey<'_> {
968		BuildStateKey {
969			ns: self.0.ns,
970			db: self.0.db,
971			tb: Cow::Borrowed(&self.0.tb),
972			ix: self.0.ix,
973		}
974	}
975
976	/// Key storing the newest generation whose build waited at the write barrier.
977	pub fn new_bw_key(&self) -> BuildBarrierKey<'_> {
978		BuildBarrierKey {
979			ns: self.0.ns,
980			db: self.0.db,
981			tb: Cow::Borrowed(&self.0.tb),
982			ix: self.0.ix,
983		}
984	}
985
986	/// Key storing the writer-admission ticket counter for a build generation.
987	pub fn new_bt_key(&self, generation: BuildGeneration) -> BuildTicketKey<'_> {
988		BuildTicketKey {
989			ns: self.0.ns,
990			db: self.0.db,
991			tb: Cow::Borrowed(&self.0.tb),
992			ix: self.0.ix,
993			generation,
994		}
995	}
996
997	/// Range covering the ticket counter of one build generation.
998	/// Ticket counters of every generation below `below`.
999	///
1000	/// The bound is on the generation field, so nothing has to reach into a range's
1001	/// bytes to move its end.
1002	pub fn new_bt_range_below(&self, below: BuildGeneration) -> Result<TypedRange<BuildTicket>> {
1003		BuildTicketIxPrefix {
1004			ns: self.0.ns,
1005			db: self.0.db,
1006			tb: Cow::Borrowed(&self.0.tb),
1007			ix: self.0.ix,
1008		}
1009		.range_where(..below)
1010	}
1011
1012	/// Range covering the ticket counters of every generation of this index.
1013	pub fn new_bt_all_generations_range(&self) -> Result<TypedRange<BuildTicket>> {
1014		BuildTicketIxPrefix {
1015			ns: self.0.ns,
1016			db: self.0.db,
1017			tb: Cow::Borrowed(&self.0.tb),
1018			ix: self.0.ix,
1019		}
1020		.range()
1021	}
1022
1023	/// Key storing one durable writer reservation for a build generation.
1024	pub fn new_br_key(
1025		&self,
1026		generation: BuildGeneration,
1027		ticket: BuildTicket,
1028	) -> BuildReservationKey<'_> {
1029		BuildReservationKey {
1030			ns: self.0.ns,
1031			db: self.0.db,
1032			tb: Cow::Borrowed(&self.0.tb),
1033			ix: self.0.ix,
1034			generation,
1035			ticket,
1036		}
1037	}
1038
1039	/// Range covering writer reservations for one build generation.
1040	pub fn new_br_range(
1041		&self,
1042		generation: BuildGeneration,
1043	) -> Result<TypedRange<IndexBuildReservation>> {
1044		BuildReservationGenerationPrefix {
1045			ns: self.0.ns,
1046			db: self.0.db,
1047			tb: Cow::Borrowed(&self.0.tb),
1048			ix: self.0.ix,
1049			generation,
1050		}
1051		.range()
1052	}
1053
1054	/// Range covering writer reservations across all generations of this index.
1055	/// As `new_br_all_generations_range`, but only generations below `below`.
1056	pub fn new_br_range_below(
1057		&self,
1058		below: BuildGeneration,
1059	) -> Result<TypedRange<IndexBuildReservation>> {
1060		BuildReservationIxPrefix {
1061			ns: self.0.ns,
1062			db: self.0.db,
1063			tb: Cow::Borrowed(&self.0.tb),
1064			ix: self.0.ix,
1065		}
1066		.range_where(..below)
1067	}
1068
1069	pub fn new_br_all_generations_range(&self) -> Result<TypedRange<IndexBuildReservation>> {
1070		BuildReservationIxPrefix {
1071			ns: self.0.ns,
1072			db: self.0.db,
1073			tb: Cow::Borrowed(&self.0.tb),
1074			ix: self.0.ix,
1075		}
1076		.range()
1077	}
1078
1079	/// Key storing one durable queued mutation for a build generation.
1080	pub fn new_bg_key(
1081		&self,
1082		generation: BuildGeneration,
1083		ticket: BuildTicket,
1084		mutation_seq: BuildTicketMutationSeq,
1085	) -> BuildAppendKey<'_> {
1086		BuildAppendKey {
1087			ns: self.0.ns,
1088			db: self.0.db,
1089			tb: Cow::Borrowed(&self.0.tb),
1090			ix: self.0.ix,
1091			generation,
1092			ticket,
1093			mutation_seq,
1094		}
1095	}
1096
1097	/// Range covering durable queued mutations for one build generation.
1098	pub fn new_bg_range(&self, generation: BuildGeneration) -> Result<TypedRange<Appending>> {
1099		BuildAppendGenerationPrefix {
1100			ns: self.0.ns,
1101			db: self.0.db,
1102			tb: Cow::Borrowed(&self.0.tb),
1103			ix: self.0.ix,
1104			generation,
1105		}
1106		.range()
1107	}
1108
1109	/// Range covering every durable queued mutation that shares one reservation
1110	/// ticket within a build generation — used by `wait_for_durable_reservations`
1111	/// to decide whether a writer has committed any of its batched mutations.
1112	pub fn new_bg_ticket_range(
1113		&self,
1114		generation: BuildGeneration,
1115		ticket: BuildTicket,
1116	) -> Result<TypedRange<Appending>> {
1117		BuildAppendTicketPrefix {
1118			ns: self.0.ns,
1119			db: self.0.db,
1120			tb: Cow::Borrowed(&self.0.tb),
1121			ix: self.0.ix,
1122			generation,
1123			ticket,
1124		}
1125		.range()
1126	}
1127
1128	/// Range covering durable queued mutations across all generations of this index.
1129	/// As `new_bg_all_generations_range`, but only generations below `below`.
1130	pub fn new_bg_range_below(&self, below: BuildGeneration) -> Result<TypedRange<Appending>> {
1131		BuildAppendIxPrefix {
1132			ns: self.0.ns,
1133			db: self.0.db,
1134			tb: Cow::Borrowed(&self.0.tb),
1135			ix: self.0.ix,
1136		}
1137		.range_where(..below)
1138	}
1139
1140	pub fn new_bg_all_generations_range(&self) -> Result<TypedRange<Appending>> {
1141		BuildAppendIxPrefix {
1142			ns: self.0.ns,
1143			db: self.0.db,
1144			tb: Cow::Borrowed(&self.0.tb),
1145			ix: self.0.ix,
1146		}
1147		.range()
1148	}
1149
1150	/// Key mapping a record to its first queued mutation during the initial scan.
1151	pub fn new_bp_key<'a>(
1152		&'a self,
1153		generation: BuildGeneration,
1154		id: &'a RecordIdKey,
1155	) -> BuildPrimaryKey<'a> {
1156		BuildPrimaryKey {
1157			ns: self.0.ns,
1158			db: self.0.db,
1159			tb: Cow::Borrowed(&self.0.tb),
1160			ix: self.0.ix,
1161			generation,
1162			id: RecordIdentity(id.clone()),
1163		}
1164	}
1165
1166	/// The key a previous release wrote `id`'s primary-appending marker at,
1167	/// when it is not [`Self::new_bp_key`]'s; see [`PreviousBpSpelling::key`].
1168	pub fn new_bp_key_in_previous_spelling(
1169		&self,
1170		generation: BuildGeneration,
1171		id: &RecordIdKey,
1172	) -> Result<Option<PreviousBuildPrimaryKey>> {
1173		let spelled = storekey::encode_vec(id).map_err(anyhow::Error::from_boxed)?;
1174		self.previous_bp_spelling(generation)?.key(id, &spelled)
1175	}
1176
1177	/// A previous release's primary-appending keys for `generation`.
1178	pub fn previous_bp_spelling(&self, generation: BuildGeneration) -> Result<PreviousBpSpelling> {
1179		let prefix = BuildPrimaryGenerationPrefix {
1180			ns: self.0.ns,
1181			db: self.0.db,
1182			tb: Cow::Borrowed(&self.0.tb),
1183			ix: self.0.ix,
1184			generation,
1185		}
1186		.encode_bound()?;
1187		Ok(PreviousBpSpelling(prefix.to_vec()))
1188	}
1189
1190	/// Range covering primary-appending markers for one build generation.
1191	///
1192	/// Only the build tests above this crate read a whole generation's markers;
1193	/// the engine deletes them by generation span instead, via
1194	/// [`Self::new_bp_range_below`].
1195	pub fn new_bp_range(
1196		&self,
1197		generation: BuildGeneration,
1198	) -> Result<TypedRange<PrimaryAppendingTicket>> {
1199		use crate::key::schema::BuildPrimaryGenerationPrefix;
1200
1201		BuildPrimaryGenerationPrefix {
1202			ns: self.0.ns,
1203			db: self.0.db,
1204			tb: Cow::Borrowed(&self.0.tb),
1205			ix: self.0.ix,
1206			generation,
1207		}
1208		.range()
1209	}
1210
1211	/// Range covering a primary-appending record-id span for one build generation.
1212	pub fn new_bp_span_range(
1213		&self,
1214		generation: BuildGeneration,
1215		after: Option<&RecordIdKey>,
1216		through: Option<&RecordIdKey>,
1217	) -> Result<TypedRange<PrimaryAppendingTicket>> {
1218		use std::ops::Bound;
1219
1220		// The bounds are spelled like the keys they page over, or they would not
1221		// line up with them: an identity encodes a nested value's numeric variant
1222		// that the index format drops.
1223		let start = match after {
1224			Some(after) => Bound::Excluded(RecordIdentity(after.clone())),
1225			None => Bound::Unbounded,
1226		};
1227		let end = match through {
1228			Some(through) => Bound::Included(RecordIdentity(through.clone())),
1229			None => Bound::Unbounded,
1230		};
1231		BuildPrimaryGenerationPrefix {
1232			ns: self.0.ns,
1233			db: self.0.db,
1234			tb: Cow::Borrowed(&self.0.tb),
1235			ix: self.0.ix,
1236			generation,
1237		}
1238		.range_where((start, end))
1239	}
1240
1241	/// Range covering primary-appending markers across all generations of this index.
1242	/// As `new_bp_all_generations_range`, but only generations below `below`.
1243	pub fn new_bp_range_below(
1244		&self,
1245		below: BuildGeneration,
1246	) -> Result<TypedRange<PrimaryAppendingTicket>> {
1247		BuildPrimaryIxPrefix {
1248			ns: self.0.ns,
1249			db: self.0.db,
1250			tb: Cow::Borrowed(&self.0.tb),
1251			ix: self.0.ix,
1252		}
1253		.range_where(..below)
1254	}
1255
1256	pub fn new_bp_all_generations_range(&self) -> Result<TypedRange<PrimaryAppendingTicket>> {
1257		BuildPrimaryIxPrefix {
1258			ns: self.0.ns,
1259			db: self.0.db,
1260			tb: Cow::Borrowed(&self.0.tb),
1261			ix: self.0.ix,
1262		}
1263		.range()
1264	}
1265
1266	pub fn new_ic_key(&self, nid: Uuid) -> IndexCompactionKey<'_> {
1267		IndexCompactionKey {
1268			ns: self.0.ns,
1269			db: self.0.db,
1270			tb: Cow::Borrowed(&self.0.tb),
1271			ix: self.0.ix,
1272			nid,
1273			uid: Uuid::now_v7(),
1274		}
1275	}
1276
1277	fn new_td_root<'a>(&'a self, term: &'a str) -> TermDocsKey<'a> {
1278		TermDocsKey {
1279			ns: self.0.ns,
1280			db: self.0.db,
1281			tb: Cow::Borrowed(&self.0.tb),
1282			ix: self.0.ix,
1283			term: Cow::Borrowed(term),
1284		}
1285	}
1286
1287	/// Per-document totals for one term that its compacted bitmap cannot hold.
1288	fn new_tr_root<'a>(&'a self, term: &'a str) -> TermDocsResidualKey<'a> {
1289		TermDocsResidualKey {
1290			ns: self.0.ns,
1291			db: self.0.db,
1292			tb: Cow::Borrowed(&self.0.tb),
1293			ix: self.0.ix,
1294			term: Cow::Borrowed(term),
1295		}
1296	}
1297
1298	/// Every term's residual (`!tr`), or only those of terms sorting before
1299	/// `below` where it is given.
1300	fn new_tr_terms_range(&self, below: Option<&str>) -> Result<TypedRange<TermDocsResidual>> {
1301		let prefix = TermDocsResidualPrefix {
1302			ns: self.0.ns,
1303			db: self.0.db,
1304			tb: Cow::Borrowed(&self.0.tb),
1305			ix: self.0.ix,
1306		};
1307		match below {
1308			Some(below) => prefix.range_where(..Cow::Borrowed(below)),
1309			None => prefix.range(),
1310		}
1311	}
1312
1313	/// The list of `term`'s posting blocks.
1314	fn new_tk<'a>(&'a self, term: &'a str) -> TermBlocksKey<'a> {
1315		TermBlocksKey {
1316			ns: self.0.ns,
1317			db: self.0.db,
1318			tb: Cow::Borrowed(&self.0.tb),
1319			ix: self.0.ix,
1320			term: Cow::Borrowed(term),
1321		}
1322	}
1323
1324	/// The posting block of `term` that starts at `start`.
1325	fn new_tp<'a>(&'a self, term: &'a str, start: DocId) -> TermBlockKey<'a> {
1326		TermBlockKey {
1327			ns: self.0.ns,
1328			db: self.0.db,
1329			tb: Cow::Borrowed(&self.0.tb),
1330			ix: self.0.ix,
1331			term: Cow::Borrowed(term),
1332			start,
1333		}
1334	}
1335
1336	/// Every posting block of `term`, in order of start.
1337	fn new_tp_term_range<'a>(&'a self, term: &'a str) -> Result<TypedRange<PostingBlock>> {
1338		TermBlockTermPrefix {
1339			ns: self.0.ns,
1340			db: self.0.db,
1341			tb: Cow::Borrowed(&self.0.tb),
1342			ix: self.0.ix,
1343			term: Cow::Borrowed(term),
1344		}
1345		.range()
1346	}
1347
1348	/// Key holding every posting for one document.
1349	fn new_dt(&self, doc_id: DocId) -> DocTermsKey<'_> {
1350		DocTermsKey {
1351			ns: self.0.ns,
1352			db: self.0.db,
1353			tb: Cow::Borrowed(&self.0.tb),
1354			ix: self.0.ix,
1355			id: doc_id,
1356		}
1357	}
1358
1359	/// Legacy per-(term, document) posting key. Written by servers before `!dt`
1360	/// existed, and still read for documents that carry no `!dt` entry.
1361	fn new_td<'a>(&'a self, term: &'a str, doc_id: DocId) -> TermPostingKey<'a> {
1362		TermPostingKey {
1363			ns: self.0.ns,
1364			db: self.0.db,
1365			tb: Cow::Borrowed(&self.0.tb),
1366			ix: self.0.ix,
1367			term: Cow::Borrowed(term),
1368			id: doc_id,
1369		}
1370	}
1371
1372	fn new_tt_term_range<'a>(&'a self, term: &'a str) -> Result<TypedRange<String>> {
1373		TermChangeSetKey {
1374			ns: self.0.ns,
1375			db: self.0.db,
1376			tb: Cow::Borrowed(&self.0.tb),
1377			ix: self.0.ix,
1378			term: Cow::Borrowed(term),
1379		}
1380		.range()
1381	}
1382
1383	fn new_tt_terms_range(&self) -> Result<TypedRange<String>> {
1384		TermChangesKey {
1385			ns: self.0.ns,
1386			db: self.0.db,
1387			tb: Cow::Borrowed(&self.0.tb),
1388			ix: self.0.ix,
1389		}
1390		.range()
1391	}
1392
1393	fn new_tx_term_range<'a>(&'a self, term: &'a str) -> Result<TypedRange<ChangeBatch>> {
1394		TermChangeBatchTermPrefix {
1395			ns: self.0.ns,
1396			db: self.0.db,
1397			tb: Cow::Borrowed(&self.0.tb),
1398			ix: self.0.ix,
1399			term: Cow::Borrowed(term),
1400		}
1401		.range()
1402	}
1403
1404	fn new_tx_terms_range(&self) -> Result<TypedRange<ChangeBatch>> {
1405		TermChangeBatchPrefix {
1406			ns: self.0.ns,
1407			db: self.0.db,
1408			tb: Cow::Borrowed(&self.0.tb),
1409			ix: self.0.ix,
1410		}
1411		.range()
1412	}
1413
1414	/// Buffers this index's contribution to one term until the transaction
1415	/// commits, where it becomes one `!tx` entry per term and direction. An
1416	/// addition's entry also carries each document's `posting`, where given:
1417	/// the term's frequency in the document and the document's length.
1418	fn buffer_tt(
1419		&self,
1420		tx: &Transaction,
1421		term: &str,
1422		doc_id: DocId,
1423		nid: Uuid,
1424		add: bool,
1425		posting: Option<(TermFrequency, DocLength)>,
1426	) -> Result<()> {
1427		tx.buffer_term_change(
1428			self.0.ns, self.0.db, &self.0.tb, self.0.ix, term, doc_id, add, posting, nid,
1429		)
1430	}
1431
1432	/// What this transaction has buffered for one term, as `(added, removed)`.
1433	fn pending_tt(&self, tx: &Transaction, term: &str) -> (RoaringTreemap, RoaringTreemap) {
1434		tx.pending_term_change(self.0.ns, self.0.db, &self.0.tb, self.0.ix, term)
1435	}
1436
1437	/// What this transaction has buffered for one document's membership of one
1438	/// term: its net change, −1, 0 or +1.
1439	fn pending_tt_of(&self, tx: &Transaction, term: &str, doc_id: DocId) -> i64 {
1440		tx.pending_term_change_of(self.0.ns, self.0.db, &self.0.tb, self.0.ix, term, doc_id)
1441	}
1442
1443	/// Buffers one document's contribution to this index's statistics.
1444	fn buffer_dx(&self, tx: &Transaction, stats: DocLengthAndCount, nid: Uuid) {
1445		tx.buffer_doc_stats(self.0.ns, self.0.db, &self.0.tb, self.0.ix, stats, nid)
1446	}
1447
1448	/// What this transaction has buffered for this index's statistics.
1449	fn pending_dx(&self, tx: &Transaction) -> DocLengthAndCount {
1450		tx.pending_doc_stats(self.0.ns, self.0.db, &self.0.tb, self.0.ix)
1451	}
1452
1453	/// Generation guard for full-text term-document (`!tt`) compaction.
1454	fn new_tv_key(&self) -> TermGenerationKey<'_> {
1455		TermGenerationKey {
1456			ns: self.0.ns,
1457			db: self.0.db,
1458			tb: Cow::Borrowed(&self.0.tb),
1459			ix: self.0.ix,
1460		}
1461	}
1462
1463	fn new_dc_compacted(&self) -> DocStatsKey<'_> {
1464		DocStatsKey {
1465			ns: self.0.ns,
1466			db: self.0.db,
1467			tb: Cow::Borrowed(&self.0.tb),
1468			ix: self.0.ix,
1469		}
1470	}
1471
1472	fn new_dx_range(&self) -> Result<TypedRange<DocLengthAndCount>> {
1473		DocStatsBatchPrefix {
1474			ns: self.0.ns,
1475			db: self.0.db,
1476			tb: Cow::Borrowed(&self.0.tb),
1477			ix: self.0.ix,
1478		}
1479		.range()
1480	}
1481
1482	/// Generation guard for full-text document-stat (`!dc`) compaction.
1483	fn new_dv_key(&self) -> DocCountKey<'_> {
1484		DocCountKey {
1485			ns: self.0.ns,
1486			db: self.0.db,
1487			tb: Cow::Borrowed(&self.0.tb),
1488			ix: self.0.ix,
1489		}
1490	}
1491
1492	fn new_dl(&self, doc_id: DocId) -> DocLengthKey<'_> {
1493		DocLengthKey {
1494			ns: self.0.ns,
1495			db: self.0.db,
1496			tb: Cow::Borrowed(&self.0.tb),
1497			ix: self.0.ix,
1498			id: doc_id,
1499		}
1500	}
1501
1502	/// Generation guard for count-index (`!iu`) compaction.
1503	pub(crate) fn new_iv_key(&self) -> IndexVersionKey<'_> {
1504		IndexVersionKey {
1505			ns: self.0.ns,
1506			db: self.0.db,
1507			tb: Cow::Borrowed(&self.0.tb),
1508			ix: self.0.ix,
1509		}
1510	}
1511
1512	pub fn ns(&self) -> NamespaceId {
1513		self.0.ns
1514	}
1515
1516	pub fn db(&self) -> DatabaseId {
1517		self.0.db
1518	}
1519
1520	pub fn table(&self) -> &TableName {
1521		&self.0.tb
1522	}
1523
1524	pub fn index(&self) -> IndexId {
1525		self.0.ix
1526	}
1527
1528	/// This index as its pending-state guards are kept for `family`.
1529	pub fn guarded(&self, family: PendingGuardFamily) -> GuardedIndex {
1530		GuardedIndex::new(family, self.ns(), self.db(), self.table().clone(), self.index())
1531	}
1532}