Skip to main content

sqlive/
scope_lookup.rs

1//! A statement's scopes for one run: its constant conditions bound to the
2//! run's values, and each join as a lookup a write runs to judge whether a
3//! row it changed meets a partner row in that partner's scope (§4). A run
4//! reads nothing for its joins; the write that changes a joined table asks.
5
6use std::cmp::Ordering;
7use std::collections::BTreeMap;
8use std::sync::Arc;
9
10use crate::row_scope::{RowScope, Scopes};
11use crate::scope_edge::MemberValue;
12use crate::scope_plan::{Membership, PartnerValue, Sources};
13use crate::scope_row::{RowCondition, RowTest};
14use crate::scope_term::{Affinity, ScopeTerm};
15use crate::sql_value::SqlValue as Value;
16
17/// What a write asks of SQLite about a changed row.
18#[derive(Clone, Copy)]
19pub enum Judging<'a> {
20    /// Whether some partner row in the lookup's scope holds the value.
21    Partner(&'a Lookup, &'a Value),
22    /// Whether a row passes a condition: the SQL and its parameters.
23    Row(&'a str, &'a [Value]),
24}
25
26/// Runs one question about a changed row: whether SQLite found a row.
27pub type Lookups<'a> = dyn FnMut(Judging<'_>) -> Result<bool, NoAnswer> + 'a;
28
29/// Why a question about a changed row has no answer.
30#[derive(Debug)]
31pub enum NoAnswer {
32    /// The question ran past `LOOKUP_STEPS` and stopped. sqlive can't tell
33    /// whether the row passes, so the live query runs again (§4).
34    Stopped,
35    /// SQLite failed.
36    Failed(rusqlite::Error),
37}
38
39impl From<rusqlite::Error> for NoAnswer {
40    fn from(error: rusqlite::Error) -> Self {
41        Self::Failed(error)
42    }
43}
44
45/// The most SQLite steps one question about a changed row runs. A lookup no
46/// index serves reads its partner row by row; past this it stops and the
47/// query runs again, so a write's cost stays bounded whatever the app's
48/// indexes.
49pub const LOOKUP_STEPS: i32 = 1_000;
50
51/// The scope of each table among `sources`, for a run bound to
52/// `parameters` that returned `last`, the ORDER BY's values of its last row,
53/// when it returned as many rows as its LIMIT. The sources placed after a
54/// sorted one look its rows up within its bound too.
55pub(crate) fn scopes(sources: &Sources, parameters: &[Value], last: Option<&[Value]>) -> Scopes {
56    let parameters: Arc<[Value]> = parameters.into();
57    let mut bound: Vec<Option<RowScope>> = sources.sources.iter().map(|_| None).collect();
58    for &position in &sources.order {
59        let source = &sources.sources[position];
60        let bind = |term: &Option<ScopeTerm>| {
61            term.as_ref().and_then(|term| term.bind(&parameters)).unwrap_or(RowScope::All)
62        };
63        let mut scope = bind(&source.term).and(bind(&source.carried));
64        let partner_scope = |membership: &Membership| {
65            bound[membership.partner].as_ref().expect("a membership's partner comes first")
66        };
67        // The rows whose membership finds a row of its partner in
68        // `partner_scope`.
69        let joined = |membership: &Membership, partner_scope: RowScope| {
70            let partner = &sources.sources[membership.partner];
71            let lookup = Arc::new(Lookup::new(
72                partner.from.clone().expect("an edge's partner reads alone"),
73                partner.qualifier.clone(),
74                membership.value.clone(),
75                membership.affinity,
76                membership.nulls,
77                partner_scope,
78                &parameters,
79            ));
80            match &membership.member {
81                MemberValue::Column(column) => RowScope::Joined { column: column.clone(), lookup },
82                // A write asks SQLite for the expression's value in the
83                // changed row and whether a partner row gives it, compared
84                // as the statement compares them (`scope_row.rs`).
85                MemberValue::Expression(term) => RowScope::Row(Arc::new(RowCondition {
86                    term: Arc::clone(term),
87                    parameters: parameters.to_vec(),
88                    test: RowTest::Joined(lookup),
89                })),
90            }
91        };
92        for membership in &source.memberships {
93            // Rows that must hold given values in the column hold no others.
94            if let (MemberValue::Column(member), PartnerValue::Column(column)) =
95                (&membership.member, &membership.value)
96            {
97                if let Some(found) = partner_scope(membership).equal_values(column) {
98                    scope = scope.and(RowScope::equal(member.clone(), found));
99                    continue;
100                }
101            }
102            scope = scope.and(joined(membership, partner_scope(membership).clone()));
103        }
104        // An OR's scope passes the rows any of its sides' scopes do.
105        for sides in &source.either {
106            let either = sides.iter().map(|side| {
107                side.memberships.iter().fold(bind(&side.term), |scope, membership| {
108                    scope.and(joined(membership, partner_scope(membership).clone()))
109                })
110            });
111            if let Some(either) = either.reduce(RowScope::or) {
112                scope = scope.and(either);
113            }
114        }
115        if let (Some(sorted), Some(last)) = (&sources.sorted, last) {
116            let found = sorted.bound(
117                position,
118                last,
119                &parameters,
120                &source.memberships,
121                |membership, before| {
122                    joined(membership, partner_scope(membership).clone().and(before))
123                },
124            );
125            if let Some(found) = found {
126                scope = scope.and(found);
127            }
128        }
129        bound[position] = Some(scope);
130    }
131    let mut scopes: BTreeMap<String, RowScope> = BTreeMap::new();
132    for (position, (source, scope)) in sources.sources.iter().zip(bound).enumerate() {
133        let (Some(table), Some(scope)) = (&source.table, scope) else {
134            continue;
135        };
136        // A subquery's window narrows its table's own scope, and no lookup
137        // of another source (`scope_window.rs`).
138        let window = sources.windows.iter().find(|window| window.item == position);
139        let scope = match window.and_then(|window| window.bind(&parameters)) {
140            Some(window) => scope.and(window),
141            None => scope,
142        };
143        let scope = match scopes.remove(table) {
144            Some(other) => other.or(scope),
145            None => scope,
146        };
147        scopes.insert(table.clone(), scope);
148    }
149    Scopes {
150        tables: scopes,
151        inlined: sources.inlined.clone(),
152        fts5_shadows: sources.fts5_shadows.clone(),
153        ..Scopes::default()
154    }
155}
156
157/// A join's lookup: whether a row of the partner FROM item, in the scope the
158/// run gave it, holds a value equal to the changed row's join column, as the
159/// statement's equality compares them.
160#[derive(Debug)]
161pub struct Lookup {
162    /// The partner FROM item, as sqlive's SQL names it with its qualifier.
163    from: String,
164    qualifier: String,
165    /// What the partner's rows give.
166    value: PartnerValue,
167    /// The joined column's.
168    affinity: Affinity,
169    /// Whether the join is on `IS`, which matches a NULL with a NULL.
170    nulls: bool,
171    /// The partner's rows in this run.
172    scope: RowScope,
173    sql: LookupSql,
174}
175
176/// A lookup's SQL, made with the lookup.
177#[derive(Debug)]
178struct LookupSql {
179    /// The value bound as it is, its parameter last.
180    plain: String,
181    /// The value given the joined column's affinity, as the statement's
182    /// comparison gives it: only for an expression, which has none.
183    typed: Option<String>,
184    /// The run's parameters, then the scope's values.
185    parameters: Vec<Value>,
186}
187
188impl Lookup {
189    /// The lookup of the partner `from` as `qualifier` names it, in its
190    /// `scope` for a run bound to `parameters`, which the FROM item and an
191    /// expression can name.
192    fn new(
193        from: String,
194        qualifier: String,
195        value: PartnerValue,
196        affinity: Affinity,
197        nulls: bool,
198        scope: RowScope,
199        parameters: &[Value],
200    ) -> Self {
201        let sql = render(&from, &qualifier, &value, affinity, nulls, &scope, parameters);
202        Self { from, qualifier, value, affinity, nulls, scope, sql }
203    }
204
205    /// Whether the join is on `IS`, so a NULL looks up a partner's NULL.
206    pub(crate) fn nulls(&self) -> bool {
207        self.nulls
208    }
209
210    /// The SQL that looks up `value`, and its parameters with `value` last.
211    pub fn sql(&self, value: &Value) -> (&str, Vec<Value>) {
212        let sql = &self.sql;
213        let typed = match (self.affinity, value) {
214            (Affinity::Text, Value::Text(_))
215            | (Affinity::Numeric, Value::Integer(_) | Value::Real(_)) => sql.typed.as_deref(),
216            _ => None,
217        };
218        let mut parameters = sql.parameters.clone();
219        parameters.push(value.clone());
220        (typed.unwrap_or(&sql.plain), parameters)
221    }
222}
223
224/// A lookup's SQL: the partner's rows in `scope` holding the looked-up value,
225/// compared by `IS` when `nulls`.
226fn render(
227    from: &str,
228    qualifier: &str,
229    partner: &PartnerValue,
230    affinity: Affinity,
231    nulls: bool,
232    scope: &RowScope,
233    parameters: &[Value],
234) -> LookupSql {
235    let mut parameters = parameters.to_vec();
236    let condition = condition(scope, qualifier, &mut parameters);
237    let value = format!("?{}", parameters.len() + 1);
238    let operator = if nulls { "IS" } else { "=" };
239    let found = |compared: &str| {
240        format!(
241            "SELECT 1 FROM {from} WHERE {} {operator} {compared} COLLATE BINARY AND {condition} LIMIT 1",
242            partner_value(qualifier, partner)
243        )
244    };
245    // An expression has no affinity, so SQLite applies the joined
246    // column's to its values. A value of that affinity's own type, cast
247    // to it, carries the affinity into the lookup's comparison; a cast
248    // would change a value of any other type, and no conversion makes
249    // such a value equal to the expression's.
250    let typed = match (partner, affinity) {
251        (PartnerValue::Expression(_), Affinity::Text) => {
252            Some(found(&format!("CAST({value} AS TEXT)")))
253        }
254        (PartnerValue::Expression(_), Affinity::Numeric) => {
255            Some(found(&format!("CAST({value} AS NUMERIC)")))
256        }
257        _ => None,
258    };
259    LookupSql { plain: found(&value), typed, parameters }
260}
261
262/// The value a partner's rows give, as SQL over the rows `qualifier` names.
263fn partner_value(qualifier: &str, value: &PartnerValue) -> String {
264    match value {
265        PartnerValue::Column(column) => format!("{qualifier}.{}", crate::sql::identifier(column)),
266        PartnerValue::Expression(sql) => format!("({sql})"),
267    }
268}
269
270/// `scope` as an SQL condition on the rows `qualifier` names, its values
271/// appended to `bound` as parameters. A join inside it lists its partner's
272/// values in a subquery that names only the partner's rows, so no name in
273/// it can mean a row around it; a join on `IS` also passes a NULL when some
274/// partner row in its scope gives NULL.
275fn condition(scope: &RowScope, qualifier: &str, bound: &mut Vec<Value>) -> String {
276    let parameter = |value: &Value, bound: &mut Vec<Value>| {
277        bound.push(value.clone());
278        format!("?{}", bound.len())
279    };
280    match scope {
281        RowScope::All => "1".into(),
282        RowScope::Compare { column, value, ordering, inclusive } => {
283            let operator = match (ordering, inclusive) {
284                (Ordering::Equal, _) => "=",
285                (Ordering::Less, false) => "<",
286                (Ordering::Less, true) => "<=",
287                (Ordering::Greater, false) => ">",
288                (Ordering::Greater, true) => ">=",
289            };
290            format!(
291                "{qualifier}.{} {operator} {}",
292                crate::sql::identifier(column),
293                parameter(value, bound)
294            )
295        }
296        RowScope::Null { column, not } => format!(
297            "{qualifier}.{} IS {}NULL",
298            crate::sql::identifier(column),
299            if *not { "NOT " } else { "" }
300        ),
301        RowScope::In { values, .. } if values.is_empty() => "0".into(),
302        RowScope::In { column, values } => {
303            let list: Vec<String> = values.iter().map(|value| parameter(value, bound)).collect();
304            format!("{qualifier}.{} IN ({})", crate::sql::identifier(column), list.join(","))
305        }
306        // Its parameters are numbered as the statement's, which the lookup
307        // binds first. A comparison with a value no cast keeps as it is
308        // passes every row, as a write's question counts it a match.
309        RowScope::Row(row) => row.sql(bound).unwrap_or_else(|| "1".into()),
310        // A window narrows only its own table's scope, which no lookup
311        // reads (`scopes`); passing every row keeps a lookup's rows whole.
312        RowScope::Window(_) => "1".into(),
313        RowScope::Joined { column, lookup } => {
314            joined(&format!("{qualifier}.{}", crate::sql::identifier(column)), lookup, bound)
315        }
316        RowScope::And(left, right) => format!(
317            "({} AND {})",
318            condition(left, qualifier, bound),
319            condition(right, qualifier, bound)
320        ),
321        RowScope::Or(left, right) => format!(
322            "({} OR {})",
323            condition(left, qualifier, bound),
324            condition(right, qualifier, bound)
325        ),
326    }
327}
328
329/// Whether `compared`, SQL over a changed row, equals a value some row of
330/// `lookup`'s partner in its scope gives, as SQL whose values go to
331/// `bound`. A join inside it lists its partner's values in a subquery that
332/// names only the partner's rows, so no name in it can mean a row around
333/// it; a join on `IS` also passes a NULL when some partner row in its scope
334/// gives NULL.
335pub(crate) fn joined(compared: &str, lookup: &Lookup, bound: &mut Vec<Value>) -> String {
336    let value = partner_value(&lookup.qualifier, &lookup.value);
337    let listed = format!(
338        "{compared} IN (SELECT {value} FROM {} WHERE {})",
339        lookup.from,
340        condition(&lookup.scope, &lookup.qualifier, bound)
341    );
342    if lookup.nulls {
343        format!(
344            "({listed} OR {compared} IS NULL AND EXISTS (SELECT 1 FROM {} WHERE {value} IS NULL AND {}))",
345            lookup.from,
346            condition(&lookup.scope, &lookup.qualifier, bound)
347        )
348    } else {
349        listed
350    }
351}