Skip to main content

uqa_storage_sqlite/
key_value.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! `SQLite` persistence and connection affinity for common logical Key/Value sessions.
8
9use std::{path::Path, sync::Arc};
10
11use crate::{ManagedConnection, Result as SQLiteResult};
12use uqa_storage::mvcc::{StorageTransactionId, VersionedKeyValueStore, VersionedSessionOptions};
13use uqa_storage::read_control::{KeyValueReadVisitor, StorageReadControl, ValueReadVisitor};
14use uqa_storage::{
15    CatalogFacade, KeyValueBatch, KeyValueCatalog, KeyValueStorageBackend, KeyValueStore,
16    PersistentStorageBackend, PersistentStorageIdentity, PersistentStorageProvider,
17    PersistentStorageSession, StorageBackendResult,
18};
19
20/// A logical byte-store session sharing transaction state with its managed connection clones.
21#[derive(Clone)]
22pub struct SQLiteKeyValueStore {
23    conn: ManagedConnection,
24    records: Arc<VersionedKeyValueStore>,
25}
26
27impl SQLiteKeyValueStore {
28    pub fn open(path: &Path) -> SQLiteResult<Self> {
29        Self::new(ManagedConnection::open(path)?)
30    }
31
32    pub fn open_in_memory() -> SQLiteResult<Self> {
33        Self::new(ManagedConnection::open_in_memory()?)
34    }
35
36    pub fn new(conn: ManagedConnection) -> SQLiteResult<Self> {
37        Self::with_options(conn, VersionedSessionOptions::default())
38    }
39
40    /// Bind the connection and every existing clone to one bounded logical session.
41    pub fn with_options(
42        conn: ManagedConnection,
43        options: VersionedSessionOptions,
44    ) -> SQLiteResult<Self> {
45        let records = conn.bind_records(options)?;
46        Ok(Self { conn, records })
47    }
48
49    pub fn connection(&self) -> ManagedConnection {
50        self.conn.clone()
51    }
52
53    pub fn new_session(&self) -> Self {
54        self.new_session_with_cancellation(&uqa_core::CancellationToken::new())
55    }
56
57    pub fn new_session_with_cancellation(
58        &self,
59        cancellation: &uqa_core::CancellationToken,
60    ) -> Self {
61        let conn = self.conn.new_session_with_cancellation(cancellation);
62        let records = conn
63            .bind_records(self.records.options())
64            .expect("a fresh connection inherits the same logical session configuration");
65        Self { conn, records }
66    }
67
68    pub fn pending_commit(&self) -> Option<StorageTransactionId> {
69        self.records.pending_commit()
70    }
71}
72
73impl uqa_storage::mvcc::IdentifierAllocator for SQLiteKeyValueStore {
74    fn identifier_watermark(&self, namespace: &[u8]) -> StorageBackendResult<Option<u64>> {
75        self.conn
76            .with_records(|store| store.identifier_watermark(namespace))
77    }
78
79    fn allocate_identifiers(
80        &self,
81        namespace: &[u8],
82        request: uqa_storage::mvcc::IdentifierRequest,
83    ) -> StorageBackendResult<uqa_storage::mvcc::IdentifierAllocation> {
84        self.conn
85            .with_records(|store| store.allocate_identifiers(namespace, request))
86    }
87}
88
89impl KeyValueStore for SQLiteKeyValueStore {
90    fn resource_leases(&self) -> Option<&dyn uqa_storage::mvcc::ResourceLeaseProvider> {
91        self.records.resource_leases()
92    }
93
94    fn auxiliary_encryption_key(&self) -> Option<uqa_storage::StorageEncryptionKey> {
95        self.conn.auxiliary_encryption_key()
96    }
97
98    fn retention_control(&self) -> Option<uqa_storage::read_control::StorageReadControl> {
99        Some(self.records.retention_control())
100    }
101
102    fn notification_publications(
103        &self,
104    ) -> Option<&dyn uqa_storage::notifications::NotificationPublicationStore> {
105        Some(&self.conn)
106    }
107
108    fn serializable_session(&self) -> Option<&dyn uqa_storage::mvcc::SerializableSession> {
109        Some(&self.conn)
110    }
111
112    fn vacuum(&self) -> StorageBackendResult<()> {
113        self.conn.vacuum().map_err(Into::into)
114    }
115
116    fn reclaim_obsolete(&self) -> StorageBackendResult<()> {
117        self.conn.reclaim_obsolete().map_err(Into::into)
118    }
119
120    fn write_cancellation(&self) -> Option<uqa_core::CancellationToken> {
121        self.records.write_cancellation()
122    }
123
124    fn open_session_with_cancellation(
125        &self,
126        cancellation: &uqa_core::CancellationToken,
127    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> {
128        cancellation.check()?;
129        Ok(Arc::new(self.new_session_with_cancellation(cancellation)))
130    }
131
132    fn open_controlled_session(
133        &self,
134        control: &uqa_storage::read_control::StorageReadControl,
135    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> {
136        let conn = self.conn.new_controlled_session(control)?;
137        let records = conn.bind_records(self.records.options())?;
138        Ok(Arc::new(Self { conn, records }))
139    }
140
141    fn open_retained_read_session(
142        &self,
143        cancellation: &uqa_core::CancellationToken,
144    ) -> StorageBackendResult<Arc<dyn KeyValueStore>> {
145        let conn = self.conn.new_retained_read_session(cancellation)?;
146        Ok(Arc::new(Self::with_options(conn, self.records.options())?))
147    }
148
149    fn transaction_model(&self) -> uqa_storage::StorageTransactionModel {
150        self.records.transaction_model()
151    }
152
153    fn refresh_transaction_snapshot(
154        &self,
155        cancellation: &uqa_core::CancellationToken,
156    ) -> StorageBackendResult<()> {
157        self.conn
158            .with_records(|store| store.refresh_transaction_snapshot(cancellation))
159    }
160
161    fn identifier_allocator(&self) -> Option<&dyn uqa_storage::mvcc::IdentifierAllocator> {
162        Some(self)
163    }
164
165    fn with_read_view(
166        &self,
167        read: &mut uqa_storage::key_value::KeyValueReadScope<'_>,
168    ) -> StorageBackendResult<()> {
169        self.conn.with_records(|store| store.with_read_view(read))
170    }
171
172    fn with_mutation(
173        &self,
174        mutate: &mut uqa_storage::key_value::KeyValueMutation<'_>,
175    ) -> StorageBackendResult<()> {
176        self.conn.with_records(|store| store.with_mutation(mutate))
177    }
178
179    fn with_versioned_mutation(
180        &self,
181        mutate: &mut uqa_storage::key_value::KeyValueVersionedMutation<'_>,
182    ) -> StorageBackendResult<()> {
183        self.conn
184            .with_records(|store| store.with_versioned_mutation(mutate))
185    }
186
187    fn transaction_affinity(&self) -> Option<uqa_storage::StorageSessionAffinity> {
188        Some(self.records.session_affinity())
189    }
190
191    fn storage_identity(&self) -> StorageBackendResult<Option<PersistentStorageIdentity>> {
192        self.records.storage_identity()
193    }
194
195    fn open_session(&self) -> StorageBackendResult<Arc<dyn KeyValueStore>> {
196        Ok(Arc::new(self.new_session()))
197    }
198
199    fn get(&self, key: &[u8]) -> StorageBackendResult<Option<Vec<u8>>> {
200        self.conn.with_records(|store| store.get(key))
201    }
202
203    fn contains_key(&self, key: &[u8]) -> StorageBackendResult<bool> {
204        self.conn.with_records(|store| store.contains_key(key))
205    }
206
207    fn contains_prefix_budgeted(
208        &self,
209        prefix: &[u8],
210        control: &StorageReadControl,
211    ) -> StorageBackendResult<bool> {
212        self.conn
213            .with_records(|store| store.contains_prefix_budgeted(prefix, control))
214    }
215
216    fn visit_value(
217        &self,
218        key: &[u8],
219        control: &StorageReadControl,
220        visit: &mut ValueReadVisitor<'_>,
221    ) -> StorageBackendResult<()> {
222        self.conn
223            .with_records(|store| store.visit_value(key, control, visit))
224    }
225
226    fn visit_value_bounded(
227        &self,
228        key: &[u8],
229        max_bytes: usize,
230        control: &StorageReadControl,
231        visit: &mut ValueReadVisitor<'_>,
232    ) -> StorageBackendResult<()> {
233        self.conn
234            .with_records(|store| store.visit_value_bounded(key, max_bytes, control, visit))
235    }
236
237    fn visit_prefix_after(
238        &self,
239        prefix: &[u8],
240        after: Option<&[u8]>,
241        limit: usize,
242        control: &StorageReadControl,
243        visit: &mut KeyValueReadVisitor<'_>,
244    ) -> StorageBackendResult<()> {
245        self.conn
246            .with_records(|store| store.visit_prefix_after(prefix, after, limit, control, visit))
247    }
248
249    fn put(&self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
250        self.conn.with_records(|store| store.put(key, value))
251    }
252
253    fn delete(&self, key: &[u8]) -> StorageBackendResult<()> {
254        self.conn.with_records(|store| store.delete(key))
255    }
256
257    fn delete_prefix(&self, prefix: &[u8]) -> StorageBackendResult<usize> {
258        self.conn.with_records(|store| store.delete_prefix(prefix))
259    }
260
261    fn scan_prefix(&self, prefix: &[u8]) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>> {
262        self.conn.with_records(|store| store.scan_prefix(prefix))
263    }
264
265    fn scan_prefix_after(
266        &self,
267        prefix: &[u8],
268        after: Option<&[u8]>,
269        limit: usize,
270    ) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>> {
271        self.conn
272            .with_records(|store| store.scan_prefix_after(prefix, after, limit))
273    }
274
275    fn scan_prefix_keys_after(
276        &self,
277        prefix: &[u8],
278        after: Option<&[u8]>,
279        limit: usize,
280    ) -> StorageBackendResult<Vec<Vec<u8>>> {
281        self.conn
282            .with_records(|store| store.scan_prefix_keys_after(prefix, after, limit))
283    }
284
285    fn first_prefix_after(
286        &self,
287        prefix: &[u8],
288        after: Option<&[u8]>,
289    ) -> StorageBackendResult<Option<(Vec<u8>, Vec<u8>)>> {
290        self.conn
291            .with_records(|store| store.first_prefix_after(prefix, after))
292    }
293
294    fn batch(&self) -> Box<dyn KeyValueBatch + '_> {
295        Box::new(SQLiteKeyValueBatch {
296            connection: &self.conn,
297            batch: self.records.batch(),
298        })
299    }
300
301    fn begin_transaction(&self) -> StorageBackendResult<()> {
302        self.conn.begin_transaction().map_err(Into::into)
303    }
304
305    fn begin_read_transaction(&self) -> StorageBackendResult<()> {
306        self.conn.begin_record_read().map_err(Into::into)
307    }
308
309    fn begin_upgradeable_transaction(&self) -> StorageBackendResult<()> {
310        self.conn.begin_deferred_transaction().map_err(Into::into)
311    }
312
313    fn in_transaction(&self) -> bool {
314        self.conn.in_transaction()
315    }
316
317    fn transaction_has_written(&self) -> StorageBackendResult<bool> {
318        self.conn.transaction_has_written().map_err(Into::into)
319    }
320
321    fn change_version(&self) -> StorageBackendResult<Option<u64>> {
322        self.conn.data_version().map_err(Into::into)
323    }
324
325    fn change_version_monitor_is_nonblocking(&self) -> StorageBackendResult<bool> {
326        Ok(true)
327    }
328
329    fn pin_transaction_snapshot(&self) -> StorageBackendResult<()> {
330        self.conn.pin_transaction_snapshot().map_err(Into::into)
331    }
332
333    fn commit_transaction(&self) -> StorageBackendResult<()> {
334        self.conn.commit_transaction().map_err(Into::into)
335    }
336
337    fn rollback_transaction(&self) -> StorageBackendResult<()> {
338        self.conn.rollback_transaction().map_err(Into::into)
339    }
340
341    fn savepoint(&self, name: &str) -> StorageBackendResult<()> {
342        self.conn.savepoint(name).map_err(Into::into)
343    }
344
345    fn release_savepoint(&self, name: &str) -> StorageBackendResult<()> {
346        self.conn.release_savepoint(name).map_err(Into::into)
347    }
348
349    fn rollback_to_savepoint(&self, name: &str) -> StorageBackendResult<()> {
350        self.conn.rollback_to_savepoint(name).map_err(Into::into)
351    }
352}
353
354struct SQLiteKeyValueBatch<'a> {
355    connection: &'a ManagedConnection,
356    batch: Box<dyn KeyValueBatch + 'a>,
357}
358
359impl KeyValueBatch for SQLiteKeyValueBatch<'_> {
360    fn serializable_participant(&self) -> Option<uqa_storage::mvcc::SerializableTransactionId> {
361        self.batch.serializable_participant()
362    }
363    fn observe_serializable_write(
364        &mut self,
365        predicate: uqa_storage::mvcc::SerializablePredicate<'_>,
366    ) -> StorageBackendResult<()> {
367        self.batch.observe_serializable_write(predicate)
368    }
369    fn require_unchanged(&mut self, key: &[u8]) -> StorageBackendResult<()> {
370        self.batch.require_unchanged(key)
371    }
372    fn require_observed(
373        &mut self,
374        key: &[u8],
375        revision: &uqa_storage::key_value::KeyValueReadRevision,
376    ) -> StorageBackendResult<()> {
377        self.batch.require_observed(key, revision)
378    }
379    fn put_observed(
380        &mut self,
381        key: &[u8],
382        value: &[u8],
383        revision: &uqa_storage::key_value::KeyValueReadRevision,
384    ) -> StorageBackendResult<()> {
385        self.batch.put_observed(key, value, revision)
386    }
387    fn put_with_retained_source(
388        &mut self,
389        key: &[u8],
390        value: &[u8],
391        source: Arc<dyn uqa_storage::key_value::KeyValueRead + Send + Sync>,
392    ) -> StorageBackendResult<()> {
393        self.batch.put_with_retained_source(key, value, source)
394    }
395    fn touch_marker(&mut self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
396        self.batch.touch_marker(key, value)
397    }
398    fn invalidate_diskann_origin(&mut self, key: &[u8]) -> StorageBackendResult<()> {
399        self.batch.invalidate_diskann_origin(key)
400    }
401    fn observe_identifier(&mut self, namespace: &[u8], value: u64) -> StorageBackendResult<()> {
402        self.batch.observe_identifier(namespace, value)
403    }
404    fn inherit_identifiers(&mut self, from: &[u8], to: &[u8]) -> StorageBackendResult<()> {
405        self.batch.inherit_identifiers(from, to)
406    }
407    fn ivf_mutation(
408        &mut self,
409        metadata: &[u8],
410        mutation: uqa_storage::ivf_index::IVFMutation<'_>,
411    ) -> StorageBackendResult<()> {
412        self.batch.ivf_mutation(metadata, mutation)
413    }
414    fn preview_ivf_record(&mut self, key: &[u8], value: Option<&[u8]>) -> StorageBackendResult<()> {
415        self.batch.preview_ivf_record(key, value)
416    }
417    fn preview_ivf_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
418        self.batch.preview_ivf_prefix(prefix)
419    }
420    fn fence_ivf_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
421        self.batch.fence_ivf_prefix(prefix)
422    }
423    fn hnsw_mutation(
424        &mut self,
425        metadata: &[u8],
426        mutation: uqa_storage::hnsw_index::HNSWMutation<'_>,
427    ) -> StorageBackendResult<()> {
428        self.batch.hnsw_mutation(metadata, mutation)
429    }
430    fn preview_hnsw_record(
431        &mut self,
432        key: &[u8],
433        value: Option<&[u8]>,
434    ) -> StorageBackendResult<()> {
435        self.batch.preview_hnsw_record(key, value)
436    }
437    fn preview_hnsw_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
438        self.batch.preview_hnsw_prefix(prefix)
439    }
440    fn fence_hnsw_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
441        self.batch.fence_hnsw_prefix(prefix)
442    }
443    fn put(&mut self, key: &[u8], value: &[u8]) -> StorageBackendResult<()> {
444        self.batch.put(key, value)
445    }
446    fn replace_statistics_maintenance(
447        &mut self,
448        key: &[u8],
449        value: &[u8],
450    ) -> StorageBackendResult<()> {
451        self.batch.replace_statistics_maintenance(key, value)
452    }
453    fn delete(&mut self, key: &[u8]) -> StorageBackendResult<()> {
454        self.batch.delete(key)
455    }
456    fn delete_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
457        self.batch.delete_prefix(prefix)
458    }
459    fn replace_occurrence_record(
460        &mut self,
461        key: &[u8],
462        value: Option<&[u8]>,
463    ) -> StorageBackendResult<()> {
464        self.batch.replace_occurrence_record(key, value)
465    }
466    fn invalidate_occurrence_prefix(&mut self, prefix: &[u8]) -> StorageBackendResult<()> {
467        self.batch.invalidate_occurrence_prefix(prefix)
468    }
469    fn occurrence_document(&mut self, table: &str, document: u64) -> StorageBackendResult<()> {
470        self.batch.occurrence_document(table, document)
471    }
472    fn reset_occurrences(&mut self, table: &str) -> StorageBackendResult<()> {
473        self.batch.reset_occurrences(table)
474    }
475    fn fence_record(&mut self, key: &[u8]) -> StorageBackendResult<()> {
476        self.batch.fence_record(key)
477    }
478    fn graph_mutation(
479        &mut self,
480        mutation: uqa_storage::mvcc::GraphMutation<'_>,
481    ) -> StorageBackendResult<()> {
482        self.batch.graph_mutation(mutation)
483    }
484    fn preview_graph_invalidation(
485        &mut self,
486        key: &[u8],
487        value: Option<&[u8]>,
488    ) -> StorageBackendResult<()> {
489        self.batch.preview_graph_invalidation(key, value)
490    }
491    fn replace_graph_cache(
492        &mut self,
493        key: &[u8],
494        value: Option<&[u8]>,
495    ) -> StorageBackendResult<()> {
496        self.batch.replace_graph_cache(key, value)
497    }
498    fn commit(self: Box<Self>) -> StorageBackendResult<()> {
499        let Self { connection, batch } = *self;
500        connection.with_records(|_| batch.commit())
501    }
502}
503
504#[cfg(test)]
505#[path = "key_value/controlled/tests.rs"]
506mod controlled_tests;
507
508/// Shared `SQLite` `KeyValue` storage handle with catalog and backend factories.
509#[derive(Clone)]
510pub struct SQLiteKeyValueStorage {
511    store: Arc<SQLiteKeyValueStore>,
512}
513
514pub type SQLiteKeyValueCatalog = KeyValueCatalog;
515pub type SQLiteKeyValueStorageBackend = KeyValueStorageBackend;
516
517impl SQLiteKeyValueStorage {
518    pub fn open(path: &Path) -> SQLiteResult<Self> {
519        Self::open_with_options(path, VersionedSessionOptions::default())
520    }
521
522    pub fn open_with_options(path: &Path, options: VersionedSessionOptions) -> SQLiteResult<Self> {
523        Self::from_connection_with_options(ManagedConnection::open(path)?, options)
524    }
525
526    pub fn open_in_memory() -> SQLiteResult<Self> {
527        Ok(Self {
528            store: Arc::new(SQLiteKeyValueStore::open_in_memory()?),
529        })
530    }
531
532    pub fn from_connection(conn: ManagedConnection) -> SQLiteResult<Self> {
533        Self::from_connection_with_options(conn, VersionedSessionOptions::default())
534    }
535
536    pub fn from_connection_with_options(
537        conn: ManagedConnection,
538        options: VersionedSessionOptions,
539    ) -> SQLiteResult<Self> {
540        Ok(Self {
541            store: Arc::new(SQLiteKeyValueStore::with_options(conn, options)?),
542        })
543    }
544
545    pub fn store(&self) -> Arc<SQLiteKeyValueStore> {
546        Arc::clone(&self.store)
547    }
548
549    pub fn catalog(&self) -> SQLiteKeyValueCatalog {
550        let store: Arc<dyn KeyValueStore> = self.store.clone();
551        KeyValueCatalog::new(store)
552    }
553
554    pub fn backend(&self) -> SQLiteKeyValueStorageBackend {
555        let store: Arc<dyn KeyValueStore> = self.store.clone();
556        KeyValueStorageBackend::new(store)
557    }
558}
559
560impl PersistentStorageProvider for SQLiteKeyValueStorage {
561    fn auxiliary_encryption_key(&self) -> Option<uqa_storage::StorageEncryptionKey> {
562        self.store.conn.auxiliary_encryption_key()
563    }
564
565    fn open_session(&self) -> StorageBackendResult<PersistentStorageSession> {
566        self.open_session_with_cancellation(&uqa_core::CancellationToken::new())
567    }
568
569    fn open_session_with_cancellation(
570        &self,
571        cancellation: &uqa_core::CancellationToken,
572    ) -> StorageBackendResult<PersistentStorageSession> {
573        cancellation.check()?;
574        let store: Arc<dyn KeyValueStore> =
575            Arc::new(self.store.new_session_with_cancellation(cancellation));
576        let catalog: Arc<dyn CatalogFacade> = Arc::new(KeyValueCatalog::new(Arc::clone(&store)));
577        let backend: Arc<dyn PersistentStorageBackend> =
578            Arc::new(KeyValueStorageBackend::new(store));
579        Ok(PersistentStorageSession::new(catalog, backend))
580    }
581
582    fn storage_identity(
583        &self,
584    ) -> StorageBackendResult<Option<uqa_storage::PersistentStorageIdentity>> {
585        self.store.connection().storage_identity()
586    }
587}
588
589#[cfg(test)]
590mod tests {
591    use std::collections::BTreeMap;
592
593    use uqa_analysis::standard_analyzer;
594    use uqa_core::Value;
595    use uqa_storage::catalog::{ColumnStatsInput, TableSchema};
596    use uqa_storage::{
597        CatalogFacade, PersistentStorageBackend, VectorIndexOpenMode, VectorIndexSpec,
598    };
599
600    use super::*;
601
602    #[test]
603    fn sqlite_key_value_store_round_trips_and_reopens() {
604        let dir = tempfile::tempdir().unwrap();
605        let path = dir.path().join("keyvalue.sqlite3");
606        {
607            let store = SQLiteKeyValueStore::open(&path).unwrap();
608            store.put(b"apple/1", b"red").unwrap();
609            store.put(b"apple/2", b"green").unwrap();
610            store.put(b"banana/1", b"yellow").unwrap();
611            store.put(&[0x10, 0xff, 0x01], b"binary-prefix").unwrap();
612            store.put(&[0x11, 0x00], b"binary-neighbour").unwrap();
613            assert_eq!(store.get(b"apple/1").unwrap().as_deref(), Some(&b"red"[..]));
614            assert_eq!(store.scan_prefix(b"apple/").unwrap().len(), 2);
615            assert_eq!(
616                store
617                    .scan_prefix_keys_after(b"apple/", Some(b"apple/1"), 1)
618                    .unwrap(),
619                vec![b"apple/2".to_vec()]
620            );
621            assert_eq!(
622                store
623                    .scan_prefix_keys_after(b"apple/", Some(b"a"), 2)
624                    .unwrap(),
625                vec![b"apple/1".to_vec(), b"apple/2".to_vec()]
626            );
627            assert!(store
628                .scan_prefix_keys_after(b"apple/", Some(b"z"), 2)
629                .unwrap()
630                .is_empty());
631            assert_eq!(
632                store.first_prefix_after(b"apple/", Some(b"a")).unwrap(),
633                Some((b"apple/1".to_vec(), b"red".to_vec()))
634            );
635            assert!(store
636                .scan_prefix_keys_after(b"apple/", None, 0)
637                .unwrap()
638                .is_empty());
639            assert_eq!(store.scan_prefix(&[0x10, 0xff]).unwrap().len(), 1);
640            store.delete_prefix(&[0x10, 0xff]).unwrap();
641            assert_eq!(
642                store.get(&[0x11, 0x00]).unwrap().as_deref(),
643                Some(&b"binary-neighbour"[..])
644            );
645        }
646        {
647            let store = SQLiteKeyValueStore::open(&path).unwrap();
648            assert_eq!(
649                store.get(b"apple/2").unwrap().as_deref(),
650                Some(&b"green"[..])
651            );
652            store.delete_prefix(b"apple/").unwrap();
653            assert!(store.get(b"apple/1").unwrap().is_none());
654            assert_eq!(
655                store.get(b"banana/1").unwrap().as_deref(),
656                Some(&b"yellow"[..])
657            );
658        }
659    }
660
661    #[test]
662    fn sqlite_store_passes_the_reusable_backend_contract() {
663        let directory = tempfile::tempdir().unwrap();
664        let reader =
665            SQLiteKeyValueStore::open(&directory.path().join("conformance.sqlite3")).unwrap();
666        let writer = reader.new_session();
667        uqa_storage::key_value::conformance::verify_store(&reader).unwrap();
668        uqa_storage::key_value::conformance::verify_session_isolation(&reader, &writer).unwrap();
669    }
670
671    #[test]
672    fn sqlite_key_value_batch_is_atomic() {
673        let store = SQLiteKeyValueStore::open_in_memory().unwrap();
674        let mut batch = store.batch();
675        batch.put(b"k1", b"v1").unwrap();
676        batch.put(b"k2", b"v2").unwrap();
677        batch.commit().unwrap();
678        assert_eq!(store.get(b"k1").unwrap().as_deref(), Some(&b"v1"[..]));
679
680        store.begin_transaction().unwrap();
681        store.put(b"k3", b"v3").unwrap();
682        store.rollback_transaction().unwrap();
683        assert!(store.get(b"k3").unwrap().is_none());
684    }
685
686    #[test]
687    fn sqlite_key_value_storage_supports_existing_store_contracts() {
688        let storage = SQLiteKeyValueStorage::open_in_memory().unwrap();
689        let backend = storage.backend();
690
691        let mut docs = backend.document_store("articles");
692        docs.put(
693            1,
694            BTreeMap::from([("title".to_string(), Value::Str("rust search".into()))]),
695        )
696        .unwrap();
697        assert_eq!(
698            docs.get_field(1, "title").unwrap(),
699            Some(Value::Str("rust search".into()))
700        );
701
702        let mut index = backend.inverted_index("articles", standard_analyzer("english"));
703        index
704            .add_document(1, BTreeMap::from([("title".into(), "rust search".into())]))
705            .unwrap();
706        assert_eq!(index.doc_freq("title", "rust").unwrap(), 1);
707
708        let mut vectors = backend
709            .vector_index(
710                "articles",
711                "embedding",
712                2,
713                VectorIndexSpec::BruteForce,
714                VectorIndexOpenMode::Create,
715            )
716            .unwrap();
717        vectors.add(1, vec![1.0, 0.0]).unwrap();
718        vectors.add(2, vec![0.0, 1.0]).unwrap();
719        let hits = vectors.search_knn(&[1.0, 0.0], 1).unwrap();
720        assert_eq!(hits.entries()[0].doc_id, 1);
721    }
722
723    #[test]
724    fn sqlite_key_value_catalog_supports_existing_registry_contracts() {
725        let storage = SQLiteKeyValueStorage::open_in_memory().unwrap();
726        let catalog = storage.catalog();
727        catalog.set_metadata("schema_version", "keyvalue").unwrap();
728        catalog.save_schema("public").unwrap();
729        catalog
730            .save_table(&TableSchema {
731                relation: uqa_storage::RelationIdentity::new("public", "docs"),
732                security: uqa_storage::RelationSecurityRow::legacy("uqa"),
733                object_id: [1; 16],
734                storage_generation: [1; 16],
735                analyzer_json: "{}".into(),
736                fts_fields: vec!["title".into()],
737                vector_fields: Vec::new(),
738                columns_json: "[]".into(),
739                constraints_json: String::new(),
740            })
741            .unwrap();
742        catalog
743            .save_analyzer("ko", "{\"name\":\"standard\"}")
744            .unwrap();
745        catalog
746            .save_table_field_analyzer("docs", "title", "index", "ko")
747            .unwrap();
748        catalog
749            .save_foreign_server("fs", "memory", "{\"root\":\"/tmp\"}")
750            .unwrap();
751        catalog
752            .save_catalog_index(
753                &uqa_storage::RelationIdentity::new("public", "idx_docs_title"),
754                "gin",
755                "public.docs",
756                "[\"title\"]",
757                "{}",
758            )
759            .unwrap();
760        catalog
761            .save_column_stats(ColumnStatsInput::basic(
762                "docs",
763                "title",
764                4,
765                0,
766                Some("a"),
767                Some("z"),
768                10,
769            ))
770            .unwrap();
771
772        assert_eq!(
773            catalog.get_metadata("schema_version").unwrap().as_deref(),
774            Some("keyvalue")
775        );
776        assert_eq!(
777            catalog.load_tables().unwrap()[0].relation.qualified_name(),
778            "public.docs"
779        );
780        assert_eq!(catalog.load_analyzers().unwrap()[0].0, "ko");
781        assert_eq!(catalog.load_foreign_servers().unwrap()[0].0, "fs");
782        assert_eq!(
783            catalog.load_catalog_indexes().unwrap()[0]
784                .relation
785                .qualified_name(),
786            "public.idx_docs_title"
787        );
788        assert_eq!(
789            catalog.load_column_stats("docs").unwrap()[0].distinct_count,
790            4
791        );
792    }
793}