Skip to main content

zero_client/
query.rs

1//! The untyped query builder (`QueryImpl` in
2//! `packages/zql/src/query/query-impl.ts`) and the builder of `where`
3//! conditions (`ExpressionBuilder` in `packages/zql/src/query/expression.ts`).
4//!
5//! The AST is always normalized: each step builds its part of the AST in
6//! normalized form. Misuse that JS reports by throwing from the builder,
7//! such as a negative `limit` or a `limit` inside a junction relationship,
8//! leaves that step out and makes the query invalid: [`AnyQuery::invalid`]
9//! holds JS's message. An unknown relationship is a programming error and
10//! panics.
11
12use crate::ast::*;
13use crate::format::Format;
14use crate::hash::query::hash_of_query_internals;
15use crate::json::{self, Object, Value};
16use crate::schema::{Cardinality, Relationship, RelationshipHop, Schema, ValueType};
17use std::cell::RefCell;
18use std::sync::Arc;
19
20/// The prefix of the aliases the builder gives `exists` subqueries
21/// (`SUBQ_PREFIX` in `packages/zero-protocol/src/ast.ts`).
22pub const SUBQUERY_ALIAS_PREFIX: &str = "zsubq_";
23
24/// The name and arguments of the named query a query was built by.
25#[derive(Clone, Debug, PartialEq)]
26pub struct CustomQueryId {
27    /// The query's name.
28    pub name: String,
29    /// Its arguments.
30    pub args: Vec<Value>,
31}
32
33/// A value taken from the context a query runs in, such as the auth data
34/// (`staticParam` in `packages/zql/src/query/static-param.ts`).
35#[derive(Clone, Debug, PartialEq)]
36pub struct StaticParameter {
37    /// What the value is taken from.
38    pub anchor: Anchor,
39    /// The field of it.
40    pub field: StaticField,
41}
42
43impl StaticParameter {
44    /// The field `field` of `anchor`.
45    pub fn new(anchor: Anchor, field: impl Into<String>) -> Self {
46        StaticParameter {
47            anchor,
48            field: StaticField::Single(field.into()),
49        }
50    }
51
52    /// The value at `path` in `anchor`.
53    pub fn path(anchor: Anchor, path: Vec<String>) -> Self {
54        StaticParameter {
55            anchor,
56            field: StaticField::Path(path),
57        }
58    }
59
60    fn position(&self) -> ValuePosition {
61        ValuePosition::Static {
62            anchor: self.anchor,
63            field: self.field.clone(),
64        }
65    }
66}
67
68/// The options of `exists` and `whereExists`.
69#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
70pub struct ExistsOptions {
71    /// Runs the subquery first and looks up the parents of its rows.
72    pub flip: Option<bool>,
73    /// Lets the server resolve the subquery to a value once.
74    pub scalar: Option<bool>,
75}
76
77/// A query over a table, named by strings.
78#[derive(Clone, Debug)]
79pub struct AnyQuery {
80    schema: Arc<Schema>,
81    table: String,
82    ast: Ast,
83    format: Format,
84    system: System,
85    custom_query_id: Option<CustomQueryId>,
86    /// The two-hop relationship this query is the destination of, if any.
87    current_junction: Option<String>,
88    /// Why the query is invalid: the first misuse JS's builder throws for.
89    invalid: Option<String>,
90}
91
92impl AnyQuery {
93    /// All rows of `table`, for the system `system` (an app uses
94    /// `System::Client`).
95    pub fn new(schema: Arc<Schema>, table: impl Into<String>, system: System) -> Self {
96        let table = table.into();
97        AnyQuery {
98            schema,
99            ast: Ast::new(table.clone()),
100            table,
101            format: Format::default(),
102            system,
103            custom_query_id: None,
104            current_junction: None,
105            invalid: None,
106        }
107    }
108
109    /// The schema the query is built on.
110    pub fn schema(&self) -> &Arc<Schema> {
111        &self.schema
112    }
113
114    /// The table the query reads.
115    pub fn table(&self) -> &str {
116        &self.table
117    }
118
119    /// The query's AST.
120    pub fn ast(&self) -> &Ast {
121        &self.ast
122    }
123
124    /// How the query's view shapes its rows.
125    pub fn format(&self) -> &Format {
126        &self.format
127    }
128
129    /// The system the query is built for.
130    pub fn system(&self) -> System {
131        self.system
132    }
133
134    /// The name and arguments the query is named by, for a named query.
135    pub fn custom_query_id(&self) -> Option<&CustomQueryId> {
136        self.custom_query_id.as_ref()
137    }
138
139    /// Why the query is invalid: the message JS's builder throws.
140    pub fn invalid(&self) -> Option<&str> {
141        self.invalid.as_deref()
142    }
143
144    /// The query's hash as the client and server know it.
145    pub fn hash(&self) -> String {
146        hash_of_query_internals(
147            &self.ast,
148            &crate::decode::JsonCodable::to_json(&self.format),
149            self.system,
150            self.current_junction.as_deref(),
151            self.custom_query_id
152                .as_ref()
153                .map(|c| (c.name.as_str(), Some(c.args.as_slice()))),
154        )
155    }
156
157    fn with(mut self, ast: Ast, format: Option<Format>) -> Self {
158        self.ast = ast;
159        if let Some(format) = format {
160            self.format = format;
161        }
162        self
163    }
164
165    /// This query, unchanged but invalid: a builder step JS throws for.
166    fn invalidated(self, message: impl Into<String>) -> Self {
167        self.with_invalid(Some(message.into()))
168    }
169
170    fn with_invalid(mut self, invalid: Option<String>) -> Self {
171        if self.invalid.is_none() {
172            self.invalid = invalid;
173        }
174        self
175    }
176
177    fn base(&self, table: &str, alias: String, format: Format, junction: Option<&str>) -> Self {
178        let mut ast = Ast::new(table);
179        ast.alias = Some(alias);
180        AnyQuery {
181            schema: self.schema.clone(),
182            table: table.to_owned(),
183            ast,
184            format,
185            system: self.system,
186            custom_query_id: self.custom_query_id.clone(),
187            current_junction: junction.map(str::to_owned),
188            invalid: None,
189        }
190    }
191
192    /// Names the query, as JS's `defineQueries` does: the server runs its own
193    /// query by `name` with `args`, and the client syncs what that returns.
194    pub fn name_and_args(mut self, name: impl Into<String>, args: Vec<Value>) -> Self {
195        self.custom_query_id = Some(CustomQueryId {
196            name: name.into(),
197            args,
198        });
199        self
200    }
201
202    /// At most one row; the view holds the row or nothing rather than a list.
203    pub fn one(self) -> Self {
204        if let Some(m) = self
205            .not_aggregated("one")
206            .or_else(|| self.not_distinct("one"))
207        {
208            return self.invalidated(m);
209        }
210        let mut ast = self.ast.clone();
211        ast.limit = Some(1.0);
212        let mut format = self.format.clone();
213        format.singular = true;
214        self.with(ast, Some(format))
215    }
216
217    /// Rows whose `field` compares to `value` by `op`.
218    pub fn where_(
219        self,
220        field: impl Into<String>,
221        op: SimpleOperator,
222        value: impl Into<Value>,
223    ) -> Self {
224        self.where_condition(cmp_condition(
225            field.into(),
226            op,
227            ValuePosition::Literal(value.into()),
228        ))
229    }
230
231    /// Rows whose `field` compares to a value of the context by `op`.
232    pub fn where_param(
233        self,
234        field: impl Into<String>,
235        op: SimpleOperator,
236        param: &StaticParameter,
237    ) -> Self {
238        self.where_condition(cmp_condition(field.into(), op, param.position()))
239    }
240
241    /// Rows that match the condition `factory` builds.
242    pub fn where_expr(self, factory: impl FnOnce(&ExpressionBuilder) -> Condition) -> Self {
243        let builder = ExpressionBuilder::new(&self);
244        let condition = factory(&builder);
245        let invalid = builder.invalid.into_inner();
246        self.where_condition(condition).with_invalid(invalid)
247    }
248
249    /// Rows that match `condition`, and any earlier `where`.
250    pub fn where_condition(self, condition: Condition) -> Self {
251        let merged = match &self.ast.where_ {
252            Some(w) => and_conditions(vec![w.clone(), condition]),
253            None => condition,
254        };
255        let mut ast = self.ast.clone();
256        ast.where_ = Some(normalize_condition(&simplify_condition(merged)));
257        self.with(ast, None)
258    }
259
260    /// Rows with a related row in `relationship` that `sub` matches.
261    pub fn where_exists(
262        self,
263        relationship: &str,
264        options: ExistsOptions,
265        sub: impl FnOnce(AnyQuery) -> AnyQuery,
266    ) -> Self {
267        self.where_expr(|eb| eb.exists(relationship, options, sub))
268    }
269
270    /// Starts after the row with these columns, or at it when `inclusive`.
271    pub fn start(self, row: Object, inclusive: bool) -> Self {
272        if let Some(m) = self
273            .not_aggregated("start")
274            .or_else(|| self.not_distinct("start"))
275        {
276            return self.invalidated(m);
277        }
278        let mut ast = self.ast.clone();
279        ast.start = Some(Bound {
280            row,
281            exclusive: !inclusive,
282        });
283        self.with(ast, None)
284    }
285
286    /// At most `limit` rows.
287    pub fn limit(self, limit: i64) -> Self {
288        if let Some(m) = self
289            .not_aggregated("limit")
290            .or_else(|| self.not_distinct("limit"))
291        {
292            return self.invalidated(m);
293        }
294        if limit < 0 {
295            return self.invalidated("Limit must be non-negative");
296        }
297        if i32::try_from(limit).is_err() {
298            return self.invalidated("Limit must be an integer");
299        }
300        if let Some(j) = &self.current_junction {
301            let m = format!(
302                "Limit is not supported in junction relationships yet. Junction relationship being limited: {j}"
303            );
304            return self.invalidated(m);
305        }
306        let mut ast = self.ast.clone();
307        ast.limit = Some(limit as f64);
308        self.with(ast, None)
309    }
310
311    /// Orders the rows by `field`, after any earlier `order_by`; the primary
312    /// key breaks ties.
313    pub fn order_by(self, field: impl Into<String>, direction: Direction) -> Self {
314        let field = field.into();
315        if let Some(j) = &self.current_junction {
316            let m = format!(
317                "Order by is not supported in junction relationships yet. Junction relationship being ordered: {j}"
318            );
319            return self.invalidated(m);
320        }
321        if let Some(group_by) = &self.ast.group_by
322            && let Some(m) = not_group_column(&field, group_by)
323        {
324            return self.invalidated(m);
325        }
326        let mut ast = self.ast.clone();
327        ast.order_by
328            .get_or_insert_with(Vec::new)
329            .push(OrderPart { field, direction });
330        self.with(ast, None)
331    }
332
333    /// Includes the rows of `relationship`, as `sub` shapes them.
334    pub fn related(self, relationship: &str, sub: impl FnOnce(AnyQuery) -> AnyQuery) -> Self {
335        assert!(
336            !relationship.starts_with(SUBQUERY_ALIAS_PREFIX),
337            "Relationship names may not start with \"{SUBQUERY_ALIAS_PREFIX}\". That is a reserved prefix."
338        );
339        if let Some(m) = self.not_distinct("related") {
340            return self.invalidated(m);
341        }
342        let hops = self.relationship_hops(relationship);
343        let mut ast = self.ast.clone();
344        let mut format = self.format.clone();
345        match hops.as_slice() {
346            [hop] => {
347                let q = sub(self.base(
348                    &hop.dest_schema,
349                    relationship.to_owned(),
350                    singular(hop),
351                    None,
352                ));
353                if let Some(m) = q
354                    .invalid
355                    .clone()
356                    .or_else(|| q.not_grouped_subquery("related"))
357                {
358                    return self.invalidated(m);
359                }
360                // The builder and the name mapper read a `related` under an
361                // aggregate as a junction's destination, so a direct one
362                // can't nest one.
363                if q.format.aggregate.is_some() && q.ast.related.is_some() {
364                    return self.invalidated(
365                        "an aggregate relationship does not support related() on its subquery",
366                    );
367                }
368                // A relationship's aggregate lives on its correlated
369                // subquery, not on the subquery's AST, which would reduce
370                // itself to a scalar too.
371                let mut subquery = q.ast;
372                subquery.aggregate = None;
373                insert_related(
374                    &mut ast.related,
375                    CorrelatedSubquery {
376                        correlation: correlation(hop),
377                        subquery: Box::new(subquery),
378                        system: Some(self.system),
379                        hidden: None,
380                        aggregate: q.format.aggregate.clone(),
381                    },
382                );
383                format.set_relationship(relationship, q.format);
384            }
385            [first, second] => {
386                let q = sub(self.base(
387                    &second.dest_schema,
388                    relationship.to_owned(),
389                    singular(second),
390                    Some(relationship),
391                ));
392                if let Some(m) = q
393                    .invalid
394                    .clone()
395                    .or_else(|| q.not_grouped_subquery("related"))
396                {
397                    return self.invalidated(m);
398                }
399                if let Some(aggregate) = q.format.aggregate.clone() {
400                    // An aggregate over a junction. A `where` on the
401                    // destination is fine; nesting and bounds are not.
402                    if q.ast.related.is_some() || q.ast.limit.is_some() || q.ast.start.is_some() {
403                        return self.invalidated(
404                            "an aggregate over a junction relationship does not yet support related/limit/start on the destination",
405                        );
406                    }
407                    let mut dest = q.ast;
408                    dest.aggregate = None;
409                    let dest_csq = CorrelatedSubquery {
410                        correlation: correlation(second),
411                        subquery: Box::new(dest),
412                        system: Some(self.system),
413                        hidden: None,
414                        aggregate: None,
415                    };
416                    let mut junction = Ast::new(first.dest_schema.clone());
417                    junction.alias = Some(relationship.to_owned());
418                    let is_count = aggregate.fn_ == AggregateFunction::Count;
419                    if is_count {
420                        // A count over the junction rows whose destination
421                        // exists (where the server applies its read
422                        // permissions), never reading the destination.
423                        junction.where_ =
424                            Some(normalize_condition(&Condition::CorrelatedSubquery {
425                                related: dest_csq,
426                                op: CorrelatedSubqueryOperator::Exists,
427                                flip: None,
428                                scalar: None,
429                            }));
430                    } else {
431                        // sum, avg, min and max need the destination's
432                        // field: the builder lifts it onto the junction row.
433                        junction.related = Some(vec![dest_csq]);
434                    }
435                    insert_related(
436                        &mut ast.related,
437                        CorrelatedSubquery {
438                            correlation: correlation(first),
439                            subquery: Box::new(junction),
440                            system: Some(self.system),
441                            hidden: None,
442                            aggregate: Some(if is_count {
443                                Aggregate::new(AggregateFunction::Count)
444                            } else {
445                                aggregate
446                            }),
447                        },
448                    );
449                    format.set_relationship(relationship, q.format);
450                } else {
451                    let mut junction = Ast::new(first.dest_schema.clone());
452                    junction.alias = Some(relationship.to_owned());
453                    junction.related = Some(vec![CorrelatedSubquery {
454                        correlation: correlation(second),
455                        subquery: Box::new(q.ast),
456                        system: Some(self.system),
457                        hidden: None,
458                        aggregate: None,
459                    }]);
460                    insert_related(
461                        &mut ast.related,
462                        CorrelatedSubquery {
463                            correlation: correlation(first),
464                            subquery: Box::new(junction),
465                            system: Some(self.system),
466                            hidden: Some(true),
467                            aggregate: None,
468                        },
469                    );
470                    format.set_relationship(relationship, q.format);
471                }
472            }
473            _ => panic!("Invalid relationship {relationship}"),
474        }
475        self.with(ast, Some(format))
476    }
477
478    /// `#exists`: the condition `exists(relationship)` adds, and why the
479    /// subquery is invalid, if it is.
480    fn exists_condition(
481        &self,
482        relationship: &str,
483        options: ExistsOptions,
484        sub: impl FnOnce(AnyQuery) -> AnyQuery,
485    ) -> (Condition, Option<String>) {
486        let hops = self.relationship_hops(relationship);
487        let exists = |related, scalar| Condition::CorrelatedSubquery {
488            related,
489            op: CorrelatedSubqueryOperator::Exists,
490            flip: options.flip,
491            scalar,
492        };
493        match hops.as_slice() {
494            [hop] => {
495                let q = sub(self.base(
496                    &hop.dest_schema,
497                    format!("{SUBQUERY_ALIAS_PREFIX}{relationship}"),
498                    Format::default(),
499                    None,
500                ));
501                let invalid = q.invalid.clone().or_else(|| q.not_exists_subquery());
502                let related = CorrelatedSubquery {
503                    correlation: correlation(hop),
504                    subquery: Box::new(q.ast),
505                    system: Some(self.system),
506                    hidden: None,
507                    aggregate: None,
508                };
509                (exists(related, options.scalar), invalid)
510            }
511            [first, second] => {
512                let q = sub(self.base(
513                    &second.dest_schema,
514                    format!("{SUBQUERY_ALIAS_PREFIX}zhidden_{relationship}"),
515                    Format::default(),
516                    Some(relationship),
517                ));
518                let invalid = q.invalid.clone().or_else(|| q.not_exists_subquery());
519                let inner = exists(
520                    CorrelatedSubquery {
521                        correlation: correlation(second),
522                        subquery: Box::new(q.ast),
523                        system: Some(self.system),
524                        hidden: None,
525                        aggregate: None,
526                    },
527                    options.scalar,
528                );
529                let mut junction = Ast::new(first.dest_schema.clone());
530                junction.alias = Some(format!("{SUBQUERY_ALIAS_PREFIX}{relationship}"));
531                junction.where_ = Some(normalize_condition(&inner));
532                // The junction hop carries `flip` but not `scalar`, as in JS.
533                let related = CorrelatedSubquery {
534                    correlation: correlation(first),
535                    subquery: Box::new(junction),
536                    system: Some(self.system),
537                    hidden: None,
538                    aggregate: None,
539                };
540                (exists(related, None), invalid)
541            }
542            _ => panic!("Invalid relationship {relationship}"),
543        }
544    }
545
546    // Aggregates and groupings.
547
548    /// The number of rows: a query of one value rather than rows.
549    pub fn count(self) -> Self {
550        self.aggregate(AggregateFunction::Count, None, None)
551    }
552
553    /// The sum of `field`'s non-null values; null when there are none.
554    pub fn sum(self, field: impl Into<String>) -> Self {
555        self.aggregate(AggregateFunction::Sum, Some(field.into()), None)
556    }
557
558    /// The sum of the numbers at a JSON path in the `json` column `column`.
559    pub fn sum_json(self, column: impl Into<String>, path: Vec<JsonPathSegment>) -> Self {
560        self.aggregate(AggregateFunction::Sum, Some(column.into()), Some(path))
561    }
562
563    /// The average of `field`'s non-null values; null when there are none.
564    pub fn avg(self, field: impl Into<String>) -> Self {
565        self.aggregate(AggregateFunction::Avg, Some(field.into()), None)
566    }
567
568    /// Reduces the query to the average of the numbers at `path` in the JSON
569    /// `column`.
570    pub fn avg_json(self, column: impl Into<String>, path: Vec<JsonPathSegment>) -> Self {
571        self.aggregate(AggregateFunction::Avg, Some(column.into()), Some(path))
572    }
573
574    /// The least of `field`'s non-null values; null when there are none.
575    pub fn min(self, field: impl Into<String>) -> Self {
576        self.aggregate(AggregateFunction::Min, Some(field.into()), None)
577    }
578
579    /// The least number or string at a JSON path; numbers sort first.
580    pub fn min_json(self, column: impl Into<String>, path: Vec<JsonPathSegment>) -> Self {
581        self.aggregate(AggregateFunction::Min, Some(column.into()), Some(path))
582    }
583
584    /// The greatest of `field`'s non-null values; null when there are none.
585    pub fn max(self, field: impl Into<String>) -> Self {
586        self.aggregate(AggregateFunction::Max, Some(field.into()), None)
587    }
588
589    /// Reduces the query to the greatest value at `path` in the JSON `column`.
590    pub fn max_json(self, column: impl Into<String>, path: Vec<JsonPathSegment>) -> Self {
591        self.aggregate(AggregateFunction::Max, Some(column.into()), Some(path))
592    }
593
594    /// `#aggregate`. On a top-level query the view holds the value; in a
595    /// `related` subquery the relationship does.
596    fn aggregate(
597        self,
598        fn_: AggregateFunction,
599        field: Option<String>,
600        path: Option<Vec<JsonPathSegment>>,
601    ) -> Self {
602        let name = fn_.as_str();
603        if let Some(m) = self.not_aggregated(name) {
604            return self.invalidated(m);
605        }
606        // A count of a distinct() counts its rows. A groupBy() has its
607        // aggregate already.
608        let distinct = self.ast.group_by.clone();
609        if distinct.is_some()
610            && (fn_ != AggregateFunction::Count || self.ast.aggregate.is_some())
611            && let Some(m) = self.not_distinct(name)
612        {
613            return self.invalidated(m);
614        }
615        // The server runs a named query's own definition, so the aggregate
616        // would never reach it.
617        if let Some(c) = &self.custom_query_id {
618            let m = format!(
619                "{name}() cannot be applied to the named query \"{}\": put it in the query's definition",
620                c.name
621            );
622            return self.invalidated(m);
623        }
624        if let (Some(path), Some(field)) = (&path, &field)
625            && let Some(m) = invalid_json_path(field, path)
626        {
627            return self.invalidated(m);
628        }
629        let aggregate = match distinct {
630            Some(columns) => Aggregate {
631                distinct: Some(columns),
632                ..Aggregate::new(fn_)
633            },
634            None => Aggregate {
635                field,
636                path,
637                ..Aggregate::new(fn_)
638            },
639        };
640        let mut ast = self.ast.clone();
641        ast.group_by = None;
642        ast.aggregate = Some(aggregate.clone());
643        let mut format = self.format.clone();
644        format.singular = true;
645        format.aggregate = Some(aggregate);
646        self.with(ast, Some(format))
647    }
648
649    /// The distinct combinations of `columns`' values, as `SELECT DISTINCT`:
650    /// rows of those columns. `count()` after it counts the combinations.
651    pub fn distinct(self, columns: Vec<String>) -> Self {
652        if let Some(m) = self.not_groupable("distinct", &columns) {
653            return self.invalidated(m);
654        }
655        let mut ast = self.ast.clone();
656        ast.group_by = Some(columns);
657        self.with(ast, None)
658    }
659
660    /// Groups the rows by `columns`, as `GROUP BY`; an aggregate of the
661    /// result gives one row per group, with the value under the function's
662    /// name.
663    pub fn group_by(self, columns: Vec<String>) -> AnyGroupedQuery {
664        let invalid = self.not_groupable("groupBy", &columns);
665        AnyGroupedQuery {
666            query: self,
667            columns,
668            invalid,
669        }
670    }
671
672    /// `groupAggregate`: the rows of `groupBy(columns)` reduced by `fn_`.
673    fn group_aggregate(
674        self,
675        columns: Vec<String>,
676        fn_: AggregateFunction,
677        field: Option<String>,
678        path: Option<Vec<JsonPathSegment>>,
679    ) -> Self {
680        let name = fn_.as_str();
681        if columns.iter().any(|c| c == name) {
682            return self.invalidated(format!(
683                "groupBy(): the column \"{name}\" has the same name as the {name}() value"
684            ));
685        }
686        if let (Some(path), Some(field)) = (&path, &field)
687            && let Some(m) = invalid_json_path(field, path)
688        {
689            return self.invalidated(m);
690        }
691        let mut ast = self.ast.clone();
692        ast.group_by = Some(columns);
693        ast.aggregate = Some(Aggregate {
694            field,
695            path,
696            ..Aggregate::new(fn_)
697        });
698        self.with(ast, None)
699    }
700
701    /// `#assertNotAggregated`: a bound goes in the same AST fields before or
702    /// after an aggregate, so it must come first.
703    fn not_aggregated(&self, method: &str) -> Option<String> {
704        let aggregate = self.format.aggregate.as_ref()?;
705        Some(format!(
706            "{method}() must come before {}(): it bounds the rows the aggregate reduces",
707            aggregate.fn_.as_str()
708        ))
709    }
710
711    /// `#assertNotDistinct`.
712    fn not_distinct(&self, method: &str) -> Option<String> {
713        self.ast.group_by.as_ref()?;
714        let kind = if self.ast.aggregate.is_some() {
715            "groupBy()"
716        } else {
717            "distinct()"
718        };
719        Some(format!("{method}() does not support {kind} yet"))
720    }
721
722    /// `#assertGroupable`.
723    fn not_groupable(&self, method: &str, columns: &[String]) -> Option<String> {
724        if let Some(m) = self
725            .not_aggregated(method)
726            .or_else(|| self.not_distinct(method))
727        {
728            return Some(m);
729        }
730        if let Some(c) = &self.custom_query_id {
731            return Some(format!(
732                "{method}() cannot be applied to the named query \"{}\": put it in the query's definition",
733                c.name
734            ));
735        }
736        if columns.is_empty() {
737            return Some(format!("{method}() needs at least one column"));
738        }
739        let table_columns = self.schema.tables.get(&self.table).map(|t| &t.columns);
740        for (i, column) in columns.iter().enumerate() {
741            let Some(column_schema) = table_columns.and_then(|c| c.get(column)) else {
742                return Some(format!(
743                    "{method}(): \"{column}\" is not a column of \"{}\"",
744                    self.table
745                ));
746            };
747            if column_schema.type_ == ValueType::Json {
748                return Some(format!(
749                    "{method}() does not support the json column \"{column}\""
750                ));
751            }
752            if columns.iter().position(|c| c == column) != Some(i) {
753                return Some(format!("{method}(): \"{column}\" is named twice"));
754            }
755            if is_synthetic_column(column) {
756                return Some(format!(
757                    "{method}(): \"{column}\" is the name of a synthetic column, which a grouped row has too"
758                ));
759            }
760        }
761        if self.ast.limit.is_some() || self.ast.start.is_some() {
762            return Some(format!(
763                "{method}() does not support limit(), start() or one() yet"
764            ));
765        }
766        if self.ast.related.is_some() {
767            return Some(format!("{method}() does not support related() yet"));
768        }
769        for part in self.ast.order_by.iter().flatten() {
770            if let Some(m) = not_group_column(&part.field, columns) {
771                return Some(m);
772            }
773        }
774        None
775    }
776
777    /// `assertSubqueryNotGrouped`.
778    fn not_grouped_subquery(&self, method: &str) -> Option<String> {
779        let distinct = self
780            .ast
781            .aggregate
782            .as_ref()
783            .is_some_and(|a| a.distinct.is_some());
784        if self.ast.group_by.is_none() && !distinct {
785            return None;
786        }
787        let kind = if self.ast.group_by.is_some() && self.ast.aggregate.is_some() {
788            "groupBy()"
789        } else {
790            "distinct()"
791        };
792        Some(format!("{method}() does not support a {kind} subquery yet"))
793    }
794
795    fn not_exists_subquery(&self) -> Option<String> {
796        if self.ast.aggregate.is_some() {
797            return Some("exists() does not support an aggregate subquery".to_owned());
798        }
799        self.not_grouped_subquery("exists")
800    }
801
802    fn relationship_hops(&self, relationship: &str) -> Relationship {
803        let Some(hops) = self.schema.relationship(&self.table, relationship) else {
804            panic!("Invalid relationship {}.{relationship}", self.table);
805        };
806        for hop in hops {
807            assert!(
808                !hop.source_field.is_empty() && hop.source_field.len() == hop.dest_field.len(),
809                "Invalid relationship {}.{relationship}",
810                self.table
811            );
812        }
813        hops.clone()
814    }
815}
816
817/// A query grouped by columns, waiting for the aggregate that reduces each
818/// group (`GroupedQuery`).
819#[derive(Clone, Debug)]
820pub struct AnyGroupedQuery {
821    query: AnyQuery,
822    columns: Vec<String>,
823    invalid: Option<String>,
824}
825
826impl AnyGroupedQuery {
827    fn reduce(
828        self,
829        fn_: AggregateFunction,
830        field: Option<String>,
831        path: Option<Vec<JsonPathSegment>>,
832    ) -> AnyQuery {
833        match self.invalid {
834            Some(m) => self.query.invalidated(m),
835            None => self.query.group_aggregate(self.columns, fn_, field, path),
836        }
837    }
838
839    /// One row per group: its columns and `count`.
840    pub fn count(self) -> AnyQuery {
841        self.reduce(AggregateFunction::Count, None, None)
842    }
843
844    /// Each group's sum of `field`.
845    pub fn sum(self, field: impl Into<String>) -> AnyQuery {
846        self.reduce(AggregateFunction::Sum, Some(field.into()), None)
847    }
848
849    /// Each group's sum of the numbers at `path` in the JSON `column`.
850    pub fn sum_json(self, column: impl Into<String>, path: Vec<JsonPathSegment>) -> AnyQuery {
851        self.reduce(AggregateFunction::Sum, Some(column.into()), Some(path))
852    }
853
854    /// Each group's average of `field`.
855    pub fn avg(self, field: impl Into<String>) -> AnyQuery {
856        self.reduce(AggregateFunction::Avg, Some(field.into()), None)
857    }
858
859    /// Each group's average of the numbers at `path` in the JSON `column`.
860    pub fn avg_json(self, column: impl Into<String>, path: Vec<JsonPathSegment>) -> AnyQuery {
861        self.reduce(AggregateFunction::Avg, Some(column.into()), Some(path))
862    }
863
864    /// Each group's least value of `field`.
865    pub fn min(self, field: impl Into<String>) -> AnyQuery {
866        self.reduce(AggregateFunction::Min, Some(field.into()), None)
867    }
868
869    /// Each group's least value at `path` in the JSON `column`.
870    pub fn min_json(self, column: impl Into<String>, path: Vec<JsonPathSegment>) -> AnyQuery {
871        self.reduce(AggregateFunction::Min, Some(column.into()), Some(path))
872    }
873
874    /// Each group's greatest value of `field`.
875    pub fn max(self, field: impl Into<String>) -> AnyQuery {
876        self.reduce(AggregateFunction::Max, Some(field.into()), None)
877    }
878
879    /// Each group's greatest value at `path` in the JSON `column`.
880    pub fn max_json(self, column: impl Into<String>, path: Vec<JsonPathSegment>) -> AnyQuery {
881        self.reduce(AggregateFunction::Max, Some(column.into()), Some(path))
882    }
883}
884
885/// Builds the conditions of a `where` (`ExpressionBuilder` in
886/// `packages/zql/src/query/expression.ts`).
887pub struct ExpressionBuilder<'a> {
888    query: &'a AnyQuery,
889    /// The first misuse JS's builder throws for, for `where`.
890    invalid: RefCell<Option<String>>,
891}
892
893impl<'a> ExpressionBuilder<'a> {
894    fn new(query: &'a AnyQuery) -> Self {
895        ExpressionBuilder {
896            query,
897            invalid: RefCell::new(None),
898        }
899    }
900
901    fn record(&self, message: String) {
902        let mut invalid = self.invalid.borrow_mut();
903        if invalid.is_none() {
904            *invalid = Some(message);
905        }
906    }
907
908    /// `field` compares to `value` by `op`.
909    pub fn cmp(
910        &self,
911        field: impl Into<String>,
912        op: SimpleOperator,
913        value: impl Into<Value>,
914    ) -> Condition {
915        cmp_condition(field.into(), op, ValuePosition::Literal(value.into()))
916    }
917
918    /// `field` compares to a value of the context by `op`.
919    pub fn cmp_param(
920        &self,
921        field: impl Into<String>,
922        op: SimpleOperator,
923        param: &StaticParameter,
924    ) -> Condition {
925        cmp_condition(field.into(), op, param.position())
926    }
927
928    /// A value inside the `json` column `column`, for [`Self::cmp_json`]:
929    /// `path` is object keys and array indices, applied in order. At least
930    /// one segment is needed, and an index must be at most
931    /// [`MAX_JSON_PATH_INDEX`].
932    pub fn json(&self, column: impl Into<String>, path: Vec<JsonPathSegment>) -> JsonPathReference {
933        let column = column.into();
934        if let Some(m) = invalid_json_path(&column, &path) {
935            self.record(m);
936        }
937        JsonPathReference { column, path }
938    }
939
940    /// Compares the value at a JSON path with a value of the same JSON type;
941    /// a value of another type never equals it. An `IN` list must hold
942    /// values of one type.
943    pub fn cmp_json(
944        &self,
945        reference: &JsonPathReference,
946        op: SimpleOperator,
947        value: impl Into<Value>,
948    ) -> Condition {
949        let value = value.into();
950        if matches!(op, SimpleOperator::In | SimpleOperator::NotIn)
951            && let Value::Array(list) = &value
952            && !is_homogeneous(list)
953        {
954            self.record(format!(
955                "{} against a JSON path requires a list of values of one type",
956                op.as_str()
957            ));
958        }
959        Condition::Simple {
960            op,
961            left: reference.position(),
962            right: ValuePosition::Literal(value),
963        }
964    }
965
966    /// The value at the JSON path compares to a value of the context by `op`.
967    pub fn cmp_json_param(
968        &self,
969        reference: &JsonPathReference,
970        op: SimpleOperator,
971        param: &StaticParameter,
972    ) -> Condition {
973        Condition::Simple {
974            op,
975            left: reference.position(),
976            right: param.position(),
977        }
978    }
979
980    /// Compares two literals, neither of them a column.
981    pub fn cmp_lit(
982        &self,
983        left: impl Into<Value>,
984        op: SimpleOperator,
985        right: impl Into<Value>,
986    ) -> Condition {
987        Condition::Simple {
988            op,
989            left: ValuePosition::Literal(left.into()),
990            right: ValuePosition::Literal(right.into()),
991        }
992    }
993
994    /// Compares a value of the context with a literal.
995    pub fn cmp_lit_param(
996        &self,
997        left: &StaticParameter,
998        op: SimpleOperator,
999        right: impl Into<Value>,
1000    ) -> Condition {
1001        Condition::Simple {
1002            op,
1003            left: left.position(),
1004            right: ValuePosition::Literal(right.into()),
1005        }
1006    }
1007
1008    /// Rows that every condition matches.
1009    pub fn and(&self, conditions: Vec<Condition>) -> Condition {
1010        and_conditions(conditions)
1011    }
1012
1013    /// Rows that any condition matches.
1014    pub fn or(&self, conditions: Vec<Condition>) -> Condition {
1015        or_conditions(conditions)
1016    }
1017
1018    /// Rows that `condition` doesn't match.
1019    pub fn not(&self, condition: Condition) -> Condition {
1020        negate_condition(condition)
1021    }
1022
1023    /// Whether a related row in `relationship` matches `sub`.
1024    pub fn exists(
1025        &self,
1026        relationship: &str,
1027        options: ExistsOptions,
1028        sub: impl FnOnce(AnyQuery) -> AnyQuery,
1029    ) -> Condition {
1030        let (condition, invalid) = self.query.exists_condition(relationship, options, sub);
1031        if let Some(m) = invalid {
1032            self.record(m);
1033        }
1034        condition
1035    }
1036}
1037
1038/// A value inside a `json` column, made by [`ExpressionBuilder::json`]
1039/// (`ColumnRef` in `packages/zql/src/query/expression.ts`).
1040#[derive(Clone, Debug, PartialEq)]
1041pub struct JsonPathReference {
1042    /// The JSON column.
1043    pub column: String,
1044    /// The path in its value.
1045    pub path: Vec<JsonPathSegment>,
1046}
1047
1048impl JsonPathReference {
1049    fn position(&self) -> ValuePosition {
1050        ValuePosition::Json {
1051            column: self.column.clone(),
1052            path: self.path.clone(),
1053        }
1054    }
1055}
1056
1057/// `TRUE`: an empty AND.
1058pub const TRUE_CONDITION: Condition = Condition::And(Vec::new());
1059/// `FALSE`: an empty OR.
1060pub const FALSE_CONDITION: Condition = Condition::Or(Vec::new());
1061
1062fn is_always_true(c: &Condition) -> bool {
1063    matches!(c, Condition::And(c) if c.is_empty())
1064}
1065
1066fn is_always_false(c: &Condition) -> bool {
1067    matches!(c, Condition::Or(c) if c.is_empty())
1068}
1069
1070fn cmp_condition(field: String, op: SimpleOperator, right: ValuePosition) -> Condition {
1071    Condition::Simple {
1072        op,
1073        left: ValuePosition::Column(field),
1074        right,
1075    }
1076}
1077
1078/// `and(...)`: drops the always-true conditions; one left is itself.
1079fn and_conditions(conditions: Vec<Condition>) -> Condition {
1080    let mut expressions: Vec<Condition> = conditions
1081        .into_iter()
1082        .filter(|c| !is_always_true(c))
1083        .collect();
1084    if expressions.len() == 1 {
1085        return expressions.pop().expect("one");
1086    }
1087    if expressions.iter().any(is_always_false) {
1088        return FALSE_CONDITION;
1089    }
1090    Condition::And(expressions)
1091}
1092
1093/// `or(...)`: drops the always-false conditions; one left is itself.
1094fn or_conditions(conditions: Vec<Condition>) -> Condition {
1095    let mut expressions: Vec<Condition> = conditions
1096        .into_iter()
1097        .filter(|c| !is_always_false(c))
1098        .collect();
1099    if expressions.len() == 1 {
1100        return expressions.pop().expect("one");
1101    }
1102    if expressions.iter().any(is_always_true) {
1103        return TRUE_CONDITION;
1104    }
1105    Condition::Or(expressions)
1106}
1107
1108/// `not`: pushes the negation down to the leaves (De Morgan).
1109fn negate_condition(condition: Condition) -> Condition {
1110    match condition {
1111        Condition::And(c) => Condition::Or(c.into_iter().map(negate_condition).collect()),
1112        Condition::Or(c) => Condition::And(c.into_iter().map(negate_condition).collect()),
1113        Condition::CorrelatedSubquery {
1114            related,
1115            op,
1116            flip,
1117            scalar,
1118        } => Condition::CorrelatedSubquery {
1119            related,
1120            op: match op {
1121                CorrelatedSubqueryOperator::Exists => CorrelatedSubqueryOperator::NotExists,
1122                CorrelatedSubqueryOperator::NotExists => CorrelatedSubqueryOperator::Exists,
1123            },
1124            flip,
1125            scalar,
1126        },
1127        Condition::Simple { op, left, right } => Condition::Simple {
1128            op: op.negated(),
1129            left,
1130            right,
1131        },
1132    }
1133}
1134
1135impl SimpleOperator {
1136    /// The operator that matches exactly the rows this one does not.
1137    pub fn negated(self) -> SimpleOperator {
1138        use SimpleOperator::*;
1139        match self {
1140            Eq => Ne,
1141            Ne => Eq,
1142            Lt => Ge,
1143            Gt => Le,
1144            Ge => Lt,
1145            Le => Gt,
1146            In => NotIn,
1147            NotIn => In,
1148            Like => NotLike,
1149            NotLike => Like,
1150            Ilike => NotIlike,
1151            NotIlike => Ilike,
1152            Is => IsNot,
1153            IsNot => Is,
1154        }
1155    }
1156}
1157
1158/// `simplifyCondition` (`packages/zql/src/query/expression.ts`).
1159pub fn simplify_condition(c: Condition) -> Condition {
1160    let (is_and, conditions) = match c {
1161        Condition::And(c) => (true, c),
1162        Condition::Or(c) => (false, c),
1163        c => return c,
1164    };
1165    if conditions.len() == 1 {
1166        return simplify_condition(conditions.into_iter().next().expect("one"));
1167    }
1168    let mut flattened = Vec::with_capacity(conditions.len());
1169    for c in conditions.into_iter().map(simplify_condition) {
1170        match (is_and, c) {
1171            (true, Condition::And(inner)) | (false, Condition::Or(inner)) => {
1172                flattened.extend(inner)
1173            }
1174            (_, c) => flattened.push(c),
1175        }
1176    }
1177    if is_and {
1178        if flattened.iter().any(is_always_false) {
1179            return FALSE_CONDITION;
1180        }
1181        Condition::And(flattened)
1182    } else {
1183        if flattened.iter().any(is_always_true) {
1184            return TRUE_CONDITION;
1185        }
1186        Condition::Or(flattened)
1187    }
1188}
1189
1190/// `insertRelated`: adds `subquery` to a normalized `related`, after the
1191/// entries it compares equal to.
1192fn insert_related(related: &mut Option<Vec<CorrelatedSubquery>>, subquery: CorrelatedSubquery) {
1193    let related = related.get_or_insert_with(Vec::new);
1194    let mut i = related.len();
1195    while i > 0 && cmp_related(&related[i - 1], &subquery).is_gt() {
1196        i -= 1;
1197    }
1198    related.insert(i, subquery);
1199}
1200
1201fn singular(hop: &RelationshipHop) -> Format {
1202    Format {
1203        singular: hop.cardinality == Cardinality::One,
1204        ..Format::default()
1205    }
1206}
1207
1208fn correlation(hop: &RelationshipHop) -> Correlation {
1209    Correlation {
1210        parent_field: hop.source_field.clone(),
1211        child_field: hop.dest_field.clone(),
1212    }
1213}
1214
1215/// `#assertGroupColumn`.
1216fn not_group_column(column: &str, columns: &[String]) -> Option<String> {
1217    if columns.iter().any(|c| c == column) {
1218        return None;
1219    }
1220    let names: Vec<String> = columns
1221        .iter()
1222        .map(|c| json::stringify(&Value::String(c.clone())))
1223        .collect();
1224    Some(format!(
1225        "orderBy(\"{column}\"): the rows can only be ordered by the grouped columns ({})",
1226        names.join(", ")
1227    ))
1228}
1229
1230/// `makeColumnRef`'s checks of a JSON path.
1231fn invalid_json_path(column: &str, path: &[JsonPathSegment]) -> Option<String> {
1232    if path.is_empty() {
1233        return Some(format!(
1234            "json('{column}') requires at least one path segment"
1235        ));
1236    }
1237    path.iter().find_map(|s| match s {
1238        JsonPathSegment::Index(i) if *i > MAX_JSON_PATH_INDEX => Some(format!(
1239            "Invalid JSON path segment {i} in json('{column}', ...): a numeric segment is an array index and must be a non-negative integer no larger than {MAX_JSON_PATH_INDEX}"
1240        )),
1241        _ => None,
1242    })
1243}
1244
1245/// `isSyntheticColumn` (`packages/zql/src/ivm/aggregate.ts`): the columns
1246/// the aggregate operators add to a row.
1247fn is_synthetic_column(column: &str) -> bool {
1248    matches!(
1249        column,
1250        "_0_key" | "_0_value" | "_0_sum" | "_0_count" | "_0_rows"
1251    )
1252}
1253
1254#[cfg(test)]
1255mod tests {
1256    use super::*;
1257
1258    /// `issue.labels` through the junction `issueLabel`, as in the zql test
1259    /// schema.
1260    fn schema() -> Arc<Schema> {
1261        let text = r#"{
1262          "tables": {
1263            "issue": {"name": "issue", "columns": {"id": {"type": "string"}}, "primaryKey": ["id"]},
1264            "issueLabel": {"name": "issueLabel", "columns": {"issueId": {"type": "string"}, "labelId": {"type": "string"}}, "primaryKey": ["issueId", "labelId"]},
1265            "label": {"name": "label", "columns": {"id": {"type": "string"}}, "primaryKey": ["id"]}
1266          },
1267          "relationships": {"issue": {"labels": [
1268            {"sourceField": ["id"], "destField": ["issueId"], "destSchema": "issueLabel", "cardinality": "many"},
1269            {"sourceField": ["labelId"], "destField": ["id"], "destSchema": "label", "cardinality": "many"}
1270          ]}}
1271        }"#;
1272        Arc::new(Schema::from_json(&json::parse(text).unwrap()).unwrap())
1273    }
1274
1275    /// No vector reaches these: JS's generator never bounds or orders a
1276    /// junction's destination.
1277    #[test]
1278    fn junction_destinations_take_no_limit_or_order() {
1279        let q = AnyQuery::new(schema(), "issue", System::Client);
1280        let limited = q.clone().related("labels", |l| l.limit(1));
1281        assert_eq!(
1282            limited.invalid(),
1283            Some(
1284                "Limit is not supported in junction relationships yet. Junction relationship being limited: labels"
1285            )
1286        );
1287        let ordered = q
1288            .clone()
1289            .related("labels", |l| l.order_by("id", Direction::Asc).limit(1));
1290        assert_eq!(
1291            ordered.invalid(),
1292            Some(
1293                "Order by is not supported in junction relationships yet. Junction relationship being ordered: labels"
1294            )
1295        );
1296        // The step JS throws for is left out; the rest of the query stands.
1297        let unbound = q.clone().limit(-1).limit(2);
1298        assert_eq!(unbound.invalid(), Some("Limit must be non-negative"));
1299        assert_eq!(unbound.ast().limit, Some(2.0));
1300        assert_eq!(q.related("labels", |l| l).invalid(), None);
1301    }
1302}