@uwdata/mosaic-sql 0.12.2 → 0.14.0

package/src/ast/query.js

@@ -1,3 +1,7 @@
+/**
+ * @import { FilterExpr, FromExpr, GroupByExpr, OrderByExpr, SelectExpr, WithExpr } from '../types.js'
+ * @import { SampleMethod } from './sample.js'
+ */
 import { DESCRIBE_QUERY, SELECT_QUERY, SET_OPERATION } from '../constants.js';
 import { asNode, asTableRef, asVerbatim } from '../util/ast.js';
 import { exprList } from '../util/function.js';
@@ -40,9 +44,18 @@ export function isDescribeQuery(value) {
 }
 
 export class Query extends ExprNode {
+  /**
+   * Create a new WITH clause with the given CTE queries.
+   * @param {...WithExpr} expr The WITH CTE queries.
+   * @returns {WithClause}
+   */
+  static with(...expr) {
+    return new WithClause(...expr);
+  }
+
   /**
    * Create a new select query with the given SELECT expressions.
-   * @param {...import('../types.js').SelectExpr} expr The SELECT expressions.
+   * @param {...SelectExpr} expr The SELECT expressions.
    * @returns {SelectQuery}
    */
   static select(...expr) {
@@ -51,22 +64,13 @@ export class Query extends ExprNode {
 
   /**
    * Create a new select query with the given FROM expressions.
-   * @param {...import('../types.js').FromExpr} expr The FROM expressions.
+   * @param {...FromExpr} expr The FROM expressions.
    * @returns {SelectQuery}
    */
   static from(...expr) {
     return new SelectQuery().from(...expr);
   }
 
-  /**
-   * Create a new select query with the given WITH CTE queries.
-   * @param {...import('../types.js').WithExpr} expr The WITH CTE queries.
-   * @returns {SelectQuery}
-   */
-  static with(...expr) {
-    return new SelectQuery().with(...expr);
-  }
-
   /**
    * Create a new UNION set operation over the given queries.
    * @param {...Query} queries The queries.
@@ -117,6 +121,8 @@ export class Query extends ExprNode {
    */
   constructor(type) {
     super(type);
+    /** @type {WithClauseNode[]} */
+    this._with = [];
     /** @type {ExprNode[]} */
     this._orderby = [];
     /** @type {number} */
@@ -143,9 +149,30 @@ export class Query extends ExprNode {
     return this;
   }
 
+  /**
+   * Add WITH common table expressions (CTEs).
+   * @param  {...WithExpr} expr Expressions to add.
+   * @returns {this}
+   */
+  with(...expr) {
+    /** @type {WithClauseNode[]} */
+    const list = [];
+    const add = (name, q) => {
+      const query = q.clone();
+      query.cteFor = this;
+      list.push(new WithClauseNode(name, query));
+    };
+    expr.flat().forEach(e => {
+      if (e instanceof WithClauseNode) list.push(e);
+      else if (e != null) for (const name in e) add(name, e[name]);
+    });
+    this._with = this._with.concat(list);
+    return this;
+  }
+
   /**
    * Add ORDER BY expressions.
-   * @param  {...import('../types.js').OrderByExpr} expr Expressions to add.
+   * @param  {...OrderByExpr} expr Expressions to add.
    * @returns
    */
   orderby(...expr) {
@@ -180,8 +207,6 @@ export class SelectQuery extends Query {
    */
   constructor() {
     super(SELECT_QUERY);
-    /** @type {WithClauseNode[]} */
-    this._with = [];
     /** @type {SelectClauseNode[]} */
     this._select = [];
     /** @type {FromClauseNode[]} */
@@ -232,29 +257,9 @@ export class SelectQuery extends Query {
     return Object.assign(new SelectQuery(), this);
   }
 
-  /**
-   * Add WITH common table expressions (CTEs).
-   * @param  {...import('../types.js').WithExpr} expr Expressions to add.
-   * @returns {this}
-   */
-  with(...expr) {
-    /** @type {WithClauseNode[]} */
-    const list = [];
-    const add = (name, q) => {
-      const query = q.clone();
-      query.cteFor = this;
-      list.push(new WithClauseNode(name, query));
-    };
-    expr.flat().forEach(e => {
-      if (e != null) for (const name in e) add(name, e[name]);
-    });
-    this._with = this._with.concat(list);
-    return this;
-  }
-
   /**
    * Add SELECT expressions.
-   * @param {...import('../types.js').SelectExpr} expr Expressions to add.
+   * @param {...SelectExpr} expr Expressions to add.
    * @returns {this}
    */
   select(...expr) {
@@ -280,7 +285,7 @@ export class SelectQuery extends Query {
 
   /**
    * Set SELECT expressions, replacing any prior expressions.
-   * @param {...import('../types.js').SelectExpr} expr Expressions to add.
+   * @param {...SelectExpr} expr Expressions to add.
    * @returns {this}
    */
   setSelect(...expr) {
@@ -300,7 +305,7 @@ export class SelectQuery extends Query {
 
   /**
    * Add table FROM expressions.
-   * @param  {...import('../types.js').FromExpr} expr Expressions to add.
+   * @param  {...FromExpr} expr Expressions to add.
    * @returns {this}
    */
   from(...expr) {
@@ -320,7 +325,7 @@ export class SelectQuery extends Query {
 
   /**
    * Set FROM expressions, replacing any prior expressions.
-   * @param {...import('../types.js').FromExpr} expr Expressions to add.
+   * @param {...FromExpr} expr Expressions to add.
    * @returns {this}
    */
   setFrom(...expr) {
@@ -332,7 +337,7 @@ export class SelectQuery extends Query {
    * Set SAMPLE settings.
    * @param {number | SampleClauseNode} value Either a sample clause node
    *  or the sample size as either a row count or percentage.
-   * @param {import('./sample.js').SampleMethod} [method] The sampling method
+   * @param {SampleMethod} [method] The sampling method
    *  to use.
    * @param {number} [seed] The random seed.
    * @returns {this}
@@ -352,7 +357,7 @@ export class SelectQuery extends Query {
 
   /**
    * Add WHERE expressions.
-   * @param  {...import('../types.js').FilterExpr} expr Expressions to add.
+   * @param  {...FilterExpr} expr Expressions to add.
    * @returns {this}
    */
   where(...expr) {
@@ -362,7 +367,7 @@ export class SelectQuery extends Query {
 
   /**
    * Set WHERE expressions, replacing any prior expressions.
-   * @param {...import('../types.js').FilterExpr} expr Expressions to add.
+   * @param {...FilterExpr} expr Expressions to add.
    * @returns {this}
    */
   setWhere(...expr) {
@@ -372,7 +377,7 @@ export class SelectQuery extends Query {
 
   /**
    * Add GROUP BY expressions.
-   * @param  {...import('../types.js').GroupByExpr} expr Expressions to add.
+   * @param  {...GroupByExpr} expr Expressions to add.
    * @returns {this}
    */
   groupby(...expr) {
@@ -382,7 +387,7 @@ export class SelectQuery extends Query {
 
   /**
    * Set GROUP BY expressions, replacing any prior expressions.
-   * @param {...import('../types.js').GroupByExpr} expr Expressions to add.
+   * @param {...GroupByExpr} expr Expressions to add.
    * @returns {this}
    */
   setGroupby(...expr) {
@@ -392,7 +397,7 @@ export class SelectQuery extends Query {
 
   /**
    * Add HAVING expressions.
-   * @param {...import('../types.js').FilterExpr} expr Expressions to add.
+   * @param {...FilterExpr} expr Expressions to add.
    * @returns {this}
    */
   having(...expr) {
@@ -418,7 +423,7 @@ export class SelectQuery extends Query {
 
   /**
    * Add QUALIFY expressions.
-   * @param {...import('../types.js').FilterExpr} expr Expressions to add.
+   * @param {...FilterExpr} expr Expressions to add.
    * @returns {this}
    */
   qualify(...expr) {
@@ -559,10 +564,14 @@ export class SetOperation extends Query {
    * @returns {string}
    */
   toString() {
-    const { op, queries, _orderby, _limit, _offset } = this;
+    const { op, queries, _with, _orderby, _limit, _offset } = this;
+    const sql = [];
+
+    // WITH
+    if (_with.length) sql.push(`WITH ${_with.join(', ')}`);
 
     // SUBQUERIES
-    const sql = [ queries.join(` ${op} `) ];
+    sql.push(queries.join(` ${op} `));
 
     // ORDER BY
     if (_orderby.length) sql.push(`ORDER BY ${_orderby.join(', ')}`);
@@ -576,3 +585,67 @@ export class SetOperation extends Query {
     return sql.join(' ');
   }
 }
+
+class WithClause {
+  /**
+   * Instantiate a new WITH clause instance.
+   * @param {...WithExpr} expr The WITH CTE queries.
+   */
+  constructor(...expr) {
+    this._with = expr;
+  }
+
+  /**
+   * Create a new select query with the given SELECT expressions.
+   * @param {...SelectExpr} expr The SELECT expressions.
+   * @returns {SelectQuery}
+   */
+  select(...expr) {
+    return Query.select(...expr).with(...this._with);
+  }
+
+  /**
+   * Create a new select query with the given FROM expressions.
+   * @param {...FromExpr} expr The FROM expressions.
+   * @returns {SelectQuery}
+   */
+  from(...expr) {
+    return Query.from(...expr).with(...this._with);
+  }
+
+  /**
+   * Create a new UNION set operation over the given queries.
+   * @param {...Query} queries The queries.
+   * @returns {SetOperation}
+   */
+  union(...queries) {
+    return Query.union(...queries).with(...this._with);
+  }
+
+  /**
+   * Create a new UNION ALL set operation over the given queries.
+   * @param {...Query} queries The queries.
+   * @returns {SetOperation}
+   */
+  unionAll(...queries) {
+    return Query.unionAll(...queries).with(...this._with);
+  }
+
+  /**
+   * Create a new INTERSECT set operation over the given queries.
+   * @param {...Query} queries The queries.
+   * @returns {SetOperation}
+   */
+  intersect(...queries) {
+    return Query.intersect(...queries).with(...this._with);
+  }
+
+  /**
+   * Create a new EXCEPT set operation over the given queries.
+   * @param {...Query} queries The queries.
+   * @returns {SetOperation}
+   */
+  except(...queries) {
+    return Query.except(...queries).with(...this._with);
+  }
+}

package/src/ast/window.js

@@ -1,3 +1,7 @@
+/**
+ * @import { ExprVarArgs, WindowFunctionName } from '../types.js'
+ * @import { ParamLike } from '../types.js'
+ */
 import { WINDOW, WINDOW_CLAUSE, WINDOW_DEF, WINDOW_FRAME } from '../constants.js';
 import { exprList } from '../util/function.js';
 import { quoteIdentifier } from '../util/string.js';
@@ -8,7 +12,7 @@ import { ExprNode, isNode, SQLNode } from './node.js';
 import { ParamNode } from './param.js';
 
 /**
- * @typedef {[any, any] | import('../types.js').ParamLike} FrameExtent
+ * @typedef {[any, any] | ParamLike} FrameExtent
  */
 
 export class WindowClauseNode extends SQLNode {
@@ -69,7 +73,7 @@ export class WindowNode extends ExprNode {
 
   /**
    * Return an updated window with the given partitions.
-   * @param {...import('../types.js').ExprVarArgs} expr The partition by criteria.
+   * @param {...ExprVarArgs} expr The partition by criteria.
    * @returns {WindowNode} A new window node.
    */
   partitionby(...expr) {
@@ -78,7 +82,7 @@ export class WindowNode extends ExprNode {
 
   /**
    * Return an updated window with the given ordering.
-   * @param {...import('../types.js').ExprVarArgs} expr The order by criteria.
+   * @param {...ExprVarArgs} expr The order by criteria.
    * @returns {WindowNode} A new window node.
    */
   orderby(...expr) {
@@ -115,7 +119,7 @@ export class WindowNode extends ExprNode {
 export class WindowFunctionNode extends FunctionNode {
   /**
    * Instantiate a window function call node.
-   * @param {import('../types.js').WindowFunctionName} name The function name.
+   * @param {WindowFunctionName} name The function name.
    * @param {ExprNode[]} [args=[]] The function arguments.
    */
   constructor(name, args) {
@@ -170,7 +174,7 @@ export class WindowDefNode extends SQLNode {
 
   /**
    * Return an updated window definition with the given partitions.
-   * @param {...import('../types.js').ExprVarArgs} expr The partition by criteria.
+   * @param {...ExprVarArgs} expr The partition by criteria.
    * @returns {WindowDefNode} A new window definition node.
    */
   partitionby(...expr) {
@@ -179,7 +183,7 @@ export class WindowDefNode extends SQLNode {
 
   /**
    * Return an updated window definition with the given ordering.
-   * @param {...import('../types.js').ExprVarArgs} expr The order by criteria.
+   * @param {...ExprVarArgs} expr The order by criteria.
    * @returns {WindowDefNode} A new window definition node.
    */
   orderby(...expr) {

package/src/ast/with.js

@@ -7,8 +7,12 @@ export class WithClauseNode extends SQLNode {
    * Instantiate a with clause node for a common table expression (CTE).
    * @param {string} name The common table expression (CTE) name.
    * @param {Query} query The common table expression (CTE) query.
+   * @param {boolean | null} [materialized] The common table expression (CTE)
+   *  materialization flag. If `true`, forces materialization of the CTE.
+   *  If `false`, materialization is not performed. Otherwise (for example, if
+   *  `undefined` or `null`), materialization is decided by the database.
    */
-  constructor(name, query) {
+  constructor(name, query, materialized = undefined) {
     super(WITH_CLAUSE);
     /**
      * The common table expression (CTE) name.
@@ -22,9 +26,19 @@ export class WithClauseNode extends SQLNode {
      * @readonly
      */
     this.query = query;
+    /**
+     * The common table expression (CTE) materialization flag.
+     * @type {boolean | null}
+     * @readonly
+     */
+    this.materialized = materialized;
   }
 
   toString() {
-    return `"${this.name}" AS (${this.query})`;
+    const flag = this.materialized;
+    const mat = flag === true ? ' MATERIALIZED'
+      : flag === false ? ' NOT MATERIALIZED'
+      : '';
+    return `"${this.name}" AS${mat} (${this.query})`;
   }
 }