@carto/api-client 0.5.0-alpha.13 → 0.5.0-alpha.15

package/src/sources/types.ts

@@ -116,11 +116,6 @@ 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 = {
@@ -364,8 +359,20 @@ export enum RasterBandColorinterp {
   Palette = 'palette',
 }
 
+export type RasterBandType =
+  | 'uint8'
+  | 'int8'
+  | 'uint16'
+  | 'int16'
+  | 'uint32'
+  | 'int32'
+  | 'uint64'
+  | 'int64'
+  | 'float32'
+  | 'float64';
+
 export type RasterMetadataBand = {
-  type: string;
+  type: RasterBandType;
   name: string;
   stats: RasterMetadataBandStats;
   /**
@@ -379,7 +386,7 @@ export type RasterMetadataBand = {
   /**
    * Default color mapping for unique values (or if coloprinterp is `palette`)
    */
-  colortable?: Record<string, number[]>;
+  colortable?: Record<string, [number, number, number, number]>;
 
   /**
    * No value representation.

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

@@ -2,13 +2,13 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {baseSource} from './base-source.js';
 import {DEFAULT_GEO_COLUMN} from '../constants-internal.js';
 import {getTileFormat} from '../utils/getTileFormat.js';
 import {
   WidgetTilesetSource,
   WidgetTilesetSourceResult,
 } from '../widget-sources/index.js';
-import {baseSource} from './base-source.js';
 import type {
   SourceOptions,
   TilesetSourceOptions,

package/src/spatial-index.ts

@@ -1,88 +1,6 @@
-import {
-  DEFAULT_AGGREGATION_RES_LEVEL_H3,
-  DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
-} from './constants-internal.js';
-import type {ModelSource} from './models/model.js';
-import type {AggregationOptions} from './sources/types.js';
-import type {ViewState} from './widget-sources/index.js';
-
+// Default tile display size in deck.gl, in viewport pixels. May differ
+// from size or resolution assumed when generating the tile data,
 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;
@@ -92,6 +10,7 @@ const BIAS = 2;
  * a H3 resolution such that the screen space size of the hexagons is
  * "similar" to the given tileSize on screen. Intended for use with deck.gl.
  * @internal
+ * @privateRemarks Source: https://github.com/visgl/deck.gl/blob/master/modules/carto/src/layers/h3-tileset-2d.ts
  */
 export function _getHexagonResolution(
   viewport: {zoom: number; latitude: number},

package/src/types.ts

@@ -12,6 +12,16 @@ export type Format = 'json' | 'geojson' | 'tilejson';
 /** @privateRemarks Source: @carto/constants, @deck.gl/carto */
 export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
 
+/** @privateRemarks Source: cloud-native */
+export type ProviderType =
+  | 'bigquery'
+  | 'postgres'
+  | 'snowflake'
+  | 'redshift'
+  | 'databricks'
+  | 'carto'
+  | 'carto_dw';
+
 /**
  * Alias for GeoJSON 'BBox' type, semantically representing a viewport.
  * Order of values is "west", "south", "east", "north".
@@ -28,8 +38,6 @@ export type Viewport = [number, number, number, number];
 export type Tile = {
   index: {x: number; y: number; z: number};
   id: string;
-  content: unknown;
-  zoom: number;
   bbox: {west: number; east: number; north: number; south: number};
   isVisible: boolean;
   data?: BinaryFeatureCollection;
@@ -40,6 +48,12 @@ export type SpatialIndexTile = Tile & {
   data?: (Feature & {id: bigint})[];
 };
 
+export type RasterTile = Tile & {
+  id: string;
+  index: {q: bigint; i: string};
+  data?: Raster;
+};
+
 /** @privateRemarks Source: @deck.gl/carto */
 export type Raster = {
   blockSize: number;

package/src/widget-sources/index.ts

@@ -1,5 +1,6 @@
 export * from './widget-source.js';
 export * from './widget-query-source.js';
+export * from './widget-raster-source.js';
 export * from './widget-remote-source.js';
 export * from './widget-table-source.js';
 export * from './widget-tileset-source.js';

package/src/widget-sources/types.ts

@@ -22,8 +22,6 @@ interface BaseRequestOptions {
   signal?: AbortSignal;
   spatialFilter?: SpatialFilter;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
-  /** Required for table- and query-based spatial index sources (H3, Quadbin). */
-  spatialIndexReferenceViewState?: ViewState;
   /** Overrides source filters, if any. */
   filters?: Filters;
   filterOwner?: string;

package/src/widget-sources/widget-raster-source.ts

@@ -0,0 +1,14 @@
+import {RasterMetadata} from '../sources/index.js';
+import {
+  WidgetTilesetSource,
+  WidgetTilesetSourceProps,
+} from './widget-tileset-source.js';
+
+export type WidgetRasterSourceProps = WidgetTilesetSourceProps & {
+  rasterMetadata: RasterMetadata;
+  spatialDataType: 'quadbin';
+};
+
+export type WidgetRasterSourceResult = {widgetSource: WidgetRasterSource};
+
+export class WidgetRasterSource extends WidgetTilesetSource<WidgetRasterSourceProps> {}

package/src/widget-sources/widget-remote-source.ts

@@ -22,7 +22,6 @@ import {DEFAULT_TILE_RESOLUTION} from '../constants-internal.js';
 import {WidgetSource, WidgetSourceProps} from './widget-source.js';
 import {Filters} from '../types.js';
 import {ApiVersion} from '../constants.js';
-import {AggregationOptions} from '../sources/types.js';
 
 export type WidgetRemoteSourceProps = WidgetSourceProps;
 
@@ -60,7 +59,6 @@ export abstract class WidgetRemoteSource<
       filtersLogicalOperator: props.filtersLogicalOperator,
       spatialDataType: props.spatialDataType,
       spatialDataColumn: props.spatialDataColumn,
-      dataResolution: (props as Partial<AggregationOptions>).dataResolution,
     };
   }
 
@@ -73,24 +71,16 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {column, operation, operationColumn} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type CategoriesModelResponse = {rows: {name: string; value: number}[]};
 
     return executeModel({
       model: 'category',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -112,24 +102,16 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {columns, dataType, featureIds, z, limit, tileResolution} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type FeaturesModelResponse = {rows: Record<string, unknown>[]};
 
     return executeModel({
       model: 'pick',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -153,25 +135,17 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       operationExp,
       ...params
     } = options;
     const {column, operation} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type FormulaModelResponse = {rows: {value: number}[]};
 
     return executeModel({
       model: 'formula',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -193,24 +167,16 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {column, operation, ticks} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type HistogramModelResponse = {rows: {tick: number; value: number}[]};
 
     const data = await executeModel({
       model: 'histogram',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -238,24 +204,16 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {column} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type RangeModelResponse = {rows: {min: number; max: number}[]};
 
     return executeModel({
       model: 'range',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -271,19 +229,11 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation} =
       params;
 
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
-
     // Make sure this is sync with the same constant in cloud-native/maps-api
     const HARD_LIMIT = 500;
 
@@ -292,8 +242,7 @@ export abstract class WidgetRemoteSource<
     return executeModel({
       model: 'scatterplot',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -317,16 +266,9 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {columns, sortBy, sortDirection, offset = 0, limit = 10} = params;
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
 
     type TableModelResponse = {
       rows: Record<string, number | string>[];
@@ -336,8 +278,7 @@ export abstract class WidgetRemoteSource<
     return executeModel({
       model: 'table',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -365,7 +306,6 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {
@@ -380,13 +320,6 @@ export abstract class WidgetRemoteSource<
       splitByCategoryValues,
     } = params;
 
-    const source = this.getModelSource(filters, filterOwner);
-    const spatialFiltersResolution = this._getSpatialFiltersResolution(
-      source,
-      spatialFilter,
-      spatialIndexReferenceViewState
-    );
-
     type TimeSeriesModelResponse = {
       rows: {name: string; value: number}[];
       metadata: {categories: string[]};
@@ -395,8 +328,7 @@ export abstract class WidgetRemoteSource<
     return executeModel({
       model: 'timeseries',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },

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

@@ -15,14 +15,11 @@ import {
   TableResponse,
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
-  ViewState,
 } from './types.js';
-import {FilterLogicalOperator, Filter, SpatialFilter} from '../types.js';
+import {FilterLogicalOperator, Filter} from '../types.js';
 import {getClient} from '../client.js';
-import {ModelSource} from '../models/model.js';
 import {SourceOptions} from '../sources/index.js';
 import {ApiVersion, DEFAULT_API_BASE_URL} from '../constants.js';
-import {getSpatialFiltersResolution} from '../spatial-index.js';
 
 export interface WidgetSourceProps extends Omit<SourceOptions, 'filters'> {
   apiVersion?: ApiVersion;
@@ -49,7 +46,11 @@ export abstract class WidgetSource<
   };
 
   constructor(props: Props) {
-    this.props = {...WidgetSource.defaultProps, ...props};
+    this.props = {
+      ...WidgetSource.defaultProps,
+      clientId: getClient(), // Refresh clientId, default may have changed.
+      ...props,
+    };
   }
 
   /**
@@ -63,25 +64,6 @@ export abstract class WidgetSource<
     // no-op in most cases, but required for worker sources.
   }
 
-  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);
-  }
-
   /**
    * Returns a list of labeled datapoints for categorical data. Suitable for
    * charts including grouped bar charts, pie charts, and tree charts.

package/src/widget-sources/widget-tileset-source-impl.ts

@@ -84,13 +84,10 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     }
 
     this._features = tileFeatures({
-      tiles: this._tiles,
-      tileFormat: this.props.tileFormat,
+      ...this.props,
       ...this._tileFeatureExtractOptions,
-
+      tiles: this._tiles,
       spatialFilter,
-      spatialDataColumn: this.props.spatialDataColumn,
-      spatialDataType: this.props.spatialDataType,
     });
 
     prevInputs.spatialFilter = spatialFilter;
@@ -128,15 +125,6 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     filterOwner,
     spatialFilter,
   }: FormulaRequestOptions): Promise<FormulaResponse> {
-    if (operation === 'custom') {
-      throw new Error('Custom aggregation not supported for tilesets');
-    }
-
-    // Column is required except when operation is 'count'.
-    if ((column && column !== '*') || operation !== 'count') {
-      assertColumn(this._features, column);
-    }
-
     const filteredFeatures = this._getFilteredFeatures(
       spatialFilter,
       filters,
@@ -147,6 +135,15 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
       return {value: null};
     }
 
+    if (operation === 'custom') {
+      throw new Error('Custom aggregation not supported for tilesets');
+    }
+
+    // Column is required except when operation is 'count'.
+    if ((column && column !== '*') || operation !== 'count') {
+      assertColumn(this._features, column);
+    }
+
     const targetOperation = aggregationFunctions[operation];
     return {
       value: targetOperation(filteredFeatures, column, joinOperation),
@@ -347,8 +344,6 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     filterOwner,
     spatialFilter,
   }: RangeRequestOptions): Promise<RangeResponse> {
-    assertColumn(this._features, column);
-
     const filteredFeatures = this._getFilteredFeatures(
       spatialFilter,
       filters,
@@ -361,6 +356,8 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
       return null;
     }
 
+    assertColumn(this._features, column);
+
     return {
       min: aggregationFunctions.min(filteredFeatures, column),
       max: aggregationFunctions.max(filteredFeatures, column),

package/src/widget-sources/widget-tileset-source.ts

@@ -55,14 +55,16 @@ export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
  * const { widgetSource } = await data;
  * ```
  */
-export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps> {
+export class WidgetTilesetSource<
+  Props extends WidgetTilesetSourceProps = WidgetTilesetSourceProps,
+> extends WidgetSource<Props> {
   protected _localImpl: WidgetTilesetSourceImpl | null = null;
 
   protected _workerImpl: Worker | null = null;
   protected _workerEnabled: boolean;
   protected _workerNextRequestId = 1;
 
-  constructor(props: WidgetTilesetSourceProps) {
+  constructor(props: Props) {
     super(props);
 
     this._workerEnabled =
@@ -198,11 +200,22 @@ export class WidgetTilesetSource extends WidgetSource<WidgetTilesetSourceProps>
 
     const worker = this._getWorker();
 
-    tiles = (tiles as Tile[]).map(({id, bbox, data}) => ({
-      id,
-      bbox,
-      data,
-    }));
+    // We cannot pass an instance of Tile2DHeader to a Web Worker, and must
+    // extract properties required for widget calculations. Note that the
+    // `tile: Tile = {...}` assignment is structured so TS will warn if any
+    // types required by the internal 'Tile' type are missing.
+    tiles = (tiles as Tile[]).map(
+      ({id, index, bbox, isVisible, data}: Tile) => {
+        const tile: Tile = {
+          id,
+          index,
+          isVisible,
+          data,
+          bbox,
+        };
+        return tile;
+      }
+    );
 
     worker.postMessage({
       method: Method.LOAD_TILES,