Managing cache in your CARTO applications

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:

• Cache defaults: How cache works in CARTO

• How to adjust the cache layer

• How to completely invalidate some or all cached results

Cache defaults: How does cache work in CARTO

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.

Visualizing tiles in a map (Maps API via deck.gl)

Data Warehouse	Source Type	Default Duration (TTL)
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	Indefinitely until the table is modified, with a minimum of 5 minutes
	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

Widgets and Requests to SQL API

Data Warehouse	Source Type	Default Duration (TTL)
All Data Warehouses	Models	5 minutes
	SQL API Queries	1 year

How to adjust the cache layer

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.

Shorter cache duration may increase costs and decrease performance

When you invalidate cached results or set short cache duration times, your application will require more SQL queries to be re-executed against your data warehouse. This will result in more data processing in the data warehouse, potentially leading to higher costs.

We recommend leaving the cache settings in their default settings, or adjusting them aiming for an optimal balance between data freshness and performance.

Generally speaking, adjusting cache settings is done by passing a cache-control 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.

CARTO + deck.gl: layers and widgets

Use the headers parameter directly in the @deck.gl/CARTO sources in your application to adjust cache settings.

Example:

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

Direct SQL API calls

Specify a cache-control header in your HTTP requests to define the cache duration.

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'

You can learn more in our API Docs.

How to completely invalidate some or all cached results

There are two methods to completely invalidate some or all cached results in your application.

Method 1: Using the no-cache directive

To completely invalidate cache, a no-cache directive can be passed alongside max-age=0 to instruct CARTO to completely invalidate the cache.

CARTO + deck.gl: Layers and Widgets

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

SQL API

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'

Method 2: Using versioning in queries and tables

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.

1. SQL Example for queries

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`,
});

2. Example for tables

let version = ... // Increase the version as needed
const dataSource = vectorTableSource({
  ...cartoConfig,
  tableName: `carto-demo-data.demo_tables.populated_places_${version}`
});

Local browser cache

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.

Conclusions

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.