O que é um cluster Redis/Valkey

Quando uma única instância de Redis ou Valkey não suporta o volume de dados ou throughput necessário, o modo Cluster permite distribuir os dados entre múltiplos nós. Em vez de manter tudo em um único servidor, o cluster particiona o keyspace em 16384 hash slots e distribui esses slots entre os nós disponíveis.

Cada nó do cluster é responsável por um subconjunto dos slots. Quando um cliente executa um comando, o cluster calcula o hash slot da chave e direciona a operação para o nó correto. Se o cliente envia o comando para o nó errado, recebe um redirecionamento MOVED com o endereço do nó correto.

A distribuição típica com 3 nós:

NóSlots
Nó A0-5460
Nó B5461-10922
Nó C10923-16383

Essa distribuição pode ser rebalanceada conforme nós são adicionados ou removidos. O comando CLUSTER SLOTS ou CLUSTER SHARDS permite consultar a distribuição atual.

Hash Slots: como funcionam os 16384 slots

O hash slot de uma chave é determinado pelos 14 bits menos significativos do CRC16 da chave:

slot = CRC16(key) mod 16384

Esse cálculo é determinístico: a mesma chave sempre resulta no mesmo slot e, portanto, no mesmo nó. Clientes inteligentes (como redis-cli --cluster, Lettuce ou Jedis no modo cluster) calculam o slot localmente e enviam o comando diretamente para o nó correto, evitando redirecionamentos.

O total de 16384 slots é um valor fixo da especificação. Não importa se o cluster tem 3 ou 100 nós — os slots são sempre 16384, apenas redistribuídos.

O problema do CROSSSLOT

Em um cenário comum, diferentes chaves de um mesmo usuário acabam em slots diferentes porque o CRC16 é calculado sobre a chave inteira:

SET user:1000:profile "João"      # slot 8421 -> Nó B
SET user:1000:orders "[...]"      # slot 12657 -> Nó C
SET user:1000:settings "{...}"    # slot 3891 -> Nó A

Acessar essas chaves individualmente funciona sem problemas. O erro aparece ao tentar operações multi-key:

MGET user:1000:profile user:1000:orders user:1000:settings
# ERRO: CROSSSLOT Keys in request don't hash to the same slot

O cluster não consegue executar uma única operação atômica entre nós diferentes. Comandos afetados:

  • MGET, MSET, DEL com múltiplas chaves
  • Transações com MULTI/EXEC
  • Scripts Lua que acessam múltiplas chaves
  • Pipelines com chaves em slots diferentes

O erro CROSSSLOT é uma restrição arquitetural: o cluster não tem um coordenador de transações distribuídas entre nós.

HashTags: a solução com {prefix}

O Redis e o Valkey oferecem um mecanismo chamado HashTags. Se uma chave contém o padrão {...}, apenas o conteúdo entre as primeiras chaves {} é usado para calcular o hash slot:

SET {user:1000}:profile "João"      # slot 7542 -> Nó B
SET {user:1000}:orders "[...]"      # slot 7542 -> Nó B
SET {user:1000}:settings "{...}"    # slot 7542 -> Nó B

Todas as chaves com a mesma HashTag {user:1000} caem no mesmo slot. Agora operações multi-key funcionam:

MGET {user:1000}:profile {user:1000}:orders {user:1000}:settings
# OK - todas as chaves estão no slot 7542

Pipelines e transações também passam a funcionar, já que o cluster resolve tudo em um único nó.

A regra de parsing é simples: o cluster procura a primeira ocorrência de { e a primeira ocorrência de } após ela. Se o conteúdo entre eles não é vazio, ele é usado como input do CRC16. Se {} está vazio ou não existe, a chave inteira é usada.

Quando usar HashTags e quando evitar

HashTags resolvem o CROSSSLOT, mas introduzem riscos:

Use quando:

  • Precisa de operações multi-key sobre dados relacionados (perfil + pedidos + configurações de um usuário)
  • Precisa de transações atômicas entre chaves relacionadas
  • Scripts Lua que manipulam múltiplas chaves do mesmo contexto

Evite quando:

  • As chaves não precisam ser acessadas juntas (GET/SET individuais não precisam de HashTags)
  • A HashTag tem baixa cardinalidade (ex: {orders} colocaria TODOS os pedidos no mesmo nó)
  • Uma entidade concentra volume desproporcional de dados — isso cria hot keys e sobrecarrega um único nó enquanto os demais ficam ociosos

Monitore a distribuição:

CLUSTER SLOTS
CLUSTER SHARDS

Se um nó está consistentemente mais carregado que os outros, pode ser sinal de HashTags com poucos valores distintos. Prefira tags com alta cardinalidade, como IDs de usuário ou tenant.

Valkey vs Redis

Desde 2024, o Valkey é o fork open-source do Redis, mantido pela Linux Foundation. Ele surgiu após a mudança de licença do Redis (de BSD para dual-license com SSPL/RSALv2). O Valkey mantém compatibilidade total com o protocolo e comandos do Redis, incluindo todo o comportamento de cluster, hash slots e HashTags descrito aqui. Se você já usa Redis Cluster, a migração para Valkey é transparente em termos de protocolo e comandos.

Referências