oxilite_core/
schema.rs

1//! Database schema.
2//!
3// @lat: [[architecture#Storage schema]]
4
5use crate::encoding::{Tag, INT_OFFSET, PAYLOAD_BITS};
6use crate::sql::{Request, Statement};
7
8/// Current schema version stored in `oxilite_meta`.
9pub const SCHEMA_VERSION: &str = "1";
10
11/// Options chosen when a store is created.
12#[derive(Debug, Clone, PartialEq, Eq)]
13#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
14#[cfg_attr(feature = "serde", serde(default, rename_all = "camelCase"))]
15pub struct StoreOptions {
16    /// Create the optional `quads_gspo` index (fast `GRAPH <g> { ?s ?p ?o }`, `CLEAR GRAPH`).
17    pub graph_index: bool,
18    /// Create the full-text index over string literals (FTS5, see [`crate::text`]).
19    pub text_index: bool,
20}
21
22impl Default for StoreOptions {
23    fn default() -> Self {
24        Self {
25            graph_index: true,
26            text_index: false,
27        }
28    }
29}
30
31/// The schema as one SQL script (for `wrangler d1 migrations`).
32pub fn schema_sql(options: &StoreOptions) -> String {
33    let mut out =
34        String::from("-- oxilite schema (generated by oxilite_core::schema::schema_sql)\n");
35    for s in create_schema(options).statements {
36        out.push_str(&s.sql);
37        out.push_str(";\n");
38    }
39    out
40}
41
42/// DDL statements creating (idempotently) the oxilite schema.
43pub fn create_schema(options: &StoreOptions) -> Request {
44    let mut s = vec![
45        "CREATE TABLE IF NOT EXISTS oxilite_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT",
46        // Hashed terms. `id` is the rowid alias: the fastest possible key.
47        "CREATE TABLE IF NOT EXISTS terms (\
48            id INTEGER PRIMARY KEY, \
49            lex TEXT NOT NULL, \
50            dt TEXT, \
51            lang TEXT, \
52            dir INTEGER, \
53            num REAL, \
54            nt INTEGER, \
55            ts REAL) STRICT",
56        "CREATE INDEX IF NOT EXISTS terms_num ON terms(num) WHERE num IS NOT NULL",
57        "CREATE INDEX IF NOT EXISTS terms_ts ON terms(ts) WHERE ts IS NOT NULL",
58        // Detects xxh3 collisions atomically: aborts the whole batch.
59        "CREATE TRIGGER IF NOT EXISTS terms_collision BEFORE INSERT ON terms \
60         WHEN EXISTS (SELECT 1 FROM terms t WHERE t.id = NEW.id AND \
61            (t.lex IS NOT NEW.lex OR t.dt IS NOT NEW.dt OR t.lang IS NOT NEW.lang OR t.dir IS NOT NEW.dir)) \
62         BEGIN SELECT RAISE(ABORT, 'oxilite: term hash collision'); END",
63        "CREATE TABLE IF NOT EXISTS triple_terms (\
64            id INTEGER PRIMARY KEY, s INTEGER NOT NULL, p INTEGER NOT NULL, o INTEGER NOT NULL, vk TEXT NOT NULL, sk TEXT NOT NULL) STRICT",
65        // The quad table is its own clustered SPOG index; secondary indexes contain every
66        // column, so every triple-pattern scan is index-only.
67        "CREATE TABLE IF NOT EXISTS quads (\
68            s INTEGER NOT NULL, p INTEGER NOT NULL, o INTEGER NOT NULL, g INTEGER NOT NULL DEFAULT 0, \
69            PRIMARY KEY (s, p, o, g)) WITHOUT ROWID, STRICT",
70        "CREATE INDEX IF NOT EXISTS quads_posg ON quads(p, o, s, g)",
71        "CREATE INDEX IF NOT EXISTS quads_ospg ON quads(o, s, p, g)",
72        "CREATE TABLE IF NOT EXISTS graphs (id INTEGER PRIMARY KEY) STRICT",
73        "CREATE TABLE IF NOT EXISTS stats_pred (\
74            p INTEGER PRIMARY KEY, triples INTEGER NOT NULL, distinct_s INTEGER NOT NULL, distinct_o INTEGER NOT NULL) STRICT",
75        "CREATE TABLE IF NOT EXISTS stats_class (o INTEGER PRIMARY KEY, instances INTEGER NOT NULL) STRICT",
76        // Frequent (predicate, object) pairs of low-cardinality predicates (planner skew).
77        "CREATE TABLE IF NOT EXISTS stats_po (p INTEGER NOT NULL, o INTEGER NOT NULL, n INTEGER NOT NULL, PRIMARY KEY (p, o)) WITHOUT ROWID, STRICT",
78        // Reasoning: the schema closure (see `reason::closure_statements`) and materialized
79        // OWL 2 RL inferences, kept apart from asserted quads.
80        "CREATE TABLE IF NOT EXISTS tbox_closure (\
81            kind INTEGER NOT NULL, sub INTEGER NOT NULL, sup INTEGER NOT NULL, PRIMARY KEY (kind, sup, sub)) WITHOUT ROWID, STRICT",
82        "CREATE INDEX IF NOT EXISTS tbox_closure_sub ON tbox_closure(kind, sub, sup)",
83        "CREATE TABLE IF NOT EXISTS quads_inf (\
84            s INTEGER NOT NULL, p INTEGER NOT NULL, o INTEGER NOT NULL, g INTEGER NOT NULL DEFAULT 0, \
85            PRIMARY KEY (s, p, o, g)) WITHOUT ROWID, STRICT",
86        "CREATE INDEX IF NOT EXISTS quads_inf_posg ON quads_inf(p, o, s, g)",
87        "CREATE INDEX IF NOT EXISTS quads_inf_ospg ON quads_inf(o, s, p, g)",
88        // Staging table for SPARQL UPDATE (DELETE/INSERT … WHERE) inside one atomic batch.
89        "CREATE TABLE IF NOT EXISTS update_buffer (\
90            op INTEGER NOT NULL, s INTEGER NOT NULL, p INTEGER NOT NULL, o INTEGER NOT NULL, g INTEGER NOT NULL) STRICT",
91        // Assertions inside atomic batches: inserting a non-NULL value aborts the batch with a
92        // "CHECK constraint failed: <name>" error naming the violated SPARQL condition.
93        "CREATE TABLE IF NOT EXISTS oxilite_guard (\
94            graph_does_not_exist INTEGER CHECK (graph_does_not_exist IS NULL), \
95            graph_already_exists INTEGER CHECK (graph_already_exists IS NULL), \
96            computed_value_not_storable INTEGER CHECK (computed_value_not_storable IS NULL)) STRICT",
97    ]
98    .into_iter()
99    .map(Statement::from)
100    .collect::<Vec<_>>();
101    if options.graph_index {
102        s.push("CREATE INDEX IF NOT EXISTS quads_gspo ON quads(g, s, p, o)".into());
103    }
104    if options.text_index {
105        s.extend(crate::text::schema_statements());
106    }
107    s.push(
108        format!(
109            "INSERT OR IGNORE INTO oxilite_meta(key, value) VALUES ('schema_version', '{SCHEMA_VERSION}'), ('graph_index', '{}'), ('int_offset', '{INT_OFFSET}'), ('payload_bits', '{PAYLOAD_BITS}'), ('integer_tag', '{}')",
110            u8::from(options.graph_index),
111            Tag::Integer as u8
112        )
113        .into(),
114    );
115    Request::atomic(s)
116}
oxilite_core/schema.rs

oxilite_core/
schema.rs
