Data Sources

When building a widget, you always need a data source. The data source includes all the necessary connection and authentication parameters.

For the full technical reference for data sources, visit the Data Sources reference.

Data sources are available through the CARTO submodule in deck.gl, and you can re-use your existing sources from CARTO + deck.gl layers, or build your own sources exclusively for widget use.

Data sources compatibility

Currently, widgets are compatible with the following sources, using server-side calculations when available, and client-side calculations as a fallback.

Data Source	Compatible with widgets	Widget mode
vectorTableSource	✅	Server-side
vectorQuerySource	✅	Server-side
vectorTilesetSource	✅	Client-side
h3TableSource	✅	Server-side
h3QuerySource	✅	Server-side
h3TilesetSource	✅	Client-side
quadbinTableSource	✅	Server-side
quadbinQuerySource	✅	Server-side
quadbinTilesetSource	✅	Client-side
rasterSource	✅	Client-side
boundaryTableSource	❌	-
boundaryQuerySource	❌	-

For boundaryTableSource and boundaryQuerySource, a recommended workaround is to use a vectorTableSource or a vectorQuerySource using the same properties, attached to the widgets. The same filters can then be attached to both sources.

Re-using data sources for Widgets and Layers

If you plan to use the same data sources in your deck.gl layers and in your data widgets, then your existing CARTO + deck.gl data sources are totally compatible with widgets

import {vectorTableSource} from 'carto-api-client';
import {VectorTileLayer} from '@deck.gl/carto';

// init your data source

const data = await vectorTableSource({
    ...cartoCredentials,
    tableName: 'carto-demo-data.demo_tables.osm_pois_usa',
    filters: filters
})

// use it in a layer

new VectorTileLayer({
    id: 'places',
    pickable: true,
    data: data,
    pointRadiusMinPixels: 4,
    getFillColor: [200, 0, 80]
})

// use the same source in a widget data model

const histogram = await data.widgetSource.getCategories({
    column: 'group_name',
    operation: 'count',
    operationColumn: '*'
    spatialFilter: currentViewStatePolygon
});

Using server-side widgets without layers

When using server-side widgets, having a layer is not a requirement. You can specify your source and build your widget without any additional layers. This is a powerful pattern to expose additional insights, use global datasets for filtering while rendering aggregated datasets, or simply to achieve advanced use cases.

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

// init your data source

const data = await vectorTableSource({
    ...cartoCredentials,
    tableName: 'carto-demo-data.demo_tables.osm_pois_usa',
    filters: filters
})

// use the source in a widget, with no layers

const histogram = await data.widgetSource.getCategories({
    column: 'group_name',
    operation: 'count',
    operationColumn: '*'
    spatialFilter: currentViewStatePolygon
});