@uwdata/mosaic-core 0.8.0 → 0.9.0

package/src/SelectionClause.js

@@ -0,0 +1,147 @@
+import {
+  SQLExpression, and, contains, isBetween, isNotDistinct, literal,
+  or, prefix, regexp_matches, suffix
+} from '@uwdata/mosaic-sql';
+import { MosaicClient } from './MosaicClient.js';
+
+/**
+ * @typedef {import('./util/selection-types.js').SelectionClause} SelectionClause
+ * @typedef {import('./util/selection-types.js').Scale} Scale
+ * @typedef {import('./util/selection-types.js').Extent} Extent
+ * @typedef {import('./util/selection-types.js').MatchMethod} MatchMethod
+ * @typedef {import('./util/selection-types.js').BinMethod} BinMethod
+ * @typedef {SQLExpression | string} Field
+ */
+
+/**
+ * Generate a selection clause for a single selected point value.
+ * @param {Field} field The table column or expression to select.
+ * @param {*} value The selected value.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function point(field, value, { source, clients = undefined }) {
+  /** @type {SQLExpression | null} */
+  const predicate = value !== undefined
+    ? isNotDistinct(field, literal(value))
+    : null;
+  return {
+    meta: { type: 'point' },
+    source,
+    clients,
+    value,
+    predicate
+  };
+}
+
+/**
+ * Generate a selection clause for multiple selected point values.
+ * @param {Field[]} fields The table columns or expressions to select.
+ * @param {any[][]} value The selected values, as an array of arrays where
+ *  each subarray contains values corresponding to each *fields* entry.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function points(fields, value, { source, clients = undefined }) {
+  /** @type {SQLExpression | null} */
+  let predicate = null;
+  if (value) {
+    const clauses = value.map(vals => {
+      const list = vals.map((v, i) => isNotDistinct(fields[i], literal(v)));
+      return list.length > 1 ? and(list) : list[0];
+    });
+    predicate = clauses.length > 1 ? or(clauses) : clauses[0];
+  }
+  return {
+    meta: { type: 'point' },
+    source,
+    clients,
+    value,
+    predicate
+  };
+}
+
+/**
+ * Generate a selection clause for a selected 1D interval.
+ * @param {Field} field The table column or expression to select.
+ * @param {Extent} value The selected interval as a [lo, hi] array.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param {Scale} [options.scale] The scale mapping descriptor.
+ * @param {BinMethod} [options.bin] A binning method hint.
+ * @param {number} [options.pixelSize=1] The interactive pixel size.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function interval(field, value, {
+  source, clients, bin, scale, pixelSize = 1
+}) {
+  /** @type {SQLExpression | null} */
+  const predicate = value != null ? isBetween(field, value) : null;
+  /** @type {import('./util/selection-types.js').IntervalMetadata} */
+  const meta = { type: 'interval', scales: [scale], bin, pixelSize };
+  return { meta, source, clients, value, predicate };
+}
+
+/**
+ * Generate a selection clause for multiple selected intervals.
+ * @param {Field[]} fields The table columns or expressions to select.
+ * @param {Extent[]} value The selected intervals, as an array of extents.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param {Scale[]} [options.scales] The scale mapping descriptors,
+ *  in an order matching the given *fields* and *value* extents.
+ * @param {BinMethod} [options.bin] A binning method hint.
+ * @param {number} [options.pixelSize=1] The interactive pixel size.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function intervals(fields, value, {
+  source, clients, bin, scales = [], pixelSize = 1
+}) {
+  /** @type {SQLExpression | null} */
+  const predicate = value != null
+    ? and(fields.map((f, i) => isBetween(f, value[i])))
+    : null;
+  /** @type {import('./util/selection-types.js').IntervalMetadata} */
+  const meta = { type: 'interval', scales, bin, pixelSize };
+  return { meta, source, clients, value, predicate };
+}
+
+const MATCH_METHODS = { contains, prefix, suffix, regexp: regexp_matches };
+
+/**
+ * Generate a selection clause for text search matching.
+ * @param {Field} field The table column or expression to select.
+ * @param {string} value The selected text search query string.
+ * @param {object} options Additional clause properties.
+ * @param {*} options.source The source component generating this clause.
+ * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param {MatchMethod} [options.method] The
+ *  text matching method to use. Defaults to `'contains'`.
+ * @returns {SelectionClause} The generated selection clause.
+ */
+export function match(field, value, {
+  source, clients = undefined, method = 'contains'
+}) {
+  let fn = MATCH_METHODS[method];
+  /** @type {SQLExpression | null} */
+  const predicate = value ? fn(field, literal(value)) : null;
+  /** @type {import('./util/selection-types.js').MatchMetadata} */
+  const meta = { type: 'match', method };
+  return { meta, source, clients, value, predicate };
+}

package/src/connectors/rest.js

@@ -2,6 +2,13 @@ import { tableFromIPC } from 'apache-arrow';
 
 export function restConnector(uri = 'http://localhost:3000/') {
   return {
+    /**
+     * Query the DuckDB server.
+     * @param {object} query
+     * @param {'exec' | 'arrow' | 'json'} [query.type] The query type: 'exec', 'arrow', or 'json'.
+     * @param {string} query.sql A SQL query string.
+     * @returns the query result
+     */
     async query(query) {
       const req = fetch(uri, {
         method: 'POST',

package/src/connectors/socket.js

@@ -81,6 +81,13 @@ export function socketConnector(uri = 'ws://localhost:3000/') {
     get connected() {
       return connected;
     },
+    /**
+     * Query the DuckDB server.
+     * @param {object} query
+     * @param {'exec' | 'arrow' | 'json'} [query.type] The query type: 'exec', 'arrow', or 'json'.
+     * @param {string} query.sql A SQL query string.
+     * @returns the query result
+     */
     query(query) {
       return new Promise(
         (resolve, reject) => enqueue(query, resolve, reject)

package/src/connectors/wasm.js

@@ -45,7 +45,7 @@ export function wasmConnector(options = {}) {
     /**
      * Query the DuckDB-WASM instance.
      * @param {object} query
-     * @param {string} [query.type] The query type: 'exec', 'arrow', or 'json'.
+     * @param {'exec' | 'arrow' | 'json'} [query.type] The query type: 'exec', 'arrow', or 'json'.
      * @param {string} query.sql A SQL query string.
      * @returns the query result
      */
@@ -55,7 +55,7 @@ export function wasmConnector(options = {}) {
       const result = await con.query(sql);
       return type === 'exec' ? undefined
         : type === 'arrow' ? result
-        : Array.from(result);
+        : result.toArray();
     }
   };
 }

package/src/index.js

@@ -3,6 +3,7 @@ export { Coordinator, coordinator } from './Coordinator.js';
 export { Selection, isSelection } from './Selection.js';
 export { Param, isParam } from './Param.js';
 export { Priority } from './QueryManager.js';
+export { point, points, interval, intervals, match } from './SelectionClause.js';
 
 export { restConnector } from './connectors/rest.js';
 export { socketConnector } from './connectors/socket.js';

package/src/util/convert-arrow.js

@@ -1,5 +1,9 @@
 import { DataType } from 'apache-arrow';
 
+/**
+ * @typedef {import('apache-arrow').Vector} Vector
+ */
+
 /**
  * Test if a value is an Apache Arrow table.
  * As sometimes multiple Arrow versions may be used simultaneously,
@@ -58,7 +62,7 @@ export function convertArrowValue(type) {
  * Large integers (BigInt) are converted to Float64 numbers.
  * Fixed-point decimal values are convert to Float64 numbers.
  * Otherwise, the default Arrow values are used.
- * @param {*} column An Apache Arrow column
+ * @param {Vector} column An Apache Arrow column
  * @returns an array of values
  */
 export function convertArrowColumn(column) {
@@ -78,10 +82,10 @@ export function convertArrowColumn(column) {
   // map bigint to number
   if (DataType.isInt(type) && type.bitWidth >= 64) {
     const size = column.length;
-    const array = new Float64Array(size);
+    const array = column.nullCount ? new Array(size) : new Float64Array(size);
     for (let row = 0; row < size; ++row) {
       const v = column.get(row);
-      array[row] = v == null ? NaN : Number(v);
+      array[row] = v == null ? null : Number(v);
     }
     return array;
   }
@@ -90,14 +94,19 @@ export function convertArrowColumn(column) {
   if (DataType.isDecimal(type)) {
     const scale = 1 / Math.pow(10, type.scale);
     const size = column.length;
-    const array = new Float64Array(size);
+    const array = column.nullCount ? new Array(size) : new Float64Array(size);
     for (let row = 0; row < size; ++row) {
       const v = column.get(row);
-      array[row] = v == null ? NaN : decimalToNumber(v, scale);
+      array[row] = v == null ? null : decimalToNumber(v, scale);
     }
     return array;
   }
 
+  // if there are null values, use a standard array
+  if (column.nullCount) {
+    return Array.from(column);
+  }
+
   // otherwise use Arrow JS defaults
   return column.toArray();
 }