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.

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, but there are several types of widget models, each of them returning a different data model more suitable for a type of data visualization:

Model base options for vector sources

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

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

Model base options for spatial index sources

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

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

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.

Model base options for tileset sources

When using tileset sources (vectorTilesetSource, h3TilesetSource, quadbinTilesetSource...), all models support the following options:

// 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.
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.
filters (optional): A valid CARTO Filters object, used to perform client-side filtering of this widget model with column-based filters.

Models in tileset sources are calculated client-side. Read more about considerations when using client-side calculations.

Model base options for raster sources

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

// 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.
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.
filters (optional): A valid CARTO Filters object, used to perform client-side filtering of this widget model with column-based filters.

Models in tileset sources are calculated client-side. Read more about considerations when using client-side calculations.

PreviousServer-side vs. client-side NextgetFormula

Last updated 3 months ago

Was this helpful?