Skip to main content

uqa_storage_sqlite/document_store/
store.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Single-document reads, writes, patching, and scalar lookup.
8
9use super::{
10    blob_marker, decode_json_field_value, decode_legacy_document_body, delete_document_blob,
11    document_id_from_sqlite, encode_document_blobs, encode_stored_value, hydrate_document_blobs,
12    params, sqlite_doc_id, upsert_document_blob, BTreeMap, DocId, Document, DocumentMetadata,
13    ManagedConnection, OptionalExtension, SQLiteDocumentStore, SQLiteResult, StorageBackendResult,
14    StoredDocument, Value, DOCUMENT_BLOBS_TABLE,
15};
16
17impl SQLiteDocumentStore {
18    pub fn new(conn: ManagedConnection, table: impl Into<String>) -> Self {
19        Self {
20            conn,
21            table: table.into(),
22            retained: None,
23        }
24    }
25
26    #[expect(
27        clippy::redundant_closure_for_method_calls,
28        reason = "a method item cannot satisfy the borrowed reader's higher-ranked lifetimes"
29    )]
30    pub fn max_doc_id(&self) -> StorageBackendResult<DocId> {
31        if let Some(max) = self.read_native(|read| read.max_doc_id())? {
32            return Ok(max);
33        }
34        Ok(self.conn.with(|c| {
35            let id: Option<i64> = c
36                .prepare_cached("SELECT MAX(doc_id) FROM _documents WHERE table_name = ?1")?
37                .query_row(params![self.table], |r| r.get(0))?;
38            id.map_or(Ok(0), document_id_from_sqlite)
39        })?)
40    }
41
42    /// `unused` names the namespace in which no document ever had `doc_id`. The legacy tables replace the row either way.
43    pub(super) fn put_stored_inner(
44        &self,
45        doc_id: DocId,
46        document: &Document,
47        metadata: DocumentMetadata,
48        unused: Option<uqa_storage::document_store::identifiers::DocumentIdNamespace>,
49    ) -> SQLiteResult<()> {
50        if self
51            .write_native(|read, batch| read.put(batch, doc_id, document, metadata, unused))?
52            .is_some()
53        {
54            return Ok(());
55        }
56        let sqlite_doc_id = sqlite_doc_id(doc_id)?;
57        let document: Document = document
58            .iter()
59            .filter(|(_, value)| !matches!(value, uqa_core::Value::Null))
60            .map(|(key, value)| (key.clone(), value.clone()))
61            .collect();
62        let (document, blobs) = encode_document_blobs(document)?;
63        let body = serde_json::to_string(&document)?;
64        self.conn.with(|c| {
65            c.prepare_cached(&format!(
66                "DELETE FROM {DOCUMENT_BLOBS_TABLE}
67                 WHERE table_name = ?1 AND doc_id = ?2"
68            ))?
69            .execute(params![self.table, sqlite_doc_id])?;
70            c.prepare_cached(
71                "INSERT INTO _documents (table_name, doc_id, body, tuple_xmin)
72                 VALUES (?1, ?2, ?3, ?4)
73                 ON CONFLICT (table_name, doc_id)
74                 DO UPDATE SET body = excluded.body, tuple_xmin = excluded.tuple_xmin",
75            )?
76            .execute(params![
77                self.table,
78                sqlite_doc_id,
79                body,
80                metadata.tuple_xmin().map(i64::from),
81            ])?;
82            for (field, bytes) in blobs {
83                c.prepare_cached(&format!(
84                    "INSERT OR REPLACE INTO {DOCUMENT_BLOBS_TABLE}
85                     (table_name, doc_id, field_name, bytes)
86                     VALUES (?1, ?2, ?3, ?4)"
87                ))?
88                .execute(params![self.table, sqlite_doc_id, field, bytes])?;
89            }
90            Ok(())
91        })
92    }
93
94    pub(super) fn get_inner(&self, doc_id: DocId) -> SQLiteResult<Option<Document>> {
95        self.get_stored_inner(doc_id)
96            .map(|document| document.map(StoredDocument::into_fields))
97    }
98
99    pub(super) fn get_stored_inner(&self, doc_id: DocId) -> SQLiteResult<Option<StoredDocument>> {
100        if let Some(document) = self.read_native(|read| read.get_stored(doc_id))? {
101            return Ok(document);
102        }
103        let sqlite_doc_id = sqlite_doc_id(doc_id)?;
104        self.conn.with(|c| {
105            let stored: Option<(String, Option<i64>)> = c
106                .prepare_cached(
107                    "SELECT body, tuple_xmin FROM _documents
108                     WHERE table_name = ?1 AND doc_id = ?2",
109                )?
110                .query_row(params![self.table, sqlite_doc_id], |row| {
111                    Ok((row.get(0)?, row.get(1)?))
112                })
113                .optional()?;
114            let Some((body, tuple_xmin)) = stored else {
115                return Ok(None);
116            };
117            let mut document = decode_legacy_document_body(&body)?;
118            hydrate_document_blobs(c, &self.table, doc_id, &mut document)?;
119            let metadata = tuple_xmin.map_or_else(
120                || Ok(DocumentMetadata::default()),
121                |tuple_xmin| {
122                    u32::try_from(tuple_xmin)
123                        .map(DocumentMetadata::with_tuple_xmin)
124                        .map_err(|_| {
125                            super::SQLiteError::StorageBackend(format!(
126                                "document `{}` row {doc_id} has an out-of-range tuple xmin",
127                                self.table
128                            ))
129                        })
130                },
131            )?;
132            Ok(Some(StoredDocument::with_metadata(document, metadata)))
133        })
134    }
135
136    pub(super) fn get_field_inner(
137        &self,
138        doc_id: DocId,
139        field: &str,
140    ) -> SQLiteResult<Option<Value>> {
141        if let Some(value) = self.read_native(|read| read.get_field(doc_id, field))? {
142            return Ok(value);
143        }
144        let sqlite_doc_id = sqlite_doc_id(doc_id)?;
145        let path = sqlite_json_path(field);
146        self.conn.with(|c| {
147            let row: Option<(Option<String>, String)> = c
148                .prepare_cached(
149                    "SELECT json_type(body, ?3), json_quote(json_extract(body, ?3))
150                     FROM _documents
151                     WHERE table_name = ?1 AND doc_id = ?2",
152                )?
153                .query_row(params![self.table, sqlite_doc_id, path], |r| {
154                    Ok((r.get(0)?, r.get(1)?))
155                })
156                .optional()?;
157            let Some((json_type, json_text)) = row else {
158                return Ok(None);
159            };
160            decode_json_field_value(c, &self.table, doc_id, field, json_type, &json_text)
161        })
162    }
163
164    pub(super) fn find_doc_id_by_field_inner(
165        &self,
166        field: &str,
167        value: &Value,
168    ) -> SQLiteResult<Option<DocId>> {
169        if let Some(id) = self.read_native(|read| read.find(field, value))? {
170            return Ok(id);
171        }
172        let path = sqlite_json_path(field);
173        match value {
174            Value::Str(value) => self
175                .conn
176                .with(|c| find_doc_id_by_scalar(c, &self.table, &path, value)),
177            Value::Int(value) => self
178                .conn
179                .with(|c| find_doc_id_by_scalar(c, &self.table, &path, value)),
180            Value::Float(value) if value.is_finite() => self
181                .conn
182                .with(|c| find_doc_id_by_scalar(c, &self.table, &path, value)),
183            Value::Bool(value) => self.conn.with(|c| {
184                let json_type = if *value { "true" } else { "false" };
185                let doc_id: Option<i64> = c
186                    .query_row(
187                        "SELECT doc_id FROM _documents
188                         WHERE table_name = ?1 AND json_type(body, ?2) = ?3
189                         ORDER BY doc_id LIMIT 1",
190                        params![self.table, path, json_type],
191                        |r| r.get(0),
192                    )
193                    .optional()?;
194                doc_id.map(document_id_from_sqlite).transpose()
195            }),
196            _ => {
197                let doc_ids = self.conn.with(|c| {
198                    let mut stmt = c.prepare_cached(
199                        "SELECT doc_id FROM _documents
200                         WHERE table_name = ?1 ORDER BY doc_id",
201                    )?;
202                    let rows = stmt.query_map(params![self.table], |row| row.get::<_, i64>(0))?;
203                    let mut out = Vec::new();
204                    for row in rows {
205                        out.push(document_id_from_sqlite(row?)?);
206                    }
207                    Ok(out)
208                })?;
209                for doc_id in doc_ids {
210                    if self.get_field_inner(doc_id, field)?.as_ref() == Some(value) {
211                        return Ok(Some(doc_id));
212                    }
213                }
214                Ok(None)
215            }
216        }
217    }
218
219    pub(super) fn patch_fields_inner(
220        &self,
221        doc_id: DocId,
222        updates: &BTreeMap<String, Value>,
223    ) -> SQLiteResult<bool> {
224        if let Some(found) = self.write_native(|read, batch| read.patch(batch, doc_id, updates))? {
225            return Ok(found);
226        }
227        if updates.is_empty() {
228            return Ok(true);
229        }
230        let sqlite_doc_id = sqlite_doc_id(doc_id)?;
231        self.conn.with(|c| {
232            let exists: Option<i64> = c
233                .prepare_cached(
234                    "SELECT 1 FROM _documents
235                     WHERE table_name = ?1 AND doc_id = ?2
236                     LIMIT 1",
237                )?
238                .query_row(params![self.table, sqlite_doc_id], |r| r.get(0))
239                .optional()?;
240            if exists.is_none() {
241                return Ok(false);
242            }
243
244            for (field, value) in updates {
245                let path = sqlite_json_path(field);
246                match value {
247                    Value::Null => {
248                        delete_document_blob(c, &self.table, doc_id, field)?;
249                        c.execute(
250                            "UPDATE _documents SET body = json_remove(body, ?3)
251                             WHERE table_name = ?1 AND doc_id = ?2",
252                            params![self.table, sqlite_doc_id, path],
253                        )?;
254                    }
255                    Value::Bytes(bytes) => {
256                        let marker = serde_json::to_string(&blob_marker(field.clone()))?;
257                        c.execute(
258                            "UPDATE _documents SET body = json_set(body, ?3, json(?4))
259                             WHERE table_name = ?1 AND doc_id = ?2",
260                            params![self.table, sqlite_doc_id, path, marker],
261                        )?;
262                        upsert_document_blob(c, &self.table, doc_id, field, bytes)?;
263                    }
264                    other => {
265                        let (stored, blob) = encode_stored_value(field, other.clone())?;
266                        let json = serde_json::to_string(&stored)?;
267                        c.execute(
268                            "UPDATE _documents SET body = json_set(body, ?3, json(?4))
269                             WHERE table_name = ?1 AND doc_id = ?2",
270                            params![self.table, sqlite_doc_id, path, json],
271                        )?;
272                        if let Some(bytes) = blob {
273                            upsert_document_blob(c, &self.table, doc_id, field, &bytes)?;
274                        } else {
275                            delete_document_blob(c, &self.table, doc_id, field)?;
276                        }
277                    }
278                }
279            }
280            Ok(true)
281        })
282    }
283}
284
285fn sqlite_json_path(field: &str) -> String {
286    if field.chars().all(|c| c == '_' || c.is_ascii_alphanumeric())
287        && field
288            .chars()
289            .next()
290            .is_some_and(|c| c == '_' || c.is_ascii_alphabetic())
291    {
292        format!("$.{field}")
293    } else {
294        format!("$.{}", serde_json::Value::String(field.to_string()))
295    }
296}
297
298fn find_doc_id_by_scalar<T: rusqlite::ToSql>(
299    conn: &rusqlite::Connection,
300    table: &str,
301    path: &str,
302    value: &T,
303) -> SQLiteResult<Option<DocId>> {
304    let doc_id: Option<i64> = conn
305        .query_row(
306            "SELECT doc_id FROM _documents
307             WHERE table_name = ?1 AND json_extract(body, ?2) = ?3
308             ORDER BY doc_id LIMIT 1",
309            (table, path, value),
310            |r| r.get(0),
311        )
312        .optional()?;
313    doc_id.map(document_id_from_sqlite).transpose()
314}