Tair (Redis® OSS-Compatible):exString

Descripción general

Las cadenas nativas de Redis almacenan un par clave-valor. TairString añade un número de versión a cada clave, lo que proporciona un mecanismo ligero para la detección de conflictos sin necesidad de coordinación externa. Cada escritura exitosa incrementa la versión en 1; si una escritura especifica una versión incorrecta, se rechaza.

TairString también permite establecer un límite mínimo o máximo en EXINCRBY y EXINCRBYFLOAT. Si un incremento sacara el valor fuera de ese rango, el comando devuelve un error en lugar de escribir el valor fuera de rango.

Capacidades principales

• Cada clave de TairString incluye un número de versión junto con su valor.

• EXSET y EXINCRBY aceptan la opción VER, que rechaza las escrituras cuando la versión ha cambiado desde la última lectura de la clave. Esto implementa una operación de comparación y asignación sin necesidad de una transacción separada.

• EXINCRBY y EXINCRBYFLOAT aceptan las opciones MIN y MAX, que limitan el contador a un rango definido.

Este módulo es de código abierto. Para obtener más información, consulte 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

Requisitos previos

Antes de empezar, asegúrese de contar con:

• Una instancia Tair DRAM-based o persistent memory-optimized con versión menor 1.2.3 o posterior

La versión menor más reciente ofrece más funciones y mayor estabilidad. Actualice la instancia a la versión menor más reciente. Para obtener más información, consulte Update the minor version of an instance . En instancias de clúster o con división de lectura/escritura, actualice también los nodos proxy a la versión menor más reciente para garantizar que todos los comandos se ejecuten correctamente.

Notas de uso

Los datos de TairString se almacenan en una instancia de Tair. Las cadenas nativas de Redis y las TairStrings pueden coexistir en la misma instancia de Tair, pero las cadenas nativas de Redis no admiten los comandos descritos en este tema.

Resumen de comandos

Convenciones de sintaxis

• MAYÚSCULAS: palabra clave del comando.

• cursiva: variable.

• [opciones]: parámetro opcional. Los parámetros sin corchetes son obligatorios.

• A|B: opciones mutuamente excluyentes; especifique solo una.

• ...: el parámetro anterior puede repetirse.

EXSET

Parámetros

• key: la clave que se va a escribir.

• value: el valor que se va a escribir.

• EX time: tiempo de expiración relativo en segundos. 0 indica que la clave expira inmediatamente. Si se omite, la clave no expira.

• EXAT time: tiempo de expiración absoluto en segundos (marca de tiempo Unix). 0 indica que la clave expira inmediatamente. Si se omite, la clave no expira.

• PX time: tiempo de expiración relativo en milisegundos. 0 indica que la clave expira inmediatamente. Si se omite, la clave no expira.

• PXAT time: tiempo de expiración absoluto en milisegundos (marca de tiempo Unix). 0 indica que la clave expira inmediatamente. Si se omite, la clave no expira.

• NX: escribe solo si la clave no existe.

• XX: escribe solo si la clave ya existe.

• VER version: operación de comparación y asignación basada en el número de versión.

  • Si la clave existe: la escritura se realiza correctamente solo cuando la versión especificada coincide con la versión actual; después, la versión se incrementa en 1. Si las versiones no coinciden, se devuelve un error.

  • Si la clave no existe o su versión actual es 0: se ignora el valor VER, la escritura se realiza correctamente y la versión se establece en 1.

• ABS version: sobrescribe la versión incondicionalmente. Después de la escritura, la versión es igual al valor ABS especificado.

• KEEPTTL: hereda el TTL (tiempo de vida) restante de la clave. No se puede combinar con EX, PX, EXAT ni PXAT.

Si no se establece ningún parámetro de expiración ( EX , PX , EXAT , PXAT o KEEPTTL ), la clave no expira.

Valores de retorno

• OK: la escritura se realizó correctamente.

• nil: se especificó XX pero la clave no existe, o se especificó NX pero la clave ya existe.

• Error: cualquier otro fallo.

Ejemplo

EXSET foo bar EX 10 NX ABS 100

OK

EXGET

Parámetros

• key: la clave que se va a leer.

Valores de retorno

• Un arreglo que contiene el valor (cadena masiva) y el número de versión (entero).

• Error: la clave no existe u ocurrió otro fallo.

Ejemplo

EXGET foo

1) "bar"
2) (integer) 1

EXSETVER

Parámetros

• key: la clave que se va a actualizar.

• version: el número de versión que se va a asignar.

Valores de retorno

• 1: la versión se estableció correctamente.

• 0: la clave no existe.

• Error: ocurrió otro fallo.

Ejemplo

EXSETVER foo 2

(integer) 1

EXINCRBY

Parámetros

• key: la clave que se va a actualizar.

• num: la cantidad entera que se va a sumar (use un valor negativo para decrementar).

• EX, EXAT, PX, PXAT, NX, XX, VER, ABS, KEEPTTL: igual que en EXSET.

• MIN minval: el valor mínimo permitido. Si el resultado fuera menor que minval, el comando devuelve un error y no escribe.

• MAX maxval: el valor máximo permitido. Si el resultado superara maxval, el comando devuelve un error y no escribe.

Si no se establece ningún parámetro de expiración ( EX , PX , EXAT , PXAT o KEEPTTL ), la clave no expira.

Valores de retorno

• El valor actualizado (entero): el incremento se realizó correctamente.

• (error) ERR increment or decrement would overflow: el resultado quedaría fuera del rango MIN/MAX.

• Error: ocurrió otro fallo.

Ejemplo

El siguiente ejemplo asume que previamente se ejecutó EXSET foo 1. El comando incrementa foo en 100 y limita el valor a un máximo de 300.

EXINCRBY foo 100 MAX 300

(integer) 101

Patrón: contador acotado

Utilice MIN y MAX para implementar un limitador de tasa o un contador de cuota que nunca exceda sus límites:

# 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: la clave que se va a actualizar.

• num: la cantidad de punto flotante que se va a sumar (use un valor negativo para decrementar).

• Todas las demás opciones (EX, EXAT, PX, PXAT, NX, XX, VER, ABS, KEEPTTL, MIN, MAX): igual que en EXINCRBY.

Si no se establece ningún parámetro de expiración ( EX , PX , EXAT , PXAT o KEEPTTL ), la clave no expira.

Valores de retorno

• El valor actualizado: el incremento se realizó correctamente.

• (error) ERR increment or decrement would overflow: el resultado quedaría fuera del rango MIN/MAX.

• Error: ocurrió otro fallo.

Ejemplo

El siguiente ejemplo asume que previamente se ejecutó EXSET foo 1.

EXINCRBYFLOAT foo 10.123

(integer) 11.123

EXCAS

Parámetros

• key: la clave que se va a actualizar.

• newvalue: el valor que se va a escribir si la versión coincide.

• version: el número de versión que se comparará con la versión actual.

Valores de retorno

• ["OK", "", latest_version]: la actualización se realizó correctamente. La cadena vacía en medio no tiene significado.

• ["ERR update version is stale", current_value, current_version]: la versión no coincidió. La clave no se modificó.

• -1: la clave no existe.

• Error: ocurrió otro fallo.

Ejemplo

El siguiente ejemplo asume que previamente se ejecutó EXSET foo bar (versión = 1).

EXCAS foo bzz 1

1) OK
2)
3) (integer) 2

Patrón: bloqueo optimista

Utilice EXCAS para implementar un bucle de lectura-modificación-escritura sin bloqueos:

# 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: la clave que se va a eliminar.

• version: el número de versión que se comparará con la versión actual.

Valores de retorno

• 1: la clave se eliminó.

• 0: la versión no coincidió; la clave no se eliminó.

• -1: la clave no existe.

• Error: ocurrió otro fallo.

Ejemplo

El siguiente ejemplo asume que previamente se ejecutó EXSET foo bar (versión = 1).

EXCAD foo 1

(integer) 1

Pasos siguientes

• Implement high-performance distributed locks by using TairString

• Implement high-performance optimistic locking by using TairString

• Implement bounded counters by using TairString