# 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**

```typescript
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](https://docs.carto.com/carto-for-developers/reference/carto-widgets-reference/models/..#model-base-options), plus:

```typescript
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:

```typescript
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.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-25b73cb060a521fffcdc241990ff4a781cea8697%2FScreenshot%202024-08-30%20at%2021.00.14.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>