Skip to main content

datacraft_query/
query_engine.rs

1//! In-memory query engine (step 7.3, item H27; decision default 7).
2//!
3//! No SQL parser: criteria strings parse to typed predicates per column
4//! kind, execution filters port rows (AND across columns, OR within a
5//! column — SQL NULL never satisfies a predicate), projects the shown
6//! columns in grid order and sorts by the sort columns (stable,
7//! leftmost-first).
8
9use crate::qbe::{QueryDef, SortOrder};
10use datacraft_types::compare;
11
12use crate::query_criteria::{Predicate, parse_predicate};
13use datacraft_types::FieldValue;
14use datacraft_types::TableDef;
15
16/// Result of a query execution.
17#[derive(Debug, Clone, PartialEq, Default)]
18pub struct QueryResult {
19    /// Projected column names in grid order.
20    pub columns: Vec<String>,
21    /// Result rows, positional to `columns`.
22    pub rows: Vec<Vec<FieldValue>>,
23}
24
25/// Engine errors: whitelist violations and coercion failures.
26#[derive(Debug, Clone, PartialEq, Eq)]
27pub enum EngineError {
28    /// A criteria column is not a field of the source table.
29    UnknownField {
30        /// The unknown name.
31        field: String,
32        /// The source table.
33        table: String,
34    },
35    /// The query grid lists the same source field more than once
36    /// among its shown columns — the by-name projection forbids
37    /// ambiguity (step 42.3, item L22).
38    DuplicateField {
39        /// The duplicated name.
40        field: String,
41        /// The query definition.
42        query: String,
43    },
44    /// A criteria literal does not fit the column's kind.
45    BadLiteral {
46        /// The column.
47        field: String,
48        /// The offending criteria text.
49        criteria: String,
50        /// Concrete reason.
51        detail: String,
52    },
53}
54
55impl std::fmt::Display for EngineError {
56    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
57        match self {
58            Self::UnknownField { field, table } => {
59                write!(f, "field {field:?} is not a field of {table:?}")
60            }
61            Self::DuplicateField { field, query } => {
62                write!(
63                    f,
64                    "field {field:?} appears more than once in query {query:?}"
65                )
66            }
67            Self::BadLiteral {
68                field,
69                criteria,
70                detail,
71            } => write!(f, "criteria {criteria:?} on {field:?}: {detail}"),
72        }
73    }
74}
75
76impl std::error::Error for EngineError {}
77
78/// Executes a query over the source table's rows.
79pub fn run_query(
80    def: &QueryDef,
81    source: &TableDef,
82    rows: &[Vec<FieldValue>],
83) -> Result<QueryResult, EngineError> {
84    let predicates = parse_predicates(def, source)?;
85    let filtered: Vec<&Vec<FieldValue>> = rows
86        .iter()
87        .filter(|row| {
88            predicates
89                .iter()
90                .all(|(index, ors)| ors.iter().any(|p| p.matches(&row[*index])))
91        })
92        .collect();
93
94    // By-name projection (step 42.3, L22): shown names resolve through
95    // the source whitelist and must be unique (case-insensitive), so a
96    // subset or reordered grid can never mis-project silently.
97    let shown_names: Vec<&str> = def
98        .fields
99        .iter()
100        .filter(|f| f.shown)
101        .map(|f| f.name.as_str())
102        .collect();
103    for (at, name) in shown_names.iter().enumerate() {
104        if shown_names[..at]
105            .iter()
106            .any(|other| other.eq_ignore_ascii_case(name))
107        {
108            return Err(EngineError::DuplicateField {
109                field: (*name).to_owned(),
110                query: def.name.clone(),
111            });
112        }
113    }
114    let shown: Vec<(usize, String)> = shown_names
115        .iter()
116        .map(|name| resolve_column(source, name))
117        .collect::<Result<Vec<_>, _>>()?;
118    let columns: Vec<String> = shown.iter().map(|(_, name)| name.clone()).collect();
119
120    // Sort on the FULL rows (hidden sort keys are legal), then project.
121    let mut filtered = filtered;
122    sort_rows(def, source, &mut filtered)?;
123
124    let result_rows: Vec<Vec<FieldValue>> = filtered
125        .iter()
126        .map(|row| shown.iter().map(|(i, _)| row[*i].clone()).collect())
127        .collect();
128
129    Ok(QueryResult {
130        columns,
131        rows: result_rows,
132    })
133}
134
135/// Resolves one grid column against the source schema whitelist by
136/// name (case-insensitive — the same rule the criteria and sort paths
137/// apply).
138fn resolve_column(source: &TableDef, name: &str) -> Result<(usize, String), EngineError> {
139    let index = source
140        .fields
141        .iter()
142        .position(|c| c.name.eq_ignore_ascii_case(name))
143        .ok_or(EngineError::UnknownField {
144            field: name.to_owned(),
145            table: source.name.clone(),
146        })?;
147    Ok((index, name.to_owned()))
148}
149
150/// Parses all criteria into per-column predicate lists (grid order).
151fn parse_predicates(
152    def: &QueryDef,
153    source: &TableDef,
154) -> Result<Vec<(usize, Vec<Predicate>)>, EngineError> {
155    def.fields
156        .iter()
157        .filter(|f| !f.criteria.is_empty())
158        .map(|field| {
159            let Some((index, column)) = source
160                .fields
161                .iter()
162                .enumerate()
163                .find(|(_, c)| c.name.eq_ignore_ascii_case(&field.name))
164            else {
165                return Err(EngineError::UnknownField {
166                    field: field.name.clone(),
167                    table: source.name.clone(),
168                });
169            };
170            let ors = field
171                .criteria
172                .iter()
173                .map(|text| parse_predicate(text, &field.name, column))
174                .collect::<Result<Vec<_>, _>>()?;
175            Ok((index, ors))
176        })
177        .collect()
178}
179
180/// Parses one criteria string: optional operator prefix, then a typed
181/// rows (sort keys may be hidden columns).
182fn sort_rows(
183    def: &QueryDef,
184    source: &TableDef,
185    rows: &mut [&Vec<FieldValue>],
186) -> Result<(), EngineError> {
187    let keys: Vec<(usize, bool)> = def
188        .fields
189        .iter()
190        .filter(|f| f.sort != SortOrder::None)
191        .map(|f| {
192            let index = source
193                .fields
194                .iter()
195                .position(|c| c.name.eq_ignore_ascii_case(&f.name))
196                .ok_or(EngineError::UnknownField {
197                    field: f.name.clone(),
198                    table: source.name.clone(),
199                })?;
200            Ok((index, f.sort == SortOrder::Descending))
201        })
202        .collect::<Result<Vec<_>, _>>()?;
203    if keys.is_empty() {
204        return Ok(());
205    }
206    rows.sort_by(|a, b| {
207        for (index, descending) in &keys {
208            let ordering = compare(&a[*index], &b[*index]).unwrap_or(std::cmp::Ordering::Equal);
209            let ordering = if *descending {
210                ordering.reverse()
211            } else {
212                ordering
213            };
214            if ordering != std::cmp::Ordering::Equal {
215                return ordering;
216            }
217        }
218        std::cmp::Ordering::Equal
219    });
220    Ok(())
221}
222
223#[cfg(test)]
224mod tests {
225    use super::*;
226    use crate::qbe::QbeField;
227    use datacraft_types::FieldValue;
228    use datacraft_types::TableDef;
229    use datacraft_types::{FieldDef, FieldKind, NumericKind};
230
231    fn one_row(value: FieldValue) -> Vec<Vec<FieldValue>> {
232        vec![vec![value]]
233    }
234
235    /// Hidden sort keys sort the full rows before projection.
236    #[test]
237    fn hidden_sort_keys_apply() {
238        let source = TableDef::new(
239            "T",
240            vec![
241                FieldDef::new("name", FieldKind::Text { max_len: 5 }),
242                FieldDef::new("rank", FieldKind::Number(NumericKind::LongInteger)),
243            ],
244        );
245        let data = vec![
246            vec![FieldValue::Text("b".into()), FieldValue::Integer(1)],
247            vec![FieldValue::Text("a".into()), FieldValue::Integer(2)],
248        ];
249        let def = QueryDef {
250            name: "q".into(),
251            table: "T".into(),
252            fields: vec![QbeField {
253                name: "name".into(),
254                shown: true,
255                sort: SortOrder::Descending,
256                criteria: Vec::new(),
257            }],
258        };
259        let mut def = def;
260        // A second, hidden sort column (rank ascending) breaks the tie.
261        def.fields.push(QbeField {
262            name: "rank".into(),
263            shown: false,
264            sort: SortOrder::Ascending,
265            criteria: Vec::new(),
266        });
267        let result = run_query(&def, &source, &data).expect("runs");
268        assert_eq!(result.columns, ["name"]);
269        assert_eq!(result.rows[0][0], FieldValue::Text("b".into()));
270        assert_eq!(result.rows[1][0], FieldValue::Text("a".into()));
271    }
272
273    /// An unknown sort column is a whitelist error (direct engine calls).
274    #[test]
275    fn unknown_sort_columns_are_whitelist_errors() {
276        let source = TableDef::new("T", vec![FieldDef::new("v", FieldKind::Currency)]);
277        let def = QueryDef {
278            name: "q".into(),
279            table: "T".into(),
280            fields: vec![QbeField {
281                name: "ghost".into(),
282                shown: true,
283                sort: SortOrder::Ascending,
284                criteria: Vec::new(),
285            }],
286        };
287        let err =
288            run_query(&def, &source, &one_row(FieldValue::Null)).expect_err("unknown sort key");
289        assert!(matches!(err, EngineError::UnknownField { .. }), "{err}");
290    }
291
292    /// A subset or reordered grid projects exactly the named columns
293    /// (step 42.3, item L22): positions resolve by name through the
294    /// source whitelist, never from grid order.
295    #[test]
296    fn projection_resolves_by_name_for_subset_and_reordered_grids() {
297        let source = TableDef::new(
298            "T",
299            vec![
300                FieldDef::new("name", FieldKind::Text { max_len: 5 }),
301                FieldDef::new("rank", FieldKind::Number(NumericKind::LongInteger)),
302                FieldDef::new("total", FieldKind::Currency),
303            ],
304        );
305        let data = vec![vec![
306            FieldValue::Text("b".into()),
307            FieldValue::Integer(2),
308            FieldValue::Currency(900),
309        ]];
310        // Grid order rank, name — a reordered subset of the source.
311        let def = QueryDef {
312            name: "q".into(),
313            table: "T".into(),
314            fields: vec![
315                QbeField {
316                    name: "rank".into(),
317                    shown: true,
318                    sort: SortOrder::None,
319                    criteria: Vec::new(),
320                },
321                QbeField {
322                    name: "name".into(),
323                    shown: true,
324                    sort: SortOrder::None,
325                    criteria: Vec::new(),
326                },
327            ],
328        };
329        let result = run_query(&def, &source, &data).expect("runs");
330        assert_eq!(result.columns, ["rank", "name"]);
331        assert_eq!(
332            result.rows[0],
333            vec![FieldValue::Integer(2), FieldValue::Text("b".into())]
334        );
335    }
336
337    /// Duplicate shown names are a precise error — the by-name
338    /// projection forbids ambiguity (step 42.3, item L22).
339    #[test]
340    fn duplicate_shown_names_fail_loudly() {
341        let source = TableDef::new("T", vec![FieldDef::new("v", FieldKind::Currency)]);
342        let def = QueryDef {
343            name: "q".into(),
344            table: "T".into(),
345            fields: vec![
346                QbeField {
347                    name: "v".into(),
348                    shown: true,
349                    sort: SortOrder::None,
350                    criteria: Vec::new(),
351                },
352                // Same column again, different spelling.
353                QbeField {
354                    name: "V".into(),
355                    shown: true,
356                    sort: SortOrder::None,
357                    criteria: Vec::new(),
358                },
359            ],
360        };
361        let err =
362            run_query(&def, &source, &one_row(FieldValue::Null)).expect_err("duplicate projection");
363        assert!(matches!(err, EngineError::DuplicateField { .. }), "{err}");
364    }
365
366    /// An unknown shown name is a whitelist error even without
367    /// criteria or sort — not a silently mis-projected column
368    /// (step 42.3, item L22).
369    #[test]
370    fn unknown_shown_names_fail_loudly() {
371        let source = TableDef::new("T", vec![FieldDef::new("v", FieldKind::Currency)]);
372        let def = QueryDef {
373            name: "q".into(),
374            table: "T".into(),
375            fields: vec![QbeField {
376                name: "ghost".into(),
377                shown: true,
378                sort: SortOrder::None,
379                criteria: Vec::new(),
380            }],
381        };
382        let err = run_query(&def, &source, &one_row(FieldValue::Null)).expect_err("unknown column");
383        assert!(matches!(err, EngineError::UnknownField { .. }), "{err}");
384    }
385
386    /// prefix parsing: each prefix selects its band.
387    #[test]
388    fn operator_prefixes_select_their_band() {
389        let source = TableDef::new("T", vec![FieldDef::new("v", FieldKind::Currency)]);
390        let data = one_row(FieldValue::Currency(10_000));
391        for (criteria, expected) in [
392            ("= 1", 1usize),
393            ("<> 1", 0usize),
394            ("< 2", 1usize),
395            ("<= 1", 1usize),
396            ("> 0", 1usize),
397            (">= 2", 0usize),
398            ("1", 1usize),
399        ] {
400            let def = QueryDef {
401                name: "q".into(),
402                table: "T".into(),
403                fields: vec![QbeField {
404                    name: "v".into(),
405                    shown: true,
406                    sort: SortOrder::None,
407                    criteria: vec![criteria.to_owned()],
408                }],
409            };
410            let result = run_query(&def, &source, &data).expect("runs");
411            assert_eq!(result.rows.len(), expected, "criteria {criteria:?}");
412        }
413    }
414}