powdb_query/
ast.rs

1use powdb_storage::types::Value;
2
3/// Top-level PowQL statement.
4#[derive(Debug, Clone, PartialEq)]
5pub enum Statement {
6    Query(QueryExpr),
7    Insert(InsertExpr),
8    UpdateQuery(UpdateExpr),
9    DeleteQuery(DeleteExpr),
10    CreateType(CreateTypeExpr),
11    AlterTable(AlterTableExpr),
12    DropTable(DropTableExpr),
13    CreateView(CreateViewExpr),
14    RefreshView(RefreshViewExpr),
15    DropView(DropViewExpr),
16    Union(UnionExpr),
17    Upsert(UpsertExpr),
18    Explain(Box<Statement>),
19    Begin,
20    Commit,
21    Rollback,
22    /// `schema` — introspection: list every type (table) in the catalog.
23    ListTypes,
24    /// `describe <Type>` / `schema <Type>` — introspection: the columns and
25    /// indexes of one type.
26    Describe(String),
27}
28
29/// `alter User add column status: str` / `alter User drop column status`
30#[derive(Debug, Clone, PartialEq)]
31pub struct AlterTableExpr {
32    pub table: String,
33    pub action: AlterAction,
34}
35
36/// A persisted index target. Stored JSON paths are table-local and therefore
37/// never retain a query alias or runtime catalog/index identifier.
38#[derive(Debug, Clone, PartialEq, Eq, Hash)]
39pub enum IndexTarget {
40    Column(String),
41    JsonPath(powdb_storage::stored_json_path::StoredJsonPathV1),
42}
43
44/// An individual ALTER TABLE action.
45#[derive(Debug, Clone, PartialEq)]
46pub enum AlterAction {
47    AddColumn {
48        name: String,
49        type_name: String,
50        required: bool,
51    },
52    DropColumn {
53        name: String,
54        /// `drop column if exists` — a missing column is a no-op instead of
55        /// an error.
56        if_exists: bool,
57    },
58    /// `alter <Table> add index [if not exists] .<column>` — creates a
59    /// B+Tree index on `column`. No-op if the index already exists.
60    AddIndex {
61        target: IndexTarget,
62        /// Parsed for symmetry with the other DDL; `add index` is already
63        /// idempotent, so this does not change behavior.
64        if_not_exists: bool,
65    },
66    /// `alter <Table> add unique [if not exists] .<column>` — creates a
67    /// UNIQUE B+Tree index on `column`. Scans existing data first and fails
68    /// if any duplicate (non-null) value is present. Without `if not exists`
69    /// it errors when the column is already indexed (no in-place upgrade);
70    /// with it, an existing index is a no-op.
71    AddUnique {
72        target: IndexTarget,
73        if_not_exists: bool,
74    },
75    /// `alter <Table> drop index [if exists] <target>` — removes either a
76    /// stored-column index or an expression index with the exact path identity.
77    DropIndex {
78        target: IndexTarget,
79        if_exists: bool,
80    },
81}
82
83/// `drop [if exists] User`
84#[derive(Debug, Clone, PartialEq)]
85pub struct DropTableExpr {
86    pub table: String,
87    /// `drop if exists` — a missing table is a no-op instead of an error.
88    pub if_exists: bool,
89}
90
91/// `create [materialized] view ActiveUsers as User filter .active = true`
92#[derive(Debug, Clone, PartialEq)]
93pub struct CreateViewExpr {
94    pub name: String,
95    pub query: QueryExpr,
96    /// The original source query text, stored for re-execution on refresh.
97    pub query_text: String,
98}
99
100/// `refresh ActiveUsers`
101#[derive(Debug, Clone, PartialEq)]
102pub struct RefreshViewExpr {
103    pub name: String,
104}
105
106/// `drop view [if exists] ActiveUsers`
107#[derive(Debug, Clone, PartialEq)]
108pub struct DropViewExpr {
109    pub name: String,
110    /// `drop view if exists` — a missing view is a no-op instead of an error.
111    pub if_exists: bool,
112}
113
114/// `User filter .age > 30 union User filter .status = "vip"`
115#[derive(Debug, Clone, PartialEq)]
116pub struct UnionExpr {
117    pub left: Box<Statement>,
118    pub right: Box<Statement>,
119    /// `true` for `union all` (keep duplicates), `false` for `union` (deduplicate).
120    pub all: bool,
121}
122
123/// A query expression: Type [join ...]* [filter ...] [order ...] [limit ...] [{ projection }]
124#[derive(Debug, Clone, PartialEq)]
125pub struct QueryExpr {
126    pub source: String,
127    /// Optional alias for the primary source (e.g. `User as u`). Used to
128    /// disambiguate qualified column references in join queries. `None` for
129    /// single-table queries.
130    pub alias: Option<String>,
131    /// Zero or more join clauses chained to the primary source. For a
132    /// single-table query this is always empty so existing code paths are
133    /// untouched.
134    pub joins: Vec<JoinClause>,
135    pub filter: Option<Expr>,
136    pub order: Option<OrderClause>,
137    pub limit: Option<Expr>,
138    pub offset: Option<Expr>,
139    pub projection: Option<Vec<ProjectionField>>,
140    pub aggregation: Option<AggregateExpr>,
141    pub distinct: bool,
142    pub group_by: Option<GroupByClause>,
143}
144
145/// GROUP BY clause: `group .field1, alias.field2 [having <expr>]`.
146#[derive(Debug, Clone, PartialEq)]
147pub struct GroupByClause {
148    pub keys: Vec<GroupKey>,
149    pub having: Option<Expr>,
150}
151
152/// A single expression-valued GROUP BY key.
153#[derive(Debug, Clone, PartialEq)]
154pub struct GroupKey {
155    pub expr: Expr,
156    pub output_name: String,
157}
158
159impl GroupKey {
160    /// Name of the output column this key produces. Unqualified keys keep
161    /// their bare field name; qualified keys are emitted as `alias.field` so
162    /// HAVING and downstream projections can reference them consistently.
163    pub fn output_name(&self) -> String {
164        self.output_name.clone()
165    }
166}
167
168/// A join clause appended to a query's primary source.
169///
170/// Example syntax (Mission E1.1 parser accepts this; executor still errors):
171///   `User as u inner join Order as o on u.id = o.user_id filter o.total > 100`
172#[derive(Debug, Clone, PartialEq)]
173pub struct JoinClause {
174    pub kind: JoinKind,
175    pub source: String,
176    pub alias: Option<String>,
177    /// `on <expr>` — required for every kind except `Cross`.
178    pub on: Option<Expr>,
179}
180
181#[derive(Debug, Clone, Copy, PartialEq, Eq)]
182pub enum JoinKind {
183    Inner,
184    LeftOuter,
185    RightOuter,
186    Cross,
187}
188
189#[derive(Debug, Clone, PartialEq)]
190pub struct ProjectionField {
191    pub alias: Option<String>,
192    pub expr: Expr,
193}
194
195#[derive(Debug, Clone, PartialEq)]
196pub struct OrderClause {
197    pub keys: Vec<OrderKey>,
198}
199
200#[derive(Debug, Clone, PartialEq)]
201pub struct OrderKey {
202    pub expr: Expr,
203    pub descending: bool,
204}
205
206#[derive(Debug, Clone, PartialEq)]
207pub struct InsertExpr {
208    pub target: String,
209    /// One assignment-block per row. Always contains at least one row;
210    /// `insert T { .. }` yields one, `insert T { .. }, { .. }` yields many.
211    pub rows: Vec<Vec<Assignment>>,
212    /// `true` when the statement ends with `returning` — the executor returns
213    /// the inserted rows (all columns) instead of a modified-count.
214    pub returning: bool,
215}
216
217#[derive(Debug, Clone, PartialEq)]
218pub struct UpdateExpr {
219    pub source: String,
220    pub filter: Option<Expr>,
221    pub assignments: Vec<Assignment>,
222    /// `true` when the statement ends with `returning` — the executor returns
223    /// the post-update rows (all columns) instead of a modified-count.
224    pub returning: bool,
225}
226
227#[derive(Debug, Clone, PartialEq)]
228pub struct DeleteExpr {
229    pub source: String,
230    pub filter: Option<Expr>,
231    /// `true` when the statement ends with `returning` — the executor returns
232    /// the pre-delete rows (all columns) instead of a modified-count.
233    pub returning: bool,
234}
235
236#[derive(Debug, Clone, PartialEq)]
237pub struct Assignment {
238    pub field: String,
239    pub value: Expr,
240}
241
242#[derive(Debug, Clone, PartialEq)]
243/// `upsert User on .id { id := 1, name := "Alice" } [on conflict { name := "Alice" }]`
244pub struct UpsertExpr {
245    pub target: String,
246    pub key_column: String,
247    pub assignments: Vec<Assignment>,
248    /// Assignments to apply on conflict. If empty, all non-key assignments
249    /// from `assignments` are used as the update set.
250    pub on_conflict: Vec<Assignment>,
251}
252
253#[derive(Debug, Clone, PartialEq)]
254pub struct CreateTypeExpr {
255    pub name: String,
256    pub fields: Vec<FieldDef>,
257    /// `type X if not exists { ... }` — re-declaring an existing type is a
258    /// no-op instead of an error.
259    pub if_not_exists: bool,
260}
261
262#[derive(Debug, Clone, PartialEq)]
263pub struct FieldDef {
264    pub name: String,
265    pub type_name: String,
266    pub required: bool,
267    /// `true` when declared with the `unique` modifier — auto-creates a
268    /// unique B+Tree index on this column at table-create time.
269    pub unique: bool,
270    /// Literal default applied when an insert omits this column. `None` means
271    /// the column has no default (omitting it yields the empty set / null).
272    pub default: Option<Literal>,
273    /// `true` when declared `auto` — an integer column whose value is assigned
274    /// from a monotonic per-table sequence when an insert omits it.
275    pub auto: bool,
276}
277
278#[derive(Debug, Clone, PartialEq)]
279pub struct AggregateExpr {
280    pub function: AggFunc,
281    pub argument: Option<Expr>,
282    pub mode: AggregateMode,
283}
284
285#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
286pub enum AggregateMode {
287    Symmetric,
288    Raw,
289}
290
291#[derive(Debug, Clone, Copy, PartialEq)]
292pub enum AggFunc {
293    Count,
294    CountDistinct,
295    Avg,
296    Sum,
297    Min,
298    Max,
299}
300
301/// Window function identifier.
302#[derive(Debug, Clone, Copy, PartialEq)]
303pub enum WindowFunc {
304    RowNumber,
305    Rank,
306    DenseRank,
307    Sum,
308    Avg,
309    Count,
310    Min,
311    Max,
312}
313
314/// Scalar (non-aggregate) function — operates on single values.
315#[derive(Debug, Clone, Copy, PartialEq)]
316pub enum ScalarFn {
317    Upper,
318    Lower,
319    Length,
320    Trim,
321    Substring, // substring(expr, start, len) — 1-indexed
322    Concat,    // concat(expr, expr, ...) — variadic
323    // Math
324    Abs,
325    Round, // round(expr) or round(expr, decimals)
326    Ceil,
327    Floor,
328    Sqrt,
329    Pow, // pow(base, exponent)
330    // Date/time
331    Now,      // now() — returns current unix timestamp in microseconds
332    Extract,  // extract("year"|"month"|..., datetime_expr)
333    DateAdd,  // date_add(datetime_expr, amount, "unit")
334    DateDiff, // date_diff(dt1, dt2, "unit")
335    // JSON
336    JsonType, // json_type(expr) — 'null'|'string'|'number'|'bool'|'object'|'array', Empty when missing
337    JsonText, // json_text(expr) — SQL ->> text, canonical JSON for object/array
338}
339
340/// Target type for CAST expressions.
341#[derive(Debug, Clone, Copy, PartialEq)]
342pub enum CastType {
343    Int,
344    Float,
345    Str,
346    Bool,
347    DateTime,
348    Uuid,
349    Bytes,
350}
351
352/// A single step in a JSON `->` path expression.
353///
354/// This is the query-crate's OWNED path-segment type (distinct from
355/// [`powdb_storage::pj1::PathSeg`], which borrows `&str` keys). Segments are
356/// STRUCTURAL: they are part of the query shape, never literal slots, so the
357/// plan cache hashes them into the canonical token stream and neither counts
358/// nor substitutes them (see `plan_cache::count_expr` / `substitute_expr`).
359#[derive(Debug, Clone, PartialEq, Eq, Hash)]
360pub enum PathSeg {
361    /// Object member access: `->author` or `->"weird key!"`.
362    Key(String),
363    /// Array element access: `->0`.
364    Index(u32),
365}
366
367/// Expressions.
368#[derive(Debug, Clone, PartialEq)]
369pub enum Expr {
370    Field(String),
371    /// A table-qualified field reference: `table.field` or `alias.field`.
372    /// Used by join queries to disambiguate columns that appear in multiple
373    /// sources. The single-table read path never emits this variant, so
374    /// existing fast paths keep matching `Expr::Field` unchanged.
375    QualifiedField {
376        qualifier: String,
377        field: String,
378    },
379    Literal(Literal),
380    Param(String),
381    BinaryOp(Box<Expr>, BinOp, Box<Expr>),
382    UnaryOp(UnaryOp, Box<Expr>),
383    FunctionCall(AggFunc, Box<Expr>, AggregateMode),
384    /// Scalar (non-aggregate) function call.
385    ScalarFunc(ScalarFn, Vec<Expr>),
386    Coalesce(Box<Expr>, Box<Expr>),
387    /// `expr in (val1, val2, ...)` or `expr not in (val1, val2, ...)`
388    InList {
389        expr: Box<Expr>,
390        list: Vec<Expr>,
391        negated: bool,
392    },
393    /// `expr [not] in (subquery)` — the subquery is a full QueryExpr
394    /// that produces a single column.
395    InSubquery {
396        expr: Box<Expr>,
397        subquery: Box<QueryExpr>,
398        negated: bool,
399    },
400    /// `[not] exists (subquery)` — the subquery is a full QueryExpr.
401    /// Currently uncorrelated only: the executor runs the subquery once
402    /// before the scan loop and replaces this node with a Bool literal.
403    ExistsSubquery {
404        subquery: Box<QueryExpr>,
405        negated: bool,
406    },
407    /// CASE WHEN ... THEN ... [ELSE ...] END
408    Case {
409        whens: Vec<(Box<Expr>, Box<Expr>)>,
410        else_expr: Option<Box<Expr>>,
411    },
412    /// Window function: `func(args) over (partition ... order ...)`
413    Window {
414        function: WindowFunc,
415        args: Vec<Expr>,
416        mode: AggregateMode,
417        partition_by: Vec<Expr>,
418        order_by: Vec<OrderKey>,
419    },
420    /// Type cast: `cast(expr, "int")` or `cast(expr, "str")` etc.
421    Cast(Box<Expr>, CastType),
422    /// A runtime-materialized literal carrying a concrete Value. Produced only
423    /// during subquery/correlated substitution (post-planning) for values that
424    /// have no Literal form (NULL, datetime, uuid, bytes); never emitted by the
425    /// parser/canonicalizer.
426    ValueLit(Value),
427    /// The `null` literal — produces `Value::Empty`.
428    Null,
429    /// A JSON path access: `base->seg->seg...`. `base` is restricted at parse
430    /// time to `Field`, `QualifiedField`, or (nested) `JsonPath`. Evaluating it
431    /// walks the base `Value::Json` document and scalarizes the addressed node
432    /// (see `eval_expr`); the `segments` are structural (see [`PathSeg`]).
433    JsonPath {
434        base: Box<Expr>,
435        segments: Vec<PathSeg>,
436    },
437}
438
439/// Versioned structural identity for a query JSON path. Unlike the stored
440/// table-local form, this retains a qualified root until binding resolves it.
441#[derive(Debug, Clone, PartialEq, Eq, Hash)]
442pub struct JsonPathIdentityV1 {
443    pub root: JsonPathRootV1,
444    pub segments: Vec<PathSeg>,
445}
446
447#[derive(Debug, Clone, PartialEq, Eq, Hash)]
448pub enum JsonPathRootV1 {
449    Unqualified(String),
450    Qualified { qualifier: String, field: String },
451}
452
453impl JsonPathIdentityV1 {
454    pub const VERSION: u8 = 1;
455
456    pub fn from_expr(expr: &Expr) -> Option<Self> {
457        let Expr::JsonPath { base, segments } = expr else {
458            return None;
459        };
460        let root = match base.as_ref() {
461            Expr::Field(field) => JsonPathRootV1::Unqualified(field.clone()),
462            Expr::QualifiedField { qualifier, field } => JsonPathRootV1::Qualified {
463                qualifier: qualifier.clone(),
464                field: field.clone(),
465            },
466            _ => return None,
467        };
468        Some(Self {
469            root,
470            segments: segments.clone(),
471        })
472    }
473
474    pub fn canonical_bytes(&self) -> Vec<u8> {
475        let mut out = vec![Self::VERSION];
476        match &self.root {
477            JsonPathRootV1::Unqualified(field) => {
478                out.push(1);
479                push_identity_str(&mut out, field);
480            }
481            JsonPathRootV1::Qualified { qualifier, field } => {
482                out.push(2);
483                push_identity_str(&mut out, qualifier);
484                push_identity_str(&mut out, field);
485            }
486        }
487        out.extend_from_slice(&(self.segments.len() as u32).to_le_bytes());
488        for segment in &self.segments {
489            match segment {
490                PathSeg::Key(key) => {
491                    out.push(1);
492                    push_identity_str(&mut out, key);
493                }
494                PathSeg::Index(index) => {
495                    out.push(2);
496                    out.extend_from_slice(&index.to_le_bytes());
497                }
498            }
499        }
500        out
501    }
502
503    pub fn canonical_text(&self) -> String {
504        let mut out = match &self.root {
505            JsonPathRootV1::Unqualified(field) => format!("v1:.{field}"),
506            JsonPathRootV1::Qualified { qualifier, field } => {
507                format!("v1:{qualifier}.{field}")
508            }
509        };
510        for segment in &self.segments {
511            match segment {
512                PathSeg::Key(key) => {
513                    out.push_str("->\"");
514                    push_identity_escaped(&mut out, key);
515                    out.push('"');
516                }
517                PathSeg::Index(index) => {
518                    out.push_str("->");
519                    out.push_str(&index.to_string());
520                }
521            }
522        }
523        out
524    }
525
526    /// Bind an unqualified root, or a qualified root matching `qualifier`, to
527    /// the storage-owned table-local identity used by future expression-index
528    /// catalog entries.
529    pub fn bind_table_local(
530        &self,
531        qualifier: Option<&str>,
532    ) -> Option<powdb_storage::stored_json_path::StoredJsonPathV1> {
533        use powdb_storage::stored_json_path::{StoredJsonPathSegmentV1, StoredJsonPathV1};
534        let column = match &self.root {
535            JsonPathRootV1::Unqualified(field) => field.clone(),
536            JsonPathRootV1::Qualified {
537                qualifier: actual,
538                field,
539            } if qualifier == Some(actual.as_str()) => field.clone(),
540            JsonPathRootV1::Qualified { .. } => return None,
541        };
542        Some(StoredJsonPathV1::new(
543            column,
544            self.segments
545                .iter()
546                .map(|segment| match segment {
547                    PathSeg::Key(key) => StoredJsonPathSegmentV1::Key(key.clone()),
548                    PathSeg::Index(index) => StoredJsonPathSegmentV1::Index(*index),
549                })
550                .collect(),
551        ))
552    }
553}
554
555pub fn expression_output_name(expr: &Expr) -> String {
556    match expr {
557        Expr::Field(field) => field.clone(),
558        Expr::QualifiedField { qualifier, field } => format!("{qualifier}.{field}"),
559        Expr::JsonPath { .. } => JsonPathIdentityV1::from_expr(expr)
560            .map(|path| path.canonical_text())
561            .unwrap_or_else(|| "?".into()),
562        _ => "?".into(),
563    }
564}
565
566fn push_identity_str(out: &mut Vec<u8>, value: &str) {
567    out.extend_from_slice(&(value.len() as u32).to_le_bytes());
568    out.extend_from_slice(value.as_bytes());
569}
570
571fn push_identity_escaped(out: &mut String, value: &str) {
572    for ch in value.chars() {
573        match ch {
574            '"' => out.push_str("\\\""),
575            '\\' => out.push_str("\\\\"),
576            '\n' => out.push_str("\\n"),
577            '\r' => out.push_str("\\r"),
578            '\t' => out.push_str("\\t"),
579            c if c <= '\u{1f}' => {
580                use std::fmt::Write;
581                let _ = write!(out, "\\u{:04x}", c as u32);
582            }
583            c => out.push(c),
584        }
585    }
586}
587
588#[derive(Debug, Clone, PartialEq)]
589pub enum Literal {
590    Int(i64),
591    Float(f64),
592    String(String),
593    Bool(bool),
594}
595
596/// A bound value supplied for a `$N` placeholder in
597/// [`crate::parser::parse_with_params`].
598///
599/// Unlike [`Literal`], this carries a `Null` variant so a parameter can
600/// bind PowQL `null` (substituted as `Token::Null`, not a string). Values
601/// are turned into literal *tokens* before parsing, so an injection-shaped
602/// string is inert data — it can never change the query's shape.
603#[derive(Debug, Clone, PartialEq)]
604pub enum ParamValue {
605    Null,
606    Int(i64),
607    Float(f64),
608    Bool(bool),
609    Str(String),
610}
611
612#[derive(Debug, Clone, Copy, PartialEq)]
613pub enum BinOp {
614    Eq,
615    Neq,
616    Lt,
617    Gt,
618    Lte,
619    Gte,
620    And,
621    Or,
622    Add,
623    Sub,
624    Mul,
625    Div,
626    Like,
627}
628
629#[derive(Debug, Clone, Copy, PartialEq)]
630pub enum UnaryOp {
631    Not,
632    Exists,
633    NotExists,
634    IsNull,
635    IsNotNull,
636}
637
638#[cfg(test)]
639mod json_path_identity_tests {
640    use super::*;
641
642    #[test]
643    fn canonical_path_identity_goldens() {
644        let unquoted = JsonPathIdentityV1 {
645            root: JsonPathRootV1::Unqualified("data".into()),
646            segments: vec![PathSeg::Key("author".into())],
647        };
648        let quoted = JsonPathIdentityV1 {
649            root: JsonPathRootV1::Unqualified("data".into()),
650            segments: vec![PathSeg::Key("author".into())],
651        };
652        assert_eq!(unquoted, quoted);
653        assert_eq!(unquoted.canonical_text(), "v1:.data->\"author\"");
654        assert_eq!(
655            unquoted.canonical_bytes(),
656            vec![
657                1, 1, 4, 0, 0, 0, b'd', b'a', b't', b'a', 1, 0, 0, 0, 1, 6, 0, 0, 0, b'a', b'u',
658                b't', b'h', b'o', b'r',
659            ]
660        );
661
662        let key_zero = JsonPathIdentityV1 {
663            root: JsonPathRootV1::Unqualified("data".into()),
664            segments: vec![PathSeg::Key("0".into())],
665        };
666        let index_zero = JsonPathIdentityV1 {
667            root: JsonPathRootV1::Unqualified("data".into()),
668            segments: vec![PathSeg::Index(0)],
669        };
670        assert_ne!(key_zero.canonical_bytes(), index_zero.canonical_bytes());
671
672        let unicode = JsonPathIdentityV1 {
673            root: JsonPathRootV1::Unqualified("data".into()),
674            segments: vec![PathSeg::Key("café\n\"x\\y".into())],
675        };
676        assert_eq!(unicode.canonical_text(), "v1:.data->\"café\\n\\\"x\\\\y\"");
677    }
678
679    #[test]
680    fn qualified_root_binding_is_explicit() {
681        let qualified = JsonPathIdentityV1 {
682            root: JsonPathRootV1::Qualified {
683                qualifier: "p".into(),
684                field: "data".into(),
685            },
686            segments: vec![PathSeg::Key("age".into())],
687        };
688        assert!(qualified.bind_table_local(Some("other")).is_none());
689        let stored = qualified
690            .bind_table_local(Some("p"))
691            .expect("matching root");
692        assert_eq!(stored.canonical_text(), "v1:.data->\"age\"");
693    }
694}
powdb_query/ast.rs

powdb_query/
ast.rs
