The CARTO platform provides a cache layer to optimize performance and save precious computing resources from your cloud data warehouse. Understanding how caching works and the default settings for the different data sources ensures that users can manage data freshness effectively while balancing performance and cost considerations.
In this guide, you will learn:
By default, CARTO stores the result of all queries to your data warehouse in a CARTO-managed CDN-based cache (for SaaS deployments) or in your varnish-cache (for Self-hosted deployments), ensuring that repeated requests for the same information do not require re-fetching data from your connection. This significantly improves performance and reduces data processing costs while maintaining data consistency based on predefined cache expiration times.
The duration of the cache (the time it takes for the cached result to expire) depends on the type of data source. Below is an explanation of the default cache behavior for the different features in CARTO.
In some circumstances, you may want to define specific freshness intervals for the data to ensure users in your application always work with the most up-to-date information.
Generally speaking, adjusting cache settings is done by passing a HTTP header with a max-age directive in all HTTP requests sent to the CARTO APIs. The max-age directive will control the duration in seconds (TTL) for the cached response.
Depending on the specific feature, the implementation of the max-age directive will be different. Below is a collection that details how to add it through the different features in CARTO for Developers.
Use the parameter directly in the in your application to adjust cache settings.
Example:
Specify a cache-control header in your HTTP requests to define the cache duration.
You can learn more in our .
There are two methods to completely invalidate some or all cached results in your application.
no-cache directiveTo completely invalidate cache, a no-cache directive can be passed alongside max-age=0 to instruct CARTO to completely invalidate the cache.
Depending on the size of your application, it might not be practical to adjust the cache-control header and trigger it for all requests. To ensure that the cache is fully cleared across a specific source or surface in your application, you can implement versioning in both your queries and tables.
By passing a new version, the query or table referenced will be treated as a new one by CARTO, and therefore previously cached results will not be used — All data presented in the visualization will be fresh and up to date.
Use this method carefully, and avoid sending unnecessary new versions. The cache helps your application be more performant and saves valuable computing resources, reducing costs.
Your browser may also be caching requests
The local cache layer in your device/browser, or other additional cache layers may be interfering in how your HTTP requests hit the CARTO APIs and how the results are cached. Assuming that your requests are sent with cache-control: no-cache headers, browsers and other systems should respect this and behave accordingly.
If your content is not being cached (or not being refreshed) as you would expect to after following this guide, please check and troubleshoot other potential additional cache layers.
CARTO provides a cache mechanism in both cloud-based SaaS and Self-hosted deployments. This cache mechanism helps save resources. You've now learnt about our cache defaults, how to adjust cache duration in your layers and widgets, and how to completely invalidate the cache.
Queries
1 year
Tilesets
1 year or until the tileset is modified
Redshift
Tables
30 minutes
Queries
1 year
Tilesets
1 year
Databricks
Tables
30 minutes
Queries
1 year
Tilesets
1 year
PostgreSQL
Tables
30 minutes
Queries
1 year
Tilesets
1 year
BigQuery
Tables
Indefinitely until the table is modified, with a minimum of 5 minutes
Queries
1 year
Tilesets
1 year or until the tileset is modified
Snowflake
Tables
All Data Warehouses
Models
5 minutes
SQL API Queries
1 year
Indefinitely until the table is modified, with a minimum of 5 minutes
import { Deck } from '@deck.gl/core';
import { VectorTileLayer } from '@deck.gl/carto';
import { vectorQuerySource } from 'carto-api-client';
const data = vectorQuerySource({
accessToken: 'XXX',
connectionName: 'carto_dw',
sqlQuery: 'SELECT * FROM cartobq.testtables.points_10k',
headers: { 'cache-control': 'max-age=60' }
// widgets and layers using this source will be cached for 60 seconds
});
const layer = new VectorTileLayer({
data,
pointRadiusMinPixels: 2,
getLineColor: [0, 0, 0, 200],
getFillColor: [238, 77, 90],
lineWidthMinPixels: 1,
// cache options in the source affect this layer's tiles
});
const result = await data.widgetSource.getFormula({
column: 'store_name',
operation: 'count'
// cache options in the source affect the widget results
});
// etc..
curl --location 'https://gcp-us-east1.api.carto.com/v3/sql/carto_dw/query?q=select%20*%20from%20carto-demo-data.demo_tables.airports' \
--header 'Authorization: Bearer ' \
--header 'Cache-Control: 'max-age=300'import { Deck } from '@deck.gl/core';
import { VectorTileLayer } from '@deck.gl/carto';
import { vectorQuerySource } from 'carto-api-client';
const data = vectorQuerySource({
accessToken: 'XXX',
connectionName: 'carto_dw',
sqlQuery: 'SELECT * FROM cartobq.testtables.points_10k',
headers: { 'cache-control': 'no-cache, max-age=0' }
});
const layer = new VectorTileLayer({
data,
pointRadiusMinPixels: 2,
getLineColor: [0, 0, 0, 200],
getFillColor: [238, 77, 90],
lineWidthMinPixels: 1,
// tiles in this layer won't use cached results and new tiles will not be cached
});
const result = await data.widgetSource.getFormula({
column: 'store_name',
operation: 'count'
// widgets from this source won't use cached results and results will not be cached
});
// etc..curl --location 'https://gcp-us-east1.api.carto.com/v3/sql/carto_dw/query?q=select%20*%20from%20carto-demo-data.demo_tables.airports' \
--header 'Authorization: Bearer ' \
--header 'Cache-Control: no-cache, max-age=0'let version = ... // Increase the version as needed
const myDataQuery = vectorQuerySource({
...cartoConfig,
sqlQuery: `WITH _version AS (SELECT ${version} AS version)
SELECT * FROM carto-demo-data.demo_tables.riskanalysis_railroad_accidents`,
});let version = ... // Increase the version as needed
const dataSource = vectorTableSource({
...cartoConfig,
tableName: `carto-demo-data.demo_tables.populated_places_${version}`
});