@webda/ql 4.0.0-beta.5 → 4.0.0-beta.7

package/lib/query.js

@@ -1,8 +1,9 @@
 import { CharStreams, CommonTokenStream } from "antlr4ts";
 import { AbstractParseTreeVisitor, TerminalNode } from "antlr4ts/tree/index.js";
 import { WebdaQLLexer } from "./WebdaQLLexer.js";
-import { OrderFieldExpressionContext, SubExpressionContext, WebdaQLParserParser } from "./WebdaQLParserParser.js";
-import { WebdaQLError } from "./webdaql-string.js";
+import { CountAllItemContext, CountDistinctItemContext, FieldItemContext, MetricItemContext, OrderFieldExpressionContext, SubExpressionContext, WebdaQLParserParser } from "./WebdaQLParserParser.js";
+import { checkAlias, validateAggregation } from "./aggregation-query.js";
+import { escapeValue, WebdaQLError } from "./webdaql-string.js";
 /**
  * Strip the quotes of a WebdaQL string literal and unescape its contents.
  *
@@ -58,11 +59,14 @@ export function unescapeStringLiteral(literal) {
  * Prepend a condition to an existing query string using AND logic
  *
  * Parses both strings, merges them, and reconstructs the combined query.
- * ORDER BY, LIMIT, and OFFSET clauses from the original query are preserved.
+ * The statement head (`SELECT fields`, `DELETE`, `UPDATE SET ...`) and the ORDER BY, LIMIT, and OFFSET clauses
+ * of the original query are preserved; the condition joins the WHERE part. Both sides keep their own grouping:
+ * `a OR b` merged with `c OR d` is `( a OR b ) AND ( c OR d )`.
  *
- * @param query - existing query string (may include ORDER BY / LIMIT / OFFSET)
- * @param condition - condition to prepend (filter expression only)
+ * @param query - existing query string (a plain filter or a statement, may include ORDER BY / LIMIT / OFFSET)
+ * @param condition - condition to prepend (a plain filter: a statement is refused)
  * @returns merged query string
+ * @throws {SyntaxError} if the condition is a statement, or adds ORDER BY / OFFSET to a DELETE or UPDATE
  *
  * @example
  * ```ts
@@ -99,6 +103,7 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
     defaultResult() {
         // An empty AND return true
         return {
+            type: "SELECT",
             filter: new AndExpression([])
         };
     }
@@ -146,41 +151,167 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
      * @param ctx - the order expression context
      */
     visitOrderExpression(ctx) {
-        this.orderBy = ctx.children
-            ?.filter(c => c instanceof OrderFieldExpressionContext)
+        this.orderBy = (ctx.children ?? [])
+            .filter(c => c instanceof OrderFieldExpressionContext)
             .map((c) => this.visitOrderFieldExpression(c));
     }
     /**
-     * Visit the root `webdaql` rule and build the complete Query
+     * Visit the root `webdaql` rule and build the complete Query: a statement or a plain filter query
+     * @param ctx - the webdaql parse context
+     * @returns the built Query
+     */
+    visitWebdaql(ctx) {
+        const statement = ctx.statement();
+        const filter = ctx.filterQuery();
+        return statement ? this.visitStatement(statement) : filter ? this.visitFilterQuery(filter) : this.defaultResult();
+    }
+    /**
+     * Visit a DELETE, UPDATE or SELECT statement
+     * @param ctx - the statement context
+     * @returns the built Query
+     */
+    visitStatement(ctx) {
+        return this.visit(ctx.getChild(0));
+    }
+    /**
+     * Visit a plain filter query: an implicit SELECT of every field
      *
      * Parses filter expression, ORDER BY, LIMIT, and OFFSET clauses.
      * Returns an empty AND expression (always true) when no filter is present.
-     * @param ctx - the webdaql parse context
+     * @param ctx - the filter query context
      * @returns the built Query
      */
-    visitWebdaql(ctx) {
-        if (ctx.childCount === 1) {
-            // An empty AND return true
-            return {
-                filter: new AndExpression([])
-            };
+    visitFilterQuery(ctx) {
+        return this.buildQuery("SELECT", ctx.expression(), ctx);
+    }
+    /**
+     * Visit `DELETE [WHERE ...] [LIMIT n]`
+     * @param ctx - the DELETE statement context
+     * @returns the built Query
+     */
+    visitDeleteStatement(ctx) {
+        return this.buildQuery("DELETE", ctx.whereClause()?.expression(), ctx);
+    }
+    /**
+     * Visit `UPDATE SET a = v, ... [WHERE ...] [LIMIT n]`
+     * @param ctx - the UPDATE statement context
+     * @returns the built Query
+     */
+    visitUpdateStatement(ctx) {
+        return {
+            ...this.buildQuery("UPDATE", ctx.whereClause()?.expression(), ctx),
+            assignments: ctx
+                .assignmentList()
+                .assignment()
+                .map(a => this.visitAssignment(a))
+        };
+    }
+    /**
+     * Visit a SELECT statement: a field list, or an aggregation when it has metrics or a GROUP BY
+     * @param ctx - the select statement context
+     * @returns the query
+     */
+    visitSelectStatement(ctx) {
+        const query = { ...this.buildQuery("SELECT", ctx.whereClause()?.expression(), ctx) };
+        const { fields, metrics } = this.visitFieldList(ctx.fieldList());
+        query.fields = fields;
+        const groupBy = ctx
+            .groupByExpression()
+            ?.identifier()
+            .map(identifier => identifier.text);
+        if (!Object.keys(metrics).length && groupBy === undefined) {
+            return query;
+        }
+        if (query.continuationToken !== undefined) {
+            throw new WebdaQLError("OFFSET is not supported with GROUP BY or aggregate functions");
         }
-        // To parse offset and limit and order by
-        for (let i = 1; i < ctx.childCount - 1; i++) {
-            this.visit(ctx.getChild(i));
+        const by = groupBy ?? [];
+        if (fields.length !== by.length || fields.some(field => !by.includes(field))) {
+            throw new WebdaQLError("With aggregate functions, the selected fields must be exactly the GROUP BY fields");
+        }
+        query.aggregation = validateAggregation({
+            filter: query.filter,
+            groupBy: by,
+            metrics,
+            orderBy: query.orderBy?.map(order => ({ key: order.field, direction: order.direction })),
+            limit: query.limit
+        });
+        return query;
+    }
+    /**
+     * Read one `field = value` of an UPDATE SET
+     * @param ctx - the assignment context
+     * @returns the assignment
+     */
+    visitAssignment(ctx) {
+        return {
+            field: ctx.identifier().text,
+            value: this.visit(ctx.getChild(2))
+        };
+    }
+    /**
+     * Read the field list of a SELECT: plain fields and aggregate metrics
+     * @param ctx - the field list context
+     * @returns the field paths and the metrics by alias
+     */
+    visitFieldList(ctx) {
+        const fields = [];
+        const metrics = {};
+        const add = (alias, metric) => {
+            // Before assigning: a `__proto__` alias would otherwise change the prototype of `metrics`
+            checkAlias(alias);
+            if (Object.prototype.hasOwnProperty.call(metrics, alias)) {
+                throw new WebdaQLError(`Duplicate metric alias '${alias}'`);
+            }
+            metrics[alias] = metric;
+        };
+        for (const item of ctx.selectItem()) {
+            if (item instanceof FieldItemContext) {
+                fields.push(item.identifier().text);
+            }
+            else if (item instanceof CountAllItemContext) {
+                add(item.identifier().text, { fn: "COUNT" });
+            }
+            else if (item instanceof CountDistinctItemContext) {
+                add(item.identifier(1).text, { fn: "COUNT_DISTINCT", field: item.identifier(0).text });
+            }
+            else if (item instanceof MetricItemContext) {
+                add(item.identifier(1).text, {
+                    fn: item.getChild(0).text,
+                    field: item.identifier(0).text
+                });
+            }
         }
-        // If the first element is a sub expression, it means we have a filter
-        if (ctx.getChild(0) instanceof SubExpressionContext) {
-            return {
-                filter: normalizeFilter(this.visit(ctx.getChild(0).getChild(1)) || new AndExpression([])),
-                limit: this.limit,
-                continuationToken: this.offset,
-                orderBy: this.orderBy
-            };
+        return { fields, metrics };
+    }
+    /**
+     * Visit a parenthesised expression: the inner expression
+     * @param ctx - the sub expression context
+     * @returns the inner expression
+     */
+    visitSubExpression(ctx) {
+        return this.visit(ctx.expression());
+    }
+    /**
+     * Build the Query of a statement or filter query: its condition and its ORDER BY, LIMIT and OFFSET clauses
+     * @param type - the statement type
+     * @param expression - the condition, if any
+     * @param ctx - the statement context holding the optional clauses
+     * @returns the Query
+     */
+    buildQuery(type, expression, ctx) {
+        for (const clause of [
+            "orderExpression" in ctx ? ctx.orderExpression() : undefined,
+            ctx.limitExpression(),
+            "offsetExpression" in ctx ? ctx.offsetExpression() : undefined
+        ]) {
+            if (clause) {
+                this.visit(clause);
+            }
         }
-        // Go down one level - if expression empty it means no expression were provided
         return {
-            filter: normalizeFilter(this.visit(ctx.getChild(0)) || new AndExpression([])),
+            type,
+            filter: normalizeFilter((expression ? this.visit(expression) : undefined) || new AndExpression([])),
             limit: this.limit,
             continuationToken: this.offset,
             orderBy: this.orderBy
@@ -199,7 +330,8 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
     getComparison(ctx) {
         const res = [];
         // eslint-disable-next-line prefer-const
-        let [left, _, right] = ctx.children;
+        let left = ctx.getChild(0);
+        let right = ctx.getChild(2);
         if (right instanceof SubExpressionContext) {
             right = right.getChild(1);
         }
@@ -237,7 +369,9 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
      * @returns the comparison expression
      */
     visitBinaryComparisonExpression(ctx) {
-        const [left, op, right] = ctx.children;
+        const left = ctx.getChild(0);
+        const op = ctx.getChild(1);
+        const right = ctx.getChild(2);
         // @ts-ignore
         return new ComparisonExpression(op.text, left.text, this.visit(right));
     }
@@ -247,7 +381,7 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
      * @returns the array of values
      */
     visitSetExpression(ctx) {
-        return ctx.children.filter((_i, id) => id % 2).map(c => this.visit(c));
+        return (ctx.children ?? []).filter((_i, id) => id % 2).map(c => this.visit(c));
     }
     /**
      * Visit a LIKE expression (e.g. `field LIKE '%pattern_'`)
@@ -255,7 +389,8 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
      * @returns the comparison expression
      */
     visitLikeExpression(ctx) {
-        const [left, _, right] = ctx.children;
+        const left = ctx.getChild(0);
+        const right = ctx.getChild(2);
         const value = this.visit(right);
         return new ComparisonExpression("LIKE", left.text, value);
     }
@@ -265,7 +400,8 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
      * @returns the comparison expression
      */
     visitInExpression(ctx) {
-        const [left, _, right] = ctx.children;
+        const left = ctx.getChild(0);
+        const right = ctx.getChild(2);
         const value = this.visit(right);
         return new ComparisonExpression("IN", left.text, value);
     }
@@ -275,7 +411,8 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
      * @returns the comparison expression
      */
     visitContainsExpression(ctx) {
-        const [left, _, right] = ctx.children;
+        const left = ctx.getChild(0);
+        const right = ctx.getChild(2);
         const value = this.visit(right);
         return new ComparisonExpression("CONTAINS", left.text, value);
     }
@@ -468,19 +605,27 @@ export class ComparisonExpression extends Expression {
      * @override
      */
     eval(target) {
-        const left = ComparisonExpression.getAttributeValue(target, this.attribute);
+        let left = ComparisonExpression.getAttributeValue(target, this.attribute);
+        // WebdaQL has no date literal: a date compared with a string compares as its ISO 8601 form, the way it is
+        // serialized; comparisons with numbers keep the native Date behavior
+        if (left instanceof Date &&
+            !isNaN(left.getTime()) &&
+            this.operator !== "LIKE" &&
+            (typeof this.value === "string" || (Array.isArray(this.value) && this.value.some(v => typeof v === "string")))) {
+            left = left.toISOString();
+        }
         switch (this.operator) {
             case "=":
                 // ignore strong type on purpose
                 return left == this.value;
             case "<=":
-                return left <= this.value;
+                return left <= (this.value ?? 0);
             case ">=":
-                return left >= this.value;
+                return left >= (this.value ?? 0);
             case "<":
-                return left < this.value;
+                return left < (this.value ?? 0);
             case ">":
-                return left > this.value;
+                return left > (this.value ?? 0);
             case "!=":
                 return left != this.value;
             case "LIKE":
@@ -522,7 +667,7 @@ export class ComparisonExpression extends Expression {
             case "boolean":
                 return value.toString().toUpperCase();
         }
-        return value?.toString();
+        return value === null ? "NULL" : value.toString();
     }
     /**
      * Allow subclass to create different display
@@ -801,17 +946,7 @@ export class QueryValidator {
      * @returns the reconstructed query string
      */
     toString() {
-        let res = this.query.filter.toString();
-        if (this.query.orderBy) {
-            res += ` ORDER BY ${this.query.orderBy.map(o => `${o.field} ${o.direction}`).join(", ")}`;
-        }
-        if (this.query.limit) {
-            res += ` LIMIT ${this.query.limit}`;
-        }
-        if (this.query.continuationToken) {
-            res += ` OFFSET "${this.query.continuationToken}"`;
-        }
-        return res.trim();
+        return stringifyQuery(this.query);
     }
     /**
      * Merge another query string into this query
@@ -823,8 +958,15 @@ export class QueryValidator {
      * @param type - logical operator to combine filters (`"AND"` or `"OR"`)
      * @returns `this` for chaining
      */
-    merge(query, type = "AND") {
+    merge(query = "", type = "AND") {
         const adds = new QueryValidator(query);
+        if (adds.query.type !== "SELECT" || adds.query.fields) {
+            throw new SyntaxError(`Only a filter can be merged into a query, not a statement (Query: ${query})`);
+        }
+        if ((this.query.type === "DELETE" || this.query.type === "UPDATE") &&
+            (adds.query.orderBy || adds.query.continuationToken)) {
+            throw new SyntaxError(`${this.query.type} statements take no ORDER BY or OFFSET (Query: ${query})`);
+        }
         // Add additional conditions
         if (adds.hasCondition()) {
             if ((this.query.filter instanceof AndExpression && type === "AND") ||
@@ -836,7 +978,7 @@ export class QueryValidator {
             }
         }
         // Set the limit if overriden
-        if (adds.query.limit) {
+        if (adds.query.limit !== undefined) {
             this.query.limit = adds.query.limit;
         }
         // Set the offset if overriden
@@ -871,11 +1013,10 @@ export class QueryValidator {
      * @returns the full query object
      */
     getQuery() {
-        return {
-            ...this.query,
-            // Use displayTree to get the truely executed query
-            toString: () => this.displayTree()
-        };
+        const query = { ...this.query };
+        // Print the current state of the query, so a caller changing its LIMIT or OFFSET prints the new values
+        query.toString = () => stringifyQuery(query);
+        return query;
     }
     /**
      * Verify if a target fit the expression
@@ -1080,7 +1221,8 @@ export class PartialExpressionBuilder extends ExpressionBuilder {
      * @returns the partial comparison expression
      */
     visitLikeExpression(ctx) {
-        const [left, _, right] = ctx.children;
+        const left = ctx.getChild(0);
+        const right = ctx.getChild(2);
         const value = this.visit(right);
         return new PartialComparisonExpression(this, "LIKE", left.text, value);
     }
@@ -1090,7 +1232,9 @@ export class PartialExpressionBuilder extends ExpressionBuilder {
      * @returns the partial comparison expression
      */
     visitBinaryComparisonExpression(ctx) {
-        const [left, op, right] = ctx.children;
+        const left = ctx.getChild(0);
+        const op = ctx.getChild(1);
+        const right = ctx.getChild(2);
         // @ts-ignore
         return new PartialComparisonExpression(this, op.text, left.text, this.visit(right));
     }
@@ -1100,7 +1244,8 @@ export class PartialExpressionBuilder extends ExpressionBuilder {
      * @returns the partial comparison expression
      */
     visitInExpression(ctx) {
-        const [left, _, right] = ctx.children;
+        const left = ctx.getChild(0);
+        const right = ctx.getChild(2);
         const value = this.visit(right);
         return new PartialComparisonExpression(this, "IN", left.text, value);
     }
@@ -1110,7 +1255,8 @@ export class PartialExpressionBuilder extends ExpressionBuilder {
      * @returns the partial comparison expression
      */
     visitContainsExpression(ctx) {
-        const [left, _, right] = ctx.children;
+        const left = ctx.getChild(0);
+        const right = ctx.getChild(2);
         const value = this.visit(right);
         return new PartialComparisonExpression(this, "CONTAINS", left.text, value);
     }
@@ -1139,12 +1285,331 @@ export class PartialExpressionBuilder extends ExpressionBuilder {
 export function unsanitize(query) {
     return query.replace(/&lt;/g, "<").replace(/&gt;/g, ">");
 }
+/**
+ * Print a query in its canonical form, which parses back to the same query
+ *
+ * - plain filter: `<filter> [ORDER BY ...] [LIMIT n] [OFFSET "token"]`
+ * - `SELECT f1, f2 [WHERE <filter>] [ORDER BY ...] [LIMIT n] [OFFSET "token"]`
+ * - `DELETE [WHERE <filter>] [LIMIT n]`
+ * - `UPDATE SET a = v, ... [WHERE <filter>] [LIMIT n]`
+ *
+ * @param query - the query
+ * @returns the query string
+ */
+export function stringifyQuery(query) {
+    const filter = query.filter.toString();
+    let head = "";
+    if (query.type === "DELETE") {
+        head = "DELETE";
+    }
+    else if (query.type === "UPDATE") {
+        head = `UPDATE SET ${(query.assignments ?? []).map(a => new ComparisonExpression("=", a.field, a.value).toString()).join(", ")}`;
+    }
+    else if (query.aggregation) {
+        const metrics = Object.entries(query.aggregation.metrics).map(([alias, metric]) => {
+            if (metric.fn === "COUNT_DISTINCT") {
+                return `COUNT(DISTINCT ${metric.field}) AS ${alias}`;
+            }
+            return `${metric.fn}(${metric.field ?? "*"}) AS ${alias}`;
+        });
+        head = `SELECT ${[...query.aggregation.groupBy, ...metrics].join(", ")}`;
+    }
+    else if (query.fields) {
+        head = `SELECT ${query.fields.join(", ")}`;
+    }
+    let res = head ? `${head}${filter ? ` WHERE ${filter}` : ""}` : filter;
+    if (query.aggregation?.groupBy.length) {
+        res += ` GROUP BY ${query.aggregation.groupBy.join(", ")}`;
+    }
+    if (query.orderBy?.length) {
+        res += ` ORDER BY ${query.orderBy.map(o => `${o.field} ${o.direction}`).join(", ")}`;
+    }
+    if (query.limit !== undefined) {
+        res += ` LIMIT ${query.limit}`;
+    }
+    if (query.continuationToken) {
+        res += ` OFFSET ${ComparisonExpression.prototype.toStringValue(query.continuationToken)}`;
+    }
+    return res.trim();
+}
+/**
+ * One segment of a field path, as the grammar's identifiers allow it: letters, digits and `_`
+ */
+const FIELD_SEGMENT = /^[A-Za-z0-9_]+$/;
+/**
+ * Check a field path of a query object
+ * @param field - the path, as a string or its segments
+ * @returns the dotted path
+ * @throws {WebdaQLError} when a segment is empty or holds anything but letters, digits and `_`
+ */
+export function checkFieldPath(field) {
+    // Copy first: what is checked is what is printed, whatever the object does on later reads
+    const segments = Array.isArray(field) ? snapshot(field) : typeof field === "string" ? field.split(".") : undefined;
+    if (!segments?.length || segments.some(segment => typeof segment !== "string" || !FIELD_SEGMENT.test(segment))) {
+        throw new WebdaQLError("Invalid field path in WebdaQL query");
+    }
+    return segments.join(".");
+}
+/**
+ * Copy an array of a query object into a plain array, reading each element once
+ * @param value - the array
+ * @returns the copy
+ */
+function snapshot(value) {
+    const length = value.length;
+    const copy = [];
+    for (let i = 0; i < length; i++) {
+        copy.push(value[i]);
+    }
+    return copy;
+}
+/**
+ * Print a single value of a query object
+ * @param value - the value
+ * @returns its WebdaQL literal
+ * @throws {WebdaQLError} for anything but a string, a finite number or a boolean
+ */
+function checkScalar(value) {
+    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+        throw new WebdaQLError(`Invalid value in WebdaQL query: ${typeof value}`);
+    }
+    return escapeValue(value);
+}
+/**
+ * Print an expression of a query object from its data only (never its own toString); every property and array is
+ * read once, so what is checked is what is printed
+ * @param expression - the expression
+ * @param nested - whether the expression is inside a logical expression
+ * @returns the WebdaQL text
+ * @throws {WebdaQLError} for an expression the grammar cannot produce
+ */
+function printExpression(expression, nested) {
+    if (expression instanceof BooleanExpression) {
+        const value = expression.value;
+        if (typeof value === "boolean") {
+            return value ? "TRUE" : "FALSE";
+        }
+        throw new WebdaQLError("Invalid expression in WebdaQL query");
+    }
+    if (expression instanceof AndExpression || expression instanceof OrExpression) {
+        const operator = expression instanceof AndExpression ? "AND" : "OR";
+        const children = expression.children;
+        if (!Array.isArray(children)) {
+            throw new WebdaQLError("Invalid expression in WebdaQL query");
+        }
+        const copy = snapshot(children);
+        if (copy.length === 0) {
+            // An empty AND or OR matches everything
+            return nested ? "TRUE" : "";
+        }
+        const text = copy.map(child => printExpression(child, true)).join(` ${operator} `);
+        return nested ? `( ${text} )` : text;
+    }
+    if (expression instanceof ComparisonExpression) {
+        const attribute = checkFieldPath(expression.attribute);
+        const operator = expression.operator;
+        const value = expression.value;
+        if (typeof operator !== "string") {
+            throw new WebdaQLError("Invalid operator in WebdaQL query");
+        }
+        if (UNARY_COMPARISON_OPERATORS.includes(operator)) {
+            return `${attribute} ${operator}`;
+        }
+        if (operator === "IN") {
+            const values = Array.isArray(value) ? snapshot(value) : undefined;
+            if (!values?.length) {
+                throw new WebdaQLError("Invalid IN values in WebdaQL query");
+            }
+            return `${attribute} IN [${values.map(checkScalar).join(", ")}]`;
+        }
+        if (!["=", "!=", "<", "<=", ">", ">=", "LIKE", "CONTAINS"].includes(operator)) {
+            throw new WebdaQLError(`Invalid operator in WebdaQL query: ${JSON.stringify(operator)}`);
+        }
+        if ((operator === "LIKE" || operator === "CONTAINS") && typeof value !== "string") {
+            throw new WebdaQLError(`${operator} takes a string in WebdaQL query`);
+        }
+        return `${attribute} ${operator} ${checkScalar(value)}`;
+    }
+    throw new WebdaQLError("Invalid expression in WebdaQL query");
+}
+/**
+ * Normalize a query object built or changed by code: every part is checked against what the grammar allows, the
+ * query is printed from its data and parsed again
+ *
+ * Use it before handing a `Query` object received from a caller to a backend: field paths (letters, digits, `_`),
+ * operators, values (strings, finite numbers, booleans), LIMIT (non-negative integer) and OFFSET (string) are
+ * checked, and the result only holds expressions built by the parser.
+ *
+ * @param query - the query object
+ * @returns the same query, as parsed from its canonical text
+ * @throws {WebdaQLError} when a part of the query cannot be written in WebdaQL
+ */
+export function normalizeQuery(query) {
+    if (!query || typeof query !== "object") {
+        throw new WebdaQLError("Invalid WebdaQL query object");
+    }
+    const type = query.type ?? "SELECT";
+    if (typeof type !== "string" || !["SELECT", "DELETE", "UPDATE"].includes(type)) {
+        throw new WebdaQLError(`Invalid statement type in WebdaQL query: ${JSON.stringify(type)}`);
+    }
+    if (query.aggregation !== undefined) {
+        throw new WebdaQLError("Aggregation queries cannot be normalized: use toAggregationQuery");
+    }
+    const filterObject = query.filter;
+    const filter = printExpression(filterObject ?? new AndExpression([]), false);
+    let head = "";
+    if (type === "DELETE") {
+        head = "DELETE";
+    }
+    else if (type === "UPDATE") {
+        const assignments = Array.isArray(query.assignments) ? snapshot(query.assignments) : [];
+        if (assignments.length === 0) {
+            throw new WebdaQLError("UPDATE needs at least one SET assignment");
+        }
+        head = `UPDATE SET ${assignments
+            .map(a => {
+            const field = a?.field;
+            const value = a?.value;
+            return `${checkFieldPath(field)} = ${checkScalar(value)}`;
+        })
+            .join(", ")}`;
+    }
+    else if (query.fields !== undefined) {
+        const fields = Array.isArray(query.fields) ? snapshot(query.fields) : [];
+        if (fields.length === 0) {
+            throw new WebdaQLError("Invalid SELECT field list in WebdaQL query");
+        }
+        head = `SELECT ${fields.map(checkFieldPath).join(", ")}`;
+    }
+    let res = head ? `${head}${filter ? ` WHERE ${filter}` : ""}` : filter;
+    const orderBy = query.orderBy;
+    if (orderBy !== undefined) {
+        if (!Array.isArray(orderBy)) {
+            throw new WebdaQLError("Invalid ORDER BY in WebdaQL query");
+        }
+        const orders = snapshot(orderBy);
+        if (orders.length) {
+            res += ` ORDER BY ${orders
+                .map(o => {
+                const field = o?.field;
+                const direction = o?.direction;
+                if (direction !== "ASC" && direction !== "DESC") {
+                    throw new WebdaQLError("Invalid ORDER BY direction in WebdaQL query");
+                }
+                return `${checkFieldPath(field)} ${direction}`;
+            })
+                .join(", ")}`;
+        }
+    }
+    const limit = query.limit;
+    if (limit !== undefined) {
+        if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 0) {
+            throw new WebdaQLError("Invalid LIMIT in WebdaQL query");
+        }
+        res += ` LIMIT ${limit}`;
+    }
+    const token = query.continuationToken;
+    if (token !== undefined && token !== null) {
+        if (typeof token !== "string") {
+            throw new WebdaQLError("Invalid OFFSET in WebdaQL query");
+        }
+        if (token) {
+            res += ` OFFSET ${escapeValue(token)}`;
+        }
+    }
+    try {
+        return parse(res.trim());
+    }
+    catch (err) {
+        throw new WebdaQLError(`Invalid WebdaQL query object: ${err.message}`);
+    }
+}
+/**
+ * Whether a field path is allowed: listed itself, or nested in a listed field (`address.city` with `address`)
+ * @param field - the field path
+ * @param allowed - the allowed field paths
+ * @returns true when allowed
+ */
+function isAllowedField(field, allowed) {
+    const segments = field.split(".");
+    for (let i = 1; i <= segments.length; i++) {
+        if (allowed.has(segments.slice(0, i).join("."))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Validate the SELECT fields, the aggregation metric fields and the UPDATE SET targets of a query against the
+ * allowed fields
+ *
+ * A dotted path is allowed when it is listed, or when one of its parents is (`profile.email` is allowed by
+ * `profile` or by `profile.email`). GROUP BY paths are the SELECT fields; the field of every aggregation metric
+ * (`SUM(points)`) is checked too, `COUNT(*)` has none. Filter attributes are not checked.
+ *
+ * @param query - parsed query to validate
+ * @param allowedFields - allowed field paths (dot-notation)
+ * @throws {SyntaxError} if a field, a metric field or an assignment target is not allowed
+ */
+export function validateQueryFields(query, allowedFields) {
+    const allowed = new Set(allowedFields);
+    for (const field of query.fields ?? []) {
+        if (!isAllowedField(field, allowed)) {
+            throw new SyntaxError(`Unknown field "${field}". Allowed fields: ${allowedFields.join(", ")}`);
+        }
+    }
+    for (const { field } of query.assignments ?? []) {
+        if (!isAllowedField(field, allowed)) {
+            throw new SyntaxError(`Unknown assignment field "${field}". Allowed fields: ${allowedFields.join(", ")}`);
+        }
+    }
+    for (const [alias, metric] of Object.entries(query.aggregation?.metrics ?? {})) {
+        if (metric.field !== undefined && !isAllowedField(metric.field, allowed)) {
+            throw new SyntaxError(`Unknown field "${metric.field}" in "${alias}". Allowed fields: ${allowedFields.join(", ")}`);
+        }
+    }
+}
+/**
+ * Refuse anything but a plain filter query: DELETE, UPDATE and SELECT with a field list
+ *
+ * Used where a query only selects objects, such as the Query operations exposed to clients. A query built by hand
+ * without `type` is a filter.
+ *
+ * @param query - the parsed query
+ * @throws {WebdaQLError} for a DELETE or UPDATE statement, or a SELECT field list
+ */
+export function assertFilterQuery(query) {
+    if (query.type !== undefined && query.type !== "SELECT") {
+        throw new WebdaQLError(`${query.type} statements are not accepted here: only a filter query is`);
+    }
+    if (query.fields !== undefined) {
+        throw new WebdaQLError("SELECT field lists are not accepted here: only a filter query is");
+    }
+}
 /**
  * Parse a query string into a Query object
+ *
+ * Accepts a plain filter query (an implicit SELECT of every field) or a statement:
+ * - `SELECT f1, f2 [WHERE <condition>] [ORDER BY ...] [LIMIT n] [OFFSET token]`
+ * - `SELECT g1, COUNT(*) AS n, SUM(f) AS s [WHERE <condition>] [GROUP BY g1] [ORDER BY ...] [LIMIT n]`: an
+ *   aggregation (metrics COUNT, COUNT(DISTINCT f), SUM, AVG, MIN, MAX), returned in `aggregation`; the
+ *   selected fields must be the GROUP BY paths, every metric needs an alias, OFFSET is refused
+ * - `DELETE [WHERE <condition>] [LIMIT n]`
+ * - `UPDATE SET a = v, b = v [WHERE <condition>] [LIMIT n]`
+ *
+ * Keywords are uppercase only: `select`, `delete`, `set`, `count`... remain field names.
+ *
  * @param query - the query string to parse
+ * @param allowedFields - when given, SELECT fields, aggregation metric fields and UPDATE SET targets must be in
+ *   this list (see {@link validateQueryFields})
  * @returns the parsed Query object
+ * @throws {SyntaxError} on a grammar error or a field outside `allowedFields`
  */
-export function parse(query) {
-    return new QueryValidator(query).getQuery();
+export function parse(query, allowedFields) {
+    const result = new QueryValidator(query).getQuery();
+    if (allowedFields) {
+        validateQueryFields(result, allowedFields);
+    }
+    return result;
 }
 //# sourceMappingURL=query.js.map