getCategories

A Category model is a data model that represents a list of labeled data points for categorical data. Suitable for charts such as grouped bar charts, pie charts, or tree charts.

Usage

const categories = await dataSource.getCategories({
    column: 'categories_column',
    operation: 'count',
    operationColumn: 'values_column',
    operationExp?: string
    // + base options...
});

Options

The getCategories model inherits all options from the base options, plus:

export interface CategoryRequestOptions extends BaseRequestOptions {
  column: string;
  operation: 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom';
  operationColumn?: string | '*';
  operationExp?: string;
  othersThreshold?: number;
}

• column: the name of the column that will be used to generate the categories.

• operation: the aggregation that will be performed on the operationColumn. Accepted values are:

  • count

  • avg

  • min

  • max

  • sum

  • custom

• operationColumn (optional): this is the column that will be aggregated for each category in the specified column , and it is required when using an operation other than custom.

• operationExp (optional): a valid SQL expression to perform a custom aggregation. For example sum(sales)/sum(area) . This is only applicable when using a custom operation.

• othersThreshold (optional): use this parameter to let CARTO group the values in categories after the threshold as "others". This value will be returned in the response as _carto_others.

Response

An array of objects where each object is a pair of category name and its corresponding value:

type CategoriesModelResponse = {name: string; value: number}[];
/* example response 
    [
        {
            name: 'category_1',
            value: '245'
        },
        {
            name: 'category_2',
            value: '673'
        },
        {
            name: 'category_3',
            value: '987'
        }
    ]  
*/    

The response can be then mapped to any charting library to create data visualizations like a bar chart.