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