@carto/api-client - npm Package Compare versions

Comparing version 0.4.3 to 0.4.4

build/api-client.modern.js

@@ -834,5 +834,6 @@ import bboxClip from '@turf/bbox-clip';
     filtersLogicalOperator = 'and',
-    geoColumn = DEFAULT_GEO_COLUMN
+    spatialDataType = 'geo',
+    spatialFiltersMode = 'intersects',
+    spatialFiltersResolution = 0
   } = source;
-  const queryParameters = source.queryParameters ? JSON.stringify(source.queryParameters) : '';
   const queryParams = {
@@ -842,30 +843,31 @@ type,
     source: data,
-    params: JSON.stringify(params),
-    queryParameters,
-    filters: JSON.stringify(filters),
+    params,
+    queryParameters: source.queryParameters || '',
+    filters,
     filtersLogicalOperator
   };
+  const spatialDataColumn = source.spatialDataColumn || DEFAULT_GEO_COLUMN;
   // Picking Model API requires 'spatialDataColumn'.
   if (model === 'pick') {
-    queryParams.spatialDataColumn = geoColumn;
+    queryParams.spatialDataColumn = spatialDataColumn;
   }
-  // API supports multiple filters, we apply it only to geoColumn
+  // API supports multiple filters, we apply it only to spatialDataColumn
   const spatialFilters = source.spatialFilter ? {
-    [geoColumn]: source.spatialFilter
+    [spatialDataColumn]: source.spatialFilter
   } : undefined;
   if (spatialFilters) {
-    queryParams.spatialFilters = JSON.stringify(spatialFilters);
+    queryParams.spatialFilters = spatialFilters;
+    queryParams.spatialDataColumn = spatialDataColumn;
+    queryParams.spatialDataType = spatialDataType;
   }
-  const urlWithSearchParams = url + '?' + new URLSearchParams(queryParams).toString();
+  if (spatialDataType !== 'geo') {
+    if (spatialFiltersResolution > 0) {
+      queryParams.spatialFiltersResolution = spatialFiltersResolution;
+    }
+    queryParams.spatialFiltersMode = spatialFiltersMode;
+  }
+  const urlWithSearchParams = url + '?' + objectToURLSearchParams(queryParams).toString();
   const isGet = urlWithSearchParams.length <= REQUEST_GET_MAX_URL_LENGTH;
   if (isGet) {
     url = urlWithSearchParams;
-  } else {
-    // undo the JSON.stringify, @TODO find a better pattern
-    queryParams.params = params;
-    queryParams.filters = filters;
-    queryParams.queryParameters = source.queryParameters;
-    if (spatialFilters) {
-      queryParams.spatialFilters = spatialFilters;
-    }
   }
@@ -882,11 +884,67 @@ return makeCall({
 }
+function objectToURLSearchParams(object) {
+  const params = new URLSearchParams();
+  for (const key in object) {
+    if (isPureObject(object[key])) {
+      params.append(key, JSON.stringify(object[key]));
+    } else if (Array.isArray(object[key])) {
+      params.append(key, JSON.stringify(object[key]));
+    } else if (object[key] === null) {
+      params.append(key, 'null');
+    } else if (object[key] !== undefined) {
+      params.append(key, String(object[key]));
+    }
+  }
+  return params;
+}
 
-const _excluded = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded2 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded3 = ["filterOwner", "spatialFilter", "abortController", "operationExp"],
-  _excluded4 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded5 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded6 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded7 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded8 = ["filterOwner", "abortController", "spatialFilter"];
+const DEFAULT_TILE_SIZE = 512;
+const QUADBIN_ZOOM_MAX_OFFSET = 4;
+function getSpatialFiltersResolution(source, viewState) {
+  var _source$dataResolutio, _source$aggregationRe;
+  const dataResolution = (_source$dataResolutio = source.dataResolution) != null ? _source$dataResolutio : Number.MAX_VALUE;
+  const aggregationResLevel = (_source$aggregationRe = source.aggregationResLevel) != null ? _source$aggregationRe : source.spatialDataType === 'h3' ? DEFAULT_AGGREGATION_RES_LEVEL_H3 : DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN;
+  const aggregationResLevelOffset = Math.max(0, Math.floor(aggregationResLevel));
+  const currentZoomInt = Math.ceil(viewState.zoom);
+  if (source.spatialDataType === 'h3') {
+    var _maxH3SpatialFiltersR, _maxH3SpatialFiltersR2;
+    const tileSize = DEFAULT_TILE_SIZE;
+    const maxResolutionForZoom = (_maxH3SpatialFiltersR = (_maxH3SpatialFiltersR2 = maxH3SpatialFiltersResolutions.find(([zoom]) => zoom === currentZoomInt)) == null ? void 0 : _maxH3SpatialFiltersR2[1]) != null ? _maxH3SpatialFiltersR : Math.max(0, currentZoomInt - 3);
+    const maxSpatialFiltersResolution = maxResolutionForZoom ? Math.min(dataResolution, maxResolutionForZoom) : dataResolution;
+    const hexagonResolution = getHexagonResolution(viewState, tileSize) + aggregationResLevelOffset;
+    return Math.min(hexagonResolution, maxSpatialFiltersResolution);
+  }
+  if (source.spatialDataType === 'quadbin') {
+    const maxResolutionForZoom = currentZoomInt + QUADBIN_ZOOM_MAX_OFFSET;
+    const maxSpatialFiltersResolution = Math.min(dataResolution, maxResolutionForZoom);
+    const quadsResolution = Math.floor(viewState.zoom) + aggregationResLevelOffset;
+    return Math.min(quadsResolution, maxSpatialFiltersResolution);
+  }
+  return undefined;
+}
+const maxH3SpatialFiltersResolutions = [[20, 14], [19, 13], [18, 12], [17, 11], [16, 10], [15, 9], [14, 8], [13, 7], [12, 7], [11, 7], [10, 6], [9, 6], [8, 5], [7, 4], [6, 4], [5, 3], [4, 2], [3, 1], [2, 1], [1, 0]];
+// stolen from https://github.com/visgl/deck.gl/blob/master/modules/carto/src/layers/h3-tileset-2d.ts
+// Relative scale factor (0 = no biasing, 2 = a few hexagons cover view)
+const BIAS = 2;
+// Resolution conversion function. Takes a WebMercatorViewport and returns
+// a H3 resolution such that the screen space size of the hexagons is
+// similar
+function getHexagonResolution(viewport, tileSize) {
+  // Difference in given tile size compared to deck's internal 512px tile size,
+  // expressed as an offset to the viewport zoom.
+  const zoomOffset = Math.log2(tileSize / DEFAULT_TILE_SIZE);
+  const hexagonScaleFactor = 2 / 3 * (viewport.zoom - zoomOffset);
+  const latitudeScaleFactor = Math.log(1 / Math.cos(Math.PI * viewport.latitude / 180));
+  // Clip and bias
+  return Math.max(0, Math.floor(hexagonScaleFactor + latitudeScaleFactor - BIAS));
+}
+
+const _excluded = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded2 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded3 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController", "operationExp"],
+  _excluded4 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded5 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded6 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded7 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded8 = ["filterOwner", "abortController", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState"];
 /**
@@ -912,5 +970,17 @@ * Source for Widget API requests on a data source defined by a SQL query.
       filtersLogicalOperator: props.filtersLogicalOperator,
-      geoColumn: props.geoColumn
+      spatialDataType: props.spatialDataType,
+      spatialDataColumn: props.spatialDataColumn,
+      dataResolution: props.dataResolution
     };
   }
+  _getSpatialFiltersResolution(source, spatialFilter, referenceViewState) {
+    // spatialFiltersResolution applies only to spatial index sources.
+    if (!spatialFilter || source.spatialDataType === 'geo') {
+      return;
+    }
+    if (!referenceViewState) {
+      throw new Error('Missing required option, "spatialIndexReferenceViewState".');
+    }
+    return getSpatialFiltersResolution(source, referenceViewState);
+  }
   /****************************************************************************
@@ -927,2 +997,4 @@ * CATEGORIES
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
@@ -936,5 +1008,9 @@ } = options,
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'category',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -967,2 +1043,4 @@ }),
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
@@ -979,5 +1057,9 @@ } = options,
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'pick',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -1014,2 +1096,4 @@ }),
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController,
@@ -1023,5 +1107,9 @@ operationExp
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'formula',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -1050,2 +1138,4 @@ }),
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
@@ -1059,5 +1149,9 @@ } = options,
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     const data = await executeModel({
       model: 'histogram',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -1098,2 +1192,4 @@ }),
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
@@ -1105,5 +1201,9 @@ } = options,
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'range',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -1130,2 +1230,4 @@ }),
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
@@ -1140,2 +1242,4 @@ } = options,
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     // Make sure this is sync with the same constant in cloud-native/maps-api
@@ -1145,3 +1249,5 @@ const HARD_LIMIT = 500;
       model: 'scatterplot',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -1175,2 +1281,4 @@ }),
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController
@@ -1186,5 +1294,9 @@ } = options,
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'table',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -1222,3 +1334,5 @@ }),
         abortController,
-        spatialFilter
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState
       } = options,
@@ -1237,5 +1351,9 @@ params = _objectWithoutPropertiesLoose(options, _excluded8);
     } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
     return executeModel({
       model: 'timeseries',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -1271,4 +1389,3 @@ }),
   filters: {},
-  filtersLogicalOperator: 'and',
-  geoColumn: DEFAULT_GEO_COLUMN
+  filtersLogicalOperator: 'and'
 };
@@ -1364,3 +1481,7 @@
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+      spatialDataColumn,
+      spatialDataType: 'h3'
+    }))
   }));
@@ -1390,3 +1511,7 @@ };
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+      spatialDataColumn,
+      spatialDataType: 'h3'
+    }))
   }));
@@ -1446,3 +1571,7 @@ };
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+      spatialDataColumn,
+      spatialDataType: 'quadbin'
+    }))
   }));
@@ -1472,3 +1601,7 @@ };
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+      spatialDataColumn,
+      spatialDataType: 'quadbin'
+    }))
   }));
@@ -1517,3 +1650,5 @@ };
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      spatialDataType: 'geo'
+    }))
   }));
@@ -1547,3 +1682,5 @@ };
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      spatialDataType: 'geo'
+    }))
   }));
@@ -1550,0 +1687,0 @@ };

build/api/query.d.ts

 import type { SourceOptions, QuerySourceOptions, QueryResult } from '../sources/types';
-export type QueryOptions = SourceOptions & Omit<QuerySourceOptions, 'spatialDataColumn'>;
+export type QueryOptions = SourceOptions & QuerySourceOptions;
 export declare const query: (options: QueryOptions) => Promise<QueryResult>;

build/models/model.d.ts

 import { Filter, FilterLogicalOperator, MapType, QueryParameters, SpatialFilter } from '../types.js';
 import { ModelRequestOptions } from './common.js';
 import { ApiVersion } from '../constants.js';
+import { SpatialDataType, SpatialFilterPolyfillMode } from '../sources/types.js';
 /** @internalRemarks Source: @carto/react-api */
@@ -17,5 +18,10 @@ declare const AVAILABLE_MODELS: readonly ["category", "histogram", "formula", "pick", "timeseries", "range", "scatterplot", "table"];
     filtersLogicalOperator?: FilterLogicalOperator;
-    geoColumn?: string;
     spatialFilter?: SpatialFilter;
     queryParameters?: QueryParameters;
+    spatialDataColumn?: string;
+    spatialDataType?: SpatialDataType;
+    spatialFiltersResolution?: number;
+    spatialFiltersMode?: SpatialFilterPolyfillMode;
+    /** original resolution of the spatial index data as stored in the DW */
+    dataResolution?: number;
 }
@@ -22,0 +28,0 @@ /**

build/sources/types.d.ts

@@ -42,2 +42,26 @@ import type { Feature } from 'geojson';
     /**
+     * The column name and the type of geospatial support.
+     *
+     * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+     */
+    spatialDataColumn?: string;
+    /**
+     * The type of geospatial support. Defaults to `'geo'`.
+     */
+    spatialDataType?: SpatialDataType;
+    /**
+     * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
+     * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
+     * the quantization grid proportionately.
+     *
+     * Supported `tileResolution` values, with corresponding grid sizes:
+     *
+     * - 0.25: 256x256
+     * - 0.5: 512x512
+     * - 1: 1024x1024
+     * - 2: 2048x2048
+     * - 4: 4096x4096
+     */
+    tileResolution?: TileResolution;
+    /**
      * By default, local in-memory caching is enabled.
@@ -77,2 +101,6 @@ */
     aggregationResLevel?: number;
+    /**
+     * Original resolution of the spatial index data as stored in the DW
+     */
+    dataResolution?: number;
 };
@@ -86,25 +114,5 @@ export type FilterOptions = {
 export type QuerySourceOptions = {
-    /**
-     * The column name and the type of geospatial support.
-     *
-     * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
-     */
-    spatialDataColumn?: string;
-    /** SQL query. */
+    /** Full SQL query with query paremeter placeholders (if any). */
     sqlQuery: string;
     /**
-     * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
-     * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
-     * the quantization grid proportionately.
-     *
-     * Supported `tileResolution` values, with corresponding grid sizes:
-     *
-     * - 0.25: 256x256
-     * - 0.5: 512x512
-     * - 1: 1024x1024
-     * - 2: 2048x2048
-     * - 4: 4096x4096
-     */
-    tileResolution?: TileResolution;
-    /**
      * Values for named or positional paramteres in the query.
@@ -149,22 +157,2 @@ *
     /**
-     * The column name and the type of geospatial support.
-     *
-     * If not present, defaults to `'geom'` for generic tables, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
-     */
-    spatialDataColumn?: string;
-    /**
-     * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
-     * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
-     * the quantization grid proportionately.
-     *
-     * Supported `tileResolution` values, with corresponding grid sizes:
-     *
-     * - 0.25: 256x256
-     * - 0.5: 512x512
-     * - 1: 1024x1024
-     * - 2: 2048x2048
-     * - 4: 4096x4096
-     */
-    tileResolution?: TileResolution;
-    /**
      * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
@@ -193,2 +181,9 @@ *
 export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
+/**
+ * Strategy used for covering spatial filter geometry with spatial indexes.
+ * See https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/quadbin#quadbin_polyfill_mode
+ * or https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/h3#h3_polyfill_mode for more information.
+ * @internalRemarks Source: cloud-native maps-api
+ * */
+export type SpatialFilterPolyfillMode = 'center' | 'intersects' | 'contains';
 export type TilejsonMapInstantiation = MapInstantiation & {
@@ -195,0 +190,0 @@ tilejson: {

build/utils.d.ts

@@ -17,3 +17,3 @@ import { Filter } from './types.js';
 /** @internalRemarks Source: @carto/react-core */
-export declare function assert(condition: unknown, message: string): void;
+export declare function assert(condition: unknown, message: string): asserts condition;
 /**
@@ -20,0 +20,0 @@ * @internalRemarks Source: @carto/react-core

build/widget-sources/types.d.ts

@@ -1,2 +0,2 @@
-import { TileResolution } from '../sources/types';
+import { SpatialFilterPolyfillMode, TileResolution } from '../sources/types';
 import { GroupDateType, SortColumnType, SortDirection, SpatialFilter } from '../types';
@@ -6,5 +6,13 @@ /******************************************************************************
  */
+export interface ViewState {
+    zoom: number;
+    latitude: number;
+    longitude: number;
+}
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
     spatialFilter?: SpatialFilter;
+    spatialFiltersMode?: SpatialFilterPolyfillMode;
+    /** Required for table- and query-based spatial index sources (H3, Quadbin). */
+    spatialIndexReferenceViewState?: ViewState;
     abortController?: AbortController;
@@ -11,0 +19,0 @@ filterOwner?: string;

build/widget-sources/widget-base-source.d.ts

@@ -1,3 +0,3 @@
-import { CategoryRequestOptions, CategoryResponse, FeaturesRequestOptions, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
-import { FilterLogicalOperator, Filter } from '../types.js';
+import { CategoryRequestOptions, CategoryResponse, FeaturesRequestOptions, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse, ViewState } from './types.js';
+import { FilterLogicalOperator, Filter, SpatialFilter } from '../types.js';
 import { ModelSource } from '../models/model.js';
@@ -8,3 +8,2 @@ import { SourceOptions } from '../sources/index.js';
     apiVersion?: ApiVersion;
-    geoColumn?: string;
     filters?: Record<string, Filter>;
@@ -31,2 +30,3 @@ filtersLogicalOperator?: FilterLogicalOperator;
     protected _getModelSource(owner?: string): Omit<ModelSource, 'type' | 'data'>;
+    protected _getSpatialFiltersResolution(source: Omit<ModelSource, 'type' | 'data'>, spatialFilter?: SpatialFilter, referenceViewState?: ViewState): number | undefined;
     /****************************************************************************
@@ -33,0 +33,0 @@ * CATEGORIES

CHANGELOG.md

@@ -7,2 +7,6 @@ # CHANGELOG
 
+### 0.4.4
+
+- feat: Add support for spatial index types (H3, quadbin) in Widget APIs
+
 ### 0.4.3
@@ -9,0 +13,0 @@

package.json

@@ -7,3 +7,3 @@ {
   "packageManager": "yarn@4.3.1",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "license": "MIT",
@@ -10,0 +10,0 @@ "publishConfig": {

src/api/query.ts

@@ -15,4 +15,3 @@ // deck.gl
 
-export type QueryOptions = SourceOptions &
-  Omit<QuerySourceOptions, 'spatialDataColumn'>;
+export type QueryOptions = SourceOptions & QuerySourceOptions;
 type UrlParameters = {q: string; queryParameters?: string};
@@ -19,0 +18,0 @@

src/models/model.ts

@@ -10,5 +10,6 @@ import {DEFAULT_GEO_COLUMN} from '../constants-internal.js';
 import {$TODO} from '../types-internal.js';
-import {assert} from '../utils.js';
+import {assert, isPureObject} from '../utils.js';
 import {ModelRequestOptions, makeCall} from './common.js';
 import {ApiVersion} from '../constants.js';
+import {SpatialDataType, SpatialFilterPolyfillMode} from '../sources/types.js';
 
@@ -39,5 +40,10 @@ /** @internalRemarks Source: @carto/react-api */
   filtersLogicalOperator?: FilterLogicalOperator;
-  geoColumn?: string;
   spatialFilter?: SpatialFilter;
   queryParameters?: QueryParameters;
+  spatialDataColumn?: string;
+  spatialDataType?: SpatialDataType;
+  spatialFiltersResolution?: number;
+  spatialFiltersMode?: SpatialFilterPolyfillMode;
+  /** original resolution of the spatial index data as stored in the DW */
+  dataResolution?: number;
 }
@@ -84,46 +90,47 @@
     filtersLogicalOperator = 'and',
-    geoColumn = DEFAULT_GEO_COLUMN,
+    spatialDataType = 'geo',
+    spatialFiltersMode = 'intersects',
+    spatialFiltersResolution = 0,
   } = source;
 
-  const queryParameters = source.queryParameters
-    ? JSON.stringify(source.queryParameters)
-    : '';
-
-  const queryParams: Record<string, string> = {
+  const queryParams: Record<string, unknown> = {
     type,
     client: clientId,
     source: data,
-    params: JSON.stringify(params),
-    queryParameters,
-    filters: JSON.stringify(filters),
+    params,
+    queryParameters: source.queryParameters || '',
+    filters,
     filtersLogicalOperator,
   };
 
+  const spatialDataColumn = source.spatialDataColumn || DEFAULT_GEO_COLUMN;
+
   // Picking Model API requires 'spatialDataColumn'.
   if (model === 'pick') {
-    queryParams.spatialDataColumn = geoColumn;
+    queryParams.spatialDataColumn = spatialDataColumn;
   }
 
-  // API supports multiple filters, we apply it only to geoColumn
+  // API supports multiple filters, we apply it only to spatialDataColumn
   const spatialFilters = source.spatialFilter
-    ? {[geoColumn]: source.spatialFilter}
+    ? {[spatialDataColumn]: source.spatialFilter}
     : undefined;
 
   if (spatialFilters) {
-    queryParams.spatialFilters = JSON.stringify(spatialFilters);
+    queryParams.spatialFilters = spatialFilters;
+    queryParams.spatialDataColumn = spatialDataColumn;
+    queryParams.spatialDataType = spatialDataType;
   }
 
+  if (spatialDataType !== 'geo') {
+    if (spatialFiltersResolution > 0) {
+      queryParams.spatialFiltersResolution = spatialFiltersResolution;
+    }
+    queryParams.spatialFiltersMode = spatialFiltersMode;
+  }
+
   const urlWithSearchParams =
-    url + '?' + new URLSearchParams(queryParams).toString();
+    url + '?' + objectToURLSearchParams(queryParams).toString();
   const isGet = urlWithSearchParams.length <= REQUEST_GET_MAX_URL_LENGTH;
   if (isGet) {
     url = urlWithSearchParams;
-  } else {
-    // undo the JSON.stringify, @TODO find a better pattern
-    queryParams.params = params as $TODO;
-    queryParams.filters = filters as $TODO;
-    queryParams.queryParameters = source.queryParameters as $TODO;
-    if (spatialFilters) {
-      queryParams.spatialFilters = spatialFilters as $TODO;
-    }
   }
@@ -140,1 +147,17 @@ return makeCall({
 }
+
+function objectToURLSearchParams(object: Record<string, unknown>) {
+  const params = new URLSearchParams();
+  for (const key in object) {
+    if (isPureObject(object[key])) {
+      params.append(key, JSON.stringify(object[key]));
+    } else if (Array.isArray(object[key])) {
+      params.append(key, JSON.stringify(object[key]));
+    } else if (object[key] === null) {
+      params.append(key, 'null');
+    } else if (object[key] !== undefined) {
+      params.append(key, String(object[key]));
+    }
+  }
+  return params;
+}

src/sources/h3-query-source.ts

@@ -22,2 +22,3 @@ // deck.gl
   FilterOptions;
+
 type UrlParameters = {
@@ -65,5 +66,10 @@ aggregationExp: string;
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource(options),
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+        spatialDataColumn,
+        spatialDataType: 'h3',
+      }),
     })
   );
 };

src/sources/h3-table-source.ts

@@ -60,5 +60,10 @@ // deck.gl
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource(options),
+      widgetSource: new WidgetTableSource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+        spatialDataColumn,
+        spatialDataType: 'h3',
+      }),
     })
   );
 };

src/sources/quadbin-query-source.ts

@@ -66,5 +66,10 @@ // deck.gl
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource(options),
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+        spatialDataColumn,
+        spatialDataType: 'quadbin',
+      }),
     })
   );
 };

src/sources/quadbin-table-source.ts

@@ -62,5 +62,10 @@ // deck.gl
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource(options),
+      widgetSource: new WidgetTableSource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+        spatialDataColumn,
+        spatialDataType: 'quadbin',
+      }),
     })
   );
 };

src/sources/types.ts

@@ -52,2 +52,29 @@ // deck.gl
   /**
+   * The column name and the type of geospatial support.
+   *
+   * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+   */
+  spatialDataColumn?: string;
+
+  /**
+   * The type of geospatial support. Defaults to `'geo'`.
+   */
+  spatialDataType?: SpatialDataType;
+
+  /**
+   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
+   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
+   * the quantization grid proportionately.
+   *
+   * Supported `tileResolution` values, with corresponding grid sizes:
+   *
+   * - 0.25: 256x256
+   * - 0.5: 512x512
+   * - 1: 1024x1024
+   * - 2: 2048x2048
+   * - 4: 4096x4096
+   */
+  tileResolution?: TileResolution;
+
+  /**
    * By default, local in-memory caching is enabled.
@@ -93,2 +120,7 @@ */
   aggregationResLevel?: number;
+
+  /**
+   * Original resolution of the spatial index data as stored in the DW
+   */
+  dataResolution?: number;
 };
@@ -104,28 +136,6 @@
 export type QuerySourceOptions = {
-  /**
-   * The column name and the type of geospatial support.
-   *
-   * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
-   */
-  spatialDataColumn?: string;
-
-  /** SQL query. */
+  /** Full SQL query with query paremeter placeholders (if any). */
   sqlQuery: string;
 
   /**
-   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
-   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
-   * the quantization grid proportionately.
-   *
-   * Supported `tileResolution` values, with corresponding grid sizes:
-   *
-   * - 0.25: 256x256
-   * - 0.5: 512x512
-   * - 1: 1024x1024
-   * - 2: 2048x2048
-   * - 4: 4096x4096
-   */
-  tileResolution?: TileResolution;
-
-  /**
    * Values for named or positional paramteres in the query.
@@ -173,24 +183,2 @@ *
   /**
-   * The column name and the type of geospatial support.
-   *
-   * If not present, defaults to `'geom'` for generic tables, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
-   */
-  spatialDataColumn?: string;
-
-  /**
-   * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
-   * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
-   * the quantization grid proportionately.
-   *
-   * Supported `tileResolution` values, with corresponding grid sizes:
-   *
-   * - 0.25: 256x256
-   * - 0.5: 512x512
-   * - 1: 1024x1024
-   * - 2: 2048x2048
-   * - 4: 4096x4096
-   */
-  tileResolution?: TileResolution;
-
-  /**
    * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
@@ -223,2 +211,10 @@ *
 
+/**
+ * Strategy used for covering spatial filter geometry with spatial indexes.
+ * See https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/quadbin#quadbin_polyfill_mode
+ * or https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/h3#h3_polyfill_mode for more information.
+ * @internalRemarks Source: cloud-native maps-api
+ * */
+export type SpatialFilterPolyfillMode = 'center' | 'intersects' | 'contains';
+
 export type TilejsonMapInstantiation = MapInstantiation & {
@@ -225,0 +221,0 @@ tilejson: {url: string[]};

src/sources/vector-query-source.ts

@@ -75,5 +75,8 @@ // deck.gl
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource(options),
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        spatialDataType: 'geo',
+      }),
     })
   );
 };

src/sources/vector-table-source.ts

@@ -70,5 +70,8 @@ // deck.gl
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource(options),
+      widgetSource: new WidgetTableSource({
+        ...options,
+        spatialDataType: 'geo',
+      }),
     })
   );
 };

src/utils.ts

@@ -60,3 +60,3 @@ import {Filter} from './types.js';
 /** @internalRemarks Source: @carto/react-core */
-export function assert(condition: unknown, message: string) {
+export function assert(condition: unknown, message: string): asserts condition {
   if (!condition) {
@@ -63,0 +63,0 @@ throw new Error(message);

src/widget-sources/types.ts

@@ -1,2 +0,2 @@
-import {TileResolution} from '../sources/types';
+import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
 import {
@@ -13,5 +13,14 @@ GroupDateType,
 
+export interface ViewState {
+  zoom: number;
+  latitude: number;
+  longitude: number;
+}
+
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
+  spatialFiltersMode?: SpatialFilterPolyfillMode;
+  /** Required for table- and query-based spatial index sources (H3, Quadbin). */
+  spatialIndexReferenceViewState?: ViewState;
   abortController?: AbortController;
@@ -18,0 +27,0 @@ filterOwner?: string;

src/widget-sources/widget-base-source.ts

@@ -19,4 +19,5 @@ import {executeModel} from '../models/index.js';
   TimeSeriesResponse,
+  ViewState,
 } from './types.js';
-import {FilterLogicalOperator, Filter} from '../types.js';
+import {FilterLogicalOperator, Filter, SpatialFilter} from '../types.js';
 import {getApplicableFilters, normalizeObjectKeys} from '../utils.js';
@@ -27,10 +28,8 @@ import {getClient} from '../client.js';
 import {ApiVersion, DEFAULT_API_BASE_URL} from '../constants.js';
-import {
-  DEFAULT_GEO_COLUMN,
-  DEFAULT_TILE_RESOLUTION,
-} from '../constants-internal.js';
+import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
+import {getSpatialFiltersResolution} from '../spatial-index.js';
+import {AggregationOptions} from '../sources/types.js';
 
 export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
   apiVersion?: ApiVersion;
-  geoColumn?: string;
   filters?: Record<string, Filter>;
@@ -56,3 +55,2 @@ filtersLogicalOperator?: FilterLogicalOperator;
     filtersLogicalOperator: 'and',
-    geoColumn: DEFAULT_GEO_COLUMN,
   };
@@ -84,6 +82,27 @@
       filtersLogicalOperator: props.filtersLogicalOperator,
-      geoColumn: props.geoColumn,
+      spatialDataType: props.spatialDataType,
+      spatialDataColumn: props.spatialDataColumn,
+      dataResolution: (props as Partial<AggregationOptions>).dataResolution,
     };
   }
 
+  protected _getSpatialFiltersResolution(
+    source: Omit<ModelSource, 'type' | 'data'>,
+    spatialFilter?: SpatialFilter,
+    referenceViewState?: ViewState
+  ): number | undefined {
+    // spatialFiltersResolution applies only to spatial index sources.
+    if (!spatialFilter || source.spatialDataType === 'geo') {
+      return;
+    }
+
+    if (!referenceViewState) {
+      throw new Error(
+        'Missing required option, "spatialIndexReferenceViewState".'
+      );
+    }
+
+    return getSpatialFiltersResolution(source, referenceViewState);
+  }
+
   /****************************************************************************
@@ -100,4 +119,17 @@ * CATEGORIES
   ): Promise<CategoryResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {column, operation, operationColumn} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
@@ -108,3 +140,8 @@ type CategoriesModelResponse = {rows: {name: string; value: number}[]};
       model: 'category',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
@@ -134,4 +171,17 @@ column,
   ): Promise<FeaturesResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {columns, dataType, featureIds, z, limit, tileResolution} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
@@ -142,3 +192,8 @@ type FeaturesModelResponse = {rows: Record<string, unknown>[]};
       model: 'pick',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
@@ -169,2 +224,4 @@ columns,
       spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
       abortController,
@@ -175,2 +232,8 @@ operationExp,
     const {column, operation} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
@@ -181,3 +244,8 @@ type FormulaModelResponse = {rows: {value: number}[]};
       model: 'formula',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {column: column ?? '*', operation, operationExp},
@@ -199,4 +267,17 @@ opts: {abortController},
   ): Promise<HistogramResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {column, operation, ticks} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
@@ -207,3 +288,8 @@ type HistogramModelResponse = {rows: {tick: number; value: number}[]};
       model: 'histogram',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {column, operation, ticks},
@@ -236,4 +322,17 @@ opts: {abortController},
   async getRange(options: RangeRequestOptions): Promise<RangeResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {column} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
@@ -244,3 +343,8 @@ type RangeModelResponse = {rows: {min: number; max: number}[]};
       model: 'range',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {column},
@@ -260,6 +364,20 @@ opts: {abortController},
   async getScatter(options: ScatterRequestOptions): Promise<ScatterResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation} =
       params;
 
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
+
     // Make sure this is sync with the same constant in cloud-native/maps-api
@@ -272,3 +390,8 @@ const HARD_LIMIT = 500;
       model: 'scatterplot',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
@@ -296,4 +419,17 @@ xAxisColumn,
   async getTable(options: TableRequestOptions): Promise<TableResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      abortController,
+      ...params
+    } = options;
     const {columns, sortBy, sortDirection, offset = 0, limit = 10} = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
 
@@ -307,3 +443,8 @@ type TableModelResponse = {
       model: 'table',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
@@ -335,4 +476,11 @@ column: columns,
   ): Promise<TimeSeriesResponse> {
-    const {filterOwner, abortController, spatialFilter, ...params} = options;
     const {
+      filterOwner,
+      abortController,
+      spatialFilter,
+      spatialFiltersMode,
+      spatialIndexReferenceViewState,
+      ...params
+    } = options;
+    const {
       column,
@@ -349,2 +497,9 @@ operationColumn,
 
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(
+      source,
+      spatialFilter,
+      spatialIndexReferenceViewState
+    );
+
     type TimeSeriesModelResponse = {
@@ -357,3 +512,8 @@ rows: {name: string; value: number}[];
       model: 'timeseries',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
@@ -360,0 +520,0 @@ column,

No alert changes

Improved metrics

Total package byte prevSize

514816

increased by11.85%

Number of package files

85

increased by2.41%

Lines of code

7901

increased by8.14%

No dependency changes