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