@uwdata/mosaic-core 0.13.0 → 0.14.0

package/dist/types/Coordinator.d.ts

@@ -155,7 +155,7 @@ export class Coordinator {
      * Connect a client to the coordinator.
      * @param {MosaicClient} client The Mosaic client to connect.
      */
-    connect(client: MosaicClient): Promise<void>;
+    connect(client: MosaicClient): void;
     initializeClient(client: any): Promise<any>;
     /**
      * Disconnect a client from the coordinator.

package/dist/types/MosaicClient.d.ts

@@ -81,7 +81,8 @@ export class MosaicClient {
     /**
      * Request the coordinator to execute a query for this client.
      * If an explicit query is not provided, the client query method will
-     * be called, filtered by the current filterBy selection.
+     * be called, filtered by the current filterBy selection. This method
+     * has no effect if the client is not registered with a coordinator.
      * @returns {Promise}
      */
     requestQuery(query: any): Promise<any>;
@@ -93,14 +94,15 @@ export class MosaicClient {
      */
     requestUpdate(): void;
     /**
-     * Reset this client, initiating new field info, call the prepare method, and query requests.
+     * Reset this client, initiating new field info, call the prepare method,
+     * and query requests. This method has no effect if the client is not
+     * registered with a coordinator.
      * @returns {Promise}
      */
     initialize(): Promise<any>;
     /**
-     * Requests a client update.
-     * For example to (re-)render an interface component.
-     *
+     * Requests a client update, for example to (re-)render an interface
+     * component.
      * @returns {this | Promise<any>}
      */
     update(): this | Promise<any>;

package/dist/types/Selection.d.ts

@@ -133,15 +133,25 @@ export class Selection extends Param {
     valueFor(source: any): any;
     /**
      * Emit an activate event with the given selection clause.
-     * @param {*} clause The clause repesenting the potential activation.
+     * @param {SelectionClause} clause The clause repesenting the potential activation.
      */
-    activate(clause: any): void;
+    activate(clause: SelectionClause): void;
     /**
      * Update the selection with a new selection clause.
-     * @param {*} clause The selection clause to add.
+     * @param {SelectionClause} clause The selection clause to add.
      * @returns {this} This Selection instance.
      */
-    update(clause: any): this;
+    update(clause: SelectionClause): this;
+    /**
+     * Reset the selection state by removing all provided clauses. If no clause
+     * array is provided as an argument, all current clauses are removed. The
+     * reset method (if defined) is invoked on all corresponding clause sources.
+     * The reset is relayed to downstream selections that include this selection.
+     * @param {SelectionClause[]} [clauses] The clauses to remove. If
+     *  unspecified, all current clauses are removed.
+     * @returns {this} This selection instance.
+     */
+    reset(clauses?: SelectionClause[]): this;
     /**
      * Indicates if a selection clause should not be applied to a given client.
      * The return value depends on the selection resolution strategy.
@@ -221,4 +231,5 @@ export class SelectionResolver {
     queueFilter(value: any): (value: any) => boolean | null;
 }
 import { Param } from './Param.js';
+import type { SelectionClause } from './util/selection-types.js';
 import { MosaicClient } from './MosaicClient.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Scalable and extensible linked data views.",
   "keywords": [
     "mosaic",
@@ -32,10 +32,10 @@
   "dependencies": {
     "@duckdb/duckdb-wasm": "^1.29.0",
     "@uwdata/flechette": "^2.0.0",
-    "@uwdata/mosaic-sql": "^0.13.0"
+    "@uwdata/mosaic-sql": "^0.14.0"
   },
   "devDependencies": {
-    "@uwdata/mosaic-duckdb": "^0.13.0"
+    "@uwdata/mosaic-duckdb": "^0.14.0"
   },
-  "gitHead": "b5a0e03e200c0f04c46562a288f084ffc9f6ad55"
+  "gitHead": "a882aab60867e4e9d9738bc950aa9de32729a806"
 }

package/src/Coordinator.js

@@ -222,13 +222,17 @@ export class Coordinator {
    * Connect a client to the coordinator.
    * @param {MosaicClient} client The Mosaic client to connect.
    */
-  async connect(client) {
+  connect(client) {
     const { clients } = this;
 
     if (clients.has(client)) {
       throw new Error('Client already connected.');
     }
-    clients.add(client); // mark as connected
+
+    // add client to client set
+    clients.add(client);
+
+    // register coordinator on client instance
     client.coordinator = this;
 
     // initialize client lifecycle

package/src/MosaicClient.js

@@ -123,12 +123,13 @@ export class MosaicClient {
   /**
    * Request the coordinator to execute a query for this client.
    * If an explicit query is not provided, the client query method will
-   * be called, filtered by the current filterBy selection.
+   * be called, filtered by the current filterBy selection. This method
+   * has no effect if the client is not registered with a coordinator.
    * @returns {Promise}
    */
   requestQuery(query) {
     const q = query || this.query(this.filterBy?.predicate(this));
-    return this._coordinator.requestQuery(this, q);
+    return this._coordinator?.requestQuery(this, q);
   }
 
   /**
@@ -142,17 +143,18 @@ export class MosaicClient {
   }
 
   /**
-   * Reset this client, initiating new field info, call the prepare method, and query requests.
+   * Reset this client, initiating new field info, call the prepare method,
+   * and query requests. This method has no effect if the client is not
+   * registered with a coordinator.
    * @returns {Promise}
    */
   initialize() {
-    return this._coordinator.initializeClient(this);
+    return this._coordinator?.initializeClient(this);
   }
 
   /**
-   * Requests a client update.
-   * For example to (re-)render an interface component.
-   *
+   * Requests a client update, for example to (re-)render an interface
+   * component.
    * @returns {this | Promise<any>}
    */
   update() {

package/src/Selection.js

@@ -1,3 +1,4 @@
+/** @import {SelectionClause} from './util/selection-types.js' */
 import { literal, or } from '@uwdata/mosaic-sql';
 import { Param } from './Param.js';
 import { MosaicClient } from './MosaicClient.js';
@@ -187,7 +188,7 @@ export class Selection extends Param {
 
   /**
    * Emit an activate event with the given selection clause.
-   * @param {*} clause The clause repesenting the potential activation.
+   * @param {SelectionClause} clause The clause repesenting the potential activation.
    */
   activate(clause) {
     this.emit('activate', clause);
@@ -196,7 +197,7 @@ export class Selection extends Param {
 
   /**
    * Update the selection with a new selection clause.
-   * @param {*} clause The selection clause to add.
+   * @param {SelectionClause} clause The selection clause to add.
    * @returns {this} This Selection instance.
    */
   update(clause) {
@@ -208,6 +209,23 @@ export class Selection extends Param {
     return super.update(this._resolved);
   }
 
+  /**
+   * Reset the selection state by removing all provided clauses. If no clause
+   * array is provided as an argument, all current clauses are removed. The
+   * reset method (if defined) is invoked on all corresponding clause sources.
+   * The reset is relayed to downstream selections that include this selection.
+   * @param {SelectionClause[]} [clauses] The clauses to remove. If
+   *  unspecified, all current clauses are removed.
+   * @returns {this} This selection instance.
+   */
+  reset(clauses) {
+    clauses ??= this._resolved;
+    clauses.forEach(c => c.source?.reset?.());
+    this._resolved = this._resolved.filter(c => clauses.includes(c));
+    this._relay.forEach(sel => sel.reset(clauses));
+    return super.update(this._resolved = []);
+  }
+
   /**
    * Upon value-typed updates, sets the current clause list to the
    * input value and returns the active clause value.

package/src/preagg/PreAggregator.js

@@ -1,4 +1,4 @@
-import { Query, and, asNode, ceil, collectColumns, createTable, float64, floor, isBetween, int32, mul, round, scaleTransform, sub, isSelectQuery, ExprNode, SelectQuery } from '@uwdata/mosaic-sql';
+import { Query, and, asNode, ceil, collectColumns, createTable, float64, floor, isBetween, int32, mul, round, scaleTransform, sub, isSelectQuery, ExprNode, SelectQuery, isAggregateExpression, ColumnNameRefNode } from '@uwdata/mosaic-sql';
 import { preaggColumns } from './preagg-columns.js';
 import { fnv_hash } from '../util/hash.js';
 
@@ -157,6 +157,10 @@ export class PreAggregator {
 
     // if cached active columns are unset, analyze the active clause
     if (!active) {
+      // if active clause predicate is null, we can't analyze it
+      // return null to backoff to standard client query
+      // non-null clauses may come later, so don't set active state
+      if (activeClause.predicate == null) return null;
       // generate active dimension columns to select over
       // will return an object with null source if it has unstable filters
       this.active = active = activeColumns(activeClause);
@@ -331,20 +335,45 @@ function preaggregateInfo(clientQuery, active, preaggCols, schema) {
 
 /**
  * Push column selections down to subqueries.
+ * @param {Query} query The (sub)query to push down to.
+ * @param {string[]} cols The column names to push down.
  */
 function subqueryPushdown(query, cols) {
   const memo = new Set;
   const pushdown = q => {
+    // it is possible to have duplicate subqueries
+    // so we memoize and exit early if already seen
     if (memo.has(q)) return;
     memo.add(q);
+
     if (isSelectQuery(q) && q._from.length) {
+      // select the pushed down columns
+      // note that the select method will deduplicate for us
       q.select(cols);
+      if (isAggregateQuery(q)) {
+        // if an aggregation query, we need to push to groupby as well
+        // we also deduplicate as the column may already be present
+        const set = new Set(
+          q._groupby.flatMap(x => x instanceof ColumnNameRefNode ? x.name : []
+        ));
+        q.groupby(cols.filter(c => !set.has(c)));
+      }
     }
     q.subqueries.forEach(pushdown);
   };
   pushdown(query);
 }
 
+/**
+ * Test if a query performs aggregation.
+ * @param {SelectQuery} query
+ * @returns {boolean}
+ */
+function isAggregateQuery(query) {
+  return query._groupby.length > 0
+    || query._select.some(node => isAggregateExpression(node));
+}
+
 /**
  * Metadata and query generator for materialized views of pre-aggregated data.
  * This object provides the information needed to generate and query the

package/src/preagg/sufficient-statistics.js

@@ -1,4 +1,4 @@
-import { AggregateNode, and, argmax, argmin, count, div, exp, ExprNode, isNotNull, ln, max, min, mul, pow, regrAvgX, regrAvgY, regrCount, sql, sqrt, sub, sum } from '@uwdata/mosaic-sql';
+import { AggregateNode, and, argmax, argmin, coalesce, count, div, exp, ExprNode, isNotNull, ln, max, min, mul, pow, regrAvgX, regrAvgY, regrCount, sql, sqrt, sub, sum } from '@uwdata/mosaic-sql';
 import { fnv_hash } from '../util/hash.js';
 
 /**
@@ -14,6 +14,7 @@ import { fnv_hash } from '../util/hash.js';
 export function sufficientStatistics(node, preagg, avg) {
   switch (node.name) {
     case 'count':
+      return sumCountExpr(preagg, node);
     case 'sum':
       return sumExpr(preagg, node);
     case 'avg':
@@ -128,11 +129,24 @@ function addStat(preagg, expr, node) {
  */
 function countExpr(preagg, node) {
   const name = addStat(preagg, count(node.args[0]), node);
-  return { expr: sum(name), name };
+  return { expr: coalesce(sum(name), 0), name };
 }
 
 /**
- * Generate an expression for calculating counts or sums over data dimensions.
+ * Generate an expression for calculating counts over data dimensions.
+ * The expression is a summation with an additional coalesce operation
+ * to map null sums to zero-valued counts.
+ * @param {Record<string, ExprNode>} preagg A map of columns (such as
+ *  sufficient statistics) to pre-aggregate.
+ * @param {AggregateNode} node The originating aggregate function call.
+ * @returns {ExprNode} An aggregate expression over pre-aggregated dimensions.
+ */
+function sumCountExpr(preagg, node) {
+  return coalesce(sumExpr(preagg, node), 0);
+}
+
+/**
+ * Generate an expression for calculating sums over data dimensions.
  * @param {Record<string, ExprNode>} preagg A map of columns (such as
  *  sufficient statistics) to pre-aggregate.
  * @param {AggregateNode} node The originating aggregate function call.