Skip to main content

oxilite_cypher/
lib.rs

1//! openCypher over oxilite.
2//!
3//! Property graphs are a view of the RDF 1.2 dataset: nodes are IRIs or blank nodes, labels
4//! are `rdf:type`, node properties are literal triples, relationships are triples, and a
5//! relationship's identity and properties live on an RDF 1.2 reifier. A Cypher statement is
6//! parsed, lowered to SPARQL algebra (compiled to SQL by oxilite, with its planner,
7//! reasoning and fallback), and what SQL cannot express — writes, lists, maps, `collect()` —
8//! runs in Rust over the query's rows. Writes are applied as one atomic request.
9//!
10//! The same [`CypherJob`] drives the blocking store, the async store (Cloudflare D1) and the
11//! wasm engine; see `oxilite::Store::cypher` for the usual entry point.
12//!
13// @lat: [[architecture#Property graph frontend]]
14#![allow(clippy::type_complexity)]
15
16pub mod ast;
17mod error;
18mod eval;
19mod exec;
20pub mod json;
21mod lexer;
22mod lower;
23mod parser;
24mod plan;
25mod schema;
26mod temporal;
27mod validate;
28mod value;
29mod vector;
30mod vocab;
31
32pub use error::{CypherError, Result};
33pub use exec::{CypherJob, CypherResult, CypherStep, StepInput, WriteStats};
34pub use parser::parse;
35pub use schema::{schema_query, Shapes as Schema};
36pub use value::{Node, Params, Path, Relationship, TemporalKind, Value, RDF_JSON};
37pub use vector::{schema_command, SchemaCommand};
38pub use vocab::Vocabulary;
39
40use oxilite_core::job::Job;
41use oxilite_core::query::{compile_query, QueryJob, QueryOutput};
42use oxilite_core::{Capabilities, QueryOptions, Request, Response, Stats, Step};
43
44/// Is `name` a function Cypher defines itself (so a host function may not take it)?
45pub fn is_builtin_function(name: &str) -> bool {
46    let name = name.to_lowercase();
47    if ast::is_aggregate(&name) || matches!(name.as_str(), "id" | "elementid" | "exists") {
48        return true;
49    }
50    // An unknown name is "unsupported"; a known one fails on its arguments, or succeeds.
51    !matches!(
52        eval::function(&name, vec![Value::Null; 8]),
53        Err(CypherError::Unsupported(m)) if m.starts_with("function ")
54    )
55}
56
57/// How a property with several RDF values is read.
58#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
59pub enum MultiValue {
60    /// As a list of the values (in value order).
61    #[default]
62    List,
63    /// As its smallest value.
64    First,
65    /// As an error.
66    Error,
67}
68
69/// Options of the Cypher frontend.
70#[derive(Debug, Clone)]
71pub struct CypherOptions {
72    /// Label, relationship-type and property-key names ↔ IRIs.
73    pub vocabulary: Vocabulary,
74    pub multi_value: MultiValue,
75    /// Maximum hops of an unbounded variable-length relationship (`*`, `*2..`).
76    pub var_length_cap: usize,
77    /// Maximum number of alternatives a `MATCH` may expand to.
78    pub max_branches: usize,
79    /// Maximum depth of an unbounded `shortestPath` search (one request per level).
80    pub shortest_path_cap: usize,
81    /// Give every created node an `rdf:type rdfs:Resource` triple, so nodes without labels,
82    /// properties or relationships still exist (hidden from `labels()`).
83    pub node_marker: bool,
84    /// Tell parallel relationships apart in uniqueness checks (costs a reifier look-up per
85    /// relationship pattern).
86    pub reifier_uniqueness: bool,
87    /// Check writes against the SHACL shapes stored in the dataset (loaded by each writing
88    /// statement unless `schema` is given).
89    pub shapes: bool,
90    /// Shapes loaded beforehand (`Store::cypher_schema`): used when planning (required
91    /// properties join without `OPTIONAL`), when reading (single-valued properties) and by the
92    /// write guards, without a per-statement load.
93    pub schema: Option<std::sync::Arc<Schema>>,
94    /// Options of the SPARQL evaluation: reasoning (OWL/RDFS entailment), union default
95    /// graph…
96    pub query: QueryOptions,
97    /// Host functions, callable by their Cypher names (see `oxilite_core::functions`).
98    pub functions: oxilite_core::functions::Functions,
99}
100
101impl Default for CypherOptions {
102    fn default() -> Self {
103        Self {
104            vocabulary: Vocabulary::default(),
105            multi_value: MultiValue::List,
106            var_length_cap: 10,
107            max_branches: 256,
108            shortest_path_cap: 32,
109            node_marker: true,
110            reifier_uniqueness: false,
111            shapes: true,
112            schema: None,
113            query: QueryOptions::default(),
114            functions: Default::default(),
115        }
116    }
117}
118
119/// Parses and plans a statement for a native backend.
120pub fn prepare(query: &str, params: &Params, options: &CypherOptions) -> Result<CypherJob> {
121    prepare_for(query, params, options, &Capabilities::default())
122}
123
124/// Parses and plans a statement for a backend.
125pub fn prepare_for(
126    query: &str,
127    params: &Params,
128    options: &CypherOptions,
129    caps: &Capabilities,
130) -> Result<CypherJob> {
131    let ast = parse(query)?;
132    validate::validate(&ast)?;
133    let mut lw = lower::Lowerer::new(&options.vocabulary, params, options);
134    let plan = plan::plan(&ast, &mut lw)?;
135    Ok(CypherJob::new(
136        plan,
137        params.clone(),
138        options.clone(),
139        caps.clone(),
140    ))
141}
142
143/// Runs a job with blocking callbacks: `query` evaluates SPARQL (with the store's
144/// fallback), `sql` runs requests.
145pub fn run_blocking(
146    mut job: CypherJob,
147    mut query: impl FnMut(&spargebra::Query, &QueryOptions) -> Result<QueryOutput>,
148    mut sql: impl FnMut(&Request) -> Result<Response>,
149) -> Result<CypherResult> {
150    let mut input = None;
151    loop {
152        input = Some(match job.step(input)? {
153            CypherStep::Query(q, o) => StepInput::Output(query(&q, &o)?),
154            CypherStep::Sql(r) | CypherStep::Write(r) => StepInput::Response(sql(&r)?),
155            CypherStep::Done(r) => return Ok(r),
156        });
157    }
158}
159
160enum Inner {
161    None,
162    Query(Box<QueryJob>),
163    Direct,
164}
165
166/// A [`CypherJob`] as a core SQL [`Job`]: SPARQL parts are compiled with
167/// [`compile_query`] (no Rust fallback), so it runs on any backend, including D1 and the
168/// wasm engine.
169pub struct SqlCypherJob {
170    job: CypherJob,
171    stats: Stats,
172    caps: Capabilities,
173    options: QueryOptions,
174    inner: Inner,
175    started: bool,
176    error: Option<CypherError>,
177}
178
179impl SqlCypherJob {
180    pub fn new(job: CypherJob, stats: Stats, caps: Capabilities, options: QueryOptions) -> Self {
181        Self {
182            job,
183            stats,
184            caps,
185            options,
186            inner: Inner::None,
187            started: false,
188            error: None,
189        }
190    }
191
192    /// The Cypher error behind an [`oxilite_core::Error::Other`] returned by `step`.
193    pub fn take_error(&mut self) -> Option<CypherError> {
194        self.error.take()
195    }
196
197    fn cypher(&mut self, input: Option<StepInput>) -> oxilite_core::Result<Step<CypherResult>> {
198        let step = match self.job.step(input) {
199            Ok(s) => s,
200            Err(CypherError::Store(e)) => return Err(e),
201            Err(e) => {
202                let msg = e.to_string();
203                self.error = Some(e);
204                return Err(oxilite_core::Error::Other(msg));
205            }
206        };
207        match step {
208            CypherStep::Done(r) => Ok(Step::Done(r)),
209            CypherStep::Sql(r) | CypherStep::Write(r) => {
210                self.inner = Inner::Direct;
211                Ok(Step::Execute(r))
212            }
213            CypherStep::Query(q, o) => {
214                let mut options = self.options.clone();
215                options.var_types.extend(o.var_types);
216                let compiled = compile_query(&q, &self.stats, &self.caps, &options)?;
217                let mut qj = QueryJob::new(compiled, self.caps.clone());
218                match qj.step(None)? {
219                    Step::Execute(r) => {
220                        self.inner = Inner::Query(Box::new(qj));
221                        Ok(Step::Execute(r))
222                    }
223                    Step::Done(out) => self.cypher(Some(StepInput::Output(out))),
224                }
225            }
226        }
227    }
228}
229
230impl Job for SqlCypherJob {
231    type Output = CypherResult;
232
233    fn step(&mut self, response: Option<Response>) -> oxilite_core::Result<Step<CypherResult>> {
234        if !self.started {
235            self.started = true;
236            return self.cypher(None);
237        }
238        match std::mem::replace(&mut self.inner, Inner::None) {
239            Inner::Direct => self.cypher(response.map(StepInput::Response)),
240            Inner::Query(mut qj) => match qj.step(response)? {
241                Step::Execute(r) => {
242                    self.inner = Inner::Query(qj);
243                    Ok(Step::Execute(r))
244                }
245                Step::Done(out) => self.cypher(Some(StepInput::Output(out))),
246            },
247            Inner::None => Err(oxilite_core::Error::Other(
248                "Cypher job resumed after completion".into(),
249            )),
250        }
251    }
252}