@carto/api-client - npm Package Compare versions

Comparing version 0.4.0 to 0.4.1-alpha.0

build/api-client.modern.js

@@ -496,5 +496,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 = {
@@ -504,30 +505,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; // JSON.stringify(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;
-    }
   }
@@ -544,11 +546,71 @@ 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$1 = ["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;
+  assert(viewState, 'viewState prop is required to compute automatic spatialFiltersResolution when using spatialFilter with spatial indexes. Either pass a `spatialFiltersResolution` prop or a `viewState` prop to avoid this error');
+  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$1 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "abortController", "viewState"],
+  _excluded2 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "abortController", "viewState"],
+  _excluded3 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "abortController", "operationExp", "viewState"],
+  _excluded4 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "abortController", "viewState"],
+  _excluded5 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "abortController", "viewState"],
+  _excluded6 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "abortController", "viewState"],
+  _excluded7 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "abortController", "viewState"],
+  _excluded8 = ["filterOwner", "abortController", "spatialFilter", "spatialFiltersMode", "viewState"];
 /**
@@ -574,3 +636,4 @@ * 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
     };
@@ -589,3 +652,5 @@ }
         spatialFilter,
-        abortController
+        spatialFiltersMode,
+        abortController,
+        viewState
       } = options,
@@ -598,5 +663,15 @@ params = _objectWithoutPropertiesLoose(options, _excluded$1);
     } = params;
+    const source = this.getModelSource(filterOwner);
+    let spatialFiltersResolution;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState
+      });
+    }
     return executeModel({
       model: 'category',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -629,3 +704,5 @@ }),
         spatialFilter,
-        abortController
+        spatialFiltersMode,
+        abortController,
+        viewState
       } = options,
@@ -641,5 +718,15 @@ params = _objectWithoutPropertiesLoose(options, _excluded2);
     } = params;
+    const source = this.getModelSource(filterOwner);
+    let spatialFiltersResolution;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState
+      });
+    }
     return executeModel({
       model: 'pick',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -673,4 +760,6 @@ }),
         spatialFilter,
+        spatialFiltersMode,
         abortController,
-        operationExp
+        operationExp,
+        viewState
       } = options,
@@ -682,5 +771,15 @@ params = _objectWithoutPropertiesLoose(options, _excluded3);
     } = params;
+    const source = this.getModelSource(filterOwner);
+    let spatialFiltersResolution;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState
+      });
+    }
     return executeModel({
       model: 'formula',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -709,3 +808,5 @@ }),
         spatialFilter,
-        abortController
+        spatialFiltersMode,
+        abortController,
+        viewState
       } = options,
@@ -718,5 +819,15 @@ params = _objectWithoutPropertiesLoose(options, _excluded4);
     } = params;
+    const source = this.getModelSource(filterOwner);
+    let spatialFiltersResolution;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState
+      });
+    }
     const data = await executeModel({
       model: 'histogram',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -757,3 +868,5 @@ }),
         spatialFilter,
-        abortController
+        spatialFiltersMode,
+        abortController,
+        viewState
       } = options,
@@ -764,5 +877,15 @@ params = _objectWithoutPropertiesLoose(options, _excluded5);
     } = params;
+    const source = this.getModelSource(filterOwner);
+    let spatialFiltersResolution;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState
+      });
+    }
     return executeModel({
       model: 'range',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -789,3 +912,5 @@ }),
         spatialFilter,
-        abortController
+        spatialFiltersMode,
+        abortController,
+        viewState
       } = options,
@@ -799,2 +924,10 @@ params = _objectWithoutPropertiesLoose(options, _excluded6);
     } = params;
+    const source = this.getModelSource(filterOwner);
+    let spatialFiltersResolution;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState
+      });
+    }
     // Make sure this is sync with the same constant in cloud-native/maps-api
@@ -804,3 +937,5 @@ const HARD_LIMIT = 500;
       model: 'scatterplot',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -834,3 +969,5 @@ }),
         spatialFilter,
-        abortController
+        spatialFiltersMode,
+        abortController,
+        viewState
       } = options,
@@ -845,5 +982,15 @@ params = _objectWithoutPropertiesLoose(options, _excluded7);
     } = params;
+    const source = this.getModelSource(filterOwner);
+    let spatialFiltersResolution;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState
+      });
+    }
     return executeModel({
       model: 'table',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -881,3 +1028,5 @@ }),
         abortController,
-        spatialFilter
+        spatialFilter,
+        spatialFiltersMode,
+        viewState
       } = options,
@@ -896,5 +1045,15 @@ params = _objectWithoutPropertiesLoose(options, _excluded8);
     } = params;
+    const source = this.getModelSource(filterOwner);
+    let spatialFiltersResolution;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState
+      });
+    }
     return executeModel({
       model: 'timeseries',
-      source: _extends({}, this.getModelSource(filterOwner), {
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
         spatialFilter
@@ -930,4 +1089,3 @@ }),
   filters: {},
-  filtersLogicalOperator: 'and',
-  geoColumn: DEFAULT_GEO_COLUMN
+  filtersLogicalOperator: 'and'
 };
@@ -1336,3 +1494,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'
+    }))
   }));
@@ -1362,3 +1524,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'
+    }))
   }));
@@ -1418,3 +1584,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'
+    }))
   }));
@@ -1444,3 +1614,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'
+    }))
   }));
@@ -1485,3 +1659,5 @@ };
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      spatialDataType: 'geo'
+    }))
   }));
@@ -1511,3 +1687,5 @@ };
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      spatialDataType: 'geo'
+    }))
   }));
@@ -1514,0 +1692,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

@@ -41,2 +41,26 @@ import type { Feature } from 'geojson';
     maxLengthURL?: number;
+    /**
+     * 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;
 };
@@ -59,2 +83,6 @@ export type SourceOptions = SourceRequiredOptions & Partial<SourceOptionalOptions>;
     aggregationResLevel?: number;
+    /**
+     * Original resolution of the spatial index data as stored in the DW
+     */
+    dataResolution?: number;
 };
@@ -68,25 +96,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.
@@ -122,22 +130,2 @@ *
     tableName: string;
-    /**
-     * 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;
 };
@@ -159,2 +147,9 @@ export type TilesetSourceOptions = {
 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 & {
@@ -161,0 +156,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,7 +6,14 @@ /******************************************************************************
  */
+export interface ViewState {
+    zoom: number;
+    latitude: number;
+    longitude: number;
+}
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
     spatialFilter?: SpatialFilter;
+    spatialFiltersMode?: SpatialFilterPolyfillMode;
     abortController?: AbortController;
     filterOwner?: string;
+    viewState?: ViewState;
 }
@@ -13,0 +20,0 @@ /** Options for {@link WidgetBaseSource#getCategories}. */

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

@@ -8,3 +8,2 @@ import { CategoryRequestOptions, CategoryResponse, FeaturesRequestOptions, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
     apiVersion?: ApiVersion;
-    geoColumn?: string;
     filters?: Record<string, Filter>;
@@ -11,0 +10,0 @@ filtersLogicalOperator?: FilterLogicalOperator;

package.json

@@ -7,3 +7,3 @@ {
   "packageManager": "yarn@4.3.1",
-  "version": "0.4.0",
+  "version": "0.4.1-alpha.0",
   "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; // JSON.stringify(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 = {
@@ -63,5 +64,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

@@ -58,5 +58,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

@@ -63,5 +63,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

@@ -59,5 +59,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

@@ -50,2 +50,29 @@ // deck.gl
   maxLengthURL?: number;
+
+  /**
+   * 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;
 };
@@ -72,2 +99,7 @@
   aggregationResLevel?: number;
+
+  /**
+   * Original resolution of the spatial index data as stored in the DW
+   */
+  dataResolution?: number;
 };
@@ -83,28 +115,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.
@@ -141,24 +151,2 @@ *
   tableName: string;
-
-  /**
-   * 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;
 };
@@ -184,2 +172,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 & {
@@ -186,0 +182,0 @@ tilejson: {url: string[]};

src/sources/vector-query-source.ts

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

src/sources/vector-table-source.ts

@@ -25,2 +25,3 @@ // deck.gl
   ColumnsOption;
+
 type UrlParameters = {
@@ -62,5 +63,8 @@ columns?: string;
       ...(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,7 +13,15 @@ GroupDateType,
 
+export interface ViewState {
+  zoom: number;
+  latitude: number;
+  longitude: number;
+}
+
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
+  spatialFiltersMode?: SpatialFilterPolyfillMode;
   abortController?: AbortController;
   filterOwner?: string;
+  viewState?: ViewState;
 }
@@ -20,0 +28,0 @@

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

@@ -19,5 +19,6 @@ import {executeModel} from '../models/index.js';
   TimeSeriesResponse,
+  ViewState,
 } from './types.js';
 import {FilterLogicalOperator, Filter} from '../types.js';
-import {getApplicableFilters, normalizeObjectKeys} from '../utils.js';
+import {assert, getApplicableFilters, normalizeObjectKeys} from '../utils.js';
 import {getClient} from '../client.js';
@@ -31,6 +32,6 @@ import {ModelSource} from '../models/model.js';
 } from '../constants-internal.js';
+import {getSpatialFiltersResolution} from '../spatial-index.js';
 
 export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
   apiVersion?: ApiVersion;
-  geoColumn?: string;
   filters?: Record<string, Filter>;
@@ -56,3 +57,2 @@ filtersLogicalOperator?: FilterLogicalOperator;
     filtersLogicalOperator: 'and',
-    geoColumn: DEFAULT_GEO_COLUMN,
   };
@@ -84,3 +84,4 @@
       filtersLogicalOperator: props.filtersLogicalOperator,
-      geoColumn: props.geoColumn,
+      spatialDataType: props.spatialDataType,
+      spatialDataColumn: props.spatialDataColumn,
     };
@@ -100,5 +101,21 @@ }
   ): Promise<CategoryResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      abortController,
+      viewState,
+      ...params
+    } = options;
     const {column, operation, operationColumn} = params;
+    const source = this.getModelSource(filterOwner);
 
+    let spatialFiltersResolution: number | undefined;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState,
+      });
+    }
+
     type CategoriesModelResponse = {rows: {name: string; value: number}[]};
@@ -108,3 +125,8 @@
       model: 'category',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
@@ -134,5 +156,21 @@ column,
   ): Promise<FeaturesResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      abortController,
+      viewState,
+      ...params
+    } = options;
     const {columns, dataType, featureIds, z, limit, tileResolution} = params;
+    const source = this.getModelSource(filterOwner);
 
+    let spatialFiltersResolution: number | undefined;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState,
+      });
+    }
+
     type FeaturesModelResponse = {rows: Record<string, unknown>[]};
@@ -142,3 +180,8 @@
       model: 'pick',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
@@ -170,8 +213,19 @@ columns,
       spatialFilter,
+      spatialFiltersMode,
       abortController,
       operationExp,
+      viewState,
       ...params
     } = options;
     const {column, operation} = params;
+    const source = this.getModelSource(filterOwner);
 
+    let spatialFiltersResolution: number | undefined;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState,
+      });
+    }
+
     type FormulaModelResponse = {rows: {value: number}[]};
@@ -181,3 +235,8 @@
       model: 'formula',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {column: column ?? '*', operation, operationExp},
@@ -199,5 +258,21 @@ opts: {abortController},
   ): Promise<HistogramResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      abortController,
+      viewState,
+      ...params
+    } = options;
     const {column, operation, ticks} = params;
+    const source = this.getModelSource(filterOwner);
 
+    let spatialFiltersResolution: number | undefined;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState,
+      });
+    }
+
     type HistogramModelResponse = {rows: {tick: number; value: number}[]};
@@ -207,3 +282,8 @@
       model: 'histogram',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {column, operation, ticks},
@@ -236,5 +316,21 @@ opts: {abortController},
   async getRange(options: RangeRequestOptions): Promise<RangeResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      abortController,
+      viewState,
+      ...params
+    } = options;
     const {column} = params;
+    const source = this.getModelSource(filterOwner);
 
+    let spatialFiltersResolution: number | undefined;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState,
+      });
+    }
+
     type RangeModelResponse = {rows: {min: number; max: number}[]};
@@ -244,3 +340,8 @@
       model: 'range',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {column},
@@ -260,6 +361,23 @@ opts: {abortController},
   async getScatter(options: ScatterRequestOptions): Promise<ScatterResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      abortController,
+      viewState,
+      ...params
+    } = options;
     const {xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation} =
       params;
 
+    const source = this.getModelSource(filterOwner);
+
+    let spatialFiltersResolution: number | undefined;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState,
+      });
+    }
+
     // 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,5 +419,21 @@ xAxisColumn,
   async getTable(options: TableRequestOptions): Promise<TableResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = options;
+    const {
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      abortController,
+      viewState,
+      ...params
+    } = options;
     const {columns, sortBy, sortDirection, offset = 0, limit = 10} = params;
+    const source = this.getModelSource(filterOwner);
 
+    let spatialFiltersResolution: number | undefined;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState,
+      });
+    }
+
     type TableModelResponse = {
@@ -307,3 +446,8 @@ rows: Record<string, number | string>[];
       model: 'table',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
@@ -335,4 +479,11 @@ column: columns,
   ): Promise<TimeSeriesResponse> {
-    const {filterOwner, abortController, spatialFilter, ...params} = options;
     const {
+      filterOwner,
+      abortController,
+      spatialFilter,
+      spatialFiltersMode,
+      viewState,
+      ...params
+    } = options;
+    const {
       column,
@@ -349,2 +500,12 @@ operationColumn,
 
+    const source = this.getModelSource(filterOwner);
+
+    let spatialFiltersResolution: number | undefined;
+    if (spatialFilter && source.spatialDataType !== 'geo') {
+      spatialFiltersResolution = getSpatialFiltersResolution({
+        source,
+        viewState,
+      });
+    }
+
     type TimeSeriesModelResponse = {
@@ -357,3 +518,8 @@ rows: {name: string; value: number}[];
       model: 'timeseries',
-      source: {...this.getModelSource(filterOwner), spatialFilter},
+      source: {
+        ...source,
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter,
+      },
       params: {
@@ -360,0 +526,0 @@ column,

No alert changes

Improved metrics

Total package byte prevSize

496426

increased by12.6%

Number of package files

85

increased by2.41%

Lines of code

7536

increased by10.01%

No dependency changes