@carto/api-client 0.4.1 → 0.4.2-alpha.0

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

@@ -509,41 +509,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; // 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;
-    }
   }
   return makeCall({
     url,
@@ -557,6 +559,68 @@ 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(_ref) {
+  let {
+    source,
+    viewState
+  } = _ref;
+  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.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(_ref2 => {
+      let [zoom] = _ref2;
+      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.
@@ -581,7 +645,9 @@ 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
     };
   }
   /****************************************************************************
@@ -597,7 +663,9 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
         abortController,
+        viewState,
         ...params
       } = options;
       const {
@@ -605,10 +673,20 @@ class WidgetBaseSource {
         operation,
         operationColumn
       } = params;
+      const source = _this.getModelSource(filterOwner);
+      let spatialFiltersResolution;
+      if (spatialFilter && source.spatialDataType !== 'geo') {
+        spatialFiltersResolution = getSpatialFiltersResolution({
+          source,
+          viewState
+        });
+      }
       return Promise.resolve(executeModel({
         model: 'category',
         source: {
-          ..._this.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -641,7 +719,9 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
         abortController,
+        viewState,
         ...params
       } = options;
       const {
@@ -652,10 +732,20 @@ class WidgetBaseSource {
         limit,
         tileResolution
       } = params;
+      const source = _this2.getModelSource(filterOwner);
+      let spatialFiltersResolution;
+      if (spatialFilter && source.spatialDataType !== 'geo') {
+        spatialFiltersResolution = getSpatialFiltersResolution({
+          source,
+          viewState
+        });
+      }
       return Promise.resolve(executeModel({
         model: 'pick',
         source: {
-          ..._this2.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -689,18 +779,30 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
         abortController,
         operationExp,
+        viewState,
         ...params
       } = options;
       const {
         column,
         operation
       } = params;
+      const source = _this3.getModelSource(filterOwner);
+      let spatialFiltersResolution;
+      if (spatialFilter && source.spatialDataType !== 'geo') {
+        spatialFiltersResolution = getSpatialFiltersResolution({
+          source,
+          viewState
+        });
+      }
       return Promise.resolve(executeModel({
         model: 'formula',
         source: {
-          ..._this3.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -729,7 +831,9 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
         abortController,
+        viewState,
         ...params
       } = options;
       const {
@@ -737,10 +841,20 @@ class WidgetBaseSource {
         operation,
         ticks
       } = params;
+      const source = _this4.getModelSource(filterOwner);
+      let spatialFiltersResolution;
+      if (spatialFilter && source.spatialDataType !== 'geo') {
+        spatialFiltersResolution = getSpatialFiltersResolution({
+          source,
+          viewState
+        });
+      }
       return Promise.resolve(executeModel({
         model: 'histogram',
         source: {
-          ..._this4.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -785,16 +899,28 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
         abortController,
+        viewState,
         ...params
       } = options;
       const {
         column
       } = params;
+      const source = _this5.getModelSource(filterOwner);
+      let spatialFiltersResolution;
+      if (spatialFilter && source.spatialDataType !== 'geo') {
+        spatialFiltersResolution = getSpatialFiltersResolution({
+          source,
+          viewState
+        });
+      }
       return Promise.resolve(executeModel({
         model: 'range',
         source: {
-          ..._this5.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -821,7 +947,9 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
         abortController,
+        viewState,
         ...params
       } = options;
       const {
@@ -830,12 +958,22 @@ class WidgetBaseSource {
         yAxisColumn,
         yAxisJoinOperation
       } = params;
+      const source = _this6.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
       const HARD_LIMIT = 500;
       return Promise.resolve(executeModel({
         model: 'scatterplot',
         source: {
-          ..._this6.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -872,7 +1010,9 @@ class WidgetBaseSource {
       const {
         filterOwner,
         spatialFilter,
+        spatialFiltersMode,
         abortController,
+        viewState,
         ...params
       } = options;
       const {
@@ -882,10 +1022,20 @@ class WidgetBaseSource {
         offset = 0,
         limit = 10
       } = params;
+      const source = _this7.getModelSource(filterOwner);
+      let spatialFiltersResolution;
+      if (spatialFilter && source.spatialDataType !== 'geo') {
+        spatialFiltersResolution = getSpatialFiltersResolution({
+          source,
+          viewState
+        });
+      }
       return Promise.resolve(executeModel({
         model: 'table',
         source: {
-          ..._this7.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -921,6 +1071,8 @@ class WidgetBaseSource {
         filterOwner,
         abortController,
         spatialFilter,
+        spatialFiltersMode,
+        viewState,
         ...params
       } = options;
       const {
@@ -934,10 +1086,20 @@ class WidgetBaseSource {
         splitByCategoryLimit,
         splitByCategoryValues
       } = params;
+      const source = _this8.getModelSource(filterOwner);
+      let spatialFiltersResolution;
+      if (spatialFilter && source.spatialDataType !== 'geo') {
+        spatialFiltersResolution = getSpatialFiltersResolution({
+          source,
+          viewState
+        });
+      }
       return Promise.resolve(executeModel({
         model: 'timeseries',
         source: {
-          ..._this8.getModelSource(filterOwner),
+          ...source,
+          spatialFiltersResolution,
+          spatialFiltersMode,
           spatialFilter
         },
         params: {
@@ -968,8 +1130,7 @@ WidgetBaseSource.defaultProps = {
   apiBaseUrl: DEFAULT_API_BASE_URL,
   clientId: getClient(),
   filters: {},
-  filtersLogicalOperator: 'and',
-  geoColumn: DEFAULT_GEO_COLUMN
+  filtersLogicalOperator: 'and'
 };
 
 /**
@@ -1449,7 +1610,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);
@@ -1480,7 +1646,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);
@@ -1549,7 +1720,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);
@@ -1580,7 +1756,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);
@@ -1630,7 +1811,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);
@@ -1661,7 +1845,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);