# getHistogram

A Histogram model is a data model that represents a list of labeled data points for *bins* (ranges) of data, defined as ticks over a numerical range, Suitable for histogram charts.

## **Usage**

```typescript
const formula = await dataSource.getHistogram({
    column: 'column_A',
    ticks: [5, 10, 15],
    operation: 'count'
    // + base options...
});
```

## **Options**

The `getHistogram` model inherits all options from the [base options](/carto-for-developers/reference/carto-widgets-reference/models.md#model-base-options), plus:

```typescript
export interface HistogramRequestOptions extends BaseRequestOptions {
  column: string;
  ticks: number[];
  operation: 'count' | 'avg' | 'min' | 'max' | 'sum';
}
```

* **column:** the name of the column that you will run the statistical operation on. It also accepts the `*` value, that will
* **ticks**: the list of numerical **upper bound** thresholds that will be used to create the bins. There's no maximum number of ticks.
* **operation:** the aggregation that will be performed on the `column` for each range bin. Accepted values are:
  * `count`
  * `avg`
  * `min`
  * `max`
  * `sum`

## **Response**

An ordered array containing the value for each histogram bin.

{% hint style="info" %}
Please note that the response always contain one additional row compared to the amount of ticks specified in the options. This is because ticks are the upper bound threshold, and there needs to be an additional bucket for values above the last tick.
{% endhint %}

```typescript
type HistogramModelResponse = number[];
/* example response 
  [
    389, // < 5
    648, // 5-9
    478, // 10-14
    120 // > 15
  ]
*/    
```

The response can be then mapped to any HTML element, but commonly it will be mapped to a a charting library to create histogram charts.

<figure><img src="/files/Ixc7r3dkQi0Dq2j9ns2o" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/carto-for-developers/reference/carto-widgets-reference/models/gethistogram.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.