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 Data Sources on the CARTO submodule reference in deck.gl

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:

Data Source	Compatible with widgets
vectorTableSource	✅
vectorQuerySource	✅
vectorTilesetSource	❌
h3TableSource	(coming soon)
h3QuerySource	(coming soon)
h3TilesetSource	❌
quadbinTableSource	(coming soon)
quadbinQuerySource	(coming soon)
quadbinTilesetSource	❌
rasterTilesetSource	(coming soon)
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 from deck.gl

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 data sources without layers

However, using layers 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
});