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 formula = 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:

• getFormula

• getCategories

• getHistogram

• getRange

• getScatterPlot

• getTimeSeries

• getTable

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

• 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 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' // 
  spatialIndexReferenceViewState: ViewState // the current viewState from a deck.gl map
  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.

• spatialIndexReferenceViewState: this property is required when using table- and query-based spatial index sources such as H3 or Quadbin. It expects the current viewState object from the deck.gl map, to perform internal calculations that will determine the spatial index resolution used to calculate the widget data. Learn more about deck.gl's viewState.

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