@carto/api-client 0.4.3 → 0.4.5-alpha.0

package/src/sources/types.ts

@@ -48,6 +48,33 @@ export type SourceOptionalOptions = {
    */
   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;
+
   /**
    * By default, local in-memory caching is enabled.
    */
@@ -89,6 +116,11 @@ export type AggregationOptions = {
    * @default 6 for quadbin and 4 for h3 sources
    */
   aggregationResLevel?: number;
+
+  /**
+   * Original resolution of the spatial index data as stored in the DW
+   */
+  dataResolution?: number;
 };
 
 export type FilterOptions = {
@@ -99,31 +131,9 @@ 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.
    *
@@ -166,28 +176,6 @@ export type TableSourceOptions = {
    */
   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;
-
   /**
    * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
    *
@@ -216,6 +204,14 @@ export type ColumnsOption = {
 
 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 & {
   tilejson: {url: string[]};
 };

package/src/sources/vector-query-source.ts

@@ -50,9 +50,11 @@ export const vectorQuerySource = async function (
     aggregationExp,
   } = options;
 
+  const spatialDataType = 'geo';
+
   const urlParameters: UrlParameters = {
     spatialDataColumn,
-    spatialDataType: 'geo',
+    spatialDataType,
     tileResolution: tileResolution.toString(),
     q: sqlQuery,
   };
@@ -69,10 +71,17 @@ export const vectorQuerySource = async function (
   if (aggregationExp) {
     urlParameters.aggregationExp = aggregationExp;
   }
+
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource(options),
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        // NOTE: Parameters with default values above must be explicitly passed here.
+        spatialDataColumn,
+        spatialDataType,
+        tileResolution,
+      }),
     })
   );
 };

package/src/sources/vector-table-source.ts

@@ -48,10 +48,12 @@ export const vectorTableSource = async function (
     aggregationExp,
   } = options;
 
+  const spatialDataType = 'geo';
+
   const urlParameters: UrlParameters = {
     name: tableName,
     spatialDataColumn,
-    spatialDataType: 'geo',
+    spatialDataType,
     tileResolution: tileResolution.toString(),
   };
 
@@ -64,10 +66,17 @@ export const vectorTableSource = async function (
   if (aggregationExp) {
     urlParameters.aggregationExp = aggregationExp;
   }
+
   return baseSource<UrlParameters>('table', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetTableSource(options),
+      widgetSource: new WidgetTableSource({
+        ...options,
+        // NOTE: Parameters with default values above must be explicitly passed here.
+        spatialDataColumn,
+        spatialDataType,
+        tileResolution,
+      }),
     })
   );
 };

package/src/spatial-index.ts

@@ -0,0 +1,111 @@
+import {
+  DEFAULT_AGGREGATION_RES_LEVEL_H3,
+  DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
+} from './constants-internal';
+import type {ModelSource} from './models/model';
+import type {AggregationOptions} from './sources/types';
+import {assert} from './utils';
+import type {ViewState} from './widget-sources';
+
+const DEFAULT_TILE_SIZE = 512;
+const QUADBIN_ZOOM_MAX_OFFSET = 4;
+
+export function getSpatialFiltersResolution(
+  source: Partial<ModelSource & AggregationOptions>,
+  viewState: ViewState
+): number | undefined {
+  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(
+        ([zoom]) => 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
+export function getHexagonResolution(
+  viewport: {zoom: number; latitude: number},
+  tileSize: number
+): number {
+  // 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)
+  );
+}

package/src/utils.ts

@@ -49,15 +49,18 @@ export function normalizeObjectKeys<T, R extends Row<T>>(el: R): R {
     return el;
   }
 
-  return Object.entries(el as Record<string, T>).reduce((acc, [key, value]) => {
-    acc[key.toLowerCase()] =
-      typeof value === 'object' && value ? normalizeObjectKeys(value) : value;
-    return acc;
-  }, {} as Record<string, T>) as R;
+  return Object.entries(el as Record<string, T>).reduce(
+    (acc, [key, value]) => {
+      acc[key.toLowerCase()] =
+        typeof value === 'object' && value ? normalizeObjectKeys(value) : value;
+      return acc;
+    },
+    {} as Record<string, T>
+  ) as R;
 }
 
 /** @internalRemarks Source: @carto/react-core */
-export function assert(condition: unknown, message: string) {
+export function assert(condition: unknown, message: string): asserts condition {
   if (!condition) {
     throw new Error(message);
   }

package/src/widget-sources/types.ts

@@ -1,4 +1,4 @@
-import {TileResolution} from '../sources/types';
+import {SpatialFilterPolyfillMode, TileResolution} from '../sources/types';
 import {
   GroupDateType,
   SortColumnType,
@@ -10,9 +10,18 @@ import {
  * WIDGET API REQUESTS
  */
 
+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;
   filterOwner?: string;
 }