@carto/api-client 0.5.15-alpha.raster-5 → 0.5.16

package/src/index.ts

@@ -2,13 +2,7 @@ export * from './client.js';
 export * from './constants.js';
 export * from './deck/index.js';
 export * from './fetch-map/index.js';
-export {
-  createVecExprEvaluator as _createVecExprEvaluator,
-  evaluateVecExpr as _evaluateVecExpr,
-  validateVecExprSyntax as _validateVecExprSyntax,
-  type VecExprResult as _VecExprResult,
-  ErrorCode as _ErrorCode,
-} from './fetch-map/vec-expr-evaluator.js';
+export type {LayerDescriptor, LayerType} from './fetch-map/index.js';
 export * from './filters.js';
 export * from './geo.js';
 export * from './sources/index.js';

package/src/models/model.ts

@@ -24,6 +24,7 @@ const AVAILABLE_MODELS = [
   'range',
   'scatterplot',
   'table',
+  'aggregations',
 ] as const;
 
 export type Model = (typeof AVAILABLE_MODELS)[number];

package/src/sources/index.ts

@@ -97,3 +97,15 @@ export type {
   VectorTilesetSourceOptions,
   VectorTilesetSourceResponse,
 } from './vector-tileset-source.js';
+
+export {trajectoryQuerySource} from './trajectory-query-source.js';
+export type {
+  TrajectoryQuerySourceOptions,
+  TrajectoryQuerySourceResponse,
+} from './trajectory-query-source.js';
+
+export {trajectoryTableSource} from './trajectory-table-source.js';
+export type {
+  TrajectoryTableSourceOptions,
+  TrajectoryTableSourceResponse,
+} from './trajectory-table-source.js';

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

@@ -0,0 +1,101 @@
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
+import {
+  WidgetQuerySource,
+  type RangeResponse,
+  type WidgetQuerySourceResult,
+} from '../widget-sources/index.js';
+import {baseSource} from './base-source.js';
+import type {
+  SourceOptions,
+  QuerySourceOptions,
+  SpatialDataType,
+  TilejsonResult,
+  ColumnsOption,
+} from './types.js';
+
+export type TrajectoryQuerySourceOptions = SourceOptions &
+  QuerySourceOptions &
+  ColumnsOption & {
+    /** Column name containing the trajectory identifier */
+    trajectoryIdColumn: string;
+    /** Column name containing the timestamp */
+    timestampColumn: string;
+  };
+
+type UrlParameters = {
+  columns?: string;
+  spatialDataType: SpatialDataType;
+  spatialDataColumn?: string;
+  tileResolution?: string;
+  q: string;
+  queryParameters?: Record<string, unknown> | unknown[];
+  aggregationExp?: string;
+  trajectoryIdColumn: string;
+  timestampColumn: string;
+};
+
+export type TrajectoryQuerySourceResponse = TilejsonResult &
+  WidgetQuerySourceResult & {
+    timestampRange: RangeResponse;
+  };
+
+export const trajectoryQuerySource = async function (
+  options: TrajectoryQuerySourceOptions
+): Promise<TrajectoryQuerySourceResponse> {
+  const {
+    columns,
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
+    sqlQuery,
+    tileResolution = DEFAULT_TILE_RESOLUTION,
+    queryParameters,
+    aggregationExp,
+    trajectoryIdColumn,
+    timestampColumn,
+  } = options;
+
+  const spatialDataType = 'trajectory';
+
+  const urlParameters: UrlParameters = {
+    spatialDataColumn,
+    spatialDataType,
+    tileResolution: tileResolution.toString(),
+    q: sqlQuery,
+    trajectoryIdColumn,
+    timestampColumn,
+  };
+
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (queryParameters) {
+    urlParameters.queryParameters = queryParameters;
+  }
+  if (aggregationExp) {
+    urlParameters.aggregationExp = aggregationExp;
+  }
+
+  const result = await baseSource<UrlParameters>(
+    'query',
+    options,
+    urlParameters
+  );
+
+  const widgetSource = new WidgetQuerySource({
+    ...options,
+    // NOTE: Parameters with default values above must be explicitly passed here.
+    spatialDataColumn,
+    spatialDataType,
+    tileResolution,
+  });
+
+  const timestampRange = await widgetSource.getRange({column: timestampColumn});
+
+  return {
+    ...result,
+    widgetSource,
+    timestampRange,
+  };
+};

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

@@ -0,0 +1,96 @@
+import {
+  DEFAULT_GEO_COLUMN,
+  DEFAULT_TILE_RESOLUTION,
+} from '../constants-internal.js';
+import {
+  WidgetTableSource,
+  type RangeResponse,
+  type WidgetTableSourceResult,
+} from '../widget-sources/index.js';
+import {baseSource} from './base-source.js';
+import type {
+  ColumnsOption,
+  SourceOptions,
+  SpatialDataType,
+  TableSourceOptions,
+  TilejsonResult,
+} from './types.js';
+
+export type TrajectoryTableSourceOptions = SourceOptions &
+  TableSourceOptions &
+  ColumnsOption & {
+    /** Column name containing the trajectory identifier */
+    trajectoryIdColumn: string;
+    /** Column name containing the timestamp */
+    timestampColumn: string;
+  };
+
+type UrlParameters = {
+  columns?: string;
+  spatialDataType: SpatialDataType;
+  spatialDataColumn?: string;
+  tileResolution?: string;
+  name: string;
+  aggregationExp?: string;
+  trajectoryIdColumn: string;
+  timestampColumn: string;
+};
+
+export type TrajectoryTableSourceResponse = TilejsonResult &
+  WidgetTableSourceResult & {
+    timestampRange: RangeResponse;
+  };
+
+export const trajectoryTableSource = async function (
+  options: TrajectoryTableSourceOptions
+): Promise<TrajectoryTableSourceResponse> {
+  const {
+    columns,
+    spatialDataColumn = DEFAULT_GEO_COLUMN,
+    tableName,
+    tileResolution = DEFAULT_TILE_RESOLUTION,
+    aggregationExp,
+    trajectoryIdColumn,
+    timestampColumn,
+  } = options;
+
+  const spatialDataType = 'trajectory';
+
+  const urlParameters: UrlParameters = {
+    name: tableName,
+    spatialDataColumn,
+    spatialDataType,
+    tileResolution: tileResolution.toString(),
+    trajectoryIdColumn,
+    timestampColumn,
+  };
+
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (aggregationExp) {
+    urlParameters.aggregationExp = aggregationExp;
+  }
+
+  const result = await baseSource<UrlParameters>(
+    'table',
+    options,
+    urlParameters
+  );
+
+  const widgetSource = new WidgetTableSource({
+    ...options,
+    // NOTE: Parameters with default values above must be explicitly passed here.
+    spatialDataColumn,
+    spatialDataType,
+    tileResolution,
+  });
+
+  const timestampRange = await widgetSource.getRange({column: timestampColumn});
+
+  return {
+    ...result,
+    widgetSource,
+    timestampRange,
+  };
+};

package/src/sources/types.ts

@@ -211,7 +211,7 @@ export type ColumnsOption = {
   columns?: string[];
 };
 
-export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
+export type SpatialDataType = 'geo' | 'h3' | 'quadbin' | 'trajectory';
 
 /**
  * Strategy used for covering spatial filter geometry with spatial indexes.
@@ -292,64 +292,14 @@ export interface Tilestats {
 
 export interface Layer {
   layer: string;
-  /** Number of features in the layer. */
   count: number;
-
-  /** Number of attributes in the layer. */
   attributeCount: number;
   attributes: Attribute[];
-
-  /** Type of geometry as in geojson geometry type (Point, LineString, Polygon, etc.) */
-  geometry?: string;
-}
-
-export interface AttributeCategoryItem {
-  category: string;
-  frequency: number;
-}
-
-/**
- * Quantiles by number of buckets.
- *
- * Example:
- * ```ts
- *   {
- *     // for 3 buckets, first 1/3 of items lies in range [min, 20], second 1/3 is in [20, 40], and last 1/3 is in [40, max]
- *     3: [20, 40],
- *     4: [20, 30, 50], for 4 buckets ...
- *   }
- * ```
- */
-export interface QuantileStats {
-  [bucketCount: number]: number[];
 }
 
 export interface Attribute {
-  /**
-   * String, Number, Timestamp, Boolean
-   */
-  type: string;
-
-  /**
-   * Attribute name.
-   */
   attribute: string;
-
-  // Stats for numeric attributes
-  min?: number;
-  max?: number;
-  sum?: number;
-
-  /** Quantiles by number of buckets */
-  quantiles?:
-    | {
-        // Quantile stats for numeric attributes in static spatial index tilesets are enclosed in extra global object
-        global: QuantileStats;
-      }
-    | QuantileStats;
-
-  // Stats for string/boolean attributes
-  categories?: AttributeCategoryItem[];
+  type: string;
 }
 
 export interface VectorLayer {
@@ -375,8 +325,17 @@ export type RasterMetadataBandStats = {
 
   /**
    * Quantiles by number of buckets.
+   *
+   * Example:
+   * ```ts
+   *   {
+   *     // for 3 buckets, first 1/3 of items lies in range [min, 20], second 1/3 is in [20, 40], and last 1/3 is in [40, max]
+   *     3: [20, 40],
+   *     4: [20, 30, 50], for 4 buckets ...
+   *   }
+   * ```
    */
-  quantiles?: QuantileStats;
+  quantiles?: Record<number, number[]>;
 
   /**
    * Top values by number of values.

package/src/widget-sources/types.ts

@@ -207,6 +207,26 @@ export interface TimeSeriesRequestOptions extends BaseRequestOptions {
   splitByCategoryValues?: string[];
 }
 
+/**
+ * Examples:
+ *   * aggregations with array syntax
+ *      * aggregations: [{column: 'pop_high', operation: 'sum', alias: 'high_pop'}, {column: 'pop_low', operation: 'avg'}]
+ *   * aggregations with string syntax
+ *      * aggregations: 'sum(pop_high) as high_pop, avg(pop_low) as avg_low'
+ *
+ * Options for {@link WidgetRemoteSource#getAggregations}.
+ */
+export interface AggregationsRequestOptions extends BaseRequestOptions {
+  /** Aggregations to compute. Can be an array of objects or a SQL string expression. */
+  aggregations:
+    | {
+        column: string;
+        operation: Exclude<AggregationType, 'custom'>;
+        alias: string;
+      }[]
+    | string;
+}
+
 /** @experimental */
 export type ExtentRequestOptions = BaseRequestOptions;
 
@@ -241,7 +261,10 @@ export type CategoryResponseRaw = {
 };
 
 /** Response from {@link WidgetRemoteSource#getRange}. */
-export type RangeResponse = {min: number; max: number} | null;
+export type RangeResponse =
+  | {min: number; max: number}
+  | {min: string; max: string}
+  | null;
 
 /** Response from {@link WidgetRemoteSource#getTable}. */
 export type TableResponse = {
@@ -261,5 +284,10 @@ export type TimeSeriesResponse = {
 /** Response from {@link WidgetRemoteSource#getHistogram}. */
 export type HistogramResponse = number[];
 
+/** Response from {@link WidgetRemoteSource#getAggregations}. */
+export type AggregationsResponse = {
+  rows: Record<string, number | string | null>[];
+};
+
 /** @experimental */
 export type ExtentResponse = {bbox: BBox};

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

@@ -1,5 +1,7 @@
 import {executeModel, type ModelSource} from '../models/index.js';
 import type {
+  AggregationsRequestOptions,
+  AggregationsResponse,
   CategoryRequestOptions,
   CategoryResponse,
   ExtentRequestOptions,
@@ -394,6 +396,34 @@ export abstract class WidgetRemoteSource<
     }));
   }
 
+  async getAggregations(
+    options: AggregationsRequestOptions
+  ): Promise<AggregationsResponse> {
+    const {
+      signal,
+      filters = this.props.filters,
+      filterOwner,
+      spatialFilter,
+      spatialFiltersMode,
+      aggregations,
+    } = options;
+
+    return executeModel({
+      model: 'aggregations',
+      source: {
+        ...this.getModelSource(filters, filterOwner),
+        spatialFiltersMode,
+        spatialFilter,
+      },
+      params: {
+        aggregations,
+      },
+      opts: {signal, headers: this.props.headers},
+    }).then((res: AggregationsResponse) => ({
+      rows: res.rows.map((row) => normalizeObjectKeys(row)),
+    }));
+  }
+
   /** @experimental */
   async getExtent(options: ExtentRequestOptions = {}): Promise<ExtentResponse> {
     const {signal, filters = this.props.filters, filterOwner} = options;

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

@@ -1,4 +1,6 @@
 import type {
+  AggregationsRequestOptions,
+  AggregationsResponse,
   CategoryRequestOptions,
   CategoryResponse,
   ExtentRequestOptions,
@@ -127,6 +129,15 @@ export abstract class WidgetSource<
     options: TimeSeriesRequestOptions
   ): Promise<TimeSeriesResponse>;
 
+  /**
+   * Returns multiple aggregated values computed over matching data. Suitable
+   * for aggregated statistics from pivoted tables, such as H3 tables with
+   * pre-computed aggregations across multiple columns.
+   */
+  abstract getAggregations(
+    options: AggregationsRequestOptions
+  ): Promise<AggregationsResponse>;
+
   /** @experimental */
   abstract getExtent(options?: ExtentRequestOptions): Promise<ExtentResponse>;
 }

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

@@ -1,5 +1,7 @@
 /* eslint-disable @typescript-eslint/require-await */
 import type {
+  AggregationsRequestOptions,
+  AggregationsResponse,
   CategoryRequestOptions,
   CategoryResponse,
   ExtentResponse,
@@ -148,6 +150,8 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     }
 
     const targetOperation = aggregationFunctions[operation];
+    assert(targetOperation, `Unsupported aggregation operation: ${operation}`);
+
     return {
       value: targetOperation(filteredFeatures, column, joinOperation),
     };
@@ -391,6 +395,51 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     };
   }
 
+  async getAggregations({
+    aggregations,
+    filters,
+    filterOwner,
+    spatialFilter,
+  }: AggregationsRequestOptions): Promise<AggregationsResponse> {
+    const filteredFeatures = this._getFilteredFeatures(
+      spatialFilter,
+      filters,
+      filterOwner
+    );
+
+    if (!this._features.length) {
+      return {rows: []};
+    }
+
+    // SQL aggregations require remote execution, and are not supported for tilesets.
+    assert(
+      typeof aggregations !== 'string',
+      'Unsupported tileset SQL aggregation'
+    );
+
+    // Handle array-based aggregations
+    const result: Record<string, number> = {};
+    const usedAliases = new Set<string>();
+
+    for (const {column, operation, alias} of aggregations) {
+      // Column is required except when operation is 'count'.
+      if ((column && column !== '*') || operation !== AggregationTypes.Count) {
+        assertColumn(this._features, column);
+      }
+
+      const aliasKey = alias.toLowerCase();
+      assert(!usedAliases.has(aliasKey), `Duplicate alias: ${aliasKey}`);
+      usedAliases.add(aliasKey);
+
+      const targetOperation = aggregationFunctions[operation];
+      assert(targetOperation, `Unsupported operation: ${operation}`);
+
+      result[alias] = targetOperation(filteredFeatures, column);
+    }
+
+    return {rows: [result]};
+  }
+
   /** @experimental */
   async getExtent(): Promise<ExtentResponse> {
     return Promise.reject(new Error('not implemented'));

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

@@ -1,4 +1,6 @@
 import type {
+  AggregationsRequestOptions,
+  AggregationsResponse,
   CategoryRequestOptions,
   CategoryResponse,
   ExtentResponse,
@@ -326,6 +328,17 @@ export class WidgetTilesetSource<
     return this._executeWorkerMethod(Method.GET_RANGE, [options], signal);
   }
 
+  async getAggregations({
+    signal,
+    ...options
+  }: AggregationsRequestOptions): Promise<AggregationsResponse> {
+    return this._executeWorkerMethod(
+      Method.GET_AGGREGATIONS,
+      [options],
+      signal
+    );
+  }
+
   /** @experimental */
   async getExtent(): Promise<ExtentResponse> {
     return Promise.resolve({

package/src/workers/constants.ts

@@ -10,4 +10,5 @@ export enum Method {
   GET_TABLE = 'getTable',
   GET_TIME_SERIES = 'getTimeSeries',
   GET_RANGE = 'getRange',
+  GET_AGGREGATIONS = 'getAggregations',
 }