Usando Comandos Redis Scan no Linux: Um Guia Completo

Redis é um armazenamento de estrutura de dados em memória, de código aberto e alto desempenho, amplamente utilizado como banco de dados chave-valor, cache e intermediário de mensagens. Entre seus recursos mais poderosos — mas frequentemente subutilizados — estão os scan commands, que permitem iterar incrementalmente através de grandes conjuntos de dados sem bloquear seu servidor ou degradar o desempenho.

Se você está executando Redis em um servidor baseado em Linux, dominar scan commands é essencial para construir aplicações escaláveis e prontas para produção. Ao contrário do comando perigoso KEYS, que recupera todas as chaves correspondentes em uma única operação bloqueante, scan commands retornam dados em pequenos lotes gerenciáveis — tornando-os a ferramenta correta para qualquer ambiente que lida com volumes significativos de dados.

Neste guia abrangente, você aprenderá exatamente como usar SCAN, SSCAN, HSCAN e ZSCAN em Redis no Linux, completo com exemplos do mundo real, scripts shell e melhores práticas para implantações em produção.

O que são Comandos Redis Scan?

Os comandos Redis scan fornecem um mecanismo baseado em cursor, não bloqueante para iterar sobre chaves, conjuntos, hashes e conjuntos ordenados. Cada comando retorna um pequeno subconjunto de elementos por chamada junto com um valor de cursor, que você usa para continuar a iteração em chamadas subsequentes. Quando o cursor retorna para 0, o conjunto de dados completo foi percorrido.

Esta abordagem é fundamentalmente mais segura e eficiente do que KEYS, que bloqueia todo o servidor Redis até terminar a varredura — um problema crítico em ambientes de produção com milhões de chaves.

Os Quatro Comandos Scan Principais

Sintaxe Básica de Comandos de Scan

Todos os quatro comandos de scan compartilham uma estrutura de sintaxe consistente:

SCAN cursor [MATCH pattern] [COUNT count]
SSCAN key cursor [MATCH pattern] [COUNT count]
HSCAN key cursor [MATCH pattern] [COUNT count]
ZSCAN key cursor [MATCH pattern] [COUNT count]

Parâmetros Explicados

• cursor — Um inteiro representando a posição atual na iteração. Sempre comece com 0 para iniciar um novo scan. Redis retorna um novo cursor com cada resposta; use-o na próxima chamada para continuar.
• MATCH pattern *(opcional)* — Filtra resultados usando correspondência de padrão estilo glob (por exemplo, user:*, *session*). Nota: a filtragem acontece *após* a recuperação, portanto correspondências de baixa densidade podem exigir muitas iterações.
• COUNT count *(opcional)* — Uma sugestão para Redis sobre quantos elementos retornar por iteração. Isto não é um limite rígido; Redis pode retornar mais ou menos. O padrão é 10.

Instalação do Redis no Linux

Antes de usar comandos scan, você precisa ter Redis instalado e em execução no seu servidor Linux. Quer você esteja em um ambiente de produção com alto tráfego ou em uma máquina de desenvolvimento, o processo de instalação é direto.

> Dica: Para cargas de trabalho de produção que exigem Redis em escala, considere implantar em um plano de VPS Hosting ou um Servidor Dedicado para garantir que você tenha a memória, CPU e recursos de I/O que Redis exige.

Instalação do Redis no Debian/Ubuntu

sudo apt update
sudo apt install redis-server -y

Instalação do Redis no CentOS/RHEL

sudo yum install redis -y

Iniciando o Serviço Redis

sudo systemctl start redis
sudo systemctl enable redis

Verificando a Instalação

sudo systemctl status redis

Você deve ver active (running) na saída. Agora conecte ao Redis CLI:

redis-cli

Uma vez dentro do CLI, teste a conexão:

127.0.0.1:6379> PING
PONG

Você está pronto para começar a usar comandos scan.

Usando o Comando SCAN

O comando SCAN itera sobre todas as chaves no espaço de chaves Redis. É o substituto de propósito geral para o comando KEYS em ambientes de produção.

Exemplo 1: SCAN Básico

Para começar a verificar todas as chaves no banco de dados, comece com o cursor 0:

SCAN 0

Saída de exemplo:

1) "14"
2) 1) "session:abc123"
   2) "user:1001"
   3) "product:55"

O primeiro elemento (14) é o próximo cursor. Use-o na sua próxima chamada SCAN. Quando o cursor retornado for 0, a iteração completa está concluída.

Exemplo 2: Filtrando Chaves com MATCH

Para recuperar apenas chaves que correspondem a um padrão específico — por exemplo, todas as chaves prefixadas com user::

SCAN 0 MATCH user:*

Isto retorna apenas chaves cujos nomes começam com user:. Continue iterando até o cursor retornar 0 para garantir que verificou todo o espaço de chaves.

Exemplo 3: Controlando o Tamanho do Lote com COUNT

Para sugerir que Redis retorne aproximadamente 100 chaves por iteração:

SCAN 0 COUNT 100

Lembre-se: COUNT é uma *sugestão*, não uma garantia. Redis pode retornar ligeiramente mais ou menos resultados dependendo das estruturas de dados internas.

Exemplo 4: Iteração Completa do Espaço de Chaves com um Script Shell

Em cenários do mundo real, você precisará fazer um loop através do espaço de chaves programaticamente. Aqui está um script Bash pronto para produção que itera através de todas as chaves que correspondem a um padrão:

#!/bin/bash

cursor=0
echo "Starting full keyspace scan..."

while true; do
    # Execute SCAN and capture the result
    result=$(redis-cli SCAN $cursor MATCH user:* COUNT 100)

    # Extract the new cursor (first line of output)
    cursor=$(echo "$result" | head -n 1)

    # Extract and display the keys (remaining lines)
    keys=$(echo "$result" | tail -n +2)
    echo "Keys found:"
    echo "$keys"

    # Break the loop when cursor returns to 0
    if [[ "$cursor" == "0" ]]; then
        echo "Scan complete."
        break
    fi
done

Para executar este script:

chmod +x scan_keys.sh
./scan_keys.sh

Usando o Comando SSCAN

SSCAN é usado para iterar incrementalmente através dos membros de um Redis Set. Segue o mesmo padrão baseado em cursor que SCAN.

Passo 1: Criar um Set e Adicionar Membros

SADD myset "apple"
SADD myset "banana"
SADD myset "cherry"
SADD myset "date"
SADD myset "elderberry"
SADD myset "mango"
SADD myset "mango:tropical"
SADD myset "mango:dried"

Passo 2: SSCAN Básico

Digitalize todos os elementos em myset começando do cursor 0:

SSCAN myset 0

Passo 3: Filtrar Elementos com MATCH

Para recuperar apenas elementos que correspondem ao padrão mango:*:

SSCAN myset 0 MATCH mango:*

Passo 4: Iterando Através de um Set com um Script Shell

#!/bin/bash

cursor=0
echo "Scanning through myset:"

while true; do
    # Scan the set
    result=$(redis-cli SSCAN myset $cursor COUNT 10)

    # Update cursor
    cursor=$(echo "$result" | head -n 1)

    # Print elements returned
    elements=$(echo "$result" | tail -n +2)
    echo "Elements: $elements"

    # Stop when cursor returns to 0
    if [[ "$cursor" == "0" ]]; then
        echo "Set scan complete."
        break
    fi
done

Salve como scan_myset.sh, torne-o executável e execute:

chmod +x scan_myset.sh
./scan_myset.sh

Usando o Comando HSCAN

HSCAN itera através dos campos e valores de um Hash Redis. Isto é particularmente útil quando um hash contém centenas ou milhares de campos e você precisa processá-los sem carregar tudo na memória de uma só vez.

Passo 1: Criar um Hash e Adicionar Campos

HSET myhash name "John Doe"
HSET myhash age "30"
HSET myhash occupation "Software Developer"
HSET myhash city "San Francisco"
HSET myhash country "USA"
HSET myhash email "john@example.com"

Passo 2: HSCAN Básico

HSCAN myhash 0

Saída de exemplo:

1) "0"
2) 1) "name"
   2) "John Doe"
   3) "age"
   4) "30"
   5) "occupation"
   6) "Software Developer"
   ...

Os resultados são retornados como pares campo-valor alternados.

Passo 3: Filtrar Campos Hash com MATCH

Para recuperar apenas campos cujos nomes contêm "city" ou correspondem a um padrão:

HSCAN myhash 0 MATCH *city*

Passo 4: Iterando Através de um Hash com um Script Shell

#!/bin/bash

cursor=0
echo "Scanning hash: myhash"

while true; do
    result=$(redis-cli HSCAN myhash $cursor COUNT 10)
    cursor=$(echo "$result" | head -n 1)
    fields=$(echo "$result" | tail -n +2)

    echo "Fields and values:"
    echo "$fields"

    if [[ "$cursor" == "0" ]]; then
        echo "Hash scan complete."
        break
    fi
done

Usando o Comando ZSCAN

ZSCAN itera através dos membros e pontuações de um Redis Sorted Set. Sorted sets são comumente usados para leaderboards, filas de prioridade e dados de séries temporais — todos cenários onde a varredura eficiente de grandes coleções é crítica.

Passo 1: Criar um Sorted Set e Adicionar Membros

ZADD mysortedset 1 "apple"
ZADD mysortedset 2 "banana"
ZADD mysortedset 3 "cherry"
ZADD mysortedset 4 "date"
ZADD mysortedset 5 "elderberry"

Passo 2: ZSCAN Básico

ZSCAN mysortedset 0

Saída de exemplo:

1) "0"
2) 1) "apple"
   2) "1"
   3) "banana"
   4) "2"
   5) "cherry"
   6) "3"

Os resultados são retornados como pares alternados de membro-pontuação.

Passo 3: Filtrar Membros com MATCH

Para encontrar todos os membros cujos nomes contêm a letra "e":

ZSCAN mysortedset 0 MATCH *e*

Passo 4: Script de Iteração Completo do Sorted Set

#!/bin/bash

cursor=0
echo "Scanning sorted set: mysortedset"

while true; do
    result=$(redis-cli ZSCAN mysortedset $cursor COUNT 10)
    cursor=$(echo "$result" | head -n 1)
    members=$(echo "$result" | tail -n +2)

    echo "Members and scores:"
    echo "$members"

    if [[ "$cursor" == "0" ]]; then
        echo "Sorted set scan complete."
        break
    fi
done

Comparação de Comandos Scan: Referência Rápida

Melhores Práticas para Usar Comandos Redis SCAN em Produção

1. Sempre Use SCAN em Vez de KEYS em Produção

O comando KEYS é single-threaded e bloqueia todas as outras operações Redis até sua conclusão. Em um banco de dados com milhões de chaves, isso pode causar picos severos de latência. Nunca use KEYS em produção. SCAN é a alternativa correta e não-bloqueante.

2. Ajuste COUNT com Base no Tamanho do Seu Dataset

Para datasets pequenos (< 1.000 chaves), o padrão COUNT 10 é adequado. Para datasets grandes, aumente COUNT para 100–1000 para reduzir o número de round trips mantendo respostas individuais gerenciáveis.

3. Não Confie Apenas em MATCH para Eficiência

O filtro MATCH é aplicado *depois* que Redis recupera elementos internamente. Se seu padrão corresponde apenas a uma pequena fração de chaves, Redis ainda verifica o dataset completo internamente. Use convenções de nomenclatura de chaves (por exemplo, prefixos consistentes) para tornar MATCH mais eficaz.

4. Processe Resultados em Lotes

Nunca acumule todos os resultados de scan na memória antes de processar. Em vez disso, processe cada lote imediatamente conforme é retornado. Isso é especialmente importante em servidores com restrições de memória.

5. Manipule o Estado do Cursor com Cuidado

Sempre inicialize o cursor para 0 e atualize-o com cada resposta. Se sua aplicação falhar durante o scan, reinicie a partir de 0. Os cursores Redis não são persistentes entre reinicializações do servidor.

6. Teste Completamente em Desenvolvimento Primeiro

Antes de implantar lógica baseada em scan em produção, valide-a em um ambiente de staging com um dataset representativo. Verifique se seu loop termina corretamente quando o cursor retorna para 0.

7. Proteja Sua Instância Redis

Redis nunca deve ser exposto à internet pública sem autenticação. Use requirepass em sua configuração Redis, vincule ao localhost ou a uma interface de rede privada, e use regras de firewall para restringir o acesso.

Escolher o Ambiente de Hosting Certo para Redis

O desempenho do Redis está diretamente ligado à RAM disponível, velocidade da CPU e latência de rede. Escolher a infraestrutura de hosting certa é tão importante quanto escrever comandos Redis eficientes.

• Desenvolvimento e pequenos projetos: Shared Web Hosting pode ser suficiente para uso leve de Redis, embora instâncias Redis dedicadas sejam sempre preferidas.
• Aplicações em crescimento: Um plano de VPS Hosting oferece recursos dedicados, acesso root e a capacidade de ajustar a configuração do Redis (maxmemory, configurações de persistência, etc.) às suas necessidades exatas.
• Sistemas de produção com alto tráfego: Dedicated Servers fornecem os recursos máximos de RAM e CPU que o Redis pode utilizar, eliminando completamente a contenção de recursos.
• Cargas de trabalho de IA e ML usando Redis como armazenamento vetorial: GPU Hosting oferece o poder computacional necessário para geração de embeddings e busca de similaridade junto com Redis.

Para aplicações que também exigem um painel de controle web para gerenciamento mais fácil, VPS com cPanel fornece uma interface amigável junto com controle total do servidor.

Resolução de Problemas Comuns

SCAN Retorna 0 Elementos Repetidamente

Isto geralmente significa que o seu padrão MATCH não corresponde a nenhuma chave, ou o conjunto de dados está vazio. Verifique a nomenclatura da sua chave com DBSIZE para verificar a contagem total de chaves.

127.0.0.1:6379> DBSIZE
(integer) 15420

Cursor Nunca Retorna a 0

Isto não deve acontecer numa instância Redis estável. Se acontecer, verifique a compatibilidade da versão Redis (os comandos scan requerem Redis 2.8+) ou interrupções de ligação que repõem o rastreamento do seu cursor.

Script Congela Indefinidamente

Certifique-se de que o seu loop lê corretamente o cursor da primeira linha da saída redis-cli. Um erro de análise que sempre produz um cursor diferente de zero causará um loop infinito.

Conclusão

Os comandos scan do Redis — SCAN, SSCAN, HSCAN e ZSCAN — são ferramentas indispensáveis para qualquer desenvolvedor ou administrador de sistemas que trabalhe com Redis em larga escala no Linux. Eles fornecem um mecanismo seguro, não-bloqueante e baseado em cursor para iterar através de grandes conjuntos de dados sem os riscos de desempenho associados a comandos como KEYS.

Ao combinar comandos scan com padrões MATCH, dicas COUNT apropriadas e scripts shell bem estruturados, você pode construir pipelines de processamento de dados eficientes que escalam graciosamente com o tamanho do seu conjunto de dados. Seguindo as melhores práticas descritas neste guia — particularmente em torno da segurança em produção, gerenciamento de memória e seleção de infraestrutura — você garantirá que suas implantações do Redis permaneçam performáticas e confiáveis.

Para as opções de comando mais atuais e detalhes de configuração avançada, sempre consulte a documentação oficial do Redis. E quando estiver pronto para implantar o Redis em um ambiente Linux de nível de produção, explore o VPS Hosting e os Servidores Dedicados da AlexHost para infraestrutura construída para lidar com cargas de trabalho exigentes e intensivas em memória.