Tair (Redis® OSS-Compatible):exString

Visão geral

As strings nativas do Redis armazenam um par chave-valor. O TairString adiciona um número de versão a cada chave, oferecendo um mecanismo leve para detecção de conflitos sem coordenação externa. Cada gravação bem-sucedida incrementa a versão em 1; o sistema rejeita gravações que especifiquem uma versão incorreta.

O TairString também permite definir limites mínimos ou máximos nos comandos EXINCRBY e EXINCRBYFLOAT. Se um incremento resultar em um valor fora desse intervalo, o comando retornará um erro em vez de gravar o valor excedente.

Principais recursos

• Cada chave TairString possui um número de versão associado ao seu valor.

• Os comandos EXSET e EXINCRBY aceitam a opção VER, que rejeita gravações quando a versão mudou desde a última leitura da chave. Isso implementa a operação compare-and-set sem necessidade de transação separada.

• Os comandos EXINCRBY e EXINCRBYFLOAT aceitam as opções MIN e MAX, que limitam o contador a um intervalo definido.

Este módulo é open source. Para mais informações, consulte o GitHub.

127.0.0.1:6379> EXSET foo 100
OK
127.0.0.1:6379> EXGET foo
1) "100"
2) (integer) 1
127.0.0.1:6379> EXSET foo 200 VER 1
OK
127.0.0.1:6379> EXGET foo
1) "200"
2) (integer) 2
127.0.0.1:6379> EXSET foo 300 VER 1
(error) ERR update version is stale
127.0.0.1:6379> EXCAS foo 400 2
1) OK
2)
3) (integer) 3
127.0.0.1:6379> EXCAD foo 3
(integer) 1

Pré-requisitos

Antes de começar, verifique se você tem:

• Uma instância Tair baseada em DRAM ou otimizada para memória persistente na versão secundária 1.2.3 ou posterior

A versão secundária mais recente oferece mais recursos e maior estabilidade. Atualize a instância para a versão secundária mais recente. Para mais informações, consulte Atualizar a versão secundária de uma instância . Em instâncias cluster ou com divisão de leitura/gravação, atualize também os nós proxy para a versão secundária mais recente. Isso garante a execução correta de todos os comandos.

Notas de uso

Os dados do TairString residem em uma instância Tair. Strings nativas do Redis e TairStrings podem coexistir na mesma instância Tair, mas as strings nativas do Redis não suportam os comandos descritos neste tópico.

Resumo dos comandos

Convenções de sintaxe

• MAIÚSCULAS: palavra-chave do comando.

• itálico: variável.

• [opções]: parâmetro opcional. Parâmetros sem colchetes são obrigatórios.

• A|B: opções mutuamente exclusivas; especifique apenas uma.

• ...: o parâmetro anterior pode ser repetido.

EXSET

Parâmetros

• key: chave a gravar.

• value: valor a gravar.

• EX time: tempo de expiração relativo em segundos. 0 significa que a chave expira imediatamente. Se omitido, a chave não expira.

• EXAT time: tempo de expiração absoluto em segundos (timestamp Unix). 0 significa que a chave expira imediatamente. Se omitido, a chave não expira.

• PX time: tempo de expiração relativo em milissegundos. 0 significa que a chave expira imediatamente. Se omitido, a chave não expira.

• PXAT time: tempo de expiração absoluto em milissegundos (timestamp Unix). 0 significa que a chave expira imediatamente. Se omitido, a chave não expira.

• NX: grava apenas se a chave não existir.

• XX: grava apenas se a chave já existir.

• VER version: operação compare-and-set baseada no número de versão.

  • Se a chave existir: a gravação só terá sucesso quando a versão especificada corresponder à versão atual; a versão é então incrementada em 1. Se as versões não corresponderem, o comando retornará um erro.

  • Se a chave não existir ou sua versão atual for 0: o valor VER é ignorado, a gravação tem sucesso e a versão é definida como 1.

• ABS version: substitui a versão incondicionalmente. Após a gravação, a versão será igual ao valor ABS especificado.

• KEEPTTL: herda o TTL (tempo de vida) restante da chave. Não pode ser combinado com EX, PX, EXAT ou PXAT.

Se nenhum parâmetro de expiração for definido ( EX , PX , EXAT , PXAT ou KEEPTTL ), a chave não expira.

Valores de retorno

• OK: gravação bem-sucedida.

• nil: XX foi especificado, mas a chave não existe, ou NX foi especificado, mas a chave já existe.

• Erro: todas as outras falhas.

Exemplo

EXSET foo bar EX 10 NX ABS 100

OK

EXGET

Parâmetros

• key: chave a ler.

Valores de retorno

• Um array contendo o valor (bulk string) e o número de versão (integer).

• Erro: a chave não existe ou ocorreu outra falha.

Exemplo

EXGET foo

1) "bar"
2) (integer) 1

EXSETVER

Parâmetros

• key: chave a atualizar.

• version: número de versão a atribuir.

Valores de retorno

• 1: versão definida com sucesso.

• 0: a chave não existe.

• Erro: ocorreu outra falha.

Exemplo

EXSETVER foo 2

(integer) 1

EXINCRBY

Parâmetros

• key: chave a atualizar.

• num: valor inteiro a adicionar (use um valor negativo para decrementar).

• EX, EXAT, PX, PXAT, NX, XX, VER, ABS, KEEPTTL: iguais aos parâmetros do comando EXSET.

• MIN minval: valor mínimo permitido. Se o resultado for menor que minval, o comando retorna um erro e não grava o valor.

• MAX maxval: valor máximo permitido. Se o resultado exceder maxval, o comando retorna um erro e não grava o valor.

Se nenhum parâmetro de expiração for definido ( EX , PX , EXAT , PXAT ou KEEPTTL ), a chave não expira.

Valores de retorno

• Valor atualizado (integer): incremento bem-sucedido.

• (error) ERR increment or decrement would overflow: o resultado ficaria fora do intervalo MIN/MAX.

• Erro: ocorreu outra falha.

Exemplo

O exemplo a seguir pressupõe a execução prévia de EXSET foo 1. O comando incrementa foo em 100 e limita o valor a um máximo de 300.

EXINCRBY foo 100 MAX 300

(integer) 101

Padrão: contador delimitado

Use MIN e MAX para implementar um limitador de taxa ou contador de cota que nunca excede seus limites:

# Initialize the counter
EXSET requests 0

# Increment on each request; reject when the limit is hit
EXINCRBY requests 1 MAX 100
# Returns (error) ERR increment or decrement would overflow when the limit is reached

EXINCRBYFLOAT

Parâmetros

• key: chave a atualizar.

• num: valor de ponto flutuante a adicionar (use um valor negativo para decrementar).

• Todas as outras opções (EX, EXAT, PX, PXAT, NX, XX, VER, ABS, KEEPTTL, MIN, MAX): iguais aos parâmetros do comando EXINCRBY.

Se nenhum parâmetro de expiração for definido ( EX , PX , EXAT , PXAT ou KEEPTTL ), a chave não expira.

Valores de retorno

• Valor atualizado: incremento bem-sucedido.

• (error) ERR increment or decrement would overflow: o resultado ficaria fora do intervalo MIN/MAX.

• Erro: ocorreu outra falha.

Exemplo

O exemplo a seguir pressupõe a execução prévia de EXSET foo 1.

EXINCRBYFLOAT foo 10.123

(integer) 11.123

EXCAS

Parâmetros

• key: chave a atualizar.

• newvalue: valor a gravar se a versão corresponder.

• version: número de versão a comparar com a versão atual.

Valores de retorno

• ["OK", "", latest_version]: atualização bem-sucedida. A string vazia no meio não tem significado.

• ["ERR update version is stale", current_value, current_version]: a versão não correspondeu. A chave não foi modificada.

• -1: a chave não existe.

• Erro: ocorreu outra falha.

Exemplo

O exemplo a seguir pressupõe a execução prévia de EXSET foo bar (versão = 1).

EXCAS foo bzz 1

1) OK
2)
3) (integer) 2

Padrão: bloqueio otimista

Use o EXCAS para implementar um ciclo de leitura-modificação-gravação sem bloqueios:

# 1. Read the current value and version
EXGET mykey
# Returns: value="old", version=5

# 2. Modify locally

# 3. Write back only if the version hasn't changed
EXCAS mykey "new" 5
# If another writer changed the key, EXCAS returns the stale-version error.
# Retry from step 1.

EXCAD

Parâmetros

• key: chave a excluir.

• version: número de versão a comparar com a versão atual.

Valores de retorno

• 1: chave excluída.

• 0: a versão não correspondeu; a chave não foi excluída.

• -1: a chave não existe.

• Erro: ocorreu outra falha.

Exemplo

O exemplo a seguir pressupõe a execução prévia de EXSET foo bar (versão = 1).

EXCAD foo 1

(integer) 1

Próximos passos

• Implementar bloqueios distribuídos de alto desempenho usando TairString

• Implementar bloqueio otimista de alto desempenho usando TairString

• Implementar contadores delimitados usando TairString