Valkey: Pesquisa e JSON

Armazene e consulte documentos JSON com o módulo de pesquisa Valkey

👋 Bem-vindo à documentação da Stackhero!

A Stackhero disponibiliza uma solução Valkey cloud pronta a usar, que oferece várias vantagens, incluindo:

Interface web Valkey Admin incluída.

Tamanho e transferências de mensagens ilimitados.

Atualizações fáceis com apenas um clique.

Performance otimizada e segurança reforçada graças a uma infraestrutura privada e dedicada.

Poupe tempo e simplifique a sua vida: bastam 5 minutos para experimentar a solução de Valkey cloud hosting da Stackhero!

A sua instância Valkey na Stackhero inclui módulos essenciais mantidos pelo projeto Valkey. Estes módulos tornam o Valkey muito mais do que uma cache: pode armazenar documentos JSON nativos, indexar os seus dados e executar pesquisas por tag, numéricas, de texto e vetoriais, tudo isto sem precisar de gerir uma base de dados separada.

Estão disponíveis três módulos, todos incluídos no seu plano e licenciados sob a mesma licença permissiva BSD 3-Clause que o Valkey:

JSON (comandos JSON.*): Armazene e atualize documentos JSON estruturados com suporte para JSONPath. Pode ler ou modificar campos individuais diretamente, sem necessidade de reescrever o documento completo para pequenas alterações.
Search (comandos FT.*): Execute indexação secundária, pesquisas por tag, numéricas, de texto integral e pesquisa por similaridade vetorial.
Bloom (comandos BF.*): Utilize filtros Bloom para responder de forma eficiente à pergunta "já vi isto antes?" em grandes volumes de dados, utilizando memória mínima.

Ativação dos módulos

Os módulos estão desativados por predefinição, por isso o seu serviço mantém o comportamento atual até que os ative.

Abra o seu serviço no dashboard da Stackhero.
Aceda à configuração do serviço.
Na secção Modules, selecione os módulos que pretende ativar.
Guarde as alterações.

O Valkey reinicia para carregar os módulos selecionados. Este processo normalmente demora apenas alguns segundos.

Se armazenou dados utilizando um módulo (como um documento JSON ou um filtro Bloom), mantenha esse módulo ativado. O Valkey não consegue ler esses dados sem o módulo que os criou. Desativar o módulo impedirá o serviço de reiniciar corretamente.

Pode verificar a qualquer momento quais os módulos atualmente carregados:

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

Armazenamento de documentos JSON

Pode armazenar documentos estruturados nativamente em formato JSON, sem necessidade de os serializar para strings:

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

Ler ou atualizar um campo individual é rápido, atómico e tratado do lado do servidor:

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

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

Esta abordagem elimina a necessidade de obter e analisar o documento completo na sua aplicação para cada atualização. Por exemplo, decrementar um contador de stock passa a ser uma operação atómica única. Não há mais condições de corrida nem código adicional.

O conjunto de comandos JSON.* corresponde à API do RedisJSON, pelo que a maioria dos clientes Valkey e Redis funcionam sem alterações.

Indexação e pesquisa

Crie um índice uma vez e o Valkey mantém-no atualizado para todas as chaves que correspondam ao seu prefixo, mesmo para chaves criadas antes do índice:

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

Pode consultar os seus dados indexados com comandos de pesquisa expressivos:

# Correspondência exata de tag
FT.SEARCH productsIndex "@brand:{Bianca}"

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

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

# Pesquisa de texto integral pelo nome
FT.SEARCH productsIndex "espresso"

Também pode executar agregações sobre o mesmo índice com FT.AGGREGATE. O comando FT.INFO permite-lhe verificar o estado do índice, incluindo o progresso das tarefas de indexação em segundo plano.

Os documentos JSON também podem ser indexados. Quando o módulo JSON está ativado, pode utilizar ON JSON e expressões JSONPath no seu esquema.

Exemplo: Utilizar a pesquisa Valkey em Node.js

Como o Valkey utiliza o mesmo protocolo que o Redis, qualquer cliente Redis é compatível. Pode usar este exemplo com o cliente oficial node-redis:

import { createClient, SCHEMA_FIELD_TYPE } from 'redis';

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

// Criar o índice uma vez no arranque
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();

Exemplo: Utilizar a pesquisa Valkey em Python

Pode utilizar o cliente redis-py para interagir com as funcionalidades de pesquisa do 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)

# Criar o índice uma vez no arranque
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)

Informações úteis

O módulo de pesquisa oferece um conjunto de comandos focado: FT.CREATE, FT.SEARCH, FT.AGGREGATE, FT.INFO, FT.DROPINDEX e FT._LIST. Estes comandos cobrem de forma eficiente pesquisas por tag, numéricas, de texto e vetoriais. Se a sua aplicação necessitar de funcionalidades avançadas de texto integral (como verificação ortográfica, sinónimos ou sugestões), o motor de pesquisa Redis oferece mais opções.
Os índices são por base de dados e funcionam em cada base de dados. Por exemplo, um índice criado na base de dados 3 só é visível e pesquisável a partir da base de dados 3. Esta é uma capacidade em que o Valkey vai além da seleção de base de dados do Redis, que apenas suporta indexação na base de dados 0.
Os índices utilizam a memória do seu plano, tal como os seus dados. Pode monitorizar o used_memory nas suas métricas Prometheus após criar um índice.
A indexação de chaves existentes é feita em segundo plano. Imediatamente após executar FT.CREATE, os resultados de pesquisa podem estar incompletos durante alguns segundos enquanto o índice está a ser construído.
Todos os comandos dos módulos estão ativados. Todos os comandos de todos os módulos estão disponíveis no seu serviço, sem restrições.

Se pretende explorar pesquisa vetorial, pesquisa semântica ou retrieval-augmented generation, consulte o guia de pesquisa vetorial.