Valkey: Búsqueda y JSON

Almacene y consulte documentos JSON con el módulo de búsqueda de Valkey

👋 ¡Bienvenido a la documentación de Stackhero!

Stackhero ofrece una solución Valkey cloud lista para usar que proporciona numerosas ventajas, entre ellas:

Interfaz web Valkey Admin incluida.

Tamaño y transferencia de mensajes ilimitados.

Actualizaciones sencillas con solo un clic.

Rendimiento óptimo y seguridad reforzada gracias a una infraestructura privada y dedicada.

Ahorre tiempo y simplifique su trabajo: solo necesita 5 minutos para probar la solución de Valkey cloud hosting de Stackhero.

Su instancia de Valkey en Stackhero incluye módulos esenciales mantenidos por el proyecto Valkey. Estos módulos convierten a Valkey en mucho más que una caché: puede almacenar documentos JSON nativos, indexar sus datos y realizar consultas por etiquetas, numéricas, de texto y vectoriales, todo ello sin tener que gestionar una base de datos independiente.

Hay tres módulos disponibles, todos incluidos en su plan y bajo la misma licencia permisiva BSD 3-Clause que Valkey:

JSON (comandos JSON.*): Almacene y actualice documentos JSON estructurados con soporte para JSONPath. Puede leer o modificar campos individuales directamente, por lo que nunca tendrá que reescribir el documento completo para pequeños cambios.
Search (comandos FT.*): Realice indexación secundaria, consultas por etiquetas, numéricas, de texto completo y búsquedas por similitud vectorial.
Bloom (comandos BF.*): Utilice filtros Bloom para responder de forma eficiente a la pregunta "¿ya he visto esto?" en grandes conjuntos de datos, utilizando una cantidad mínima de memoria.

Activación de los módulos

Los módulos están desactivados por defecto, por lo que su servicio actual mantiene su comportamiento hasta que los active.

Abra su servicio en el panel de Stackhero.
Vaya a la configuración del servicio.
En la sección Modules, seleccione los módulos que desea activar.
Guarde los cambios.

Valkey se reiniciará para cargar los módulos seleccionados. Este proceso suele tardar solo unos segundos.

Si ha almacenado datos utilizando un módulo (como un documento JSON o un filtro Bloom), mantenga ese módulo activado. Valkey no puede leer esos datos sin el módulo que los creó. Si desactiva el módulo, su servicio no podrá reiniciarse correctamente.

Puede comprobar en cualquier momento qué módulos están actualmente cargados:

valkey-cli -u "rediss://default:<yourPassword>@<XXXXXX>.stackhero-network.com:<PORT_TLS>" MODULE LIST

Almacenamiento de documentos JSON

Puede almacenar documentos estructurados de forma nativa como JSON, sin necesidad de serializarlos como cadenas de texto:

JSON.SET product:1 $ '{"name":"Espresso machine","brand":"Bianca","price":459,"stock":12}'

Leer o actualizar un solo campo es rápido, atómico y se gestiona en el servidor:

JSON.GET product:1 $.price
# "[459]"

JSON.NUMINCRBY product:1 $.stock -1
# "[11]"

Este enfoque elimina la necesidad de recuperar y analizar el documento completo en su aplicación para cada actualización. Por ejemplo, decrementar un contador de stock ahora es una única operación atómica. Ya no hay condiciones de carrera ni código adicional.

El conjunto de comandos JSON.* es compatible con la API de RedisJSON, por lo que la mayoría de los clientes de Valkey y Redis funcionan sin cambios.

Indexación y búsqueda

Cree un índice una sola vez y Valkey lo mantendrá actualizado para cada clave que coincida con su prefijo, incluso para claves escritas antes de crear el índice:

FT.CREATE productsIndex
  ON HASH
  PREFIX 1 product:
  SCHEMA
    name TEXT
    brand TAG
    price NUMERIC

Puede consultar sus datos indexados con comandos de búsqueda expresivos:

# Coincidencia exacta de etiqueta
FT.SEARCH productsIndex "@brand:{Bianca}"

# Rango numérico
FT.SEARCH productsIndex "@price:[0 500]"

# Consulta combinada
FT.SEARCH productsIndex "@brand:{Bianca} @price:[0 500]"

# Búsqueda de texto completo por nombre
FT.SEARCH productsIndex "espresso"

También puede realizar agregaciones sobre el mismo índice con FT.AGGREGATE. El comando FT.INFO le permite comprobar el estado del índice, incluyendo el progreso de los trabajos de indexación en segundo plano.

Los documentos JSON también se pueden indexar. Cuando el módulo JSON está activado, puede utilizar ON JSON y expresiones JSONPath en su esquema.

Ejemplo: Uso de la búsqueda de Valkey en Node.js

Como Valkey utiliza el mismo protocolo que Redis, cualquier cliente de Redis es compatible. Puede utilizar este ejemplo con el cliente oficial node-redis:

import { createClient, SCHEMA_FIELD_TYPE } from 'redis';

const client = createClient({ url: process.env.STACKHERO_VALKEY_URL_TLS });
await client.connect();

// Cree el índice una sola vez al iniciar
try {
  await client.ft.create(
    'productsIndex',
    {
      name: SCHEMA_FIELD_TYPE.TEXT,
      brand: SCHEMA_FIELD_TYPE.TAG,
      price: SCHEMA_FIELD_TYPE.NUMERIC
    },
    { ON: 'HASH', PREFIX: 'product:' }
  );
} catch (error) {
  if (!error.message.includes('Index already exists')) {
    throw error;
  }
}

await client.hSet('product:1', { name: 'Espresso machine', brand: 'Bianca', price: '459' });

const results = await client.ft.search('productsIndex', '@brand:{Bianca} @price:[0 500]');
console.log(results.total, results.documents);

await client.quit();

Ejemplo: Uso de la búsqueda de Valkey en Python

Puede utilizar el cliente redis-py para trabajar con las funcionalidades de búsqueda de Valkey:

import os
import redis
from redis.commands.search.field import TextField, TagField, NumericField
from redis.commands.search.index_definition import IndexDefinition, IndexType
from redis.commands.search.query import Query

r = redis.from_url(os.environ['STACKHERO_VALKEY_URL_TLS'], decode_responses=True)

# Cree el índice una sola vez al iniciar
try:
    r.ft('productsIndex').create_index(
        (TextField('name'), TagField('brand'), NumericField('price')),
        definition=IndexDefinition(prefix=['product:'], index_type=IndexType.HASH),
    )
except redis.ResponseError as error:
    if 'Index already exists' not in str(error):
        raise

r.hset('product:1', mapping={'name': 'Espresso machine', 'brand': 'Bianca', 'price': 459})

results = r.ft('productsIndex').search(Query('@brand:{Bianca} @price:[0 500]'))
print(results.total, results.docs)

Información útil

El módulo de búsqueda ofrece un conjunto de comandos enfocado: FT.CREATE, FT.SEARCH, FT.AGGREGATE, FT.INFO, FT.DROPINDEX y FT._LIST. Estos cubren de forma eficiente las consultas por etiquetas, numéricas, de texto y vectoriales. Si su aplicación necesita funciones avanzadas de texto completo (como corrección ortográfica, sinónimos o diccionarios de sugerencias), el motor de consultas de Redis ofrece más posibilidades.
Los índices son por base de datos y funcionan en cada base. Por ejemplo, un índice creado en la base de datos 3 solo es visible y consultable desde la base de datos 3. Esta es una capacidad en la que Valkey va más allá de la selección de base de datos de Redis, que solo permite indexar en la base 0.
Los índices utilizan la memoria de su plan, igual que sus datos. Puede monitorizar used_memory en sus métricas de Prometheus después de crear un índice.
La indexación de claves existentes se realiza en segundo plano. Justo después de ejecutar FT.CREATE, los resultados de búsqueda pueden ser incompletos durante unos segundos mientras se construye el índice.
Todos los comandos de los módulos están habilitados. Cada comando de cada módulo está disponible en su servicio, sin restricciones.

Si desea explorar la búsqueda vectorial, la búsqueda semántica o el retrieval-augmented generation, puede consultar la guía de búsqueda vectorial.