@uwdata/mosaic-sql 0.16.2 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-sql",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "SQL query construction and analysis.",
   "keywords": [
     "sql",
@@ -11,7 +11,7 @@
   "author": "Jeffrey Heer (https://idl.uw.edu)",
   "type": "module",
   "exports": {
-    "types": "./dist/types/index-types.d.ts",
+    "types": "./dist/src/index-types.d.ts",
     "default": "./src/index.js"
   },
   "repository": {
@@ -20,12 +20,8 @@
   },
   "scripts": {
     "prebuild": "rimraf dist && mkdir dist",
-    "build": "npm run types",
-    "types": "tsc",
     "lint": "eslint src test",
-    "test": "vitest run && npm run tsc",
-    "tsc": "tsc -p jsconfig.json",
-    "prepublishOnly": "npm run test && npm run lint && npm run build"
-  },
-  "gitHead": "26d2719f4bcab471d2831145e1f03f39f3509869"
+    "test": "vitest run && tsc",
+    "prepublishOnly": "npm run test && npm run lint && tsc"
+  }
 }

package/src/ast/aggregate.js

@@ -1,8 +1,10 @@
 /**
- * @import { ExprVarArgs } from '../types.js'
+ * @import { ExprVarArgs, OrderByExpr } from '../types.js'
+ * @import { WindowFrameNode } from './window-frame.js'
  */
 import { AGGREGATE } from '../constants.js';
 import { asVerbatim } from '../util/ast.js';
+import { exprList } from '../util/function.js';
 import { isString } from '../util/type-check.js';
 import { ExprNode } from './node.js';
 import { WindowNode } from './window.js';
@@ -14,8 +16,9 @@ export class AggregateNode extends ExprNode {
    * @param {ExprNode[]} args The aggregate function arguments.
    * @param {boolean} [distinct] The distinct flag.
    * @param {ExprNode} [filter] Filter expression.
+   * @param {OrderByExpr} [argOrder] Order by expression.
    */
-  constructor(name, args, distinct, filter) {
+  constructor(name, args, distinct = false, filter = null, argOrder = []) {
     super(AGGREGATE);
     /**
      * The aggregate function name.
@@ -41,6 +44,12 @@ export class AggregateNode extends ExprNode {
      * @readonly
      */
     this.filter = filter;
+    /**
+     * Order by expression for order-sensitive aggregates.
+     * @type {ExprNode[]}
+     * @readonly
+     */
+    this.order = exprList([argOrder]);
   }
 
   /**
@@ -49,7 +58,7 @@ export class AggregateNode extends ExprNode {
    * @returns {AggregateNode} A new aggregate node.
    */
   distinct(isDistinct = true) {
-    return new AggregateNode(this.name, this.args, isDistinct, this.filter);
+    return new AggregateNode(this.name, this.args, isDistinct, this.filter, this.order);
   }
 
   /**
@@ -59,7 +68,16 @@ export class AggregateNode extends ExprNode {
    */
   where(filter) {
     if (isString(filter)) filter = asVerbatim(filter);
-    return new AggregateNode(this.name, this.args, this.isDistinct, filter);
+    return new AggregateNode(this.name, this.args, this.isDistinct, filter, this.order);
+  }
+
+  /**
+   * Return a new derived aggregate function that sorts values prior to aggregation.
+   * @param {OrderByExpr} order The order by expression.
+   * @returns {AggregateNode} A new aggregate node.
+   */
+  argOrder(order) {
+    return new AggregateNode(this.name, this.args, this.isDistinct, this.filter, order);
   }
 
   /**
@@ -88,19 +106,42 @@ export class AggregateNode extends ExprNode {
     return this.window().orderby(...expr);
   }
 
+  /**
+   * Return a new window function over this aggregate with the given frame.
+   * @param {WindowFrameNode} framedef The window frame definition.
+   * @returns {WindowNode} A new window node.
+   */
+  frame(framedef) {
+    return this.window().frame(framedef);
+  }
+
   /**
    * Generate a SQL query string for this node.
    * @returns {string}
    */
   toString() {
-    const { name, args, isDistinct, filter } = this;
-    const dist = isDistinct ? 'DISTINCT ' : '';
-    const arg = args?.length ? args.join(', ') : '*';
+    const { name, args, isDistinct, filter, order } = this;
+    const arg = [
+      isDistinct ? 'DISTINCT' : '',
+      args?.length ? args.join(', ')
+        : name.toLowerCase() === 'count' ?  '*'
+        : '',
+      order.length ? `ORDER BY ${order.join(', ')}` : ''
+    ].filter(x => x).join(' ');
     const filt = filter ? ` FILTER (WHERE ${filter})` : '';
-    return `${name}(${dist}${arg})${filt}`;
+    return `${name}(${arg})${filt}`;
   }
 }
 
+/**
+ * Check if a function name corresponds to an aggregate function.
+ * @param {string} name The function name to check
+ * @returns {boolean} True if a known aggregate function, false otherwise.
+ */
+export function isAggregateFunction(name) {
+  return aggregateNames.includes(name.toLowerCase());
+}
+
 /**
  * An array of known aggregate function names.
  * From https://duckdb.org/docs/sql/functions/aggregates.html.
@@ -124,6 +165,7 @@ export const aggregateNames = [
   'bool_or',
   'corr',
   'count',
+  'count_star',
   'covar_pop',
   'covar_samp',
   'entropy',

package/src/ast/collate.js

@@ -0,0 +1,33 @@
+import { COLLATE } from '../constants.js';
+import { ExprNode } from './node.js';
+
+export class CollateNode extends ExprNode {
+  /**
+   * Instantiate a collate node.
+   * @param {ExprNode} expr The expression to collate.
+   * @param {string} collation The collation type.
+   */
+  constructor(expr, collation) {
+    super(COLLATE);
+    /**
+     * The expression to collate.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this.expr = expr;
+    /**
+     * The collation type.
+     * @type {string}
+     * @readonly
+     */
+    this.collation = collation;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    return `${this.expr} ${COLLATE} ${this.collation}`;
+  }
+}

package/src/ast/from.js

@@ -1,3 +1,4 @@
+/** @import { SampleClauseNode } from './sample.js' */
 import { FROM_CLAUSE } from '../constants.js';
 import { quoteIdentifier } from '../util/string.js';
 import { SQLNode } from './node.js';
@@ -8,9 +9,10 @@ export class FromClauseNode extends SQLNode {
   /**
    * Instantiate a from node.
    * @param {SQLNode} expr The from expression.
-   * @param {string} alias The output name.
+   * @param {string} [alias] The output name.
+   * @param {SampleClauseNode} [sample] The table sample.
    */
-  constructor(expr, alias) {
+  constructor(expr, alias, sample) {
     super(FROM_CLAUSE);
     /**
      * The from expression.
@@ -24,6 +26,12 @@ export class FromClauseNode extends SQLNode {
      * @readonly
      */
     this.alias = alias;
+    /**
+     * The table sample.
+     * @type {SampleClauseNode}
+     * @readonly
+     */
+    this.sample = sample;
   }
 
   /**
@@ -31,10 +39,11 @@ export class FromClauseNode extends SQLNode {
    * @returns {string}
    */
   toString() {
-    const { expr, alias } = this;
+    const { expr, alias, sample } = this;
     const ref = isQuery(expr) ? `(${expr})` : `${expr}`;
-    return alias && !(isTableRef(expr) && expr.table.join('.') === alias)
+    const from = alias && !(isTableRef(expr) && expr.table.join('.') === alias)
       ? `${ref} AS ${quoteIdentifier(alias)}`
       : `${ref}`;
+    return `${from}${sample ? ` TABLESAMPLE ${sample}` : ''}`;
   }
 }

package/src/ast/node.js

@@ -20,6 +20,19 @@ export class SQLNode {
      */
     this.type = type;
   }
+
+  /**
+   * Create a shallow clone of this SQL AST node.
+   * @returns {this} The shallow clone node.
+   */
+  clone() {
+    // @ts-expect-error
+    const clone = new this.constructor();
+    for (const key in this) {
+      clone[key] = this[key];
+    }
+    return clone;
+  }
 }
 
 /**

package/src/ast/query.js

@@ -125,9 +125,11 @@ export class Query extends ExprNode {
     this._with = [];
     /** @type {ExprNode[]} */
     this._orderby = [];
-    /** @type {number} */
+    /** @type {boolean} */
+    this._limitPerc = false;
+    /** @type {ExprNode} */
     this._limit = undefined;
-    /** @type {number} */
+    /** @type {ExprNode} */
     this._offset = undefined;
     /** @type {Query | null} */
     this.cteFor = null;
@@ -143,12 +145,20 @@ export class Query extends ExprNode {
 
   /**
    * Clone this query.
-   * @returns {Query}
+   * @returns {this}
    */
   clone() {
     return this;
   }
 
+  /**
+   * Add a pointer to the query for which this query is a CTE.
+   * @param {Query | null} query
+   */
+  setCteFor(query) {
+    this.cteFor = query;
+  }
+
   /**
    * Add WITH common table expressions (CTEs).
    * @param  {...WithExpr} expr Expressions to add.
@@ -159,7 +169,7 @@ export class Query extends ExprNode {
     const list = [];
     const add = (name, q) => {
       const query = q.clone();
-      query.cteFor = this;
+      query.setCteFor(this);
       list.push(new WithClauseNode(name, query));
     };
     expr.flat().forEach(e => {
@@ -180,23 +190,35 @@ export class Query extends ExprNode {
     return this;
   }
 
+  /**
+   * Set the query result LIMIT as a percentage value.
+   * @param {number | ExprNode} value The limit percentage value.
+   * @returns {this}
+   */
+  limitPercent(value) {
+    this._limitPerc = true;
+    this._limit = asNode(value);
+    return this;
+  }
+
   /**
    * Set the query result LIMIT.
-   * @param {number} value The limit value.
+   * @param {number | ExprNode} value The limit value.
    * @returns {this}
    */
   limit(value) {
-    this._limit = Number.isFinite(value) ? value : undefined;
+    this._limitPerc = false;
+    this._limit = asNode(value);
     return this;
   }
 
   /**
    * Set the query result OFFSET.
-   * @param {number} value The offset value.
+   * @param {number | ExprNode} value The offset value.
    * @returns {this}
    */
   offset(value) {
-    this._offset = Number.isFinite(value) ? value : undefined;
+    this._offset = asNode(value);
     return this;
   }
 }
@@ -251,7 +273,7 @@ export class SelectQuery extends Query {
 
   /**
    * Clone this query.
-   * @returns {SelectQuery}
+   * @returns {this}
    */
   clone() {
     return Object.assign(new SelectQuery(), this);
@@ -278,7 +300,7 @@ export class SelectQuery extends Query {
 
     const keys = new Set(list.map(x => x.alias));
     this._select = this._select
-      .filter(x => !keys.has(x.alias))
+      .filter(x => x.alias && !keys.has(x.alias))
       .concat(list.filter(x => x.expr));
     return this;
   }
@@ -313,6 +335,7 @@ export class SelectQuery extends Query {
     const add = (v, as) => list.push(new FromClauseNode(asTableRef(v), unquote(as)));
     expr.flat().forEach(e => {
       if (e == null) return;
+      else if (e instanceof FromClauseNode) list.push(e);
       else if (isString(e)) add(e, e);
       else if (isTableRef(e)) add(e, e.name);
       else if (isNode(e)) add(e);
@@ -438,7 +461,7 @@ export class SelectQuery extends Query {
   toString() {
     const {
       _with, _select, _distinct, _from, _sample, _where, _groupby,
-      _having, _window, _qualify, _orderby, _limit, _offset
+      _having, _window, _qualify, _orderby, _limitPerc, _limit, _offset
     } = this;
     const sql = [];
 
@@ -484,10 +507,10 @@ export class SelectQuery extends Query {
     if (_orderby.length) sql.push(`ORDER BY ${_orderby.join(', ')}`);
 
     // LIMIT
-    if (Number.isFinite(_limit)) sql.push(`LIMIT ${_limit}`);
+    if (_limit) sql.push(`LIMIT ${_limit}${_limitPerc ? '%' : ''}`);
 
     // OFFSET
-    if (Number.isFinite(_offset)) sql.push(`OFFSET ${_offset}`);
+    if (_offset) sql.push(`OFFSET ${_offset}`);
 
     return sql.join(' ');
   }
@@ -504,9 +527,10 @@ export class DescribeQuery extends SQLNode {
 
   /**
    * Clone this describe query.
-   * @returns {DescribeQuery}
+   * @returns {this}
    */
   clone() {
+    // @ts-expect-error
     return new DescribeQuery(this.query.clone());
   }
 
@@ -539,23 +563,31 @@ export class SetOperation extends Query {
     this.queries = queries;
   }
 
+  /**
+   * Add a pointer to the query for which this query is a CTE.
+   * @param {Query | null} query
+   */
+  setCteFor(query) {
+    super.setCteFor(query);
+    const { queries, cteFor } = this;
+    if (cteFor) queries.forEach(q => q.setCteFor(cteFor));
+  }
+
   /**
    * Return a list of subqueries.
    * @returns {Query[]}
    */
   get subqueries() {
-    const { queries, cteFor } = this;
-    // TODO: revisit this?
-    if (cteFor) queries.forEach(q => q.cteFor = cteFor);
-    return queries;
+    return this.queries;
   }
 
   /**
    * Clone this set operation.
-   * @returns {SetOperation}
+   * @returns {this}
    */
   clone() {
     const { op, queries, ...rest } = this;
+    // @ts-expect-error
     return Object.assign(new SetOperation(op, queries), rest);
   }
 
@@ -564,7 +596,7 @@ export class SetOperation extends Query {
    * @returns {string}
    */
   toString() {
-    const { op, queries, _with, _orderby, _limit, _offset } = this;
+    const { op, queries, _with, _orderby, _limitPerc, _limit, _offset } = this;
     const sql = [];
 
     // WITH
@@ -577,10 +609,10 @@ export class SetOperation extends Query {
     if (_orderby.length) sql.push(`ORDER BY ${_orderby.join(', ')}`);
 
     // LIMIT
-    if (Number.isFinite(_limit)) sql.push(`LIMIT ${_limit}`);
+    if (_limit) sql.push(`LIMIT ${_limit}${_limitPerc ? '%' : ''}`);
 
     // OFFSET
-    if (Number.isFinite(_offset)) sql.push(`OFFSET ${_offset}`);
+    if (_offset) sql.push(`OFFSET ${_offset}`);
 
     return sql.join(' ');
   }

package/src/ast/sample.js

@@ -46,8 +46,8 @@ export class SampleClauseNode extends SQLNode {
 
   toString() {
     const { size, perc, method, seed } = this;
-    const unit = perc ? '%' : ' ROWS';
-    const s = seed != null ? `, ${seed}` : '';
-    return `${size}${unit}${method ? ` (${method}${s})` : ''}`;
+    const m = method ? `${method} ` : '';
+    const s = seed != null ? ` REPEATABLE (${seed})` : '';
+    return `${m}(${size}${perc ? '%' : ' ROWS'})${s}`;
   }
 }

package/src/ast/subquery.js

@@ -0,0 +1,23 @@
+/** @import { Query } from './query.js' */
+import { SCALAR_SUBQUERY } from '../constants.js';
+import { ExprNode } from './node.js';
+
+export class ScalarSubqueryNode extends ExprNode {
+  /**
+   * Instantiate a scalar subquery node.
+   * @param {Query} subquery The scalar subquery.
+   */
+  constructor(subquery) {
+    super(SCALAR_SUBQUERY);
+    /**
+     * The scalar subquery.
+     * @type {Query}
+     * @readonly
+     */
+    this.subquery = subquery;
+  }
+
+  toString() {
+    return `(${this.subquery})`;
+  }
+}

package/src/ast/verbatim.js

@@ -5,8 +5,9 @@ export class VerbatimNode extends ExprNode {
   /**
    * Instantiate a raw node with verbatim content.
    * @param {string} value The verbatim content to include.
+   * @param {string} [hint] A type hint for analyzing verbatim content.
    */
-  constructor(value) {
+  constructor(value, hint) {
     super(VERBATIM);
     /**
      * The verbatim content to include.
@@ -14,6 +15,12 @@ export class VerbatimNode extends ExprNode {
      * @readonly
      */
     this.value = value;
+    /**
+     * A type hint for analyzing verbatim content.
+     * @type {string}
+     * @readonly
+     */
+    this.hint = hint;
   }
 
   /**

package/src/ast/window-frame.js

@@ -0,0 +1,107 @@
+/**
+ * @import { FrameExtent, FrameScope, FrameValue } from '../types.js'
+ */
+import { WINDOW_EXTENT_EXPR, WINDOW_FRAME } from '../constants.js';
+import { isParamLike } from '../util/type-check.js';
+import { isNode, SQLNode } from './node.js';
+import { ParamNode } from './param.js';
+
+/**
+ * @typedef {ROWS | RANGE | GROUPS} FrameType
+ * @typedef {'NO OTHERS' | 'CURRENT ROW' | 'TIES' | 'GROUP'} FrameExclude
+ */
+
+export const ROWS = 'ROWS';
+export const RANGE = 'RANGE';
+export const GROUPS = 'GROUPS';
+export const PRECEDING = 'PRECEDING';
+export const FOLLOWING = 'FOLLOWING';
+export const CURRENT_ROW = 'CURRENT ROW';
+export const UNBOUNDED = 'UNBOUNDED';
+
+export class WindowFrameNode extends SQLNode {
+  /**
+   * Instantiate a window frame definition node.
+   * @param {FrameType} frameType The frame type, one of ROWS, RANGE, or GROUPS.
+   * @param {FrameExtent} extent The window frame extent.
+   * @param {FrameExclude} [exclude] The window frame exclusion criteria.
+   */
+  constructor(frameType, extent, exclude = undefined) {
+    super(WINDOW_FRAME);
+    /**
+     * The frame type, one of ROWS, RANGE, or GROUPS.
+     * @type {FrameType}
+     * @readonly
+     */
+    this.frameType = frameType;
+    /**
+     * The window frame extent.
+     * @type {[any, any] | ParamNode}
+     * @readonly
+     */
+    this.extent = isParamLike(extent) ? new ParamNode(extent) : extent;
+    /**
+     * The window frame exclusion criteria.
+     * @type {FrameExclude}
+     * @readonly
+     */
+    this.exclude = exclude;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    const { frameType, exclude, extent } = this;
+    const [prev, next] = isNode(extent) ? extent.value : extent;
+    const a = asFrameExpr(prev, PRECEDING);
+    const b = asFrameExpr(next, FOLLOWING);
+    return `${frameType} BETWEEN ${a} AND ${b}${exclude ? ` ${exclude}` : ''}`;
+  }
+}
+
+function asFrameExpr(value, scope) {
+  return value instanceof WindowFrameExprNode ? value
+    : value != null && typeof value !== 'number' ? `${value} ${scope}`
+    : value === 0 ? CURRENT_ROW
+    : !(value && Number.isFinite(value)) ? `${UNBOUNDED} ${scope}`
+    : `${Math.abs(value)} ${scope}`;
+}
+
+export class WindowFrameExprNode extends SQLNode {
+  /**
+   * Instantiate a window frame definition node.
+   * @param {FrameScope} scope The frame scope, one of PRECEDING, FOLLOWING, or CURRENT ROW.
+   * @param {FrameValue | null} [expr] The window frame extent expression.
+   */
+  constructor(scope, expr = null) {
+    super(WINDOW_EXTENT_EXPR);
+
+    /**
+     * The window frame extent.
+     * @type {FrameScope}
+     * @readonly
+     */
+    this.scope = scope;
+
+    /**
+     * The window frame extent expression. This value should be null
+     * in the case of current row or unbounded extent values.
+     * @type {FrameValue | null}
+     * @readonly
+     */
+    this.expr = expr;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    const { scope, expr } = this;
+    return scope === CURRENT_ROW
+      ? scope
+      : `${expr ?? UNBOUNDED} ${scope}`;
+  }
+}