Skip to main content

uqa_storage_sqlite/
btree_index.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Persistent backing for logical `btree` value indexes.
8//!
9//! Compact `(table, field, doc_id, value)` rows live in `SQLite`. Native sessions additionally maintain scalar/tuple equality keys and support certificates, allowing equality probes without hydrating the field. Other scans and legacy sessions hydrate an in-memory [`uqa_storage::BTreeIndex`]. Native publication maintains its projections in the same managed transaction as the document mutation.
10
11use std::collections::BTreeMap;
12
13use rusqlite::{params, OptionalExtension};
14use serde::{Deserialize, Serialize};
15use uqa_core::{
16    ArrayValue, DecimalValue, DocId, EnumValue, LegacyVectorValue, TemporalValue, Value,
17};
18
19use super::{ManagedConnection, Result, SQLiteError};
20use crate::value_index_key::SQLiteValueIndexKey;
21
22pub(crate) mod coverage;
23mod entries;
24pub(crate) mod equality;
25mod native;
26pub(crate) mod probe;
27pub(crate) use native::columns::change_column as change_native_column;
28pub(crate) use native::delete_document as delete_native_document_entries;
29
30fn encode_doc_id(doc_id: DocId) -> Result<i64> {
31    i64::try_from(doc_id).map_err(|_| {
32        SQLiteError::StorageBackend(format!(
33            "document id {doc_id} does not fit in SQLite INTEGER"
34        ))
35    })
36}
37
38pub(crate) fn decode_doc_id(doc_id: i64) -> Result<DocId> {
39    DocId::try_from(doc_id).map_err(|_| {
40        SQLiteError::StorageBackend(format!(
41            "invalid negative document id {doc_id} in persisted B-tree index"
42        ))
43    })
44}
45
46#[derive(Debug, Clone, Serialize, Deserialize)]
47#[serde(tag = "type", content = "value")]
48enum StoredValue {
49    Null,
50    Void,
51    Bool(bool),
52    Int(i64),
53    /// IEEE-754 bits preserve NaN payloads, infinities, and signed zero.
54    Float(u64),
55    Str(String),
56    FixedChar(String),
57    Bytes(Vec<u8>),
58    Temporal(TemporalValue),
59    Decimal(DecimalValue),
60    Json(String),
61    JsonB(String),
62    Array(ArrayValue),
63    LegacyVector(LegacyVectorValue),
64    List(Vec<StoredValue>),
65    Row(Vec<StoredValue>),
66    TypedRow(uqa_core::RowValue),
67    TypedRecord(uqa_core::RecordValue),
68    Record(Vec<(String, StoredValue)>),
69    Map(BTreeMap<String, StoredValue>),
70    Enum(EnumValue),
71    Datum(uqa_core::DatumValue),
72    BitString(uqa_core::BitStringValue),
73}
74
75impl From<&Value> for StoredValue {
76    fn from(value: &Value) -> Self {
77        match value {
78            Value::Null => Self::Null,
79            Value::Void => Self::Void,
80            Value::Bool(value) => Self::Bool(*value),
81            Value::Int(value) => Self::Int(*value),
82            Value::Float(value) => Self::Float(value.to_bits()),
83            Value::Str(value) => Self::Str(value.clone()),
84            Value::FixedChar(value) => Self::FixedChar(value.clone()),
85            Value::Bytes(value) => Self::Bytes(value.clone()),
86            Value::BitString(value) => Self::BitString(value.clone()),
87            Value::Temporal(value) => Self::Temporal(value.clone()),
88            Value::Decimal(value) => Self::Decimal(value.clone()),
89            Value::Json(value) => Self::Json(value.clone()),
90            Value::JsonB(value) => Self::JsonB(value.clone()),
91            Value::Array(value) => Self::Array(value.clone()),
92            Value::LegacyVector(value) => Self::LegacyVector(value.clone()),
93            Value::List(values) => Self::List(values.iter().map(Self::from).collect()),
94            Value::Row(values) if values.field_types().is_some() => Self::TypedRow(values.clone()),
95            Value::Row(values) => Self::Row(values.iter().map(Self::from).collect()),
96            Value::Record(fields) if fields.type_oid().is_some() => {
97                Self::TypedRecord(fields.clone())
98            }
99            Value::Record(fields) => Self::Record(
100                fields
101                    .iter()
102                    .map(|(name, value)| (name.clone(), Self::from(value)))
103                    .collect(),
104            ),
105            Value::Map(values) => Self::Map(
106                values
107                    .iter()
108                    .map(|(key, value)| (key.clone(), Self::from(value)))
109                    .collect(),
110            ),
111            Value::Enum(value) => Self::Enum(value.clone()),
112            Value::Datum(value) => Self::Datum(value.clone()),
113        }
114    }
115}
116
117impl StoredValue {
118    fn into_value(self) -> Value {
119        match self {
120            Self::Null => Value::Null,
121            Self::Void => Value::Void,
122            Self::Bool(value) => Value::Bool(value),
123            Self::Int(value) => Value::Int(value),
124            Self::Float(bits) => Value::Float(f64::from_bits(bits)),
125            Self::Str(value) => Value::Str(value),
126            Self::FixedChar(value) => Value::FixedChar(value),
127            Self::Bytes(value) => Value::Bytes(value),
128            Self::BitString(value) => Value::BitString(value),
129            Self::Temporal(value) => Value::Temporal(value),
130            Self::Decimal(value) => Value::Decimal(value),
131            Self::Json(value) => Value::Json(value),
132            Self::JsonB(value) => Value::JsonB(value),
133            Self::Array(value) => Value::Array(value),
134            Self::LegacyVector(value) => Value::LegacyVector(value),
135            Self::List(values) => Value::List(values.into_iter().map(Self::into_value).collect()),
136            Self::Row(values) => Value::Row(values.into_iter().map(Self::into_value).collect()),
137            Self::TypedRow(value) => Value::Row(value),
138            Self::TypedRecord(value) => Value::Record(value),
139            Self::Record(fields) => Value::Record(
140                fields
141                    .into_iter()
142                    .map(|(name, value)| (name, value.into_value()))
143                    .collect::<Vec<_>>()
144                    .into(),
145            ),
146            Self::Map(values) => Value::Map(
147                values
148                    .into_iter()
149                    .map(|(key, value)| (key, value.into_value()))
150                    .collect(),
151            ),
152            Self::Enum(value) => Value::Enum(value),
153            Self::Datum(value) => Value::Datum(value),
154        }
155    }
156}
157
158fn encode_value(value: &Value) -> Result<String> {
159    Ok(serde_json::to_string(&StoredValue::from(value))?)
160}
161
162pub(crate) fn decode_value(encoded: &str) -> Result<Value> {
163    Ok(serde_json::from_str::<StoredValue>(encoded)?.into_value())
164}
165
166#[derive(Clone)]
167pub struct SQLiteBTreeIndexStore {
168    conn: ManagedConnection,
169}
170
171impl SQLiteBTreeIndexStore {
172    pub fn new(conn: ManagedConnection) -> Self {
173        Self { conn }
174    }
175
176    /// Seek the persisted value index, retaining native snapshot and private-row visibility.
177    pub fn probe_equal(
178        &self,
179        table: &str,
180        field: &uqa_storage::ValueIndexKey,
181        value: &Value,
182    ) -> Result<Option<Vec<DocId>>> {
183        if let Some(snapshot) = self.conn.native_snapshot()? {
184            let Some(probe) = probe::EqualityProbe::new(value, &snapshot.control)? else {
185                return Ok(None);
186            };
187            return native::probe_equal(&snapshot, table, field, &probe);
188        }
189        // Unmanaged legacy writers cannot certify population maintenance. Their original hydration and sparse-repair path remains authoritative.
190        Ok(None)
191    }
192
193    /// Visit ordered equality candidates without retaining their population. Unsupported snapshots or domains decline before invoking the callback.
194    pub fn visit_equal(
195        &self,
196        table: &str,
197        field: &uqa_storage::ValueIndexKey,
198        value: &Value,
199        visit: &mut dyn FnMut(DocId) -> bool,
200    ) -> Result<bool> {
201        let Some(snapshot) = self.conn.native_snapshot()? else {
202            return Ok(false);
203        };
204        let Some(probe) = probe::EqualityProbe::new(value, &snapshot.control)? else {
205            return Ok(false);
206        };
207        native::visit_equal(&snapshot, table, field, &probe, visit)
208    }
209
210    pub fn fields(&self, table: &str) -> Result<Vec<uqa_storage::ValueIndexKey>> {
211        if let Some(snapshot) = self.conn.native_snapshot()? {
212            return native::fields(&snapshot, table);
213        }
214        self.conn.with(|conn| {
215            let mut stmt = conn.prepare_cached(
216                "SELECT field FROM _btree_indexes
217                 WHERE table_name = ?1
218                 ORDER BY field",
219            )?;
220            let rows = stmt.query_map([table], |row| {
221                row.get::<_, SQLiteValueIndexKey<uqa_storage::ValueIndexKey>>(0)
222                    .map(|key| key.0)
223            })?;
224            let mut fields = Vec::new();
225            for row in rows {
226                fields.push(row?);
227            }
228            Ok(fields)
229        })
230    }
231
232    pub fn repairs(&self) -> Result<Vec<(String, uqa_storage::ValueIndexKey)>> {
233        if let Some(snapshot) = self.conn.native_snapshot()? {
234            return native::repairs(&snapshot);
235        }
236        self.conn.with(|conn| {
237            let mut stmt = conn.prepare_cached(
238                "SELECT table_name, field FROM _btree_index_repairs ORDER BY table_name, field",
239            )?;
240            let rows = stmt.query_map([], |row| {
241                Ok((
242                    row.get::<_, String>(0)?,
243                    row.get::<_, SQLiteValueIndexKey<uqa_storage::ValueIndexKey>>(1)?
244                        .0,
245                ))
246            })?;
247            let mut repairs = Vec::new();
248            for row in rows {
249                repairs.push(row?);
250            }
251            Ok(repairs)
252        })
253    }
254
255    pub fn clear_repair(&self, table: &str, field: &uqa_storage::ValueIndexKey) -> Result<()> {
256        if self
257            .conn
258            .with_native_write(|snapshot, batch| {
259                native::clear_repair(snapshot, batch, table, field)
260            })?
261            .is_some()
262        {
263            return Ok(());
264        }
265        self.conn.with(|conn| {
266            conn.execute(
267                "DELETE FROM _btree_index_repairs
268                 WHERE table_name = ?1 AND field = ?2",
269                params![table, SQLiteValueIndexKey(field)],
270            )?;
271            Ok(())
272        })
273    }
274
275    /// Read one stored key without rebuilding or reevaluating its expression. Both metadata and entry come from the same retained native or connection read.
276    pub fn read_entry(
277        &self,
278        table: &str,
279        field: &uqa_storage::ValueIndexKey,
280        doc_id: DocId,
281    ) -> Result<uqa_storage::ValueIndexEntry> {
282        if let Some(snapshot) = self.conn.native_snapshot()? {
283            return native::read_entry(&snapshot, table, field, doc_id);
284        }
285        let id = encode_doc_id(doc_id)?;
286        self.conn.with(|conn| {
287            let encoded = conn
288                .prepare_cached(
289                    "SELECT entry.value_json FROM _btree_indexes AS definition
290                     LEFT JOIN _btree_index_entries AS entry
291                       ON entry.table_name = definition.table_name
292                      AND entry.field = definition.field AND entry.doc_id = ?3
293                     WHERE definition.table_name = ?1 AND definition.field = ?2",
294                )?
295                .query_row(params![table, SQLiteValueIndexKey(field), id], |row| {
296                    row.get::<_, Option<String>>(0)
297                })
298                .optional()?;
299            match encoded {
300                None => Ok(uqa_storage::ValueIndexEntry::Unbuilt),
301                Some(None) => Ok(uqa_storage::ValueIndexEntry::Absent),
302                Some(Some(value)) => {
303                    decode_value(&value).map(uqa_storage::ValueIndexEntry::Present)
304                }
305            }
306        })
307    }
308
309    /// Load a complete persisted index. `None` means this field has not been
310    /// built yet and the engine must backfill it from the document store once.
311    pub fn load(
312        &self,
313        table: &str,
314        field: &uqa_storage::ValueIndexKey,
315    ) -> Result<Option<Vec<(DocId, Value)>>> {
316        if let Some(snapshot) = self.conn.native_snapshot()? {
317            return native::load(&snapshot, table, field);
318        }
319        self.conn.with(|conn| {
320            let exists = conn
321                .prepare_cached(
322                    "SELECT 1 FROM _btree_indexes
323                     WHERE table_name = ?1 AND field = ?2",
324                )?
325                .query_row(params![table, SQLiteValueIndexKey(field)], |row| {
326                    row.get::<_, i64>(0)
327                })
328                .optional()?
329                .is_some();
330            if !exists {
331                return Ok(None);
332            }
333
334            let mut stmt = conn.prepare_cached(
335                "SELECT doc_id, value_json
336                 FROM _btree_index_entries
337                 WHERE table_name = ?1 AND field = ?2
338                 ORDER BY doc_id",
339            )?;
340            let mut rows = stmt.query(params![table, SQLiteValueIndexKey(field)])?;
341            let mut values = Vec::new();
342            while let Some(row) = rows.next()? {
343                let doc_id = decode_doc_id(row.get::<_, i64>(0)?)?;
344                let encoded = row.get::<_, String>(1)?;
345                values.push((doc_id, decode_value(&encoded)?));
346            }
347            Ok(Some(values))
348        })
349    }
350
351    /// Atomically replace the complete persisted posting set and mark it built.
352    pub fn replace(
353        &self,
354        table: &str,
355        field: &uqa_storage::ValueIndexKey,
356        values: &[(DocId, Value)],
357    ) -> Result<()> {
358        self.replace_many(table, &[(field, values)])
359    }
360
361    /// Apply a sparse structural repair while retaining every valid posting.
362    /// All ids and values are encoded before opening the savepoint so a range
363    /// or serialization error cannot leave half of the delta applied.
364    pub fn repair(
365        &self,
366        table: &str,
367        field: &uqa_storage::ValueIndexKey,
368        stale_doc_ids: &[DocId],
369        missing: &[(DocId, Value)],
370    ) -> Result<()> {
371        if self
372            .conn
373            .with_native_write(|snapshot, batch| {
374                native::repair(snapshot, batch, table, field, stale_doc_ids, missing)
375            })?
376            .is_some()
377        {
378            return Ok(());
379        }
380        let stale_doc_ids = stale_doc_ids
381            .iter()
382            .map(|doc_id| encode_doc_id(*doc_id))
383            .collect::<Result<Vec<_>>>()?;
384        let missing = missing
385            .iter()
386            .map(|(doc_id, value)| Ok((encode_doc_id(*doc_id)?, encode_value(value)?)))
387            .collect::<Result<Vec<_>>>()?;
388        self.conn.with_mut(|conn| {
389            let tx = conn.savepoint()?;
390            tx.execute(
391                "INSERT OR IGNORE INTO _btree_indexes (table_name, field)
392                 VALUES (?1, ?2)",
393                params![table, SQLiteValueIndexKey(field)],
394            )?;
395            {
396                let mut delete = tx.prepare_cached(
397                    "DELETE FROM _btree_index_entries
398                     WHERE table_name = ?1 AND field = ?2 AND doc_id = ?3",
399                )?;
400                for doc_id in &stale_doc_ids {
401                    delete.execute(params![table, SQLiteValueIndexKey(field), doc_id])?;
402                }
403            }
404            {
405                let mut insert = tx.prepare_cached(
406                    "INSERT INTO _btree_index_entries
407                       (table_name, field, doc_id, value_json)
408                     VALUES (?1, ?2, ?3, ?4)
409                     ON CONFLICT (table_name, field, doc_id)
410                     DO UPDATE SET value_json = excluded.value_json",
411                )?;
412                for (doc_id, value_json) in &missing {
413                    insert.execute(params![
414                        table,
415                        SQLiteValueIndexKey(field),
416                        doc_id,
417                        value_json
418                    ])?;
419                }
420            }
421            tx.commit()?;
422            Ok(())
423        })
424    }
425
426    /// Atomically replace several complete posting sets for one table. Repair
427    /// paths commonly rebuild every indexed column together; one savepoint and
428    /// one set of prepared statements avoids repeating `SQLite` setup per field.
429    pub fn replace_many(
430        &self,
431        table: &str,
432        indexes: &[(&uqa_storage::ValueIndexKey, &[(DocId, Value)])],
433    ) -> Result<()> {
434        if self
435            .conn
436            .with_native_write(|snapshot, batch| {
437                native::replace_many(snapshot, batch, table, indexes)
438            })?
439            .is_some()
440        {
441            return Ok(());
442        }
443        let encoded = indexes
444            .iter()
445            .map(|(field, values)| {
446                let values = values
447                    .iter()
448                    .map(|(doc_id, value)| Ok((encode_doc_id(*doc_id)?, encode_value(value)?)))
449                    .collect::<Result<Vec<_>>>()?;
450                Ok((*field, values))
451            })
452            .collect::<Result<Vec<_>>>()?;
453        self.conn.with_mut(|conn| {
454            let tx = conn.savepoint()?;
455            {
456                let mut delete = tx.prepare_cached(
457                    "DELETE FROM _btree_index_entries
458                     WHERE table_name = ?1 AND field = ?2",
459                )?;
460                let mut mark = tx.prepare_cached(
461                    "INSERT OR IGNORE INTO _btree_indexes (table_name, field)
462                     VALUES (?1, ?2)",
463                )?;
464                let mut insert = tx.prepare_cached(
465                    "INSERT INTO _btree_index_entries
466                       (table_name, field, doc_id, value_json)
467                     VALUES (?1, ?2, ?3, ?4)",
468                )?;
469                for (field, values) in &encoded {
470                    delete.execute(params![table, SQLiteValueIndexKey(*field)])?;
471                    mark.execute(params![table, SQLiteValueIndexKey(*field)])?;
472                    for (doc_id, value_json) in values {
473                        insert.execute(params![
474                            table,
475                            SQLiteValueIndexKey(*field),
476                            doc_id,
477                            value_json
478                        ])?;
479                    }
480                }
481            }
482            tx.commit()?;
483            Ok(())
484        })
485    }
486
487    /// Write the entries of a document whose identity no document of the table ever had in `namespace`, so that no entry of that identity exists to replace. The legacy tables replace by primary key either way.
488    pub fn apply_unused_write(
489        &self,
490        table: &str,
491        doc_id: DocId,
492        values: &BTreeMap<uqa_storage::ValueIndexKey, Value>,
493        namespace: uqa_storage::document_store::identifiers::DocumentIdNamespace,
494    ) -> Result<()> {
495        if self
496            .conn
497            .with_native_write(|snapshot, batch| {
498                native::apply_write(
499                    snapshot,
500                    batch,
501                    table,
502                    doc_id,
503                    Some(values),
504                    Some(namespace),
505                )
506            })?
507            .is_some()
508        {
509            return Ok(());
510        }
511        self.apply_write(table, doc_id, Some(values))
512    }
513
514    /// Apply one document write to every persisted field currently loaded by
515    /// the engine. A replacement uses the `(table, field, doc_id)` primary key,
516    /// so updates never need a separate old-value delete.
517    pub fn apply_write(
518        &self,
519        table: &str,
520        doc_id: DocId,
521        values: Option<&BTreeMap<uqa_storage::ValueIndexKey, Value>>,
522    ) -> Result<()> {
523        if self
524            .conn
525            .with_native_write(|snapshot, batch| {
526                native::apply_write(snapshot, batch, table, doc_id, values, None)
527            })?
528            .is_some()
529        {
530            return Ok(());
531        }
532        let doc_id = encode_doc_id(doc_id)?;
533        let encoded = values
534            .map(|values| {
535                values
536                    .iter()
537                    .map(|(field, value)| Ok((field.clone(), encode_value(value)?)))
538                    .collect::<Result<Vec<_>>>()
539            })
540            .transpose()?;
541        self.conn.with_mut(|conn| {
542            let tx = conn.savepoint()?;
543            match encoded.as_ref() {
544                Some(values) => {
545                    let mut stmt = tx.prepare_cached(
546                        "INSERT INTO _btree_index_entries
547                           (table_name, field, doc_id, value_json)
548                         SELECT ?1, ?2, ?3, ?4
549                         WHERE EXISTS (
550                             SELECT 1 FROM _btree_indexes
551                             WHERE table_name = ?1 AND field = ?2
552                         )
553                         ON CONFLICT (table_name, field, doc_id)
554                         DO UPDATE SET value_json = excluded.value_json",
555                    )?;
556                    for (field, value_json) in values {
557                        stmt.execute(params![
558                            table,
559                            SQLiteValueIndexKey(field),
560                            doc_id,
561                            value_json
562                        ])?;
563                    }
564                }
565                None => {
566                    tx.execute(
567                        "DELETE FROM _btree_index_entries
568                         WHERE table_name = ?1 AND doc_id = ?2",
569                        params![table, doc_id],
570                    )?;
571                }
572            }
573            tx.commit()?;
574            Ok(())
575        })
576    }
577
578    pub fn drop_index(&self, table: &str, field: &uqa_storage::ValueIndexKey) -> Result<()> {
579        if self
580            .conn
581            .with_native_write(|snapshot, batch| native::drop_index(snapshot, batch, table, field))?
582            .is_some()
583        {
584            return Ok(());
585        }
586        self.conn.with_mut(|conn| {
587            let tx = conn.savepoint()?;
588            tx.execute(
589                "DELETE FROM _btree_index_entries
590                 WHERE table_name = ?1 AND field = ?2",
591                params![table, SQLiteValueIndexKey(field)],
592            )?;
593            tx.execute(
594                "DELETE FROM _btree_indexes
595                 WHERE table_name = ?1 AND field = ?2",
596                params![table, SQLiteValueIndexKey(field)],
597            )?;
598            tx.commit()?;
599            Ok(())
600        })
601    }
602
603    /// TRUNCATE keeps the index definitions but removes every posting.
604    pub fn clear_table(&self, table: &str) -> Result<()> {
605        if self
606            .conn
607            .with_native_write(|snapshot, batch| native::clear_table(snapshot, batch, table))?
608            .is_some()
609        {
610            return Ok(());
611        }
612        self.conn.with(|conn| {
613            conn.execute(
614                "DELETE FROM _btree_index_entries WHERE table_name = ?1",
615                params![table],
616            )?;
617            Ok(())
618        })
619    }
620}
621
622#[cfg(test)]
623mod tests {
624    use super::*;
625    use crate::Catalog;
626
627    fn store() -> SQLiteBTreeIndexStore {
628        let conn = ManagedConnection::open_in_memory().unwrap();
629        let _catalog = Catalog::open(conn.clone()).unwrap();
630        conn.with(|connection| {
631            connection.execute_batch(
632                "INSERT INTO _documents (table_name, doc_id, body)
633                 VALUES ('messages', 1, '{}'), ('messages', 2, '{}');",
634            )?;
635            Ok(())
636        })
637        .unwrap();
638        SQLiteBTreeIndexStore::new(conn)
639    }
640
641    #[test]
642    fn stored_point_reads_preserve_null_absence_and_selected_namespace() {
643        use uqa_storage::{ValueIndexEntry, ValueIndexKey};
644        let store = store();
645        let column = ValueIndexKey::Column("price".into());
646        let named = ValueIndexKey::Index("price".into());
647        assert_eq!(
648            store.read_entry("messages", &column, 1).unwrap(),
649            ValueIndexEntry::Unbuilt
650        );
651        store
652            .replace("messages", &column, &[(1, Value::Null)])
653            .unwrap();
654        store
655            .replace(
656                "messages",
657                &named,
658                &[(1, Value::Row(vec![Value::Int(5)].into()))],
659            )
660            .unwrap();
661        assert_eq!(
662            store.read_entry("messages", &column, 1).unwrap(),
663            ValueIndexEntry::Present(Value::Null)
664        );
665        assert_eq!(
666            store.read_entry("messages", &column, 2).unwrap(),
667            ValueIndexEntry::Absent
668        );
669        assert_eq!(
670            store.read_entry("messages", &named, 1).unwrap(),
671            ValueIndexEntry::Present(Value::Row(vec![Value::Int(5)].into()))
672        );
673        store.clear_table("messages").unwrap();
674        assert_eq!(
675            store.read_entry("messages", &column, 1).unwrap(),
676            ValueIndexEntry::Absent
677        );
678        store.drop_index("messages", &column).unwrap();
679        assert_eq!(
680            store.read_entry("messages", &column, 1).unwrap(),
681            ValueIndexEntry::Unbuilt
682        );
683    }
684
685    #[test]
686    fn tagged_values_round_trip_without_untagged_serde_ambiguity() {
687        let values = vec![
688            Value::Null,
689            Value::Bool(true),
690            Value::Int(7),
691            Value::Float(-0.0),
692            Value::Float(f64::NAN),
693            Value::Str("seven".into()),
694            Value::FixedChar("seven   ".into()),
695            Value::Bytes(vec![1, 2, 3]),
696            Value::Json("{\"b\":2,\"a\":1}".into()),
697            Value::JsonB("{\"a\": 1, \"b\": 2}".into()),
698            Value::List(vec![Value::Int(1), Value::Int(2)]),
699            Value::LegacyVector(
700                LegacyVectorValue::try_new(uqa_core::LegacyVectorKind::SmallInteger, vec![])
701                    .unwrap(),
702            ),
703            Value::LegacyVector(
704                LegacyVectorValue::try_new(
705                    uqa_core::LegacyVectorKind::Oid,
706                    vec![Value::Int(0), Value::Int(4_294_967_295)],
707                )
708                .unwrap(),
709            ),
710            Value::Map(BTreeMap::from([("k".into(), Value::Str("v".into()))])),
711            Value::Record(uqa_core::RecordValue::from_parts(
712                vec![("n".into(), Value::Float(0.1))],
713                Some(20_001),
714            )),
715        ];
716        for value in values {
717            let decoded = decode_value(&encode_value(&value).unwrap()).unwrap();
718            match (&value, &decoded) {
719                (Value::Float(left), Value::Float(right)) if left.is_nan() => {
720                    assert!(right.is_nan());
721                }
722                _ => assert!(decoded.has_same_representation(&value)),
723            }
724        }
725    }
726
727    #[test]
728    fn replace_load_write_delete_and_clear_round_trip() {
729        let store = store();
730        store
731            .replace(
732                "messages",
733                &"public_id".into(),
734                &[(1, Value::Str("m1".into())), (2, Value::Null)],
735            )
736            .unwrap();
737        assert_eq!(
738            store.load("messages", &"public_id".into()).unwrap(),
739            Some(vec![(1, Value::Str("m1".into())), (2, Value::Null)])
740        );
741        assert_eq!(
742            store.fields("messages").unwrap(),
743            vec![uqa_storage::ValueIndexKey::from("public_id")]
744        );
745
746        store
747            .apply_write(
748                "messages",
749                2,
750                Some(&BTreeMap::from([
751                    ("public_id".into(), Value::Str("m2".into())),
752                    ("not_built".into(), Value::Int(9)),
753                ])),
754            )
755            .unwrap();
756        store.apply_write("messages", 1, None).unwrap();
757        assert_eq!(
758            store.load("messages", &"public_id".into()).unwrap(),
759            Some(vec![(2, Value::Str("m2".into()))])
760        );
761
762        store.clear_table("messages").unwrap();
763        assert_eq!(
764            store.load("messages", &"public_id".into()).unwrap(),
765            Some(vec![])
766        );
767        store.drop_index("messages", &"public_id".into()).unwrap();
768        assert_eq!(store.load("messages", &"public_id".into()).unwrap(), None);
769    }
770
771    #[test]
772    fn sparse_repair_preserves_valid_postings() {
773        let store = store();
774        store
775            .replace(
776                "messages",
777                &"public_id".into(),
778                &[(1, Value::Str("m1".into())), (2, Value::Str("m2".into()))],
779            )
780            .unwrap();
781        let row_id_before: i64 = store
782            .conn
783            .with(|conn| {
784                Ok(conn.query_row(
785                    "SELECT rowid FROM _btree_index_entries
786                     WHERE table_name = 'messages'
787                       AND field = 'public_id' AND doc_id = 2",
788                    [],
789                    |row| row.get(0),
790                )?)
791            })
792            .unwrap();
793        store
794            .conn
795            .with(|conn| {
796                conn.execute(
797                    "INSERT INTO _documents (table_name, doc_id, body)
798                     VALUES ('messages', 3, '{}')",
799                    [],
800                )?;
801                Ok(())
802            })
803            .unwrap();
804
805        store
806            .repair(
807                "messages",
808                &"public_id".into(),
809                &[1],
810                &[(3, Value::Str("m3".into()))],
811            )
812            .unwrap();
813
814        assert_eq!(
815            store.load("messages", &"public_id".into()).unwrap(),
816            Some(vec![
817                (2, Value::Str("m2".into())),
818                (3, Value::Str("m3".into()))
819            ])
820        );
821        let row_id_after: i64 = store
822            .conn
823            .with(|conn| {
824                Ok(conn.query_row(
825                    "SELECT rowid FROM _btree_index_entries
826                     WHERE table_name = 'messages'
827                       AND field = 'public_id' AND doc_id = 2",
828                    [],
829                    |row| row.get(0),
830                )?)
831            })
832            .unwrap();
833        assert_eq!(row_id_after, row_id_before);
834    }
835
836    #[test]
837    fn out_of_range_document_ids_fail_before_replacing_existing_entries() {
838        let store = store();
839        store
840            .replace(
841                "messages",
842                &"public_id".into(),
843                &[(1, Value::Str("m1".into()))],
844            )
845            .unwrap();
846
847        let error = store
848            .replace(
849                "messages",
850                &"public_id".into(),
851                &[(u64::MAX, Value::Str("overflow".into()))],
852            )
853            .unwrap_err();
854        assert!(error.to_string().contains("does not fit in SQLite INTEGER"));
855        assert_eq!(
856            store.load("messages", &"public_id".into()).unwrap(),
857            Some(vec![(1, Value::Str("m1".into()))])
858        );
859
860        let error = store
861            .apply_write(
862                "messages",
863                u64::MAX,
864                Some(&BTreeMap::from([(
865                    "public_id".into(),
866                    Value::Str("overflow".into()),
867                )])),
868            )
869            .unwrap_err();
870        assert!(error.to_string().contains("does not fit in SQLite INTEGER"));
871    }
872
873    #[test]
874    fn negative_persisted_document_id_is_reported_as_corruption() {
875        let store = store();
876        store
877            .replace(
878                "messages",
879                &"public_id".into(),
880                &[(1, Value::Str("m1".into()))],
881            )
882            .unwrap();
883        store
884            .conn
885            .with(|conn| {
886                conn.execute(
887                    "INSERT INTO _documents (table_name, doc_id, body)
888                     VALUES ('messages', -1, '{}')",
889                    [],
890                )?;
891                conn.execute(
892                    "INSERT INTO _btree_index_entries
893                       (table_name, field, doc_id, value_json)
894                     VALUES (?1, ?2, ?3, ?4)",
895                    params![
896                        "messages",
897                        "public_id",
898                        -1_i64,
899                        encode_value(&Value::Str("corrupt".into()))?
900                    ],
901                )?;
902                Ok(())
903            })
904            .unwrap();
905
906        let error = store.load("messages", &"public_id".into()).unwrap_err();
907        assert!(error
908            .to_string()
909            .contains("invalid negative document id -1"));
910    }
911}