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