Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Guida introduttiva alla ricerca vettoriale Amazon ElastiCache for Valkey supporta la ricerca vettoriale, che consente di archiviare, cercare e aggiornare miliardi di incorporamenti vettoriali ad alta dimensione in memoria con latenze di appena microsecondi e richiami superiori al 99%. ElastiCache for Valkey offre funzionalità per indicizzare, cercare e aggiornare miliardi di incorporamenti vettoriali ad alta dimensione di provider famosi come Amazon Bedrock, Amazon, SageMaker Anthropic o OpenAI per una ricerca e un recupero rapidi. La ricerca vettoriale per Amazon ElastiCache è ideale per i casi d'uso in cui le massime prestazioni e la scalabilità sono i criteri di selezione più importanti. Ciò include la memorizzazione nella cache semantica, la generazione aumentata di recupero, i consigli in tempo reale, la personalizzazione e il rilevamento delle anomalie. La ricerca vettoriale può essere utilizzata insieme ad altre funzionalità per migliorare le applicazioni. ElastiCache ElastiCache [La ricerca vettoriale di è disponibile nella versione 8.2 di Valkey su cluster basati su nodi in tutte le regioni senza costi aggiuntivi.AWS](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/) Per iniziare, crea un nuovo cluster Valkey 8.2 utilizzando, SDK o. [Console di gestione AWS](https://console.aws.amazon.com/elasticache/)AWSAWS CLI[Puoi anche utilizzare la ricerca vettoriale sul tuo cluster esistente eseguendo l'aggiornamento da qualsiasi versione precedente di Valkey o Redis OSS a Valkey 8.2 con pochi clic e senza tempi di inattività.](VersionManagement.HowTo.md) # Panoramica della ricerca vettoriale ElastiCache for Valkey offre funzionalità per indicizzare, cercare e aggiornare miliardi di incorporamenti vettoriali ad alta dimensione. La ricerca vettoriale consente di creare, gestire e utilizzare indici secondari per una ricerca efficiente e scalabile. Ogni operazione di ricerca vettoriale si applica a un singolo indice. Le operazioni sull'indice si applicano solo all'indice specificato. È possibile eseguire un numero qualsiasi di operazioni su qualsiasi indice in qualsiasi momento, ad eccezione delle operazioni di creazione ed eliminazione dell'indice. A livello di cluster, possono essere in corso più operazioni su più indici contemporaneamente. All'interno di questo documento i termini chiave, riga e record sono identici e utilizzati in modo intercambiabile. Allo stesso modo, anche i termini colonna, campo, percorso e membro vengono usati in modo intercambiabile. Il `FT.CREATE` comando può essere utilizzato per creare un indice per un sottoinsieme di chiavi con i tipi di indice specificati. `FT.SEARCH`esegue interrogazioni sugli indici creati e `FT.DROPINDEX` rimuove un indice esistente e tutti i dati associati. Non esistono comandi speciali per aggiungere, eliminare o modificare i dati indicizzati. I `JSON` comandi esistenti `HASH` o che modificano una chiave presente in un indice aggiornano automaticamente l'indice. **Topics** + [Indici e keyspace Valkey OSS](#indexes-keyspace) + [Tipi di campi indice](#index-field-types) + [Algoritmi di indice vettoriale](#vector-index-algorithms) + [Sicurezza della ricerca vettoriale](#vector-search-security) ## Indici e keyspace Valkey OSS Gli indici sono costruiti e gestiti su un sottoinsieme dello spazio delle chiavi Valkey OSS. Lo spazio chiave per ogni indice è definito da un elenco di prefissi chiave forniti al momento della creazione dell'indice. L'elenco dei prefissi è facoltativo e, se omesso, l'intero spazio delle chiavi farà parte di quell'indice. Più indici possono scegliere sottoinsiemi disgiunti o sovrapposti dello spazio chiave senza limitazioni. Gli indici vengono inoltre digitati in quanto coprono solo le chiavi di tipo corrispondente. Attualmente, gli indici sono supportati solo sui tipi e. `JSON` `HASH` Un `HASH` indice indicizza solo le `HASH` chiavi incluse nel suo elenco di prefissi e analogamente un `JSON` indice indicizza solo le `JSON` chiavi che sono incluse nel suo elenco di prefissi. Le chiavi all'interno dell'elenco dei prefissi dello spazio dei tasti di un indice che non hanno il tipo designato vengono ignorate e non influiscono sulle operazioni di ricerca. Un indice viene aggiornato quando un comando modifica una chiave che si trova all'interno dello spazio chiave dell'indice. Valkey estrae automaticamente i campi dichiarati per ogni indice e aggiorna l'indice con il nuovo valore. Il processo di aggiornamento prevede tre fasi. Nella prima fase, la chiave HASH o JSON viene modificata e il client richiedente viene bloccato. Il secondo passaggio viene eseguito in background e aggiorna ciascuno degli indici che contengono la chiave modificata. Nella terza fase, il client viene sbloccato. Pertanto, per le operazioni di interrogazione eseguite sulla stessa connessione di una mutazione, tale modifica è immediatamente visibile nei risultati della ricerca. La creazione di un indice è un processo in più fasi. Il primo passo consiste nell'eseguire il comando FT.CREATE che definisce l'indice. L'esecuzione corretta di una creazione avvia automaticamente il secondo passaggio: il backfilling. Il processo di riempimento viene eseguito in un thread in background e analizza lo spazio chiave alla ricerca di chiavi che si trovano all'interno dell'elenco di prefissi del nuovo indice. Ogni chiave trovata viene aggiunta all'indice. Alla fine viene scansionato l'intero keyspace, completando il processo di creazione dell'indice. Nota che mentre il processo di riempimento dell'indice è in esecuzione, le mutazioni delle chiavi indicizzate sono consentite, non ci sono restrizioni e il processo di riempimento dell'indice non verrà completato finché tutte le chiavi non saranno indicizzate correttamente. Le operazioni di interrogazione tentate mentre un indice è in fase di riempimento non sono consentite e vengono terminate con un errore. Il comando FT.INFO restituisce lo stato del processo di backfill nel campo 'backfill\$1status'. ## Tipi di campi indice Ogni indice ha un tipo specifico che viene dichiarato al momento della creazione dell'indice insieme alla posizione di un campo (colonna) da indicizzare. Per `HASH` le chiavi, la posizione è il nome del campo all'interno di. `HASH` Per `JSON` le chiavi, la posizione è una descrizione del percorso JSON. Quando una chiave viene modificata, i dati associati ai campi dichiarati vengono estratti, convertiti nel tipo dichiarato e memorizzati nell'indice. Se i dati mancano o non possono essere convertiti correttamente nel tipo dichiarato, quel campo viene omesso dall'indice. Esistono tre tipi di campi, come spiegato di seguito: + **I campi vettoriali** contengono un vettore di numeri noto anche come incorporamento vettoriale. I campi vettoriali possono essere utilizzati per filtrare i vettori in base a metriche di distanza specifiche che misurano la somiglianza. Per gli `HASH` indici, il campo deve contenere l'intero vettore codificato in formato binario (Little-endian IEEE 754). Per `JSON` le chiavi, il percorso deve fare riferimento a un array della dimensione corretta pieno di numeri. Nota che quando un array JSON viene utilizzato come campo vettoriale, la rappresentazione interna dell'array all'interno della chiave JSON viene convertita nel formato richiesto dall'algoritmo selezionato, riducendo il consumo di memoria e la precisione. Le successive operazioni di lettura che utilizzano i comandi JSON produrranno un valore di precisione ridotto. + **I campi numerici** contengono un solo numero. I campi numerici possono essere utilizzati con l'operatore di ricerca per intervalli. Infatti`HASH`, si prevede che il campo contenga il testo ASCII di un numero scritto nel formato standard di numeri a virgola fissa o mobile. Per `JSON` i campi, è necessario seguire le regole numeriche dei numeri JSON. Indipendentemente dalla rappresentazione all'interno della chiave, questo campo viene convertito in un numero a virgola mobile a 64 bit per la memorizzazione all'interno dell'indice. Poiché i numeri sottostanti sono memorizzati in virgola mobile con i relativi limiti di precisione, si applicano le consuete regole sui confronti numerici per i numeri in virgola mobile. + **I campi tag** contengono zero o più valori di tag codificati come una singola stringa UTF-8. I campi tag possono essere utilizzati per filtrare le query in base all'equivalenza dei valori dei tag con un confronto con o senza distinzione tra maiuscole e minuscole. La stringa viene analizzata in valori di tag utilizzando un carattere separatore (l'impostazione predefinita è una virgola ma può essere sovrascritta) con gli spazi bianchi iniziali e finali rimossi. Qualsiasi numero di valori di tag può essere contenuto in un singolo campo di tag. ## Algoritmi di indice vettoriale In Valkey sono supportati due algoritmi di indice vettoriale: + **Flat** — L'algoritmo Flat è un'elaborazione lineare a forza bruta di ogni vettore dell'indice, che fornisce risposte esatte entro i limiti della precisione dei calcoli della distanza. Grazie all'elaborazione lineare dell'indice, i tempi di esecuzione di questo algoritmo possono essere molto elevati per indici di grandi dimensioni. Gli indici piatti supportano velocità di ingestione più elevate. + **Hierarchical Navigable Small Worlds (HNSW): l'algoritmo HNSW** è un'alternativa che fornisce corrispondenze vettoriali approssimative più vicine in cambio di tempi di esecuzione sostanzialmente inferiori. L'algoritmo è controllato da tre parametri e. `M` `EF_CONSTRUCTION` `EF_RUNTIME` I primi due parametri vengono specificati al momento della creazione dell'indice e non possono essere modificati. Il `EF_RUNTIME` parametro ha un valore predefinito che viene specificato al momento della creazione dell'indice, ma può essere sovrascritto in ogni singola operazione di interrogazione in seguito. Questi tre parametri interagiscono per bilanciare il consumo di memoria e CPU durante le operazioni di inserimento e interrogazione, nonché per controllare la qualità dell'approssimazione di una ricerca KNN esatta (nota come rapporto di richiamo). In HNSW, il parametro M controlla il numero massimo di vicini a cui ogni nodo può connettersi, determinando la densità dell'indice. Un valore M più alto, ad esempio 32 e superiore, produce un grafo più connesso, migliorando la velocità di richiamo e di interrogazione perché esistono più percorsi per raggiungere i vicini pertinenti. Tuttavia, aumenta la dimensione dell'indice, l'uso della memoria e rallenta l'indicizzazione. Un valore M inferiore, ad esempio 8 e inferiore, produce un faster-to-build indice più piccolo con un minore utilizzo della memoria, ma il richiamo diminuisce e le query possono richiedere più tempo a causa del minor numero di connessioni. Il parametro EF\$1Construction determina quante connessioni candidate vengono valutate durante la creazione dell'indice. Un EF\$1Construction più elevato, ad esempio 400 e versioni successive, significa che l'indicizzatore considera più percorsi prima di selezionare i vicini, ottenendo un grafico che migliora l'efficienza del richiamo e delle query in un secondo momento, ma a scapito di una indicizzazione più lenta e di un maggiore utilizzo di CPU e memoria durante la costruzione. Un valore EF\$1Construction basso, ad esempio 64-120, accelera l'indicizzazione e riduce l'uso delle risorse, ma il grafico risultante può ridurre il richiamo e rallentare le query anche se EF\$1Runtime è impostato su un valore elevato. Infine, EF\$1Runtime regola l'ampiezza della ricerca durante l'interrogazione, controllando quanti candidati adiacenti vengono esplorati in fase di esecuzione. Impostarlo su un valore elevato aumenta il richiamo e la precisione, ma a scapito della latenza delle query e dell'uso della CPU. Un EF\$1Runtime basso rende le query più veloci e leggere, ma con un richiamo ridotto. A differenza di M o EF\$1Construction, questo parametro non influisce sulla dimensione dell'indice o sul tempo di compilazione, quindi è il parametro che consente di regolare i compromessi tra richiamo e latenza dopo la creazione di un indice. Entrambi gli algoritmi di ricerca vettoriale (Flat e HNSW) supportano un parametro opzionale. `INITIAL_CAP` Quando specificato, questo parametro prealloca la memoria per gli indici, con conseguente riduzione del sovraccarico di gestione della memoria e aumento delle velocità di ingestione vettoriale. Gli indici flat supportano velocità di ingestione migliori rispetto a HNSW. Gli algoritmi di ricerca vettoriale come HNSW potrebbero non gestire in modo efficiente l'eliminazione o la sovrascrittura dei vettori precedentemente inseriti. L'uso di queste operazioni può comportare un consumo eccessivo di memoria indicizzata, un deterioramento della qualità di richiamo. and/or La reindicizzazione è un metodo per ripristinare il recupero ottimale dell'utilizzo della memoria. and/or ## Sicurezza della ricerca vettoriale I meccanismi di sicurezza [Valkey ACL (Access Control Lists)](https://valkey.io/topics/acl/) per l'accesso ai comandi e ai dati sono estesi per controllare la funzione di ricerca. Il controllo ACL dei singoli comandi di ricerca è completamente supportato. Viene fornita una nuova categoria ACL e molte delle categorie esistenti (`@fast`, `@read``@write`, ecc.) vengono aggiornate per includere i nuovi comandi. `@search` I comandi di ricerca non modificano i dati chiave, il che significa che il meccanismo ACL esistente per l'accesso in scrittura viene preservato. Le regole di accesso `HASH` e le `JSON` operazioni non vengono modificate dalla presenza di un indice; il normale controllo dell'accesso a livello di chiave viene ancora applicato a tali comandi. L'accesso ai comandi di ricerca con un indice è inoltre controllato tramite ACL. I controlli di accesso vengono eseguiti a livello dell'intero indice, non a livello di chiave. Ciò significa che l'accesso a un indice viene concesso a un utente solo se tale utente è autorizzato ad accedere a tutte le chiavi possibili all'interno dell'elenco dei prefissi dello spazio chiave di quell'indice. In altre parole, il contenuto effettivo di un indice non controlla l'accesso. Piuttosto, sono i contenuti teorici di un indice, come definito dall'elenco dei prefissi, che viene utilizzato per il controllo di sicurezza. Sono possibili situazioni in cui un utente ha accesso in lettura e and/or scrittura a una chiave ma non è in grado di accedere a un indice contenente quella chiave. Tieni presente che per creare o utilizzare un indice è necessario solo l'accesso in lettura allo spazio delle chiavi: la presenza o l'assenza di accesso in scrittura non viene considerata # Caratteristiche e limiti della ricerca vettoriale ## Disponibilità della ricerca vettoriale La ricerca vettoriale per Amazon ElastiCache è disponibile con Valkey versione 8.2 su cluster basati su nodi in tutte le AWS regioni senza costi aggiuntivi. [Puoi anche utilizzare la ricerca vettoriale sui cluster esistenti eseguendo l'aggiornamento da qualsiasi versione di Valkey o Redis OSS a Valkey 8.2, in pochi clic e senza tempi di inattività.](VersionManagement.HowTo.md) La ricerca vettoriale è attualmente disponibile su tutti i tipi di istanze diversi dai nodi con suddivisione in più livelli dei dati. ElastiCache L'utilizzo della ricerca vettoriale su istanze t2, t3 e t4g richiede l'aumento della riserva di memoria ad almeno il 50% per le istanze micro e al 30% per le istanze di piccole dimensioni. Consulta [questa](redis-memory-management.md) pagina per saperne di più. ## Restrizioni parametriche La tabella seguente mostra i limiti per vari elementi di ricerca vettoriale: **Limiti di ricerca vettoriale** | Elemento | Valore massimo | | --- | --- | | Numero di dimensioni in un vettore | 32768 | | Numero di indici che possono essere creati | 10 | | Numero di campi in un indice | 50 | | Clausola FT.SEARCH TIMEOUT (millisecondi) | 60000 | | Numero massimo di prefissi consentiti per indice | 16 | | Lunghezza massima di un campo di tag | 10000 | | Lunghezza massima di un campo numerico | 256 | | Parametro HNSW M | 2000000 | | Parametro HNSW EF\$1CONSTRUCTION | 4096 | | Parametro HNSW EF\$1RUNTIME | 4096 | ## Restrizioni operative ### Persistenza e riempimento dell'indice Il processo di aggiornamento prevede tre fasi. Nella prima fase, la chiave HASH o JSON viene modificata e il client richiedente viene bloccato. Il secondo passaggio viene eseguito in background e aggiorna ciascuno degli indici che contengono la chiave modificata. Nella terza fase, il client viene sbloccato. Pertanto, per le operazioni di interrogazione eseguite sulla stessa connessione di una mutazione, tale modifica è immediatamente visibile nei risultati della ricerca. Tuttavia, l'inserimento o l'aggiornamento di una chiave potrebbe non essere visibile nei risultati di ricerca di altri client per un breve periodo di tempo. Durante i periodi di intenso carico di sistema ( and/or forte mutazione dei dati), il ritardo di visibilità può aumentare. La funzione di ricerca vettoriale mantiene la definizione degli indici e il contenuto degli indici. Gli indici per i campi vettoriali vengono salvati ma gli indici per TAGS e NUMERIC non vengono salvati, il che significa che devono essere ricostruiti quando vengono caricati esternamente (sincronizzazione completa o ricarica). Ciò significa che durante qualsiasi richiesta o evento operativo che causa l'avvio o il riavvio di un nodo, la definizione dell'indice e il contenuto dei vettori vengono ripristinati dall'istantanea più recente. Non è richiesta alcuna azione da parte dell'utente per avviare questa operazione. Tuttavia, per gli indici TAGS e NUMERIC, la ricostruzione viene eseguita come operazione di riempimento non appena i dati vengono ripristinati. Dal punto di vista funzionale, ciò equivale all'esecuzione automatica da parte del sistema di un comando FT.CREATE per ogni indice definito. Si noti che il nodo diventa disponibile per le operazioni dell'applicazione non appena i dati vengono ripristinati, ma probabilmente prima del completamento del riempimento dell'indice, il che significa che le operazioni di riempimento saranno nuovamente visibili alle applicazioni. Il completamento del riempimento dell'indice non è sincronizzato tra un primario e una replica. Questa mancanza di sincronizzazione può diventare inaspettatamente visibile alle applicazioni, pertanto è consigliabile che le applicazioni verifichino il completamento del backfill sulle repliche primarie e su tutte le repliche prima di iniziare le operazioni di ricerca. ### Limiti di scalabilità Durante gli eventi di scalabilità, l'indice può essere sottoposto a riempimento man mano che i dati vengono migrati. Ciò comporterà una riduzione del richiamo per le query di ricerca. ### Istantanea import/export e migrazione in tempo reale I file RDB di un cluster con indici di ricerca possono essere importati in un altro cluster ElastiCache Valkey con versione 8.2 o successiva. Il nuovo cluster ricostruirà il contenuto dell'indice durante il caricamento del file RDB. Tuttavia, la presenza di indici di ricerca in un file RDB limita la compatibilità di tali dati con le versioni precedenti di Valkey. Il formato degli indici di ricerca definiti dalla funzionalità di ricerca vettoriale è compreso solo da un altro ElastiCache cluster con Valkey versione 8.2 o successiva. Tuttavia, i file RDB che non contengono indici non sono soggetti a restrizioni in questo modo. ### Memoria insufficiente durante il riempimento Analogamente alle operazioni di scrittura di Valkey OSS, un riempimento dell'indice è soggetto a limitazioni. out-of-memory Se la memoria del motore è piena mentre è in corso un riempimento, tutti i backfill vengono messi in pausa. Se la memoria diventa disponibile, il processo di riempimento viene ripreso. È possibile eliminare un indice quando il riempimento è in pausa a causa dell'esaurimento della memoria. ### Transazioni I comandi`FT.CREATE`,, `FT.DROPINDEX` `FT.ALIASADD``FT.ALIASDEL`, e `FT.ALIASUPDATE` non possono essere eseguiti in un contesto transazionale, cioè non all'interno di un `MULTI/EXEC` blocco o all'interno di uno script LUA o FUNCTION. # Scelta della configurazione appropriata Nell'esperienza della console, ElastiCache offre un modo semplice per scegliere il tipo di istanza giusto in base ai requisiti di memoria e CPU del carico di lavoro vettoriale. ## Consumo di memoria Il consumo di memoria si basa sul numero di vettori, sul numero di dimensioni, sul valore M e sulla quantità di dati non vettoriali, come i metadati associati al vettore o altri dati memorizzati all'interno dell'istanza. La memoria totale richiesta è una combinazione dello spazio necessario per i dati vettoriali effettivi e dello spazio richiesto per gli indici vettoriali. Lo spazio richiesto per i dati vettoriali viene calcolato misurando la capacità effettiva richiesta per archiviare i vettori all'interno `HASH` delle nostre strutture di `JSON` dati e il sovraccarico nelle lastre di memoria più vicine, per allocazioni di memoria ottimali. Ciascuno degli indici vettoriali utilizza riferimenti ai dati vettoriali memorizzati in queste strutture di dati, nonché una copia aggiuntiva del vettore nell'indice. Si consiglia di pianificare questo consumo di spazio aggiuntivo da parte dell'indice. Il numero di vettori dipende da come decidi di rappresentare i dati come vettori. Ad esempio, puoi scegliere di rappresentare un singolo documento in più blocchi, in cui ogni blocco rappresenta un vettore. In alternativa, puoi scegliere di rappresentare l'intero documento come un unico vettore. Il numero di dimensioni dei vettori dipende dal modello di incorporamento scelto. Ad esempio, se scegli di utilizzare il modello di incorporamento AWS Titan, il numero di dimensioni sarebbe 1536. Tieni presente che dovresti testare il tipo di istanza per assicurarti che soddisfi i tuoi requisiti. ## Ridimensionamento del carico di lavoro La ricerca vettoriale supporta tutti e tre i metodi di ridimensionamento: orizzontale, verticale e repliche. Quando si ridimensiona in base alla capacità, la ricerca vettoriale si comporta proprio come un normale Valkey, ovvero aumentando la memoria dei singoli nodi (ridimensionamento verticale) o aumentando il numero di nodi (ridimensionamento orizzontale) si aumenterà la capacità complessiva. In modalità cluster, il `FT.CREATE` comando può essere inviato a qualsiasi nodo primario del cluster e il sistema distribuirà automaticamente la nuova definizione dell'indice a tutti i membri del cluster. Tuttavia, dal punto di vista delle prestazioni, la ricerca vettoriale si comporta in modo molto diverso dal normale Valkey. L'implementazione multithread della ricerca vettoriale significa un CPUs rendimento aggiuntivo fino ad aumenti lineari del throughput di query e ingestione. Il ridimensionamento orizzontale produce aumenti lineari della velocità di inserimento, ma può ridurre la velocità di trasmissione delle query. Se è richiesta una velocità di trasmissione delle query aggiuntiva, è necessaria la scalabilità tramite repliche o una maggiore velocità di trasmissione. CPUs # Comandi di ricerca vettoriale Di seguito è riportato un elenco di comandi supportati per la ricerca vettoriale. **Topics** + [FT.CREATE](vector-search-commands-ft.create.md) + [FT.SEARCH](vector-search-commands-ft.search.md) + [INDICE FT.DROP](vector-search-commands-ft.dropindex.md) + [FT.INFO](vector-search-commands-ft.info.md) + [PIEDI. \$1LISTA](vector-search-commands-ft.list.md) # FT.CREATE Il `FT.CREATE` comando crea un indice vuoto e avvia il processo di riempimento. Ogni indice è composto da una serie di definizioni di campo. Ogni definizione di campo specifica un nome di campo, un tipo di campo e un percorso all'interno di ciascuna chiave indicizzata per individuare un valore del tipo dichiarato. Alcune definizioni dei tipi di campo hanno identificatori di sottotipo aggiuntivi. Per gli indici sulle chiavi HASH, il percorso è lo stesso del nome del membro hash. La `AS` clausola opzionale può essere utilizzata per rinominare il campo, se lo si desidera. La ridenominazione dei campi è particolarmente utile quando il nome del membro contiene caratteri speciali. Per gli indici su chiavi JSON, il percorso è un percorso JSON per i dati del tipo dichiarato. Poiché il percorso JSON contiene sempre caratteri speciali, la clausola è obbligatoria. `AS` **Sintassi** ``` FT.CREATE ON HASH | JSON [PREFIX [...]] SCHEMA ( [AS ] | VECTOR [HNSW|FLAT] [ ]) | TAG [SEPARATOR ] [CASESENSITIVE] | NUMERIC )+ ``` **(obbligatorio):** Questo è il nome che dai al tuo indice. Se esiste già un indice con lo stesso nome, viene restituito un errore. **ON HASH \$1 JSON (opzionale):** in questo indice sono incluse solo le chiavi che corrispondono al tipo specificato. Se omesso, viene utilizzato HASH. **PREFIX (opzionale):** se viene specificata questa clausola, in questo indice verranno incluse solo le chiavi che iniziano con gli stessi byte di uno o più prefissi specificati. Se questa clausola viene omessa, verranno incluse tutte le chiavi del tipo corretto. Un prefisso di lunghezza zero corrisponderebbe anche a tutte le chiavi del tipo corretto. **Tipi di campo:** + TAG: un campo tag è una stringa che contiene uno o più valori di tag. + SEPARATORE (opzionale): uno dei caratteri `,.<>{}[]"':;!@#$%^&*()-+=~` utilizzati per delimitare i singoli tag. Se omesso, il valore predefinito è. `,` + CASESENSITIVE (opzionale): se presente, i confronti tra tag faranno distinzione tra maiuscole e minuscole. L'impostazione predefinita è che i confronti tra tag NON fanno distinzione tra maiuscole e minuscole. + NUMERICO: Un campo numerico contiene un numero. + VETTORE: Un campo vettoriale contiene un vettore. Attualmente sono supportati due algoritmi di indicizzazione vettoriale: HNSW (Hierarchical Navigable Small World) e FLAT (forza bruta). Ogni algoritmo ha una serie di attributi aggiuntivi, alcuni obbligatori e altri opzionali. + FLAT: L'algoritmo Flat fornisce risposte esatte, ma ha un'autonomia proporzionale al numero di vettori indicizzati e pertanto potrebbe non essere appropriato per set di dati di grandi dimensioni. + DIM (obbligatorio): specifica il numero di dimensioni in un vettore. + TIPO FLOAT32 (obbligatorio): tipo di dati, attualmente è supportato solo FLOAT32 . + DISTANCE\$1METRIC [L2 \$1 IP \$1 COSINE] (obbligatorio): specifica l'algoritmo di distanza. + INITIAL\$1CAP (opzionale): dimensione iniziale dell'indice. + HNSW: l'algoritmo HNSW fornisce risposte approssimative, ma funziona molto più velocemente di FLAT. + DIM (obbligatorio): specifica il numero di dimensioni in un vettore. + TIPO FLOAT32 (obbligatorio): tipo di dati, attualmente è supportato solo FLOAT32 . + DISTANCE\$1METRIC [L2 \$1 IP \$1 COSINE] (obbligatorio): specifica l'algoritmo di distanza. + INITIAL\$1CAP (opzionale): dimensione iniziale dell'indice. + M (opzionale): numero massimo di bordi in uscita consentiti per ogni nodo del grafico in ogni livello. Sul livello zero, il numero massimo di spigoli in uscita sarà 2\$1M. Il valore predefinito è 16, il massimo è 512. + EF\$1CONSTRUCTION (opzionale): controlla il numero di vettori esaminati durante la costruzione dell'indice. Valori più alti per questo parametro miglioreranno il rapporto di richiamo a scapito di tempi più lunghi di creazione dell'indice. Il valore predefinito è 200. Il valore massimo è 4096. + EF\$1RUNTIME (opzionale): controlla il numero di vettori da esaminare durante un'operazione di interrogazione. L'impostazione predefinita è 10 e il massimo è 4096. È possibile impostare questo valore di parametro per ogni query eseguita. Valori più alti aumentano i tempi di interrogazione, ma migliorano il richiamo delle query. **RISPOSTA:** OK o errore. # FT.SEARCH Esegue una ricerca nell'indice specificato. Vengono restituite le chiavi che corrispondono all'espressione della query. ``` FT.SEARCH [NOCONTENT] [RETURN ( [AS ])+] [TIMEOUT timeout] [PARAMS [ ]] [LIMIT ] ``` + (obbligatorio): Il nome dell'indice su cui si desidera eseguire la query. + (obbligatorio): La stringa di query, vedi sotto per i dettagli. + NOCONTENT (opzionale): quando presente, vengono restituiti solo i nomi delle chiavi risultanti, non vengono inclusi i valori chiave. + TIMEOUT (opzionale): consente di impostare un valore di timeout per il comando di ricerca. Deve essere un numero intero in millisecondi. + PARAMETRI... (opzionale): `count` indica il numero di argomenti, cioè il doppio del numero di coppie di nomi di valori. Vedi la stringa di query per i dettagli sull'utilizzo. + RITORNA ... (opzionale): count è il numero di campi da restituire. Specificate i campi che desiderate recuperare dai documenti, insieme agli eventuali alias per i valori restituiti. Per impostazione predefinita, vengono restituiti tutti i campi a meno che non sia impostata l'opzione NOCONTENT, nel qual caso non viene restituito alcun campo. Se count è impostato su 0, si comporta come NOCONTENT. + LIMIT: : Consente di scegliere una parte del risultato. Le prime chiavi vengono ignorate e viene incluso solo un massimo di chiavi. L'impostazione predefinita è LIMIT 0 10, che restituisce al massimo 10 chiavi. + PARAMS: due volte il numero di coppie chiave-valore. È possibile fare riferimento alle key/value coppie di parametri dall'interno dell'espressione di query. Per ulteriori informazioni, vedete Espressione di interrogazione di [ricerca vettoriale](https://docs.aws.amazon.com/memorydb/latest/devguide/vector-search-overview.html#vector-search-query-expression). + DIALETTO: (opzionale): specifica il dialetto. L'unico dialetto supportato è il 2. **RISPOSTA** Il comando restituisce un array in caso di successo o un errore. In caso di successo, la prima voce nell'array di risposta rappresenta il conteggio delle chiavi corrispondenti, seguita da una voce dell'array per ogni chiave corrispondente. Nota che se l'`LIMIT`opzione viene specificata, controllerà solo il numero di chiavi restituite e non influirà sul valore della prima voce. Quando `NOCONTENT` viene specificato, ogni voce nella risposta contiene solo il nome chiave corrispondente. Altrimenti, ogni voce include il nome chiave corrispondente, seguito da una matrice dei campi restituiti. I campi dei risultati per una chiave sono costituiti da un insieme di name/value coppie. La prima name/value coppia è per la distanza calcolata. Il nome di questa coppia è costruito a partire dal nome del campo vettoriale preceduto da «\$1\$1» e aggiunto da «\$1score» e il valore è la distanza calcolata. Le name/value coppie rimanenti sono i membri e i valori della chiave controllati dalla clausola. `RETURN` La stringa di interrogazione è conforme alla seguente sintassi: ``` =>[ KNN @ $ ] ``` Dove: + : È un \$1 o un'espressione di filtro. Un \$1 indica l'assenza di filtri e pertanto la ricerca viene effettuata in tutti i vettori all'interno dell'indice. È possibile fornire un'espressione di filtro per designare un sottoinsieme dei vettori da cercare. + : il nome di un campo vettoriale all'interno dell'indice specificato. + : il numero di vettori vicini più prossimi da restituire. + : un nome PARAM il cui valore corrispondente fornisce il vettore di interrogazione per l'algoritmo KNN. Si noti che questo parametro deve essere codificato come virgola mobile binaria IEEE 754 a 32 bit in formato little-endian. + : (Facoltativo) Un elenco di coppie che modificano questa particolare ricerca KNN. keyword/value Attualmente sono supportate due parole chiave: + EF\$1RUNTIME: questa parola chiave è accompagnata da un valore intero che sostituisce il valore predefinito di EF\$1RUNTIME specificato al momento della creazione dell'indice. + AS: Questa parola chiave è accompagnata da un valore di stringa che diventa il nome del campo di punteggio nel risultato, sostituendo l'algoritmo di generazione dei nomi dei campi di punteggio predefinito. **Espressione di filtro** Un'espressione di filtro è costruita come una combinazione logica di operatori di ricerca numerici e tag contenuti tra parentesi. **Tag** L'operatore di ricerca per tag viene specificato con una o più stringhe separate dal carattere \$1. Una chiave soddisferà l'operatore di ricerca dei tag se il campo indicato contiene una delle stringhe specificate. ``` @:{} or @:{ | } or @:{ | | ...} ``` Ad esempio, la seguente query restituirà documenti di colore blu O nero O verde. `@color:{blue | black | green}` Come altro esempio, la seguente query restituirà documenti contenenti «hello world» o «hello universe». `@description:{hello world | hello universe}` **Intervallo numerico** L'operatore di intervallo numerico consente di filtrare le query per restituire solo i valori compresi tra un determinato valore iniziale e finale. Sono supportate sia le interrogazioni con intervallo inclusivo che quelle con intervallo esclusivo. Per semplici confronti relazionali, è possibile utilizzare \$1inf, -inf con una query di intervallo. La sintassi per un operatore di ricerca per intervalli è: ``` @:[ [(] [(] ] ``` ... dove è un numero o \$1inf o -inf. I limiti senza la parentesi principale aperta sono inclusivi, mentre i limiti con la parentesi principale aperta sono esclusivi. Utilizza la tabella seguente come guida per mappare le espressioni matematiche alle interrogazioni di filtraggio: ``` min <= field <= max @field:[min max] min < field <= max @field:[(min max] min <= field < max @field:[min (max] min < field < max @field:[(min (max] field >= min @field:[min +inf] field > min @field:[(min +inf] field <= max @field:[-inf max] field < max @field:[-inf (max] field == val @field:[val val] ``` **Operatori logici** È possibile utilizzare più tag e operatori di ricerca numerici per creare query complesse utilizzando operatori logici. **AND logico** Per impostare un AND logico, utilizzate uno spazio tra i predicati. Esempio: `query1 query2 query3` **OR logico** Per impostare un OR logico, utilizzate uno spazio tra i predicati. Esempio: `query1 | query2 | query3` **Negazione logica** Qualsiasi interrogazione può essere annullata anteponendo il `-` carattere prima di ogni interrogazione. Le query negative restituiscono tutte le voci che non corrispondono alla query. Ciò include anche le chiavi che non dispongono del campo. Ad esempio, una query negativa su @genre: \$1comedy\$1 restituirà tutti i libri che non sono comici E tutti i libri che non hanno un campo di genere. La seguente query restituirà tutti i libri di genere «commedia» che non sono stati pubblicati tra il 2015 e il 2024 o che non hanno il campo dell'anno: @genre: [commedia] - @year: [2015 2024] **Precedenza degli operatori** Si applicano le tipiche regole di precedenza degli operatori, ad esempio NEGATE logico è la priorità più alta, seguito da AND logico e quindi OR logico con la priorità più bassa. Le parentesi possono essere utilizzate per sovrascrivere le regole di precedenza predefinite. *Esempi di combinazione di operatori logici* Gli operatori logici possono essere combinati per formare espressioni di filtro complesse. La seguente query restituirà tutti i libri di genere «commedia» o «horror» (AND) pubblicati tra il 2015 e il 2024: `@genre:[comedy|horror] @year:[2015 2024]` La seguente query restituirà tutti i libri di genere «commedia» o «horror» (OR) pubblicati tra il 2015 e il 2024: `@genre:[comedy|horror] | @year:[2015 2024]` La seguente query restituirà tutti i libri che non hanno un campo di genere o un campo di genere diverso da «commedia», pubblicati tra il 2015 e il 2024: `-@genre:[comedy] @year:[2015 2024]` # INDICE FT.DROP **Sintassi** ``` FT.DROPINDEX ``` L'indice specificato viene eliminato. Restituisce OK o restituisce un errore se l'indice non esiste. + (obbligatorio): Il nome dell'indice da eliminare. # FT.INFO **Sintassi** ``` FT.INFO ``` La ricerca vettoriale amplia il comando [FT.INFO](https://valkey.io/commands/info/) con diverse sezioni aggiuntive di statistiche e contatori. Una richiesta di recupero della sezione SEARCH recupererà tutte le seguenti statistiche: | Nome chiave | Value type (Tipo di valore) | Description | | --- | --- | --- | | nome\$1indice | stringa | Nome dell'indice | | opzioni\$1indice | stringa | Riservata. Attualmente impostato su «0" | | index\$1definition | array | Vedi sotto per la definizione di questi elementi dell'array. | | attributes | matrice di informazioni sugli attributi | Un elemento in questo array per ogni attributo definito, vedi sotto per la definizione delle informazioni sugli attributi. | | num\$1docs | intero | Numero di chiavi attualmente contenute nell'indice | | num\$1terms | intero | Riservata. Attualmente impostato su «0". | | record\$1count | intero | La somma del campo «size» per ogni attributo. | | hash\$1indexing\$1failures | intero | Numero di volte in cui un attributo non può essere convertito nel tipo di attributo dichiarato. Nonostante il nome, questo vale anche per le chiavi JSON. | | backfill\$1in\$1progress | intero | Se è attualmente in corso un riempimento, questo sarà un '1', altrimenti sarà uno '0' | | backfill\$1percent\$1complete | virgola mobile | Stima del completamento del riempimento, un numero frazionario nell'intervallo [0.. 1] | | mutation\$1queue\$1size | intero | Numero di chiavi in attesa di aggiornamento dell'indice. | | recent\$1mutations\$1queue\$1delay | intero | Stima del ritardo (in secondi) dell'aggiornamento dell'indice. 0 se non sono in corso aggiornamenti. | | stato | stringa | Stato di riempimento: «pronto» indica che il riempimento è stato completato correttamente. «backfill\$1in\$1progress» indica che il riempimento è in corso. «backfill\$1paused\$1by\$1oom» significa che il riempimento è stato messo in pausa a causa di una condizione di memoria insufficiente. Una volta risolta la condizione di memoria insufficiente, il backill continuerà. | La struttura index\$1definition è una matrice di key/value coppie definita come: | Nome chiave | Value type (Tipo di valore) | Description | | --- | --- | --- | | tipo\$1chiave | stringa | O la stringa 'JSON' o la stringa 'HASH' | | prefissi | array | Ogni elemento dell'array è un prefisso definito per l'indice. Se non è stato specificato alcun prefisso al momento della creazione dell'indice, questo array avrà 0 voci. | | default\$1score | stringa | Riservata. Attualmente impostato su «1" | Informazioni sugli attributi: le informazioni sugli attributi sono specifiche del tipo. Attributi numerici: | Chiave | Value type (Tipo di valore) | Description | | --- | --- | --- | | identificatore | stringa | Posizione dell'attributo all'interno di una chiave. Nome del membro hash o percorso JSON | | alias | stringa | Nome dell'attributo utilizzato nelle descrizioni delle query. | | tipo | stringa | La stringa «NUMERIC» | | formato | intero | Il numero di chiavi con valori numerici validi in questo attributo. | Attributi dei tag: | Nome chiave | Value type (Tipo di valore) | Description | | --- | --- | --- | | identificatore | stringa | Posizione dell'attributo all'interno di una chiave. Nome del membro hash o percorso JSON | | alias | stringa | Nome dell'attributo utilizzato nelle descrizioni delle query. | | tipo | stringa | La stringa «TAG» | | SEPARATOR | carattere | Il carattere separatore definito al momento della creazione dell'indice | | DISTINGUE TRA MAIUSCOLE E MINUSCOLE | N/A | Questa chiave non ha alcun valore associato. È presente solo se l'attributo è stato creato con questa opzione. | | formato | intero | Il numero di chiavi con valori di tag validi in questo attributo | Attributi vettoriali: | Nome chiave | Value type (Tipo di valore) | Description | | --- | --- | --- | | identificatore | stringa | Posizione dell'attributo all'interno di una chiave. Nome del membro hash o percorso JSON | | alias | stringa | Nome dell'attributo utilizzato nelle descrizioni delle query. | | tipo | stringa | La stringa «VECTOR» | | indice | carattere | Per un'ulteriore descrizione dell'indice vettoriale, vedi sotto. | Descrizione dell'indice vettoriale: | Nome chiave | Value type (Tipo di valore) | Description | | --- | --- | --- | | capacità | stringa | Capacità attuale dell'indice | | dimensioni | stringa | Numero di elementi in ogni vettore | | distance\$1metric | stringa | Uno tra «COSINE», «L2" o «IP» | | formato | array | Descrizione dell'indice vettoriale, vedi sotto. | | data\$1type | stringa | Tipo di dati dichiarato. Attualmente è supportato solo FLOAT32 "". | | Algoritmo | array | Ulteriore descrizione dell'algoritmo di ricerca vettoriale. | Descrizione dell'algoritmo di ricerca vettoriale FLAT: | Nome chiave | Value type (Tipo di valore) | Description | | --- | --- | --- | | nome | stringa | Nome dell'algoritmo: FLAT | | block\$1size | numero | Dimensione di un blocco dell'indice FLAT. | Descrizione dell'indice vettoriale HNSW: | Nome chiave | Value type (Tipo di valore) | Description | | --- | --- | --- | | nome | stringa | Nome dell'algoritmo: HNSW | | m | numero | Il parametro «M» per HNSW | | ef\$1construction | numero | Il parametro «ef\$1construction» per HNSW | | ef\$1runtime | numero | Il parametro «ef\$1runtime» per HNSW. | # PIEDI. \$1LISTA Elenca tutti gli indici. **Sintassi** ``` FT._LIST ``` Restituisce una matrice di stringhe che sono i nomi dell'indice attualmente definito.