Valkey: Wyszukiwanie i JSON

Przechowywanie i zapytania do dokumentów JSON z modułem wyszukiwania Valkey

👋 Witamy w dokumentacji Stackhero!

Stackhero oferuje gotowe do użycia rozwiązanie Valkey cloud, które zapewnia szereg korzyści, w tym:

Wbudowany web UI Valkey Admin.

Nieograniczony rozmiar i transfer wiadomości.

Bezproblemowe aktualizacje jednym kliknięciem.

Optymalna wydajność i wysoki poziom bezpieczeństwa dzięki prywatnej, dedykowanej infrastrukturze.

Oszczędzaj czas i uprość sobie życie: wystarczy 5 minut, aby przetestować rozwiązanie Valkey cloud hosting od Stackhero!

Twoja instancja Valkey na Stackhero zawiera podstawowe moduły utrzymywane przez projekt Valkey. Dzięki nim Valkey to znacznie więcej niż tylko cache: możesz natywnie przechowywać dokumenty JSON, indeksować dane oraz wykonywać zapytania tagowe, numeryczne, tekstowe i wektorowe — wszystko bez konieczności zarządzania osobną bazą danych.

Dostępne są trzy moduły, każdy wliczony w Twój plan i objęty tą samą liberalną licencją BSD 3-Clause co Valkey:

JSON (polecenia JSON.*): Przechowuj i aktualizuj strukturalne dokumenty JSON z obsługą JSONPath. Możesz odczytywać lub modyfikować pojedyncze pola bez konieczności przepisywania całego dokumentu przy drobnych zmianach.
Search (polecenia FT.*): Wykonuj indeksowanie wtórne, zapytania tagowe, numeryczne, pełnotekstowe oraz wyszukiwanie podobieństwa wektorowego.
Bloom (polecenia BF.*): Używaj filtrów Bloom do efektywnego odpowiadania na pytanie „czy już to widziałem?” na dużych zbiorach danych, przy minimalnym zużyciu pamięci.

Włączanie modułów

Moduły są domyślnie wyłączone, więc Twój obecny serwis zachowuje dotychczasowe działanie, dopóki ich nie aktywujesz.

Otwórz swój serwis na panelu Stackhero.
Przejdź do konfiguracji serwisu.
W sekcji Modules wybierz moduły, które chcesz włączyć.
Zapisz zmiany.

Valkey zostanie zrestartowany, aby załadować wybrane moduły. Zwykle trwa to tylko kilka sekund.

Jeśli przechowujesz dane przy użyciu modułu (np. dokument JSON lub filtr Bloom), pozostaw ten moduł włączony. Valkey nie jest w stanie odczytać tych danych bez modułu, który je utworzył. Wyłączenie modułu uniemożliwi poprawne ponowne uruchomienie serwisu.

W każdej chwili możesz sprawdzić, które moduły są aktualnie załadowane:

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

Przechowywanie dokumentów JSON

Możesz natywnie przechowywać strukturalne dokumenty jako JSON, bez potrzeby serializacji do ciągów znaków:

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

Odczyt lub aktualizacja pojedynczego pola jest szybka, atomowa i realizowana po stronie serwera:

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

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

Takie podejście eliminuje konieczność pobierania i parsowania całego dokumentu w aplikacji przy każdej aktualizacji. Na przykład dekrementacja licznika stanu magazynowego to teraz pojedyncza, atomowa operacja — bez warunków wyścigu i dodatkowego kodu.

Zestaw poleceń JSON.* jest zgodny z API RedisJSON, więc większość klientów Valkey i Redis działa bez zmian.

Indeksowanie i wyszukiwanie

Utwórz indeks raz, a Valkey będzie go utrzymywać na bieżąco dla każdego klucza z Twoim prefiksem, nawet dla kluczy zapisanych przed utworzeniem indeksu:

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

Możesz wykonywać zapytania do zindeksowanych danych za pomocą rozbudowanych poleceń wyszukiwania:

# Dokładne dopasowanie tagu
FT.SEARCH productsIndex "@brand:{Bianca}"

# Zakres numeryczny
FT.SEARCH productsIndex "@price:[0 500]"

# Zapytanie złożone
FT.SEARCH productsIndex "@brand:{Bianca} @price:[0 500]"

# Wyszukiwanie pełnotekstowe po nazwie
FT.SEARCH productsIndex "espresso"

Możesz także wykonywać agregacje na tym samym indeksie za pomocą FT.AGGREGATE. Polecenie FT.INFO pozwala sprawdzić status indeksu, w tym postęp zadań indeksowania w tle.

Dokumenty JSON również mogą być indeksowane. Po włączeniu modułu JSON możesz używać ON JSON oraz wyrażeń JSONPath w schemacie.

Przykład: Wyszukiwanie Valkey w Node.js

Ponieważ Valkey używa tego samego protokołu co Redis, każdy klient Redis jest kompatybilny. Możesz użyć poniższego przykładu z oficjalnym klientem node-redis:

import { createClient, SCHEMA_FIELD_TYPE } from 'redis';

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

// Utwórz indeks raz przy starcie aplikacji
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();

Przykład: Wyszukiwanie Valkey w Pythonie

Możesz użyć klienta redis-py, aby korzystać z funkcji wyszukiwania 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)

# Utwórz indeks raz przy starcie aplikacji
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)

Warto wiedzieć

Moduł wyszukiwania oferuje wyselekcjonowany zestaw poleceń: FT.CREATE, FT.SEARCH, FT.AGGREGATE, FT.INFO, FT.DROPINDEX oraz FT._LIST. Obejmują one efektywne zapytania tagowe, numeryczne, tekstowe i wektorowe. Jeśli Twoja aplikacja wymaga zaawansowanych funkcji pełnotekstowych (np. sprawdzania pisowni, synonimów czy słowników podpowiedzi), silnik zapytań Redis oferuje szersze możliwości.
Indeksy są przypisane do konkretnej bazy danych i działają w jej obrębie. Na przykład indeks utworzony w bazie 3 jest widoczny i dostępny tylko z tej bazy. To funkcjonalność, w której Valkey wykracza poza wybór bazy Redis, który obsługuje indeksowanie tylko na bazie 0.
Indeksy wykorzystują pamięć Twojego planu, tak samo jak dane. Możesz monitorować used_memory w swoich metrykach Prometheus po utworzeniu indeksu.
Indeksowanie istniejących kluczy odbywa się w tle. Bezpośrednio po uruchomieniu FT.CREATE wyniki wyszukiwania mogą być niepełne przez kilka sekund, dopóki indeks nie zostanie zbudowany.
Wszystkie polecenia modułów są dostępne. Każde polecenie z każdego modułu jest dostępne w Twoim serwisie, bez żadnych ograniczeń.

Jeśli chcesz zgłębić wyszukiwanie wektorowe, wyszukiwanie semantyczne lub retrieval-augmented generation, zapoznaj się z przewodnikiem po wyszukiwaniu wektorowym.