Valkey: Ricerca e JSON

Archivia e interroga documenti JSON con il modulo di ricerca Valkey

👋 Benvenuto nella documentazione di Stackhero!

Stackhero offre una soluzione Valkey cloud pronta all'uso che garantisce numerosi vantaggi, tra cui:

Interfaccia web Valkey Admin inclusa.

Dimensione e trasferimento dei messaggi illimitati.

Aggiornamenti semplici con un solo clic.

Prestazioni ottimali e sicurezza avanzata grazie a un'infrastruttura privata e dedicata.

Risparmia tempo e semplificati la vita: bastano 5 minuti per provare la soluzione Valkey cloud hosting di Stackhero!

La tua istanza Valkey su Stackhero include moduli essenziali mantenuti dal progetto Valkey. Questi moduli rendono Valkey molto più di una semplice cache: puoi archiviare documenti JSON nativi, indicizzare i tuoi dati ed eseguire query per tag, numeriche, testuali e vettoriali, tutto senza dover gestire un database separato.

Sono disponibili tre moduli, tutti inclusi nel tuo piano e con la stessa licenza BSD 3-Clause permissiva di Valkey:

JSON (comandi JSON.*): Archivia e aggiorna documenti JSON strutturati con supporto JSONPath. Puoi leggere o modificare direttamente i singoli campi, senza dover mai riscrivere l'intero documento per piccole modifiche.
Search (comandi FT.*): Esegui indicizzazione secondaria, query per tag, numeriche, full-text e ricerca per similarità vettoriale.
Bloom (comandi BF.*): Utilizza Bloom filter per rispondere in modo efficiente alla domanda "l'ho già visto?" su grandi dataset, utilizzando pochissima memoria.

Abilitazione dei moduli

I moduli sono disabilitati per impostazione predefinita, quindi il tuo servizio mantiene il comportamento attuale finché non li abiliti.

Apri il tuo servizio sulla dashboard Stackhero.
Vai alla configurazione del servizio.
Nella sezione Modules, seleziona i moduli che desideri abilitare.
Salva le modifiche.

Valkey verrà riavviato per caricare i moduli selezionati. Questa operazione richiede solitamente solo pochi secondi.

Se hai archiviato dati utilizzando un modulo (come un documento JSON o un Bloom filter), mantieni quel modulo abilitato. Valkey non può leggere quei dati senza il modulo che li ha creati. Disabilitare il modulo impedirebbe il corretto riavvio del servizio.

Puoi verificare in qualsiasi momento quali moduli sono attualmente caricati:

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

Archiviazione di documenti JSON

Puoi archiviare documenti strutturati nativamente come JSON, senza serializzarli in stringhe:

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

La lettura o l'aggiornamento di un singolo campo è veloce, atomica e gestita lato server:

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

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

Questo approccio elimina la necessità di recuperare e analizzare l'intero documento nella tua applicazione per ogni aggiornamento. Ad esempio, decrementare un contatore di stock diventa un'unica operazione atomica. Niente più condizioni di race o codice aggiuntivo.

Il set di comandi JSON.* corrisponde all'API di RedisJSON, quindi la maggior parte dei client Valkey e Redis funziona senza modifiche.

Indicizzazione e ricerca

Crea un indice una sola volta e Valkey lo mantiene aggiornato per ogni chiave che corrisponde al tuo prefisso, anche per le chiavi scritte prima della creazione dell'indice:

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

Puoi interrogare i dati indicizzati con comandi di ricerca espressivi:

# Corrispondenza esatta del tag
FT.SEARCH productsIndex "@brand:{Bianca}"

# Intervallo numerico
FT.SEARCH productsIndex "@price:[0 500]"

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

# Ricerca full-text per nome
FT.SEARCH productsIndex "espresso"

Puoi anche eseguire aggregazioni sullo stesso indice con FT.AGGREGATE. Il comando FT.INFO ti permette di verificare lo stato dell'indice, inclusa la progressione dei job di indicizzazione in background.

Anche i documenti JSON sono indicizzabili. Quando il modulo JSON è abilitato, puoi usare ON JSON ed espressioni JSONPath nello schema.

Esempio: Utilizzo della ricerca Valkey in Node.js

Poiché Valkey utilizza lo stesso protocollo di Redis, qualsiasi client Redis è compatibile. Puoi utilizzare questo esempio con il client node-redis ufficiale:

import { createClient, SCHEMA_FIELD_TYPE } from 'redis';

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

// Crea l'indice una sola volta all'avvio
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();

Esempio: Utilizzo della ricerca Valkey in Python

Puoi utilizzare il client redis-py per interagire con le funzionalità di ricerca di 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)

# Crea l'indice una sola volta all'avvio
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)

Da sapere

Il modulo di ricerca offre un set di comandi mirato: FT.CREATE, FT.SEARCH, FT.AGGREGATE, FT.INFO, FT.DROPINDEX e FT._LIST. Questi coprono in modo efficiente query per tag, numeriche, testuali e vettoriali. Se la tua applicazione necessita di funzionalità avanzate di full-text search (come correzione ortografica, sinonimi o dizionari di suggerimenti), il motore di query Redis offre maggiori possibilità.
Gli indici sono per database e funzionano in ogni database. Ad esempio, un indice creato nel database 3 è visibile e interrogabile solo dal database 3. Questa è una funzionalità in cui Valkey va oltre la selezione database di Redis, che supporta l'indicizzazione solo sul database 0.
Gli indici utilizzano la memoria del tuo piano, proprio come i tuoi dati. Puoi monitorare used_memory nelle tue metriche Prometheus dopo aver costruito un indice.
L'indicizzazione delle chiavi esistenti avviene in background. Subito dopo aver eseguito FT.CREATE, i risultati di ricerca potrebbero essere incompleti per alcuni secondi mentre l'indice viene costruito.
Tutti i comandi dei moduli sono abilitati. Ogni comando di ogni modulo è disponibile sul tuo servizio, senza alcuna restrizione.

Se vuoi esplorare la ricerca vettoriale, la semantic search o il retrieval-augmented generation, puoi consultare la guida alla ricerca vettoriale.