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

package/src/fetch-map/types.ts

@@ -0,0 +1,268 @@
+import {LayerType, SCALE_TYPE} from './layer-map.js';
+import {Format, MapType, ProviderType, QueryParameters} from '../types.js';
+import {TilejsonResult, GeojsonResult, JsonResult} from '../sources/types.js';
+
+export type VisualChannelField = {
+  name: string;
+  type: string;
+  colorColumn?: string;
+};
+
+export type VisualChannels = {
+  colorField?: VisualChannelField;
+  colorScale?: SCALE_TYPE;
+
+  customMarkersField?: VisualChannelField;
+  customMarkersScale?: SCALE_TYPE;
+
+  radiusField?: VisualChannelField;
+  radiusScale?: SCALE_TYPE;
+
+  rotationScale?: SCALE_TYPE;
+  rotationField?: VisualChannelField;
+
+  sizeField?: VisualChannelField;
+  sizeScale?: SCALE_TYPE;
+
+  strokeColorField?: VisualChannelField;
+  strokeColorScale?: SCALE_TYPE;
+
+  heightField?: VisualChannelField;
+  heightScale?: SCALE_TYPE;
+
+  weightField?: VisualChannelField;
+};
+
+export type ColorRange = {
+  category: string;
+  colors: string[];
+  colorMap: string[][] | undefined;
+  name: string;
+  type: string;
+};
+
+export type CustomMarkersRange = {
+  markerMap: {
+    value: string;
+    markerUrl?: string;
+  }[];
+  othersMarker?: string;
+};
+
+export type VisConfig = {
+  filled?: boolean;
+  opacity?: number;
+  enable3d?: boolean;
+
+  colorAggregation?: any;
+  colorRange: ColorRange;
+
+  customMarkers?: boolean;
+  customMarkersRange?: CustomMarkersRange | null;
+  customMarkersUrl?: string | null;
+
+  radius: number;
+  radiusRange?: number[];
+
+  sizeAggregation?: any;
+  sizeRange?: any;
+
+  strokeColorAggregation?: any;
+  strokeOpacity?: number;
+  strokeColorRange?: ColorRange;
+
+  heightRange?: any;
+  heightAggregation?: any;
+
+  weightAggregation?: any;
+};
+
+export type TextLabel = {
+  field: VisualChannelField | null | undefined;
+  alignment?: 'center' | 'bottom' | 'top';
+  anchor?: 'middle' | 'start' | 'end';
+  size: number;
+  color?: number[];
+  offset?: [number, number];
+  outlineColor?: number[];
+};
+
+export type MapLayerConfig = {
+  columns?: Record<string, any>;
+  color?: number[];
+  label?: string;
+  dataId: string;
+  textLabel: TextLabel[];
+  visConfig: VisConfig;
+};
+
+export type MapConfigLayer = {
+  type: LayerType;
+  id: string;
+  config: MapLayerConfig;
+  visualChannels: VisualChannels;
+};
+
+export interface CustomStyle {
+  url?: string;
+  style?: any;
+  customAttribution?: string;
+}
+
+// TODO replace with more complete type from Builder
+export type KeplerMapConfig = {
+  filters: any;
+  mapState: any;
+  mapStyle: {
+    styleType: string;
+    visibleLayerGroups: Record<string, boolean>;
+  };
+  popupSettings: any;
+  visState: {
+    layers: MapConfigLayer[];
+    layerBlending: any;
+    interactionConfig: any;
+  };
+  customBaseMaps?: {
+    customStyle?: CustomStyle;
+  };
+};
+
+export type BasemapType = 'maplibre' | 'google-maps';
+
+export type Basemap = MapLibreBasemap | GoogleBasemap;
+
+export type BasemapCommon = {
+  /**
+   * Type of basemap.
+   */
+  type: BasemapType;
+
+  /**
+   * Custom attribution for style data if not provided by style definition.
+   */
+  attribution?: string;
+
+  /**
+   * Properties of the basemap. These properties are specific to the basemap type.
+   */
+  props: Record<string, any>;
+};
+
+export type MapLibreBasemap = BasemapCommon & {
+  type: 'maplibre';
+
+  /**
+   * MapLibre map properties.
+   *
+   * Meant to be passed to directly to `maplibregl.Map` object.
+   */
+  props: MapLibreBasemapProps;
+
+  /**
+   * Layer groups to be displayed in the basemap.
+   */
+  visibleLayerGroups?: Record<string, boolean>;
+
+  /**
+   * If `style` has been filtered by `visibleLayerGroups` then this property contains original style object, so user
+   * can use `applyLayerGroupFilters` again with new settings.
+   */
+  rawStyle?: string | Record<string, any>;
+};
+
+// Cherry-pick of maplibregl Map API props that are supported/provided by fetchMap interface
+export type MapLibreBasemapProps = {
+  style: string | Record<string, any>;
+  center: [number, number];
+  zoom: number;
+  pitch?: number;
+  bearing?: number;
+};
+
+export type GoogleBasemap = BasemapCommon & {
+  type: 'google-maps';
+
+  /**
+   * Google map properties.
+   *
+   * Meant to be passed to directly to `google.maps.Map` object.
+   */
+  props: GoogleBasemapProps;
+};
+
+// Cherry-pick of Google Map API props that are supported/provided by fetchMap interface
+export type GoogleBasemapProps = {
+  mapTypeId: string;
+  mapId?: string;
+  center?: {lat: number; lng: number};
+  zoom?: number;
+  tilt?: number;
+  heading?: number;
+};
+
+export type Dataset = {
+  id: string;
+  type: MapType;
+  source: string;
+  cache?: number;
+  connectionName: string;
+  geoColumn: string;
+  data: TilejsonResult | GeojsonResult | JsonResult;
+  columns: string[];
+  format: Format;
+  aggregationExp: string;
+  aggregationResLevel: number;
+  queryParameters: QueryParameters;
+  connectionId?: string;
+  providerId: ProviderType;
+  createdAt?: string;
+  updatedAt?: string;
+  label?: string;
+  color?: string;
+  uniqueIdProperty?: string;
+  queryTemplate?: string | null;
+  name?: string | null;
+  spatialIndex?: string | null;
+  exportToBucketAvailable?: boolean;
+};
+
+export type AttributeType = 'String' | 'Number' | 'Timestamp' | 'Boolean';
+
+export type AttributeStatsBase = {
+  attribute: string;
+  type: AttributeType;
+};
+
+export type AttributeStatsNumber = AttributeStatsBase & {
+  type: 'Number';
+  min: number;
+  avg: number;
+  max: number;
+  sum: number;
+  quantiles: number[][];
+};
+
+export type AttributeStatsTimestamp = AttributeStatsBase & {
+  type: 'Timestamp';
+  min: string;
+  max: string;
+};
+
+export interface AttributeStatsStringCategory {
+  category: string;
+  frequency: number;
+}
+
+export type AttributeStatsString = AttributeStatsBase & {
+  type: 'String' | 'Boolean';
+  categories: AttributeStatsStringCategory[];
+};
+
+/**
+ * Result of getAttributeStats request to backend.
+ */
+export type AttributeStats =
+  | AttributeStatsString
+  | AttributeStatsNumber
+  | AttributeStatsTimestamp;

package/src/fetch-map/utils.ts

@@ -0,0 +1,69 @@
+import type {BinaryFeature} from '@loaders.gl/schema';
+import type {Dataset} from './types.js';
+type Properties = BinaryFeature['properties'];
+type NumericProps = BinaryFeature['numericProps'];
+
+// Returns a Proxy object that allows accessing binary data
+// as if it were JSON properties
+export function createBinaryProxy(
+  data: {numericProps: NumericProps; properties: Properties[]},
+  index: number
+) {
+  const {properties, numericProps} = data;
+  return new Proxy(properties[index] || {}, {
+    get(target, property) {
+      if (property in numericProps) {
+        return numericProps[property as string].value[index];
+      }
+      return target[property as any];
+    },
+
+    has(target, property) {
+      return property in numericProps || property in target;
+    },
+
+    ownKeys(target) {
+      return [...Object.keys(numericProps), ...Reflect.ownKeys(target)];
+    },
+
+    getOwnPropertyDescriptor() {
+      return {enumerable: true, configurable: true};
+    },
+  });
+}
+
+export function scaleIdentity() {
+  let unknown: any;
+
+  function scale(x: any) {
+    return x === null ? unknown : x;
+  }
+
+  scale.invert = scale;
+
+  scale.domain = scale.range = (d: any) => d;
+
+  scale.unknown = (u: any) => {
+    if (u) {
+      unknown = u;
+    }
+
+    return unknown;
+  };
+
+  scale.copy = () => {
+    const scaleCopy = scaleIdentity();
+    scaleCopy.unknown(unknown);
+    return scaleCopy;
+  };
+
+  return scale;
+}
+
+export function isRemoteCalculationSupported(dataset: Dataset) {
+  if (dataset?.type === 'tileset' || dataset.providerId === 'databricks') {
+    return false;
+  }
+
+  return true;
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './client.js';
 export * from './constants.js';
 export * from './deck/index.js';
+export * from './fetch-map/index.js';
 export * from './filters.js';
 export * from './geo.js';
 export * from './sources/index.js';

package/src/models/model.ts

@@ -39,10 +39,7 @@ export interface ModelSource {
   queryParameters?: QueryParameters;
   spatialDataColumn?: string;
   spatialDataType?: SpatialDataType;
-  spatialFiltersResolution?: number;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
-  /** original resolution of the spatial index data as stored in the DW */
-  dataResolution?: number;
 }
 
 const {V3} = ApiVersion;
@@ -86,7 +83,6 @@ export function executeModel(props: {
     filtersLogicalOperator = 'and',
     spatialDataType = 'geo',
     spatialFiltersMode = 'intersects',
-    spatialFiltersResolution = 0,
   } = source;
 
   const queryParams: Record<string, unknown> = {
@@ -118,9 +114,6 @@ export function executeModel(props: {
   }
 
   if (spatialDataType !== 'geo') {
-    if (spatialFiltersResolution > 0) {
-      queryParams.spatialFiltersResolution = spatialFiltersResolution;
-    }
     queryParams.spatialFiltersMode = spatialFiltersMode;
   }
 

package/src/sources/base-source.ts

@@ -18,9 +18,8 @@ import {MapType} from '../types.js';
 import {APIErrorContext} from '../api/index.js';
 import {getClient} from '../client.js';
 
-export const SOURCE_DEFAULTS: SourceOptionalOptions = {
+export const SOURCE_DEFAULTS: Omit<SourceOptionalOptions, 'clientId'> = {
   apiBaseUrl: DEFAULT_API_BASE_URL,
-  clientId: getClient(),
   format: 'tilejson',
   headers: {},
   maxLengthURL: DEFAULT_MAX_LENGTH_URL,
@@ -34,6 +33,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
   const {accessToken, connectionName, cache, ...optionalOptions} = options;
   const mergedOptions = {
     ...SOURCE_DEFAULTS,
+    clientId: getClient(),
     accessToken,
     connectionName,
     endpoint,
@@ -80,6 +80,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
   if (format === 'tilejson') {
     const json = await requestWithParameters<TilejsonResult>({
       baseUrl: dataUrl,
+      parameters: {client: clientId},
       headers,
       errorContext,
       maxLengthURL,
@@ -93,6 +94,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
 
   return await requestWithParameters<GeojsonResult | JsonResult>({
     baseUrl: dataUrl,
+    parameters: {client: clientId},
     headers,
     errorContext,
     maxLengthURL,

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

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

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

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

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 = {

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".

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;