> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-self-hosted/concepts/in-memory-cache.md).

# How CARTO uses Caches

## Two caches, two purposes

CARTO Self-Hosted has **two distinct caching layers**, and they are easy to confuse. When admins say "the cache," they usually mean the **HTTP cache** — the layer that shapes what end users experience. CARTO also runs an internal **in-memory store**, which is technically a cache too but serves a completely different purpose. Keep them separate:

| Layer               | Technology             | What it does                                                                                                                                                                                                   | User-facing? |
| ------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| **HTTP cache**      | Varnish (`http-cache`) | CDN-style response caching in front of the APIs — serves repeated read-heavy responses (e.g. `maps-api` tiles/metadata) without re-computing them. The layer that directly shapes the **end-user experience**. | **Yes**      |
| **In-memory store** | Valkey (`valkey`)      | Internal acceleration: cached credentials/tokens, metadata, session/auth state, and rate-limit counters. Ephemeral; **not** served to end users.                                                               | **No**       |

The two sections below explain each one. When planning capacity, troubleshooting end-user latency, or configuring high availability, treat them separately.

```mermaid
flowchart LR
  U["Users and API clients"] --> H[("HTTP cache - Varnish")]
  H --> S["CARTO services"]
  S -->|credentials, metadata, rate limits| C[("In-memory store - Valkey")]
  S -->|runtime queries| DW[("Data warehouse")]
  S -->|platform state| MD[("Metadata database - PostgreSQL")]
```

## HTTP cache (Varnish)

The HTTP cache is the layer most admins mean by "the cache." It sits **in front of the CARTO APIs** and serves repeated read-heavy responses — map tiles and metadata from `maps-api`, and some `workspace-api` responses — without re-computing them, CDN-style. It is therefore the layer that most directly shapes **end-user experience and latency**.

In CARTO Self-Hosted the HTTP cache ships as the bundled **`http-cache`** component (Varnish). In `kubectl get pods` it appears as `carto-http-cache-*` (prefixed by your Helm release name). It is part of the deployment and requires no external service. For how it fits into the request flow, see the [Architecture overview](/carto-self-hosted/getting-started/architecture.md).

{% hint style="info" %}
The HTTP cache holds **responses only** — it is not where platform state lives. Cached content is purged automatically when the underlying data changes (via the `cdn-invalidator-sub` worker).
{% endhint %}

## In-memory store (Valkey)

The in-memory store is an **internal** layer — not user-facing. CARTO uses **Valkey** to cache credentials and tokens, frequently-read metadata, session and authentication state, and rate-limit counters, accelerating work inside the platform. It is ephemeral and can be flushed without losing persistent data (which lives in the metadata database). A bundled Valkey instance is included in the deployment and is suitable for most production workloads; it runs as the **`valkey`** component, appearing as `carto-valkey-*` in `kubectl get pods` (prefixed by your Helm release name). For high availability, multi-replica scaling, or advanced operational controls, you can configure an **external managed in-memory store** (a Valkey- or Redis-compatible service) instead.

{% hint style="info" %}
**Valkey replaces Redis as of CARTO Self-Hosted 2026.04.** [Valkey](https://valkey.io/) is an open-source fork of Redis 7.2 and is fully wire-compatible: existing external Redis instances continue to work as a drop-in store without configuration changes. For versions earlier than 2026.04, see the [legacy documentation](/carto-self-hosted/carto-self-hosted-legacy.md).
{% endhint %}

The in-memory store sits in front of slower lookups: CARTO services check it first for cached credentials, metadata, and rate-limit state before falling back to the metadata database or re-establishing the value.

Common external in-memory store services:

| Provider            | Service name              |
| ------------------- | ------------------------- |
| Google Cloud        | Memorystore for Redis     |
| Amazon Web Services | ElastiCache for Redis     |
| Microsoft Azure     | Azure Cache for Redis     |
| Self-managed        | Valkey or Redis OSS (v6+) |

### What the in-memory store holds

| Data type                                   | Purpose                                                                                                                                           |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connection credentials & OAuth tokens**   | Cached data-warehouse OAuth tokens (BigQuery, Snowflake, Databricks) and viewer credentials, so they don't have to be re-fetched on every request |
| **Account, organization & source metadata** | Frequently-read account/organization settings and map/named-source metadata                                                                       |
| **Session & authentication state**          | Login sessions, refresh tokens, and SSO/OAuth flow state                                                                                          |
| **Rate-limit counters**                     | Per-user and per-organization API rate-limit state                                                                                                |

{% hint style="info" %}
The in-memory store is not a persistent store; persistent data lives in the metadata database. It can be flushed without losing that data — cached credentials and metadata are simply re-fetched, though active sessions may need to re-authenticate.
{% endhint %}

### Bundled vs. external in-memory store

|                                 | Bundled Valkey              | External managed Valkey                 |
| ------------------------------- | --------------------------- | --------------------------------------- |
| **Setup effort**                | None — included by default  | Requires provisioning before deployment |
| **Recommended for**             | Most production deployments | High-availability deployments           |
| **High availability**           | Not supported               | Supported (Sentinel / Cluster)          |
| **Persistence across restarts** | Lost on pod restart         | Configurable                            |
| **Scaling**                     | Limited to pod resources    | Independent scaling                     |
| **Monitoring**                  | Basic pod metrics           | Cloud provider metrics and alerts       |

**When to use an external in-memory store:**

* High-availability configurations requiring Sentinel or Cluster
* When you need cloud provider-level monitoring, alerting, or SLA guarantees for the in-memory store

### High availability considerations

For high-availability deployments, an external in-memory store is required. The supported topologies and how to configure them are covered in [Configure an external in-memory cache](/carto-self-hosted/configuration/data-and-storage/configure-an-external-in-memory-cache.md) and the [Performance & HA](/carto-self-hosted/configuration/performance-ha/high-availability.md) section.

{% hint style="warning" %}
Valkey persistence (RDB/AOF) is not required for CARTO; the in-memory store is ephemeral by design. Do not enable persistence settings that may impact Valkey performance unless you have a specific operational reason.
{% endhint %}

### Plan your deployment

When sizing your deployment and deciding between the bundled and an external in-memory store, see [Plan Your Deployment](/carto-self-hosted/planning.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-self-hosted/concepts/in-memory-cache.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.