@carto/api-client 0.5.0-alpha.8 → 0.5.0

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 = {
@@ -196,7 +191,7 @@ export type TilesetSourceOptions = {
    * Whether to use Web Workers for local widget calculations. Workers
    * are used by default if the runtime environment supports ES Module Workers.
    */
-  widgetSourceWorker?: boolean;
+  widgetWorker?: boolean;
 };
 
 export type ColumnsOption = {
@@ -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;
 
@@ -34,13 +33,6 @@ export type WidgetRemoteSourceProps = WidgetSourceProps;
 export abstract class WidgetRemoteSource<
   Props extends WidgetRemoteSourceProps,
 > extends WidgetSource<Props> {
-  protected _headers: Record<string, string> = {};
-
-  /** Assigns HTTP headers to be included on API requests from this source. */
-  setRequestHeaders(headers: Record<string, string>): void {
-    this._headers = headers;
-  }
-
   /**
    * Subclasses of {@link WidgetRemoteSource} must implement this method, calling
    * {@link WidgetRemoteSource.prototype._getModelSource} for common source
@@ -67,7 +59,6 @@ export abstract class WidgetRemoteSource<
       filtersLogicalOperator: props.filtersLogicalOperator,
       spatialDataType: props.spatialDataType,
       spatialDataColumn: props.spatialDataColumn,
-      dataResolution: (props as Partial<AggregationOptions>).dataResolution,
     };
   }
 
@@ -80,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,
       },
@@ -106,7 +89,7 @@ export abstract class WidgetRemoteSource<
         operation,
         operationColumn: operationColumn || column,
       },
-      opts: {signal, headers: this._headers},
+      opts: {signal, headers: this.props.headers},
     }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
   }
 
@@ -119,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,
       },
@@ -148,7 +123,7 @@ export abstract class WidgetRemoteSource<
         limit: limit || 1000,
         tileResolution: tileResolution || DEFAULT_TILE_RESOLUTION,
       },
-      opts: {signal, headers: this._headers},
+      opts: {signal, headers: this.props.headers},
       // Avoid `normalizeObjectKeys()`, which changes column names.
     }).then(({rows}: FeaturesModelResponse) => ({rows}));
   }
@@ -160,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,
       },
@@ -187,7 +154,7 @@ export abstract class WidgetRemoteSource<
         operation: operation ?? 'count',
         operationExp,
       },
-      opts: {signal, headers: this._headers},
+      opts: {signal, headers: this.props.headers},
     }).then((res: FormulaModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
@@ -200,29 +167,21 @@ 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,
       },
       params: {column, operation, ticks},
-      opts: {signal, headers: this._headers},
+      opts: {signal, headers: this.props.headers},
     }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
 
     if (data.length) {
@@ -245,29 +204,21 @@ 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,
       },
       params: {column},
-      opts: {signal, headers: this._headers},
+      opts: {signal, headers: this.props.headers},
     }).then((res: RangeModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
@@ -278,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;
 
@@ -299,8 +242,7 @@ export abstract class WidgetRemoteSource<
     return executeModel({
       model: 'scatterplot',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -311,7 +253,7 @@ export abstract class WidgetRemoteSource<
         yAxisJoinOperation,
         limit: HARD_LIMIT,
       },
-      opts: {signal, headers: this._headers},
+      opts: {signal, headers: this.props.headers},
     })
       .then((res: ScatterModelResponse) => normalizeObjectKeys(res.rows))
       .then((res) => res.map(({x, y}: {x: number; y: number}) => [x, y]));
@@ -324,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>[];
@@ -343,8 +278,7 @@ export abstract class WidgetRemoteSource<
     return executeModel({
       model: 'table',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -355,7 +289,7 @@ export abstract class WidgetRemoteSource<
         limit,
         offset,
       },
-      opts: {signal, headers: this._headers},
+      opts: {signal, headers: this.props.headers},
     }).then((res: TableModelResponse) => ({
       // Avoid `normalizeObjectKeys()`, which changes column names.
       rows: res.rows ?? (res as any).ROWS,
@@ -372,7 +306,6 @@ export abstract class WidgetRemoteSource<
       filterOwner,
       spatialFilter,
       spatialFiltersMode,
-      spatialIndexReferenceViewState,
       ...params
     } = options;
     const {
@@ -387,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[]};
@@ -402,8 +328,7 @@ export abstract class WidgetRemoteSource<
     return executeModel({
       model: 'timeseries',
       source: {
-        ...source,
-        spatialFiltersResolution,
+        ...this.getModelSource(filters, filterOwner),
         spatialFiltersMode,
         spatialFilter,
       },
@@ -418,7 +343,7 @@ export abstract class WidgetRemoteSource<
         splitByCategoryLimit,
         splitByCategoryValues,
       },
-      opts: {signal, headers: this._headers},
+      opts: {signal, headers: this.props.headers},
     }).then((res: TimeSeriesModelResponse) => ({
       rows: normalizeObjectKeys(res.rows),
       categories: res.metadata?.categories,

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;
@@ -35,7 +32,9 @@ export interface WidgetSourceProps extends Omit<SourceOptions, 'filters'> {
  *
  * Abstract class. Use {@link WidgetQuerySource} or {@link WidgetTableSource}.
  */
-export abstract class WidgetSource<Props extends WidgetSourceProps> {
+export abstract class WidgetSource<
+  Props extends WidgetSourceProps = WidgetSourceProps,
+> {
   readonly props: Props;
 
   static defaultProps: Partial<WidgetSourceProps> = {
@@ -47,7 +46,11 @@ export abstract class WidgetSource<Props extends WidgetSourceProps> {
   };
 
   constructor(props: Props) {
-    this.props = {...WidgetSource.defaultProps, ...props};
+    this.props = {
+      ...WidgetSource.defaultProps,
+      clientId: getClient(), // Refresh clientId, default may have changed.
+      ...props,
+    };
   }
 
   /**
@@ -61,25 +64,6 @@ export abstract class WidgetSource<Props extends WidgetSourceProps> {
     // 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),