@carto/api-client 0.5.5 → 0.5.6-alpha.0

package/build/api-client.d.cts

@@ -1147,10 +1147,31 @@ interface BaseRequestOptions {
     filters?: Filters;
     filterOwner?: string;
 }
-/** Options for {@link WidgetRemoteSource#getCategories}. */
+/**
+ * Examples:
+ *   * population by state
+ *      * column: 'state'
+ *      * operation: 'sum'
+ *      * operationColumn: 'population'
+ *   * average salary by department
+ *      * column: 'department'
+ *      * operation: 'avg'
+ *      * operationColumn: 'salary'
+ *   * custom aggregation by storetype
+ *      * column: 'storetype'
+ *      * operation: 'custom'
+ *      * operationExp: 'sum(sales)/sum(area)'
+ *
+ * Options for {@link WidgetRemoteSource#getCategories}.
+ */
 interface CategoryRequestOptions extends BaseRequestOptions {
+    /** The column that to categorize by. */
     column: string;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+    /** The type of aggregation to apply on data in scope of each category. */
+    operation: AggregationType;
+    /** Remote only. Only valid if operation is 'custom' */
+    operationExp?: string;
+    /** The aggregated column per each category. */
     operationColumn?: string;
     /** Local only. */
     joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
@@ -1192,11 +1213,28 @@ interface FeaturesRequestOptions extends BaseRequestOptions {
      */
     tileResolution?: TileResolution;
 }
-/** Options for {@link WidgetRemoteSource#getFormula}. */
+/**
+ * Examples:
+ *   * sum of all sales
+ *      * column: 'sales'
+ *      * operation: 'sum'
+ *   * average salary
+ *      * column: 'salary'
+ *      * operation: 'avg'
+ *   * custom aggregation over all rows
+ *      * operation: 'custom'
+ *      * operationExp: 'sum(sales)/sum(area)'
+ *
+ * Options for {@link WidgetRemoteSource#getFormula}.
+ */
 interface FormulaRequestOptions extends BaseRequestOptions {
-    column: string;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom';
+    /** The column to apply the aggregation operation on. Not needed for 'custom' operation. */
+    column?: string;
+    /** The type of aggregation to apply on data. */
+    operation: AggregationType;
+    /** Remote only. Only valid if operation is 'custom' */
     operationExp?: string;
+    /** Local only. */
     joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
 }
 /** Options for {@link WidgetRemoteSource#getHistogram}. */
@@ -1231,12 +1269,25 @@ interface TableRequestOptions extends BaseRequestOptions {
     /** @deprecated Supported for tilesets only. Prefer `filters` (for all sources) instead. */
     searchFilterText?: string;
 }
-/** Options for {@link WidgetRemoteSource#getTimeSeries}. */
+/**
+ * Examples:
+ *   * sum of all sales by month
+ *      * column: 'sales'
+ *      * stepSize: 'month'
+ *      * operation: 'sum'
+ *   * average salary by year
+ *      * column: 'salary'
+ *      * stepSize: 'year'
+ *      * operation: 'avg'
+ * Options for {@link WidgetRemoteSource#getTimeSeries}.
+ */
 interface TimeSeriesRequestOptions extends BaseRequestOptions {
     column: string;
     stepSize: GroupDateType;
     stepMultiplier?: number;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+    operation: AggregationType;
+    /** Remote only. Only valid if operation is 'custom' */
+    operationExp?: string;
     operationColumn?: string;
     joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
     splitByCategory?: string;

package/build/api-client.d.ts

@@ -1147,10 +1147,31 @@ interface BaseRequestOptions {
     filters?: Filters;
     filterOwner?: string;
 }
-/** Options for {@link WidgetRemoteSource#getCategories}. */
+/**
+ * Examples:
+ *   * population by state
+ *      * column: 'state'
+ *      * operation: 'sum'
+ *      * operationColumn: 'population'
+ *   * average salary by department
+ *      * column: 'department'
+ *      * operation: 'avg'
+ *      * operationColumn: 'salary'
+ *   * custom aggregation by storetype
+ *      * column: 'storetype'
+ *      * operation: 'custom'
+ *      * operationExp: 'sum(sales)/sum(area)'
+ *
+ * Options for {@link WidgetRemoteSource#getCategories}.
+ */
 interface CategoryRequestOptions extends BaseRequestOptions {
+    /** The column that to categorize by. */
     column: string;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+    /** The type of aggregation to apply on data in scope of each category. */
+    operation: AggregationType;
+    /** Remote only. Only valid if operation is 'custom' */
+    operationExp?: string;
+    /** The aggregated column per each category. */
     operationColumn?: string;
     /** Local only. */
     joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
@@ -1192,11 +1213,28 @@ interface FeaturesRequestOptions extends BaseRequestOptions {
      */
     tileResolution?: TileResolution;
 }
-/** Options for {@link WidgetRemoteSource#getFormula}. */
+/**
+ * Examples:
+ *   * sum of all sales
+ *      * column: 'sales'
+ *      * operation: 'sum'
+ *   * average salary
+ *      * column: 'salary'
+ *      * operation: 'avg'
+ *   * custom aggregation over all rows
+ *      * operation: 'custom'
+ *      * operationExp: 'sum(sales)/sum(area)'
+ *
+ * Options for {@link WidgetRemoteSource#getFormula}.
+ */
 interface FormulaRequestOptions extends BaseRequestOptions {
-    column: string;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom';
+    /** The column to apply the aggregation operation on. Not needed for 'custom' operation. */
+    column?: string;
+    /** The type of aggregation to apply on data. */
+    operation: AggregationType;
+    /** Remote only. Only valid if operation is 'custom' */
     operationExp?: string;
+    /** Local only. */
     joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
 }
 /** Options for {@link WidgetRemoteSource#getHistogram}. */
@@ -1231,12 +1269,25 @@ interface TableRequestOptions extends BaseRequestOptions {
     /** @deprecated Supported for tilesets only. Prefer `filters` (for all sources) instead. */
     searchFilterText?: string;
 }
-/** Options for {@link WidgetRemoteSource#getTimeSeries}. */
+/**
+ * Examples:
+ *   * sum of all sales by month
+ *      * column: 'sales'
+ *      * stepSize: 'month'
+ *      * operation: 'sum'
+ *   * average salary by year
+ *      * column: 'salary'
+ *      * stepSize: 'year'
+ *      * operation: 'avg'
+ * Options for {@link WidgetRemoteSource#getTimeSeries}.
+ */
 interface TimeSeriesRequestOptions extends BaseRequestOptions {
     column: string;
     stepSize: GroupDateType;
     stepMultiplier?: number;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+    operation: AggregationType;
+    /** Remote only. Only valid if operation is 'custom' */
+    operationExp?: string;
     operationColumn?: string;
     joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
     splitByCategory?: string;

package/build/api-client.js

@@ -6263,7 +6263,10 @@ var WidgetRemoteSource = class extends WidgetSource {
       spatialFiltersMode,
       ...params
     } = options;
-    const { column, operation: operation2, operationColumn } = params;
+    const { column, operation: operation2, operationColumn, operationExp } = params;
+    if (operation2 === "custom") {
+      assert2(operationExp, "operationExp is required for custom operation");
+    }
     return executeModel({
       model: "category",
       source: {
@@ -6274,6 +6277,7 @@ var WidgetRemoteSource = class extends WidgetSource {
       params: {
         column,
         operation: operation2,
+        operationExp,
         operationColumn: operationColumn || column
       },
       opts: { signal, headers: this.props.headers }
@@ -6319,6 +6323,9 @@ var WidgetRemoteSource = class extends WidgetSource {
       ...params
     } = options;
     const { column, operation: operation2 } = params;
+    if (operation2 === "custom") {
+      assert2(operationExp, "operationExp is required for custom operation");
+    }
     return executeModel({
       model: "formula",
       source: {
@@ -6457,12 +6464,16 @@ var WidgetRemoteSource = class extends WidgetSource {
       operationColumn,
       joinOperation,
       operation: operation2,
+      operationExp,
       stepSize,
       stepMultiplier,
       splitByCategory,
       splitByCategoryLimit,
       splitByCategoryValues
     } = params;
+    if (operation2 === "custom") {
+      assert2(operationExp, "operationExp is required for custom operation");
+    }
     return executeModel({
       model: "timeseries",
       source: {
@@ -6477,6 +6488,7 @@ var WidgetRemoteSource = class extends WidgetSource {
         operationColumn: operationColumn || column,
         joinOperation,
         operation: operation2,
+        operationExp,
         splitByCategory,
         splitByCategoryLimit,
         splitByCategoryValues
@@ -7362,6 +7374,10 @@ var WidgetTilesetSourceImpl = class extends WidgetSource {
       return { rows: [] };
     }
     assertColumn(this._features, column, operationColumn);
+    assert2(
+      operation2 !== "custom",
+      "Custom operation not supported for tilesets"
+    );
     const rows = groupValuesByDateColumn({
       data: filteredFeatures,
       valuesColumns: normalizeColumns(operationColumn || column),