Skip to main content

uqa_storage_sqlite/document_store/
trait_impl.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Complete `DocumentStore` query, mutation, iteration, and snapshot contract.
8
9use super::{
10    allocation_error, blob_marker_info, chunk_bind_values, decode_legacy_document_body,
11    doc_id_in_placeholders, document_id_from_sqlite, hydrate_document_blobs,
12    load_marked_document_blob, params, read_doc_id, should_probe_doc_ids, sorted_unique_doc_ids,
13    sqlite_doc_id, take_requested_field, Arc, BTreeMap, DocId, Document, DocumentMetadata,
14    DocumentStore, OptionalExtension, SQLiteDocumentStore, SQLiteError, SQLiteResult,
15    StorageBackendResult, StoredDocument, Value, DOCUMENT_BLOBS_TABLE, DOC_ID_IN_CHUNK,
16};
17
18impl DocumentStore for SQLiteDocumentStore {
19    fn put(&mut self, doc_id: DocId, document: Document) -> StorageBackendResult<()> {
20        if self
21            .write_native(|read, batch| {
22                read.put(
23                    batch,
24                    doc_id,
25                    &document,
26                    read.metadata(doc_id)?.unwrap_or_default(),
27                    None,
28                )
29            })?
30            .is_some()
31        {
32            return Ok(());
33        }
34        let metadata = self.get_metadata(doc_id)?.unwrap_or_default();
35        self.put_stored_inner(doc_id, &document, metadata, None)?;
36        Ok(())
37    }
38
39    fn get(&self, doc_id: DocId) -> StorageBackendResult<Option<Document>> {
40        Ok(self.get_inner(doc_id)?)
41    }
42
43    fn put_stored(&mut self, doc_id: DocId, document: StoredDocument) -> StorageBackendResult<()> {
44        let (fields, metadata) = document.into_parts();
45        self.put_stored_inner(doc_id, &fields, metadata, None)?;
46        Ok(())
47    }
48
49    fn put_stored_unused(
50        &mut self,
51        doc_id: DocId,
52        document: StoredDocument,
53        namespace: uqa_storage::document_store::identifiers::DocumentIdNamespace,
54    ) -> StorageBackendResult<()> {
55        let (fields, metadata) = document.into_parts();
56        self.put_stored_inner(doc_id, &fields, metadata, Some(namespace))?;
57        Ok(())
58    }
59
60    fn get_stored(&self, doc_id: DocId) -> StorageBackendResult<Option<StoredDocument>> {
61        Ok(self.get_stored_inner(doc_id)?)
62    }
63
64    fn get_stored_many_controlled(
65        &self,
66        ids: &[DocId],
67        control: &uqa_storage::read_control::StorageReadControl,
68    ) -> StorageBackendResult<uqa_storage::RetainedDocumentPage> {
69        Ok(self.read_rows_controlled(ids, control)?)
70    }
71
72    fn get_stored_many(
73        &self,
74        doc_ids: &[DocId],
75    ) -> StorageBackendResult<BTreeMap<DocId, StoredDocument>> {
76        if let Some(documents) = self.read_native(|read| read.stored_many(doc_ids))? {
77            return Ok(documents);
78        }
79        let mut out = BTreeMap::new();
80        if doc_ids.is_empty() {
81            return Ok(out);
82        }
83
84        let decode_row = |connection: &rusqlite::Connection,
85                          row: &rusqlite::Row<'_>|
86         -> SQLiteResult<(DocId, StoredDocument)> {
87            let doc_id = read_doc_id(row, 0)?;
88            let body = row.get::<_, String>(1)?;
89            let tuple_xmin = row.get::<_, Option<i64>>(2)?;
90            let mut fields = decode_legacy_document_body(&body)?;
91            hydrate_document_blobs(connection, &self.table, doc_id, &mut fields)?;
92            let metadata = tuple_xmin.map_or_else(
93                || Ok(DocumentMetadata::default()),
94                |tuple_xmin| {
95                    u32::try_from(tuple_xmin)
96                        .map(DocumentMetadata::with_tuple_xmin)
97                        .map_err(|_| {
98                            SQLiteError::StorageBackend(format!(
99                                "document `{}` row {doc_id} has an out-of-range tuple xmin",
100                                self.table
101                            ))
102                        })
103                },
104            )?;
105            Ok((doc_id, StoredDocument::with_metadata(fields, metadata)))
106        };
107
108        let should_probe =
109            doc_ids.len() <= DOC_ID_IN_CHUNK || should_probe_doc_ids(doc_ids.len(), self.len()?);
110        if should_probe {
111            let leading = [rusqlite::types::Value::Text(self.table.clone())];
112            let sql = format!(
113                "SELECT doc_id, body, tuple_xmin FROM _documents
114                 WHERE table_name = ?1 AND doc_id IN ({})",
115                doc_id_in_placeholders(2, DOC_ID_IN_CHUNK)?
116            );
117            self.conn.with(|connection| {
118                for chunk in doc_ids.chunks(DOC_ID_IN_CHUNK) {
119                    let mut statement = connection.prepare_cached(&sql)?;
120                    let bind = chunk_bind_values(&leading, chunk)?;
121                    let mut rows = statement.query(rusqlite::params_from_iter(bind))?;
122                    while let Some(row) = rows.next()? {
123                        let (doc_id, document) = decode_row(connection, row)?;
124                        out.insert(doc_id, document);
125                    }
126                }
127                Ok(())
128            })?;
129            return Ok(out);
130        }
131
132        let requested = sorted_unique_doc_ids(doc_ids)?;
133        self.conn.with(|connection| {
134            let mut statement = connection.prepare_cached(
135                "SELECT doc_id, body, tuple_xmin FROM _documents
136                 WHERE table_name = ?1
137                 ORDER BY doc_id",
138            )?;
139            let mut rows = statement.query(params![self.table])?;
140            while let Some(row) = rows.next()? {
141                let doc_id = read_doc_id(row, 0)?;
142                if requested.binary_search(&doc_id).is_err() {
143                    continue;
144                }
145                let (doc_id, document) = decode_row(connection, row)?;
146                out.insert(doc_id, document);
147            }
148            Ok(())
149        })?;
150        Ok(out)
151    }
152
153    fn get_metadata(&self, doc_id: DocId) -> StorageBackendResult<Option<DocumentMetadata>> {
154        if let Some(metadata) = self.read_native(|read| read.metadata(doc_id))? {
155            return Ok(metadata);
156        }
157        let sqlite_doc_id = sqlite_doc_id(doc_id)?;
158        let tuple_xmin = self.conn.with(|connection| {
159            Ok(connection
160                .prepare_cached(
161                    "SELECT tuple_xmin FROM _documents
162                     WHERE table_name = ?1 AND doc_id = ?2",
163                )?
164                .query_row(params![self.table, sqlite_doc_id], |row| {
165                    row.get::<_, Option<i64>>(0)
166                })
167                .optional()?)
168        })?;
169        tuple_xmin
170            .map(|tuple_xmin| {
171                tuple_xmin.map_or_else(
172                    || Ok(DocumentMetadata::default()),
173                    |tuple_xmin| {
174                        u32::try_from(tuple_xmin)
175                            .map(DocumentMetadata::with_tuple_xmin)
176                            .map_err(|_| {
177                                SQLiteError::StorageBackend(format!(
178                                    "document `{}` row {doc_id} has an out-of-range tuple xmin",
179                                    self.table
180                                ))
181                                .into()
182                            })
183                    },
184                )
185            })
186            .transpose()
187    }
188
189    fn contains_doc_id(&self, doc_id: DocId) -> StorageBackendResult<bool> {
190        if let Some(found) = self.read_native(|read| read.contains(doc_id))? {
191            return Ok(found);
192        }
193        let sqlite_doc_id = sqlite_doc_id(doc_id)?;
194        Ok(self.conn.with(|c| {
195            let found: Option<i64> = c
196                .prepare_cached(
197                    "SELECT 1 FROM _documents
198                         WHERE table_name = ?1 AND doc_id = ?2
199                         LIMIT 1",
200                )?
201                .query_row(params![self.table, sqlite_doc_id], |r| r.get(0))
202                .optional()?;
203            Ok(found.is_some())
204        })?)
205    }
206
207    fn get_field(
208        &self,
209        doc_id: DocId,
210        field: &str,
211    ) -> StorageBackendResult<Option<uqa_core::Value>> {
212        Ok(self.get_field_inner(doc_id, field)?)
213    }
214
215    fn find_doc_id_by_field(
216        &self,
217        field: &str,
218        value: &Value,
219    ) -> StorageBackendResult<Option<DocId>> {
220        Ok(self.find_doc_id_by_field_inner(field, value)?)
221    }
222
223    fn has_value(&self, field: &str, value: &Value) -> StorageBackendResult<bool> {
224        if let Some(found) = self.read_native(|read| read.find(field, value))? {
225            return Ok(found.is_some());
226        }
227        for id in self.doc_ids()? {
228            if self.get_field(id, field)?.as_ref() == Some(value) {
229                return Ok(true);
230            }
231        }
232        Ok(false)
233    }
234
235    fn find_doc_id_by_fields(
236        &self,
237        fields: &[String],
238        values: &[Value],
239    ) -> StorageBackendResult<Option<DocId>> {
240        if let Some(found) = self.read_native(|read| read.find_fields(fields, values))? {
241            return Ok(found);
242        }
243        if fields.is_empty() || fields.len() != values.len() {
244            return Ok(None);
245        }
246        for id in self.doc_ids()? {
247            let mut matches = true;
248            for (field, value) in fields.iter().zip(values) {
249                if self.get_field(id, field)?.unwrap_or(Value::Null) != *value {
250                    matches = false;
251                    break;
252                }
253            }
254            if matches {
255                return Ok(Some(id));
256            }
257        }
258        Ok(None)
259    }
260
261    fn for_each_fields_multi_ref(
262        &self,
263        doc_ids: &[DocId],
264        fields: &[&str],
265        visitor: &mut dyn FnMut(DocId, &[&Value]) -> bool,
266    ) -> StorageBackendResult<()> {
267        self.for_each_fields_multi_ref_with_presence(doc_ids, fields, &mut |id, _, values| {
268            visitor(id, values)
269        })
270    }
271
272    fn for_each_fields_multi(
273        &self,
274        doc_ids: &[DocId],
275        fields: &[&str],
276        visitor: &mut dyn FnMut(DocId, Vec<Value>) -> bool,
277    ) -> StorageBackendResult<()> {
278        self.for_each_fields_multi_ref_with_presence(doc_ids, fields, &mut |id, _, values| {
279            visitor(id, values.iter().map(|value| (*value).clone()).collect())
280        })
281    }
282
283    fn for_each_fields_multi_ref_with_presence(
284        &self,
285        doc_ids: &[DocId],
286        fields: &[&str],
287        visitor: &mut dyn FnMut(DocId, bool, &[&Value]) -> bool,
288    ) -> StorageBackendResult<()> {
289        if self
290            .read_native(|read| read.visit_projection(doc_ids, fields, visitor))?
291            .is_some()
292        {
293            return Ok(());
294        }
295        let snapshot = self.snapshot()?;
296        if fields.is_empty() {
297            for &id in doc_ids {
298                if !visitor(id, snapshot.contains_doc_id(id)?, &[]) {
299                    break;
300                }
301            }
302        } else {
303            let projected = snapshot.get_fields_multi(doc_ids, fields)?;
304            let missing = vec![&Value::Null; fields.len()];
305            for &id in doc_ids {
306                let keep_going = match projected.get(&id) {
307                    Some(values) => visitor(id, true, &values.iter().collect::<Vec<_>>()),
308                    None => visitor(id, false, &missing),
309                };
310                if !keep_going {
311                    break;
312                }
313            }
314        }
315        Ok(())
316    }
317
318    fn field_presence_controlled(
319        &self,
320        ids: &[DocId],
321        fields: &[&str],
322        control: &uqa_storage::read_control::StorageReadControl,
323    ) -> StorageBackendResult<uqa_core::memory::BudgetedVec<bool>> {
324        control.check()?;
325        let mut present = uqa_core::memory::BudgetedVec::new(control.memory());
326        if fields.is_empty() {
327            return Ok(present);
328        }
329        // Existence depends on body keys, so metadata reads never hydrate value BLOBs.
330        let rows = self.read_projected_rows_controlled(ids, Some(&[]), control)?;
331        for row in rows.iter() {
332            for field in fields {
333                control.check()?;
334                present.push(
335                    row.as_ref()
336                        .is_some_and(|row| row.fields().contains_key(*field)),
337                )?;
338            }
339        }
340        control.check()?;
341        Ok(present)
342    }
343
344    fn iter_all(&self) -> StorageBackendResult<Box<dyn Iterator<Item = (DocId, Document)> + '_>> {
345        let snapshot = self.snapshot()?;
346        let mut rows = Vec::new();
347        for id in snapshot.doc_ids()? {
348            if let Some(document) = snapshot.get(id)? {
349                rows.push((id, document));
350            }
351        }
352        Ok(Box::new(rows.into_iter()))
353    }
354
355    fn get_fields_bulk(
356        &self,
357        doc_ids: &[DocId],
358        field: &str,
359    ) -> StorageBackendResult<BTreeMap<DocId, Value>> {
360        if let Some(values) = self.read_native(|read| read.fields_bulk(doc_ids, field))? {
361            return Ok(values);
362        }
363        let mut out: BTreeMap<DocId, Value> = doc_ids
364            .iter()
365            .copied()
366            .map(|doc_id| (doc_id, Value::Null))
367            .collect();
368        if doc_ids.is_empty() {
369            return Ok(out);
370        }
371        // Fetch the document body and extract the field in Rust: one
372        // JSON parse per row. Extracting through `json_type` +
373        // `json_extract` made `SQLite` parse the same body twice per
374        // requested field.
375        let mut decode_row = |c: &rusqlite::Connection,
376                              row: &rusqlite::Row<'_>|
377         -> SQLiteResult<()> {
378            let doc_id = read_doc_id(row, 0)?;
379            let body = row.get::<_, String>(1)?;
380            let mut document = decode_legacy_document_body(&body)?;
381            if let Some(value) = take_requested_field(c, &self.table, doc_id, &mut document, field)?
382            {
383                out.insert(doc_id, value);
384            }
385            Ok(())
386        };
387
388        // Selective requests probe by id; wide requests (half the
389        // table or more) sequential-scan once instead of issuing many
390        // B-tree probes.
391        let should_probe =
392            doc_ids.len() <= DOC_ID_IN_CHUNK || should_probe_doc_ids(doc_ids.len(), self.len()?);
393        if should_probe {
394            let leading = [rusqlite::types::Value::Text(self.table.clone())];
395            let sql = format!(
396                "SELECT doc_id, body FROM _documents
397                 WHERE table_name = ?1 AND doc_id IN ({})",
398                doc_id_in_placeholders(2, DOC_ID_IN_CHUNK)?
399            );
400            self.conn.with(|c| {
401                for chunk in doc_ids.chunks(DOC_ID_IN_CHUNK) {
402                    let mut stmt = c.prepare_cached(&sql)?;
403                    let bind = chunk_bind_values(&leading, chunk)?;
404                    let mut rows = stmt.query(rusqlite::params_from_iter(bind))?;
405                    while let Some(row) = rows.next()? {
406                        decode_row(c, row)?;
407                    }
408                }
409                Ok(())
410            })?;
411            return Ok(out);
412        }
413
414        let requested = sorted_unique_doc_ids(doc_ids)?;
415        self.conn.with(|c| {
416            let mut stmt = c.prepare_cached(
417                "SELECT doc_id, body FROM _documents
418                 WHERE table_name = ?1
419                 ORDER BY doc_id",
420            )?;
421            let mut rows = stmt.query(params![self.table])?;
422            while let Some(row) = rows.next()? {
423                let doc_id = read_doc_id(row, 0)?;
424                if requested.binary_search(&doc_id).is_err() {
425                    continue;
426                }
427                decode_row(c, row)?;
428            }
429            Ok(())
430        })?;
431        Ok(out)
432    }
433
434    fn get_fields_multi(
435        &self,
436        doc_ids: &[DocId],
437        fields: &[&str],
438    ) -> StorageBackendResult<BTreeMap<DocId, Vec<Value>>> {
439        if let Some(values) = self.read_native(|read| read.fields_multi(doc_ids, fields))? {
440            return Ok(values);
441        }
442        let mut out: BTreeMap<DocId, Vec<Value>> = BTreeMap::new();
443        if doc_ids.is_empty() || fields.is_empty() {
444            return Ok(out);
445        }
446        // Fetch the document body and extract every requested field in
447        // Rust: one JSON parse per row, however many fields the caller
448        // asked for. The previous `json_type` + `json_extract` pair per
449        // field made `SQLite` parse the same body twice per field.
450        let decode_row = |c: &rusqlite::Connection,
451                          row: &rusqlite::Row<'_>|
452         -> SQLiteResult<(DocId, Vec<Value>)> {
453            let doc_id = read_doc_id(row, 0)?;
454            let body = row.get::<_, String>(1)?;
455            let document = decode_legacy_document_body(&body)?;
456            let mut values = Vec::new();
457            values
458                .try_reserve_exact(fields.len())
459                .map_err(|error| allocation_error("multi-field document values", error))?;
460            for field in fields {
461                let mut value = document.get(*field).cloned().unwrap_or(Value::Null);
462                if let Some(marker) = blob_marker_info(&value) {
463                    if let Some(decoded) =
464                        load_marked_document_blob(c, &self.table, doc_id, field, &marker)?
465                    {
466                        value = decoded;
467                    }
468                }
469                values.push(value);
470            }
471            Ok((doc_id, values))
472        };
473
474        let should_probe =
475            doc_ids.len() <= DOC_ID_IN_CHUNK || should_probe_doc_ids(doc_ids.len(), self.len()?);
476        if should_probe {
477            let leading = [rusqlite::types::Value::Text(self.table.clone())];
478            let sql = format!(
479                "SELECT doc_id, body FROM _documents
480                 WHERE table_name = ?1 AND doc_id IN ({})",
481                doc_id_in_placeholders(2, DOC_ID_IN_CHUNK)?
482            );
483            self.conn.with(|c| {
484                for chunk in doc_ids.chunks(DOC_ID_IN_CHUNK) {
485                    let mut stmt = c.prepare_cached(&sql)?;
486                    let bind = chunk_bind_values(&leading, chunk)?;
487                    let mut rows = stmt.query(rusqlite::params_from_iter(bind))?;
488                    while let Some(row) = rows.next()? {
489                        let (doc_id, values) = decode_row(c, row)?;
490                        out.insert(doc_id, values);
491                    }
492                }
493                Ok(())
494            })?;
495            return Ok(out);
496        }
497
498        let requested = sorted_unique_doc_ids(doc_ids)?;
499        self.conn.with(|c| {
500            let mut stmt = c.prepare_cached(
501                "SELECT doc_id, body FROM _documents
502                 WHERE table_name = ?1
503                 ORDER BY doc_id",
504            )?;
505            let mut rows = stmt.query(params![self.table])?;
506            while let Some(row) = rows.next()? {
507                let doc_id = read_doc_id(row, 0)?;
508                if requested.binary_search(&doc_id).is_err() {
509                    continue;
510                }
511                let (doc_id, values) = decode_row(c, row)?;
512                out.insert(doc_id, values);
513            }
514            Ok(())
515        })?;
516        Ok(out)
517    }
518
519    fn get_many(&self, doc_ids: &[DocId]) -> StorageBackendResult<BTreeMap<DocId, Document>> {
520        self.get_stored_many(doc_ids).map(|documents| {
521            documents
522                .into_iter()
523                .map(|(doc_id, document)| (doc_id, document.into_fields()))
524                .collect()
525        })
526    }
527
528    fn patch_fields(
529        &mut self,
530        doc_id: DocId,
531        updates: &BTreeMap<String, Value>,
532    ) -> StorageBackendResult<bool> {
533        Ok(self.patch_fields_inner(doc_id, updates)?)
534    }
535
536    fn delete(&mut self, doc_id: DocId) -> StorageBackendResult<()> {
537        if self
538            .write_native(|read, batch| read.delete(batch, doc_id))?
539            .is_some()
540        {
541            return Ok(());
542        }
543        let sqlite_doc_id = sqlite_doc_id(doc_id)?;
544        self.conn.with(|c| {
545            c.prepare_cached(&format!(
546                "DELETE FROM {DOCUMENT_BLOBS_TABLE}
547                 WHERE table_name = ?1 AND doc_id = ?2"
548            ))?
549            .execute(params![self.table, sqlite_doc_id])?;
550            c.prepare_cached("DELETE FROM _documents WHERE table_name = ?1 AND doc_id = ?2")?
551                .execute(params![self.table, sqlite_doc_id])?;
552            Ok(())
553        })?;
554        Ok(())
555    }
556
557    fn clear(&mut self) -> StorageBackendResult<()> {
558        if self
559            .write_native(|read, batch| read.clear(batch))?
560            .is_some()
561        {
562            return Ok(());
563        }
564        self.conn.with(|c| {
565            c.execute(
566                &format!("DELETE FROM {DOCUMENT_BLOBS_TABLE} WHERE table_name = ?1"),
567                params![self.table],
568            )?;
569            c.execute(
570                "DELETE FROM _documents WHERE table_name = ?1",
571                params![self.table],
572            )?;
573            Ok(())
574        })?;
575        Ok(())
576    }
577
578    fn doc_ids(&self) -> StorageBackendResult<Vec<DocId>> {
579        if let Some(ids) = self.read_native(|read| read.ids(None, usize::MAX))? {
580            return Ok(ids);
581        }
582        Ok(self.conn.with(|c| {
583            let mut stmt = c.prepare_cached(
584                "SELECT doc_id FROM _documents WHERE table_name = ?1 ORDER BY doc_id",
585            )?;
586            let rows = stmt.query_map(params![self.table], |r| r.get::<_, i64>(0))?;
587            let mut out = Vec::new();
588            for row in rows {
589                out.push(document_id_from_sqlite(row?)?);
590            }
591            Ok(out)
592        })?)
593    }
594
595    fn next_doc_id(&self, after: Option<DocId>) -> StorageBackendResult<Option<DocId>> {
596        if let Some(ids) = self.read_native(|read| read.ids(after, 1))? {
597            return Ok(ids.first().copied());
598        }
599        let after = after.map(sqlite_doc_id).transpose()?;
600        Ok(self.conn.with(|connection| {
601            let doc_id: Option<i64> = match after {
602                Some(after) => connection
603                    .prepare_cached(
604                        "SELECT doc_id FROM _documents
605                         WHERE table_name = ?1 AND doc_id > ?2
606                         ORDER BY doc_id LIMIT 1",
607                    )?
608                    .query_row(params![self.table, after], |row| row.get::<_, i64>(0))
609                    .optional()?,
610                None => connection
611                    .prepare_cached(
612                        "SELECT doc_id FROM _documents
613                         WHERE table_name = ?1
614                         ORDER BY doc_id LIMIT 1",
615                    )?
616                    .query_row(params![self.table], |row| row.get::<_, i64>(0))
617                    .optional()?,
618            };
619            doc_id.map(document_id_from_sqlite).transpose()
620        })?)
621    }
622
623    fn next_doc_ids(&self, after: Option<DocId>, limit: usize) -> StorageBackendResult<Vec<DocId>> {
624        if let Some(ids) = self.read_native(|read| read.ids(after, limit))? {
625            return Ok(ids);
626        }
627        if limit == 0 {
628            return Ok(Vec::new());
629        }
630        let after = after.map(sqlite_doc_id).transpose()?;
631        let limit = i64::try_from(limit).map_err(|_| {
632            SQLiteError::StorageBackend(format!(
633                "document cursor limit {limit} is outside SQLite's integer range"
634            ))
635        })?;
636        Ok(self.conn.with(|connection| {
637            let mut out = Vec::new();
638            if let Some(after) = after {
639                let mut stmt = connection.prepare_cached(
640                    "SELECT doc_id FROM _documents
641                     WHERE table_name = ?1 AND doc_id > ?2
642                     ORDER BY doc_id LIMIT ?3",
643                )?;
644                let rows = stmt.query_map(params![self.table, after, limit], |row| {
645                    row.get::<_, i64>(0)
646                })?;
647                for row in rows {
648                    out.push(document_id_from_sqlite(row?)?);
649                }
650            } else {
651                let mut stmt = connection.prepare_cached(
652                    "SELECT doc_id FROM _documents
653                     WHERE table_name = ?1
654                     ORDER BY doc_id LIMIT ?2",
655                )?;
656                let rows =
657                    stmt.query_map(params![self.table, limit], |row| row.get::<_, i64>(0))?;
658                for row in rows {
659                    out.push(document_id_from_sqlite(row?)?);
660                }
661            }
662            Ok(out)
663        })?)
664    }
665
666    fn next_doc_ids_controlled(
667        &self,
668        after: Option<DocId>,
669        limit: usize,
670        control: &uqa_storage::read_control::StorageReadControl,
671    ) -> StorageBackendResult<uqa_core::memory::BudgetedVec<DocId>> {
672        Ok(self.read_ids_controlled(after, limit, control)?)
673    }
674
675    fn max_doc_id(&self) -> StorageBackendResult<DocId> {
676        SQLiteDocumentStore::max_doc_id(self)
677    }
678
679    fn for_each_next_fields(
680        &self,
681        after: Option<DocId>,
682        limit: usize,
683        fields: &[&str],
684        visitor: &mut dyn FnMut(DocId, &[&Value]) -> bool,
685    ) -> StorageBackendResult<Option<usize>> {
686        if !fields.is_empty() {
687            return Ok(None);
688        }
689        Ok(self.read_native(|read| read.visit_next_ids(after, limit, visitor))?)
690    }
691
692    fn for_each_next_fields_borrowed(
693        &self,
694        after: Option<DocId>,
695        limit: usize,
696        fields: &[&str],
697        visitor: &mut dyn FnMut(DocId, &[&Value]) -> bool,
698    ) -> StorageBackendResult<Option<usize>> {
699        Ok(self.read_native(|read| read.visit_borrowed_fields(after, limit, fields, visitor))?)
700    }
701
702    fn for_each_fields_multi_borrowed(
703        &self,
704        ids: &[DocId],
705        fields: &[&str],
706        visitor: &mut dyn FnMut(DocId, bool, &[&Value]) -> bool,
707    ) -> StorageBackendResult<Option<usize>> {
708        if fields.is_empty() {
709            return Ok(None);
710        }
711        Ok(self.read_native(|read| read.visit_borrowed_points(ids, fields, visitor))?)
712    }
713
714    #[expect(
715        clippy::redundant_closure_for_method_calls,
716        reason = "a method item cannot satisfy the borrowed reader's higher-ranked lifetimes"
717    )]
718    fn len(&self) -> StorageBackendResult<usize> {
719        if let Some(count) = self.read_native(|read| read.len())? {
720            return Ok(count);
721        }
722        Ok(self.conn.with(|c| {
723            let n: i64 = c
724                .prepare_cached("SELECT COUNT(*) FROM _documents WHERE table_name = ?1")?
725                .query_row(params![self.table], |r| r.get(0))?;
726            usize::try_from(n).map_err(|_| {
727                SQLiteError::StorageBackend(format!(
728                    "document count {n} is outside the addressable range"
729                ))
730            })
731        })?)
732    }
733
734    fn snapshot(&self) -> StorageBackendResult<Arc<dyn DocumentStore>> {
735        let mut snapshot = self.clone();
736        if snapshot.retained.is_none() {
737            snapshot.retained = self.conn.native_snapshot()?;
738        }
739        Ok(Arc::new(snapshot))
740    }
741}