# Models

Once you've specified a Data Source, you can easily access a widget model using any of the functions in this a page. This is a basic usage example for a category model that can be used to build a bar chart.

```typescript
import {vectorTableSource} from 'carto-api-client';

const data = await vectorTableSource({...})

const categories = await data.widgetSource.getCategories({
    column: 'column_A',
    operation: 'count',
    operationColumn: 'column_B'
});
```

All models support a set of [base options](#model-base-options), but there are several types of widget models, each of them returning a different data model more suitable for a type of data visualization:

* [getFormula](#getformula)
* [getCategories](/carto-for-developers/reference/carto-widgets-reference/models/getcategories.md)
* [getHistogram](#gethistogram)
* [getRange](#getrange)
* [getScatterPlot](#getscatterplot)
* [getTimeSeries](#gettimeseries)
* [getTable](#gettable)

## Model base options for vector sources

When using **vector-based sources** (`vectorTableSource`, `vectorQuerySource`...), all models support the following options:

```typescript
// when using vectorTableSource or vectorQuerySource
interface BaseRequestOptions {
  spatialFilter?: GeoJSON.Polygon | GeoJSON.MultiPolygon; // GeoJSON Polygon or MultiPolygon geometry
  signal?: AbortSignal;
  filterOwner?: string;
}
```

* **spatialFilter** (optional)**:** Used for filtering a widget based on a geometry, such as a user input or the current deck.gl map view state. Learn more about [filters](/carto-for-developers/reference/filters.md).
* **signal** (optional)**:** Allows you to cancel ongoing requests, saving data warehouse resources and free up computing and queuing capacity.
* **filterOwner** (optional)**:** This widget will be excluded from all column filters with a matching `owner` property. In other words, filters with a matching `owner` property won't filter this widget's data. The most common use case for this is when filters are originated based on user interactions with the widget. [Learn more about column-based filtering](/carto-for-developers/reference/filters/column-filters.md).

## Model base options for spatial index sources

When using **spatial index-based sources** (`h3TableSource`, `h3QuerySource`, `quadbinTableSource`, `quadbinQuerySource`...), all models support the following options:

```typescript
// when using h3TableSource, h3QuerySource, quadbinTableSource or quadbinQuerySource
interface BaseRequestOptions {
  spatialFilter?: GeoJSON.Polygon | GeoJSON.MultiPolygon; // GeoJSON Polygon or MultiPolygon geometry
  spatialFilterPolyfillMode?: 'center' | 'intersects' | 'contains' // 
  abortController?: AbortController;
  filterOwner?: string;
}
```

* **spatialFilter** (optional)**:** Used for filtering a widget based on a geometry, such as a user input or the current deck.gl map view state. Learn more about [filters](/carto-for-developers/reference/filters.md).
* **spatialFilterPolyfillMode** (optional): Used to determine how the spatial index cells are filtered according to the `spatialFilter`. Default value is `intersects`. Accepted values are:
  * `center`: filters only spatial index cells whose center is inside the `spatialFilter` polygon.
  * `intersects`: filters only spatial index cells that intersect the `spatialFilter` polygon. This is the default value.
  * `contains`: filters only spatial index cells that are entirely contained inside the `spatialFilter` polygon.

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

* **abortController** (optional)**:** Allows you to cancel ongoing requests, saving data warehouse resources and free up computing and queuing capacity.
* **filterOwner** (optional)**:** This widget will be excluded from all column filters with a matching `owner` property. In other words, filters with a matching `owner` property won't filter this widget's data. The most common use case for this is when filters are originated based on user interactions with the widget. [Learn more about column-based filtering](/carto-for-developers/reference/filters/column-filters.md).

## Model base options for tileset sources

When using **tileset sources** ([`vectorTilesetSource`](/carto-for-developers/reference/data-sources/vectortilesetsource.md), [`h3TilesetSource`](/carto-for-developers/reference/data-sources/h3tilesetsource.md), [`quadbinTilesetSource`](/carto-for-developers/reference/data-sources/quadbintilesetsource.md)...), all models support the following options:

```typescript
// when using vectorTilesetSource, h3TilesetSource or quadbinTilesetSource
interface BaseRequestOptions {
  spatialFilter: GeoJSON.Polygon | GeoJSON.MultiPolygon; // GeoJSON Polygon or MultiPolygon geometry
  abortController?: AbortController;
  filterOwner?: string;
  filters?: Filters;
}
```

* **spatialFilter:** Used for filtering a widget based on a geometry, such as a user input or the current deck.gl map view state. Learn more about [filters](/carto-for-developers/reference/filters.md).
* **abortController** (optional)**:** Allows you to cancel ongoing requests, saving data warehouse resources and free up computing and queuing capacity.
* **filterOwner** (optional)**:** This widget will be excluded from all column filters with a matching `owner` property. In other words, filters with a matching `owner` property won't filter this widget's data. The most common use case for this is when filters are originated based on user interactions with the widget. [Learn more about column-based filtering](/carto-for-developers/reference/filters/column-filters.md).
* **filters** (optional): A valid [CARTO Filters](/carto-for-developers/reference/filters/column-filters.md) object, used to perform client-side filtering of this widget model with column-based filters.

{% hint style="warning" %}
Models in tileset sources are calculated client-side. Read more about [considerations when using client-side calculations](/carto-for-developers/reference/carto-widgets-reference/server-side-vs.-client-side.md#client-side-widget-calculation).
{% endhint %}

## Model base options for raster sources

When using **raster-based sources** (`rasterTableSource`), all models support the following options:

```typescript
// when using vectorTableSource or vectorQuerySource
interface BaseRequestOptions {
  spatialFilter: GeoJSON.Polygon | GeoJSON.MultiPolygon; // GeoJSON Polygon or MultiPolygon geometry
  abortController?: AbortController;
  filterOwner?: string;
  filters?: Filters;
}
```

* **spatialFilter:** Used for filtering a widget based on a geometry, such as a user input or the current deck.gl map view state. Learn more about [filters](/carto-for-developers/reference/filters.md).
* **abortController** (optional)**:** Allows you to cancel ongoing requests, saving data warehouse resources and free up computing and queuing capacity.
* **filterOwner** (optional)**:** This widget will be excluded from all column filters with a matching `owner` property. In other words, filters with a matching `owner` property won't filter this widget's data. The most common use case for this is when filters are originated based on user interactions with the widget. [Learn more about column-based filtering](/carto-for-developers/reference/filters/column-filters.md).
* **filters** (optional): A valid [CARTO Filters](/carto-for-developers/reference/filters/column-filters.md) object, used to perform client-side filtering of this widget model with column-based filters.

{% hint style="warning" %}
Models in tileset sources are calculated client-side. Read more about [considerations when using client-side calculations](/carto-for-developers/reference/carto-widgets-reference/server-side-vs.-client-side.md#client-side-widget-calculation).
{% endhint %}

##


---

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