# Cache key vs restore key: como funcionam as buscas de cache no CI

> Uma cache key é a entrada exata para salvar e buscar; restore keys são fallbacks por prefixo para um quase-acerto. Entenda como as duas equilibram frescor e acertos.

Source: https://latchkey.dev/pt/learn/ci-cd-concepts/cache-key-vs-restore-key  
Updated: 2026-06-25

A cache key é o nome exato sob o qual você salva e busca primeiro. Restore keys são prefixos que capturam um quase-acerto, para que uma pequena alteração restaure um cache antigo útil em vez de nada.

O cache de CI tem dois botões que as pessoas confundem: a key precisa e as restore keys de fallback. Entender como uma busca caminha de uma para a outra é a chave tanto para altas taxas de acerto quanto para dados frescos.

## A key exata

Ao salvar, o cache é armazenado sob a key. Ao restaurar, o runner primeiro busca uma correspondência exata. Uma correspondência perfeita é o ideal: ela restaura precisamente o cache para este conjunto de dependências. A key normalmente embute um hash de lockfile para que mude apenas quando deve.

## Restore keys (fallback por prefixo)

Se não há correspondência exata, o runner tenta cada restore key como um *prefixo*, pegando o cache mais recente cuja key começa com esse prefixo. Isso significa que um lockfile alterado (nova key exata, sem acerto exato) ainda pode restaurar o store da execução anterior e deixar o instalador atualizar só o delta.

```Exact key + prefix fallback
key: deps-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
  deps-
```

## Semântica de save vs restore

- Save: grava sob a key exata (no-op se essa key já existe).
- Restore: key exata primeiro, depois restore-keys como prefixos, mais recente vence.
- Um acerto por restore-key é parcial - o instalador reconcilia a diferença.

## Ajustando o trade-off

Uma key específica demais sem restore keys → erros totais frequentes e instalações a frio. Um prefixo frouxo demais → você pode restaurar um cache obsoleto e inchado. Uma key exata apertada mais um fallback de prefixo sensato dá frescor em uma correspondência e um início aquecido em um erro.

## FAQ

### What is Cache key vs restore Key: how CI cache lookups work?

CI caching has two knobs that people conflate: the precise key and the fallback restore keys. Understanding how a lookup walks from one to the other is the key to both high hit rates and fresh data.

### The exact key?

On save, the cache is stored under the key. On restore, the runner first looks for an exact match. A perfect match is the ideal: it restores precisely the cache for this dependency set. The key usually embeds a lockfile hash so it changes only when it should.

### Restore keys (prefix fallback)?

If there is no exact match, the runner tries each restore key as a *prefix*, taking the most recent cache whose key starts with that prefix. This means a changed lockfile (new exact key, no exact hit) can still restore the previous run’s store and let the installer update just the delta.

### Tuning the trade-off?

Too specific a key with no restore keys → frequent total misses and cold installs. Too loose a prefix → you may restore a stale, bloated cache. A tight exact key plus a sensible prefix fallback gives you freshness on a match and a warm start on a miss.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt