@carto/api-client 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ## 0.4
 
+### 0.4.4
+
+- feat: Add support for spatial index types (H3, quadbin) in Widget APIs
+
 ### 0.4.3
 
 - feat: Add support for`aggregationExp` parameter to `vectorQuerySource` and `vectorTableSource`

package/build/api/query.d.ts

@@ -1,3 +1,3 @@
 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>;

package/build/api-client.cjs

@@ -893,41 +893,43 @@ function executeModel(props) {
     data,
     filters,
     filtersLogicalOperator = 'and',
-    geoColumn = DEFAULT_GEO_COLUMN
+    spatialDataType = 'geo',
+    spatialFiltersMode = 'intersects',
+    spatialFiltersResolution = 0
   } = source;
-  const queryParameters = source.queryParameters ? JSON.stringify(source.queryParameters) : '';
   const queryParams = {
     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();
+  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;
-    }
   }
   return makeCall({
     url,
@@ -941,6 +943,63 @@ function executeModel(props) {
     }
   });
 }
+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 DEFAULT_TILE_SIZE = 512;
+const QUADBIN_ZOOM_MAX_OFFSET = 4;
+function getSpatialFiltersResolution(source, viewState) {
+  const dataResolution = source.dataResolution ?? Number.MAX_VALUE;
+  const aggregationResLevel = source.aggregationResLevel ?? (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') {
+    const tileSize = DEFAULT_TILE_SIZE;
+    const maxResolutionForZoom = maxH3SpatialFiltersResolutions.find(_ref => {
+      let [zoom] = _ref;
+      return zoom === currentZoomInt;
+    })?.[1] ?? 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));
+}
 
 /**
  * Source for Widget API requests on a data source defined by a SQL query.
@@ -965,9 +1024,21 @@ class WidgetBaseSource {
       connectionName: props.connectionName,
       filters: getApplicableFilters(owner, props.filters),
       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);
+  }
   /****************************************************************************
    * CATEGORIES
    */
@@ -981,6 +1052,8 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController,
         ...params
       } = options;
@@ -989,10 +1062,14 @@ class WidgetBaseSource {
         operation,
         operationColumn
       } = params;
+      const source = _this.getModelSource(filterOwner);
+      const spatialFiltersResolution = _this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
       return Promise.resolve(executeModel({
         model: 'category',
         source: {
-          ..._this.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -1025,6 +1102,8 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController,
         ...params
       } = options;
@@ -1036,10 +1115,14 @@ class WidgetBaseSource {
         limit,
         tileResolution
       } = params;
+      const source = _this2.getModelSource(filterOwner);
+      const spatialFiltersResolution = _this2._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
       return Promise.resolve(executeModel({
         model: 'pick',
         source: {
-          ..._this2.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -1079,6 +1162,8 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController,
         operationExp,
         ...params
@@ -1087,10 +1172,14 @@ class WidgetBaseSource {
         column,
         operation
       } = params;
+      const source = _this3.getModelSource(filterOwner);
+      const spatialFiltersResolution = _this3._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
       return Promise.resolve(executeModel({
         model: 'formula',
         source: {
-          ..._this3.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -1119,6 +1208,8 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController,
         ...params
       } = options;
@@ -1127,10 +1218,14 @@ class WidgetBaseSource {
         operation,
         ticks
       } = params;
+      const source = _this4.getModelSource(filterOwner);
+      const spatialFiltersResolution = _this4._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
       return Promise.resolve(executeModel({
         model: 'histogram',
         source: {
-          ..._this4.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -1175,16 +1270,22 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController,
         ...params
       } = options;
       const {
         column
       } = params;
+      const source = _this5.getModelSource(filterOwner);
+      const spatialFiltersResolution = _this5._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
       return Promise.resolve(executeModel({
         model: 'range',
         source: {
-          ..._this5.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -1211,6 +1312,8 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController,
         ...params
       } = options;
@@ -1220,12 +1323,16 @@ class WidgetBaseSource {
         yAxisColumn,
         yAxisJoinOperation
       } = params;
+      const source = _this6.getModelSource(filterOwner);
+      const spatialFiltersResolution = _this6._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
       // Make sure this is sync with the same constant in cloud-native/maps-api
       const HARD_LIMIT = 500;
       return Promise.resolve(executeModel({
         model: 'scatterplot',
         source: {
-          ..._this6.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -1262,6 +1369,8 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         abortController,
         ...params
       } = options;
@@ -1272,10 +1381,14 @@ class WidgetBaseSource {
         offset = 0,
         limit = 10
       } = params;
+      const source = _this7.getModelSource(filterOwner);
+      const spatialFiltersResolution = _this7._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
       return Promise.resolve(executeModel({
         model: 'table',
         source: {
-          ..._this7.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -1311,6 +1424,8 @@ class WidgetBaseSource {
         filterOwner,
         abortController,
         spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
         ...params
       } = options;
       const {
@@ -1324,10 +1439,14 @@ class WidgetBaseSource {
         splitByCategoryLimit,
         splitByCategoryValues
       } = params;
+      const source = _this8.getModelSource(filterOwner);
+      const spatialFiltersResolution = _this8._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
       return Promise.resolve(executeModel({
         model: 'timeseries',
         source: {
-          ..._this8.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -1358,8 +1477,7 @@ WidgetBaseSource.defaultProps = {
   apiBaseUrl: DEFAULT_API_BASE_URL,
   clientId: getClient(),
   filters: {},
-  filtersLogicalOperator: 'and',
-  geoColumn: DEFAULT_GEO_COLUMN
+  filtersLogicalOperator: 'and'
 };
 
 /**
@@ -1455,7 +1573,12 @@ const h3QuerySource = function (options) {
     }
     return Promise.resolve(baseSource('query', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetQuerySource(options)
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+        spatialDataColumn,
+        spatialDataType: 'h3'
+      })
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1486,7 +1609,12 @@ const h3TableSource = function (options) {
     }
     return Promise.resolve(baseSource('table', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetTableSource(options)
+      widgetSource: new WidgetTableSource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+        spatialDataColumn,
+        spatialDataType: 'h3'
+      })
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1555,7 +1683,12 @@ const quadbinQuerySource = function (options) {
     }
     return Promise.resolve(baseSource('query', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetQuerySource(options)
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+        spatialDataColumn,
+        spatialDataType: 'quadbin'
+      })
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1586,7 +1719,12 @@ const quadbinTableSource = function (options) {
     }
     return Promise.resolve(baseSource('table', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetTableSource(options)
+      widgetSource: new WidgetTableSource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+        spatialDataColumn,
+        spatialDataType: 'quadbin'
+      })
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1640,7 +1778,10 @@ const vectorQuerySource = function (options) {
     }
     return Promise.resolve(baseSource('query', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetQuerySource(options)
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        spatialDataType: 'geo'
+      })
     })));
   } catch (e) {
     return Promise.reject(e);
@@ -1675,7 +1816,10 @@ const vectorTableSource = function (options) {
     }
     return Promise.resolve(baseSource('table', options, urlParameters).then(result => ({
       ...result,
-      widgetSource: new WidgetTableSource(options)
+      widgetSource: new WidgetTableSource({
+        ...options,
+        spatialDataType: 'geo'
+      })
     })));
   } catch (e) {
     return Promise.reject(e);