@uwdata/mosaic-sql 0.16.2 → 0.18.0

package/src/{constants.js → constants.ts}

@@ -8,6 +8,7 @@ export const ORDER_BY = 'ORDER_BY';
 export const CAST = 'CAST';
 export const CASE = 'CASE';
 export const WHEN = 'WHEN';
+export const COLLATE = 'COLLATE';
 
 export const UNARY_OPERATOR = 'UNARY';
 export const UNARY_POSTFIX_OPERATOR = 'UNARY_POSTFIX';
@@ -20,8 +21,10 @@ export const IN_OPERATOR = 'IN';
 export const FUNCTION = 'FUNCTION';
 export const AGGREGATE = 'AGGREGATE';
 export const WINDOW = 'WINDOW';
+export const WINDOW_FUNCTION = 'WINDOW_FUNCTION';
 export const WINDOW_DEF = 'WINDOW_DEF';
 export const WINDOW_FRAME = 'WINDOW_FRAME';
+export const WINDOW_EXTENT_EXPR = 'WINDOW_EXTENT_EXPR';
 
 export const EXPRESSION = 'EXPRESSION';
 export const FRAGMENT = 'FRAGMENT';
@@ -29,16 +32,12 @@ export const VERBATIM = 'VERBATIM';
 export const PARAM = 'PARAM';
 
 export const WITH_CLAUSE = 'WITH_CLAUSE';
+export const WINDOW_CLAUSE = 'WINDOW_CLAUSE';
 export const SELECT_CLAUSE = 'SELECT_CLAUSE';
 export const FROM_CLAUSE = 'FROM_CLAUSE';
-export const WHERE_CLAUSE = 'WHERE_CLAUSE';
 export const SAMPLE_CLAUSE = 'SAMPLE_CLAUSE';
-export const GROUPBY_CLAUSE = 'GROUPBY_CLAUSE';
-export const HAVING_CLAUSE = 'HAVING_CLAUSE';
-export const WINDOW_CLAUSE = 'WINDOW_CLAUSE';
-export const QUALIFY_CLAUSE = 'QUALIFY_CLAUSE';
-export const ORDERBY_CLAUSE = 'ORDERBY_CLAUSE';
 
 export const SELECT_QUERY = 'SELECT_QUERY';
 export const DESCRIBE_QUERY = 'DESCRIBE_QUERY';
 export const SET_OPERATION = 'SET_OPERATION';
+export const SCALAR_SUBQUERY = 'SCALAR_SUBQUERY';

package/src/functions/aggregate.ts

@@ -0,0 +1,344 @@
+import type { ExprValue } from '../types.js';
+import { aggFn } from '../util/function.js';
+
+/**
+ * Compute an arg_max aggregate.
+ * @param y The argument to return.
+ * @param x The expression to maximize.
+ * @returns A SQL aggregate function call.
+ */
+export function argmax(y: ExprValue, x: ExprValue) {
+  return aggFn('arg_max', y, x);
+}
+
+/**
+ * Compute an arg_min aggregate.
+ * @param y The argument to return.
+ * @param x The expression to minimize.
+ * @returns A SQL aggregate function call.
+ */
+export function argmin(y: ExprValue, x: ExprValue) {
+  return aggFn('arg_min', y, x);
+}
+
+/**
+ * Compute an array aggregation.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function arrayAgg(expr: ExprValue) {
+  return aggFn('array_agg', expr);
+}
+
+/**
+ * Compute an average aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function avg(expr: ExprValue) {
+  return aggFn('avg', expr);
+}
+
+/**
+ * Compute a correlation aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function corr(x: ExprValue, y: ExprValue) {
+  return aggFn('corr', x, y);
+}
+
+/**
+ * Compute a count aggregate.
+ * @param [expr] An optional expression
+ *  to count. If specified, only non-null expression values are counted.
+ *  If omitted, all rows within a group are counted.
+ * @returns A SQL aggregate function call.
+ */
+export function count(expr?: ExprValue) {
+  return aggFn('count', expr);
+}
+
+/**
+ * Compute a sample covariance aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function covariance(x: ExprValue, y: ExprValue) {
+  return aggFn('covar_samp', x, y);
+}
+
+/**
+ * Compute a population covariance aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function covarPop(x: ExprValue, y: ExprValue) {
+  return aggFn('covar_pop', x, y);
+}
+
+/**
+ * Compute an entropy aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function entropy(expr: ExprValue) {
+  return aggFn('entropy', expr);
+}
+
+/**
+ * Compute a first aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function first(expr: ExprValue) {
+  return aggFn('first', expr);
+}
+
+/**
+ * Compute a geomean aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function geomean(expr: ExprValue) {
+  return aggFn('geomean', expr);
+}
+
+/**
+ * Compute a sample kurtosis aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function kurtosis(expr: ExprValue) {
+  return aggFn('kurtosis', expr);
+}
+
+/**
+ * Compute a median absolute deviation (MAD) aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function mad(expr: ExprValue) {
+  return aggFn('mad', expr);
+}
+
+/**
+ * Compute a maximum aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function max(expr: ExprValue) {
+  return aggFn('max', expr);
+}
+
+/**
+ * Compute a median aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function median(expr: ExprValue) {
+  return aggFn('median', expr);
+}
+
+/**
+ * Compute a minimum aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function min(expr: ExprValue) {
+  return aggFn('min', expr);
+}
+
+/**
+ * Compute a mode aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function mode(expr: ExprValue) {
+  return aggFn('mode', expr);
+}
+
+/**
+ * Compute a last aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function last(expr: ExprValue) {
+  return aggFn('last', expr);
+}
+
+/**
+ * Compute a product aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function product(expr: ExprValue) {
+  return aggFn('product', expr);
+}
+
+/**
+ * Compute a quantile aggregate.
+ * @param expr The expression to aggregate.
+ * @param p The quantile value.
+ * @returns A SQL aggregate function call.
+ */
+export function quantile(expr: ExprValue, p: ExprValue) {
+  return aggFn('quantile', expr, p);
+}
+
+/**
+ * Compute a linear regression reg_avgX aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrAvgX(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_avgx', x, y);
+}
+
+/**
+ * Compute a linear regression reg_avgY aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrAvgY(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_avgy', x, y);
+}
+
+/**
+ * Compute a linear regression count aggregate.
+ * This returns the count of rows where both x and y are non-null.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrCount(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_count', x, y);
+}
+
+/**
+ * Compute a linear regression intercept aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrIntercept(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_intercept', x, y);
+}
+
+/**
+ * Compute a linear regression R^2 aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrR2(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_r2', x, y);
+}
+
+/**
+ * Compute a linear regression regr_sxx aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrSXX(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_sxx', x, y);
+}
+
+/**
+ * Compute a linear regression regr_sxy aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrSXY(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_sxy', x, y);
+}
+
+/**
+ * Compute a linear regression regr_syy aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrSYY(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_syy', x, y);
+}
+
+/**
+ * Compute a linear regression slope aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrSlope(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_slope', x, y);
+}
+
+/**
+ * Compute a skewness aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function skewness(expr: ExprValue) {
+  return aggFn('skewness', expr);
+}
+
+/**
+ * Compute a sample standard deviation aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function stddev(expr: ExprValue) {
+  return aggFn('stddev', expr);
+}
+
+/**
+ * Compute a population standard deviation aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function stddevPop(expr: ExprValue) {
+  return aggFn('stddev_pop', expr);
+}
+
+/**
+ * Compute a string aggregation.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function stringAgg(expr: ExprValue) {
+  return aggFn('string_agg', expr);
+}
+
+/**
+ * Compute a sum aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function sum(expr: ExprValue) {
+  return aggFn('sum', expr);
+}
+
+/**
+ * Compute a sample variance aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function variance(expr: ExprValue) {
+  return aggFn('var_samp', expr);
+}
+
+/**
+ * Compute a population variance aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function varPop(expr: ExprValue) {
+  return aggFn('var_pop', expr);
+}

package/src/functions/{case.js → case.ts}

@@ -1,6 +1,4 @@
-/**
- * @import { ExprValue } from '../types.js'
- */
+import type { ExprValue } from '../types.js';
 import { CaseNode, WhenNode } from '../ast/case.js';
 import { asNode } from '../util/ast.js';
 
@@ -9,12 +7,11 @@ import { asNode } from '../util/ast.js';
  * acts like a ternary conditional (if, then, else). If no arguments are
  * provided, the chained `when` and `else` methods can be used to to complete
  * a conditional statement with WHEN/THEN and ELSE expressions.
- * @param {ExprValue} [when] A conditional WHEN expression.
- * @param {ExprValue} [then] A THEN value expression.
- * @param {ExprValue} [other] An ELSE expression.
- * @returns {CaseNode}
+ * @param when A conditional WHEN expression.
+ * @param then A THEN value expression.
+ * @param other An ELSE expression.
  */
-export function cond(when, then, other) {
+export function cond(when?: ExprValue, then?: ExprValue, other?: ExprValue) {
   return when
     ? new CaseNode(undefined, [new WhenNode(asNode(when), asNode(then))], asNode(other))
     : new CaseNode();

package/src/functions/{cast.js → cast.ts}

@@ -3,37 +3,33 @@ import { asNode } from '../util/ast.js';
 
 /**
  * Perform a type cast.
- * @param {*} expr The expression to type cast.
- * @param {string} type The type to cast to.
- * @returns {CastNode}
+ * @param expr The expression to type cast.
+ * @param type The type to cast to.
  */
-export function cast(expr, type) {
+export function cast(expr: unknown, type: string) {
   return new CastNode(asNode(expr), type);
 }
 
 /**
  * Cast an expression to a 32-bit integer type.
- * @param {*} expr The expression to type cast.
- * @returns {CastNode}
+ * @param expr The expression to type cast.
  */
-export function int32(expr) {
+export function int32(expr: unknown) {
   return cast(expr, 'INTEGER');
 }
 
 /**
  * Cast an expression to a 32-bit floating point number type.
- * @param {*} expr The expression to type cast.
- * @returns {CastNode}
+ * @param expr The expression to type cast.
  */
-export function float32(expr) {
+export function float32(expr: unknown) {
   return cast(expr, 'FLOAT');
 }
 
 /**
  * Cast an expression to a 64-bit floating point number type.
- * @param {*} expr The expression to type cast.
- * @returns {CastNode}
+ * @param expr The expression to type cast.
  */
-export function float64(expr) {
+export function float64(expr: unknown) {
   return cast(expr, 'DOUBLE');
 }

package/src/functions/collate.ts

@@ -0,0 +1,13 @@
+import type { ExprValue } from '../types.js';
+import { CollateNode } from '../ast/collate.js';
+import { asNode } from '../util/ast.js';
+
+/**
+ * Indicate ascending sort order for an expression.
+ * @param expr The expression to collate.
+ * @param collation The collation type, such as
+ *  'NOCASE', 'NOACCENT', 'NFC', or locale-specific collations.
+ */
+export function collate(expr: ExprValue, collation: string) {
+  return new CollateNode(asNode(expr), collation);
+}

package/src/functions/{column.js → column.ts}

@@ -1,8 +1,6 @@
-/**
- * @import { ColumnRefNode } from '../ast/column-ref.js'
- * @import { TableRefNode } from '../ast/table-ref.js'
- * @import { ParamLike } from '../types.js'
- */
+import type { ColumnRefNode } from '../ast/column-ref.js';
+import type { TableRefNode } from '../ast/table-ref.js';
+import type { ParamLike } from '../types.js';
 import { ColumnParamNode } from '../ast/column-param.js';
 import { ColumnNameRefNode } from '../ast/column-ref.js';
 import { ParamNode } from '../ast/param.js';
@@ -11,12 +9,13 @@ import { isParamLike } from '../util/type-check.js';
 
 /**
  * Create a column reference.
- * @param {string | ParamLike} name The column name,
- *  as a string or as a dynamic parameter.
- * @param {string | string[] | TableRefNode} [table] The table reference.
- * @returns {ColumnRefNode}
+ * @param name The column name, as a string or as a dynamic parameter.
+ * @param table The table reference.
  */
-export function column(name, table) {
+export function column(
+  name: string | ParamLike,
+  table?: string | string[] | TableRefNode
+): ColumnRefNode {
   const tref = asTableRef(table);
   return isParamLike(name)
     ? new ColumnParamNode(new ParamNode(name), tref)

package/src/functions/{cte.js → cte.ts}

@@ -1,16 +1,19 @@
-/** @import { Query } from '../ast/query.js' */
+import type { Query } from '../ast/query.js';
 import { WithClauseNode } from '../ast/with.js';
 
 /**
  * Create a common table expression (CTE) to include within a WITH clause.
- * @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)
+ * @param name The common table expression (CTE) name.
+ * @param query The common table expression (CTE) query.
+ * @param 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.
- * @returns {WithClauseNode}
  */
-export function cte(name, query, materialized) {
+export function cte(
+  name: string,
+  query: Query,
+  materialized: boolean | null = null
+) {
   return new WithClauseNode(name, query, materialized);
 }

package/src/functions/datetime.ts

@@ -0,0 +1,50 @@
+import type { ExprValue } from '../types.js';
+import { asNode } from '../util/ast.js';
+import { fn } from '../util/function.js';
+import { interval } from './interval.js';
+
+/**
+ * Given a date/time value, return the milliseconds since the UNIX epoch.
+ * @param {ExprValue} expr The date/time expression.
+ */
+export function epoch_ms(expr: ExprValue) {
+  return fn('epoch_ms', expr);
+}
+
+/**
+ * Perform data binning according to the provided interval unit and steps.
+ * @param expr The date/time expression to bin.
+ * @param unit The datetime interval unit to bin by.
+ * @param steps The number of interval steps.
+ */
+export function dateBin(expr: ExprValue, unit: string, steps: number = 1) {
+  return fn('time_bucket', interval(unit, steps), expr);
+}
+
+/**
+ * Map date/times to a month value, all within the same year for comparison.
+ * The resulting value is still date-typed.
+ * @param expr The date/time expression.
+ */
+export function dateMonth(expr: ExprValue) {
+  return fn('make_date', 2012, fn('month', expr), 1);
+}
+
+/**
+ * Map date/times to a month and day value, all within the same year for
+ * comparison. The resulting value is still date-typed.
+ * @param expr The date/time expression.
+ */
+export function dateMonthDay(expr: ExprValue) {
+  const d = asNode(expr);
+  return fn('make_date', 2012, fn('month', d), fn('day', d));
+}
+
+/**
+ * Map date/times to a day of the month value, all within the same year and month
+ * for comparison. The resulting value is still date-typed.
+ * @param expr The date/time expression.
+ */
+export function dateDay(expr: ExprValue) {
+  return fn('make_date', 2012, 1, fn('day', expr));
+}

package/src/functions/interval.ts

@@ -0,0 +1,74 @@
+import { IntervalNode } from '../ast/interval.js';
+
+/**
+ * Create a new interval.
+ * @param unit The interval unit, such as day or year.
+ * @param steps The number of interval unit steps.
+ */
+export function interval(unit: string, steps: number) {
+  return new IntervalNode(unit, steps);
+}
+
+/**
+ * Create a new years interval.
+ * @param steps The number of years.
+ */
+export function years(steps: number) {
+  return interval('YEARS', steps);
+}
+
+/**
+ * Create a new months interval.
+ * @param steps The number of months.
+ */
+export function months(steps: number) {
+  return interval('MONTHS', steps);
+}
+
+/**
+ * Create a new days interval.
+ * @param steps The number of days.
+ */
+export function days(steps: number) {
+  return interval('DAYS', steps);
+}
+
+/**
+ * Create a new hours interval.
+ * @param steps The number of hours.
+ */
+export function hours(steps: number) {
+  return interval('HOURS', steps);
+}
+
+/**
+ * Create a new minutes interval.
+ * @param steps The number of minutes.
+ */
+export function minutes(steps: number) {
+  return interval('MINUTES', steps);
+}
+
+/**
+ * Create a new seconds interval.
+ * @param steps The number of seconds.
+ */
+export function seconds(steps: number) {
+  return interval('SECONDS', steps);
+}
+
+/**
+ * Create a new milliseconds interval.
+ * @param steps The number of milliseconds.
+ */
+export function milliseconds(steps: number) {
+  return interval('MILLISECONDS', steps);
+}
+
+/**
+ * Create a new microseconds interval.
+ * @param steps The number of microseconds.
+ */
+export function microseconds(steps: number) {
+  return interval('MICROSECONDS', steps);
+}

package/src/functions/{literal.js → literal.ts}

@@ -5,18 +5,17 @@ import { VerbatimNode } from '../ast/verbatim.js';
  * Return a SQL AST node for a literal value. The supported types are
  * null, string, number, boolean, Date, and RegExp. Otherwise, the
  * input value will be directly coerced to a string.
- * @param {*} value The literal value.
- * @returns {LiteralNode}
+ * @param value The literal value.
  */
-export function literal(value) {
+export function literal(value: unknown) {
   return new LiteralNode(value);
 }
 
 /**
  * Return a SQL AST node for verbatim string content.
- * @param {string} value The verbatim value.
- * @returns {VerbatimNode}
+ * @param value The verbatim value.
+ * @param hint A type hint for analyzing verbatim content.
  */
-export function verbatim(value) {
-  return new VerbatimNode(value);
+export function verbatim(value: string, hint?: string) {
+  return new VerbatimNode(value, hint);
 }