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

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

Conclusions

Last updated

Was this helpful?