Gestire gli indici di vettori

Questo documento descrive come creare e gestire gli indici di vettori.

Un indice vettoriale è una struttura di dati progettata per consentire alla funzione VECTOR_SEARCH di eseguire una ricerca vettoriale più efficiente degli embedding. Quando VECTOR_SEARCH è in grado di utilizzare un indice vettoriale, la funzione utilizza la tecnica di ricerca Vicino più prossimo approssimativo per contribuire a migliorare il rendimento della ricerca, con il compromesso di ridurre il ricordo e quindi restituire risultati più approssimativi.

Ruoli e autorizzazioni

Per creare un indice vettoriale, devi disporre dell'autorizzazione IAM bigquery.tables.createIndex per la tabella in cui stai creando l'indice. Per eliminare un indice di vettori, devi disporre dell'autorizzazione bigquery.tables.deleteIndex. Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per lavorare con gli indici di vettori:

• BigQuery Data Owner (roles/bigquery.dataOwner)
• BigQuery Data Editor (roles/bigquery.dataEditor)

Creare un indice di vettori

Per creare un indice di vettori, utilizza l'istruzione DDL (Data Definition Language) CREATE VECTOR INDEX:

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, seleziona un tipo di indice ed esegui una delle seguenti istruzioni SQL:

   Per creare un indice di vettori IVF:

   CREATE [ OR REPLACE ] VECTOR INDEX [ IF NOT EXISTS ] INDEX_NAME
   ON DATASET_NAME.TABLE_NAME(COLUMN_NAME)
   STORING(STORED_COLUMN_NAME [, ...])
   OPTIONS(index_type = "IVF",
     distance_type = "DISTANCE_TYPE",
     ivf_options = '{"num_lists":NUM_LISTS}')

   Per creare un indice di vettori TreeAH:

   CREATE [ OR REPLACE ] VECTOR INDEX [ IF NOT EXISTS ] INDEX_NAME
   ON DATASET_NAME.TABLE_NAME(COLUMN_NAME)
   OPTIONS(index_type = "TREE_AH",
     distance_type = "DISTANCE_TYPE",
     tree_ah_options = '{"leaf_node_embedding_count":LEAF_NODE_EMBEDDING_COUNT,
       "normalization_type":"NORMALIZATION_TYPE"}')

   Per ulteriori informazioni, consulta Scegliere un tipo di indice di vettore.

   Sostituisci quanto segue:

   • INDEX_NAME: il nome dell'indice di vettori che stai creando. Poiché l'indice viene sempre creato nello stesso progetto e nello stesso set di dati della tabella di base, non è necessario specificarli nel nome.
   • DATASET_NAME: il nome del set di dati che contiene la tabella.
   • TABLE_NAME: il nome della tabella che contiene la colonna con i dati degli embedding.
   • COLUMN_NAME: il nome di una colonna che contiene i dati degli embedding. La colonna deve essere di tipo ARRAY<FLOAT64>. La colonna non può avere campi secondari. Tutti gli elementi dell'array devono essere non NULL e tutti i valori della colonna devono avere le stesse dimensioni dell'array.
   • STORED_COLUMN_NAME: il nome di una colonna di primo livello nella tabella da memorizzare nell'indice del vettore. Il tipo di colonna non può essere RANGE. Le colonne archiviate non vengono utilizzate se la tabella ha una norma di accesso a livello di riga o se la colonna ha un tag di criteri. Per informazioni su come attivare le colonne archiviate, consulta Archiviare le colonne e applicare un prefiltro.

   • DISTANCE_TYPE: specifica il tipo di distanza predefinito da utilizzare quando esegui una ricerca di vettori utilizzando questo indice. I valori supportati sono EUCLIDEAN, COSINE e DOT_PRODUCT. EUCLIDEAN è il valore predefinito.

     La creazione dell'indice stesso utilizza sempre la distanza EUCLIDEAN per l'addestramento, ma la distanza utilizzata nella funzione VECTOR_SEARCH può essere diversa.

     Se specifichi un valore per l'argomento distance_type della funzione VECTOR_SEARCH, questo viene utilizzato al posto del valore DISTANCE_TYPE.

   • NUM_LISTS: un valore INT64 minore o uguale a 5000 che determina il numero di elenchi creati dall'algoritmo IVF. L'algoritmo IVF suddivide l'intero spazio di dati in un numero di elenchi uguale a NUM_LISTS, con punti dati più vicini tra loro che hanno maggiori probabilità di essere inseriti nello stesso elenco. Se NUM_LISTS è piccolo, hai meno elenchi con più punti dati, mentre un valore più elevato crea più elenchi con meno punti dati.

     Puoi utilizzare NUM_LISTS in combinazione con l'argomento fraction_lists_to_search nella funzione VECTOR_SEARCH per creare una ricerca di vettori efficiente. Se hai dati distribuiti in molti piccoli gruppi nello spazio di embedding, specifica un valore NUM_LISTS elevato per creare un indice con più elenchi e un valore fraction_lists_to_search inferiore per eseguire la scansione di un numero inferiore di elenchi nella ricerca di vettori. Utilizza un valore NUM_LISTS inferiore e un valore fraction_lists_to_search superiore quando i dati sono distribuiti in gruppi più piccoli e più grandi. L'utilizzo di un valore num_lists elevato potrebbe prolungare i tempi di creazione dell'indice di vettori.

     Se non specifichi NUM_LISTS, BigQuery calcola un valore appropriato.

   • LEAF_NODE_EMBEDDING_COUNT: un valore INT64 superiore o uguale a 500 che specifica il numero approssimativo di vettori in ogni nodo foglia dell'albero creato dall'algoritmo TreeAH. L'algoritmo TreeAH suddivide l'intero spazio di dati in una serie di elenchi, ciascuno contenente circa LEAF_NODE_EMBEDDING_COUNT punti dati. Un valore inferiore crea più elenchi con meno punti dati, mentre un valore superiore crea meno elenchi con più punti dati. Il valore predefinito è 1000.

   • NORMALIZATION_TYPE: un valore STRING. I valori supportati sono NONE o L2. Il valore predefinito è NONE. La normalizzazione avviene prima di qualsiasi elaborazione, sia per i dati della tabella di base sia per i dati della query, ma non modifica la colonna di incorporamento COLUMN_NAME in TABLE_NAME. A seconda del set di dati, del modello di embedding e del tipo di distanza utilizzato durante VECTOR_SEARCH, la normalizzazione degli embedding potrebbe migliorare il richiamo.

L'esempio seguente crea un indice vettoriale nella colonna embedding di my_table:

CREATE TABLE my_dataset.my_table(embedding ARRAY<FLOAT64>);

CREATE VECTOR INDEX my_index ON my_dataset.my_table(embedding)
OPTIONS(index_type = 'IVF');

L'esempio seguente crea un indice di vettori nella colonna embedding di my_table e specifica il tipo di distanza da utilizzare e le opzioni IVF:

CREATE TABLE my_dataset.my_table(embedding ARRAY<FLOAT64>);

CREATE VECTOR INDEX my_index ON my_dataset.my_table(embedding)
OPTIONS(index_type = 'IVF', distance_type = 'COSINE',
ivf_options = '{"num_lists": 2500}')

L'esempio seguente crea un indice di vettori nella colonna embedding di my_table e specifica il tipo di distanza da utilizzare e le opzioni TreeAH:

CREATE TABLE my_dataset.my_table(id INT64, embedding ARRAY<FLOAT64>);

CREATE VECTOR INDEX my_index ON my_dataset.my_table(embedding)
OPTIONS (index_type = 'TREE_AH', distance_type = 'EUCLIDEAN',
tree_ah_options = '{"normalization_type": "L2"}');

Scegli un tipo di indice di vettore

BigQuery offre due tipi di indici vettoriali.

Indice IVF

IVF è un indice file invertito che utilizza un algoritmo k-means per raggruppare i dati vettoriali e poi li partiziona in base a questi cluster. Quando utilizzi la funzione VECTOR_SEARCH per cercare i dati vettoriali, può utilizzare queste partizioni per ridurre la quantità di dati da leggere per determinare un risultato.

Indice TreeAH

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

TreeAH è un tipo di indice vettoriale che utilizza l'algoritmo ScaNN di Google. Ecco come funziona:

• La tabella di base è divisa in frammenti più piccoli e gestibili.

• Viene addestrato un modello di clustering, con il numero di cluster dedotto dall'opzione leaf_node_embedding_count in tree_ah_options.

• I vettori vengono quantizzati e memorizzati nelle tabelle di indice.

• Durante VECTOR_SEARCH, un elenco di candidati per ogni vettore di query viene calcolato in modo efficiente utilizzando l'hashing asimmetrico, che è ottimizzato per l'hardware per i calcoli approssimativi della distanza. A questi candidati viene poi assegnato un nuovo punteggio e un nuovo ranking utilizzando embedding esatti.

L'algoritmo TreeAH è ottimizzato per le query batch che elaborano centinaia o più vettori di query. L'utilizzo della quantizzazione dei prodotti può ridurre notevolmente la latenza e i costi, potenzialmente di ordini di grandezza rispetto all'IVF. Tuttavia, a causa dell'aumento del sovraccarico, l'algoritmo IVF potrebbe essere migliore quando hai un numero inferiore di vettori di query.

Ti consigliamo di provare il tipo di indice TreeAH se il tuo caso d'uso soddisfa i seguenti criteri:

• La tabella contiene al massimo 200 milioni di righe.

• Esegui spesso query batch di grandi dimensioni che coinvolgono centinaia o più vettori di query.

  Per le query in batch di piccole dimensioni, VECTOR_SEARCH l'utilizzo del tipo di indice TreeAH potrebbe ricadere sulla ricerca forzata. In questo caso, viene inserito un motivo del mancato utilizzo dell'indice vettoriale per spiegare il motivo.

• Il flusso di lavoro non richiede l'utilizzo di colonne archiviate o prefiltri. BigQuery tratta i prefiltri utilizzati con un indice TreeAH come postfiltri.

Per tutte le domande e i dubbi, in particolare su scalabilità, limiti e prestazioni, contattaci all'indirizzo [e-mail].

Memorizza le colonne e prefiltra

Per migliorare ulteriormente l'efficienza dell'indice di vettori, puoi specificare le colonne della tabella di base da memorizzare nell'indice di vettori. L'utilizzo delle colonne archiviate può ottimizzare le query che chiamano la funzione VECTOR_SEARCH nei seguenti modi:

• La funzione VECTOR_SEARCH restituisce una struttura denominata base che contiene tutte le colonne della tabella di base. Senza colonne archiviate, è necessaria un'unione potenzialmente costosa per recuperare le colonne archiviate in base. Se la query seleziona solo le colonne archiviate da base, BigQuery la ottimizza per eliminare l'unione.

• Invece di cercare in un'intera tabella, puoi chiamare la funzione VECTOR_SEARCH in un'istruzione di query che pre-filtra la tabella di base con una clausola WHERE. Se la tabella ha un indice e filtri solo in base alle colonne memorizzate, BigQuery ottimizza la query filtrando i dati prima di eseguire la ricerca e poi utilizzando l'indice per cercare nell'insieme di risultati più piccolo. Se applichi un filtro a colonne non memorizzate, BigQuery applica il filtro dopo la ricerca nella tabella o dopo i filtri.

  Il filtro post-ricerca è meno efficiente e può causare meno di top_k corrispondenze nel set di risultati. In alcuni casi, il pre-filtro può anche ridurre le dimensioni del set di risultati. In questo caso, prova ad aumentare il valore di fraction_lists_to_search nella chiamata a VECTOR_SEARCH.

Per memorizzare le colonne, elencale nella clausola STORING dell'istruzione DDL CREATE VECTOR INDEX. La memorizzazione delle colonne aumenta le dimensioni dell'indice di vettore, pertanto è meglio memorizzare solo le colonne più utilizzate o filtrate.

L'esempio seguente crea un indice di vettori con colonne archiviate e poi spiega il comportamento di diversi tipi di ricerche di vettori:

-- Create a table that contains an embedding.
CREATE TABLE my_dataset.my_table(embedding ARRAY<FLOAT64>, type STRING, creation_time DATETIME, id INT64);

-- Create a query table that contains an embedding.
CREATE TABLE my_dataset.my_testdata(embedding ARRAY<FLOAT64>, test_id INT64);

-- Create a vector index with stored columns.
CREATE VECTOR INDEX my_index ON my_dataset.my_table(embedding)
STORING (type, creation_time)
OPTIONS (index_type = 'IVF');

-- Select only stored columns from a vector search to avoid an expensive join.
SELECT query, base.type, distance
FROM
  VECTOR_SEARCH(
    TABLE my_dataset.my_table,
    'embedding'
    TABLE my_dataset.my_testdata);

-- Pre-filter on a stored column. The index speeds up the query.
SELECT *
FROM
  VECTOR_SEARCH(
    (SELECT * FROM my_dataset.my_table WHERE type = 'animal'),
    'embedding',
    TABLE my_dataset.my_testdata);

-- Filter on a column that isn't stored. The index is used to search the
-- entire table, and then the results are post-filtered. You might see fewer
-- than 5 matches returned for some embeddings.
SELECT query.test_id, base.type, distance
FROM
  VECTOR_SEARCH(
    (SELECT * FROM my_dataset.my_table WHERE id = 123),
    'embedding',
    TABLE my_dataset.my_testdata,
    top_k => 5);

-- Use post-filters. The index is used, but the entire table is searched and
-- the post-filtering might reduce the number of results.
SELECT query.test_id, base.type, distance
FROM
  VECTOR_SEARCH(
    TABLE my_dataset.my_table,
    'embedding',
    TABLE my_dataset.my_testdata,
    top_k => 5)
WHERE base.type = 'animal';

-- Use pre-filters with brute force. The data is filtered and then searched
-- with brute force for exact results.
SELECT query.test_id, base.type, distance
FROM
  VECTOR_SEARCH(
    (SELECT * FROM my_dataset.my_table WHERE id = 123),
    'embedding',
    TABLE my_dataset.my_testdata,
    options => '{"use_brute_force":true}');

Limitazioni

• Non puoi utilizzare le visualizzazioni logiche nel prefiltro.
• Se il prefiltro contiene una sottoquery, potrebbe interferire con l'utilizzo dell'indice.
• Se la modalità, il tipo o lo schema di una colonna vengono modificati nella tabella di base e se si tratta di una colonna archiviata nell'indice di vettori, può verificarsi un ritardo prima che la modifica venga applicata all'indice di vettori. Fino a quando gli aggiornamenti non vengono applicati all'indice, le query di ricerca vettoriale utilizzano le colonne archiviate modificate della tabella di base.
• Se selezioni una colonna di tipo STRUCT dall'output query di una query VECTOR_SEARCH su una tabella che ha un indice con colonne archiviate, l'intera query potrebbe non riuscire.
• Le colonne archiviate non sono supportate per gli indici TreeAH.

Informazioni sull'aggiornamento dell'indice

Gli indici di vettori sono completamente gestiti da BigQuery e aggiornati automaticamente quando la tabella indicizzata cambia. Se elimini la colonna indicizzata in una tabella o rinomini la tabella stessa, l'indice vettoriale viene eliminato automaticamente.

Se crei un indice vettoriale in una tabella di dimensioni inferiori a 10 MB, l'indice vettoriale non viene compilato. Analogamente, se elimini i dati da una tabella indicizzata e le dimensioni della tabella scendono al di sotto di 10 MB, l'indice di vettore viene disattivato temporaneamente. In questo caso, le query di ricerca vettoriale non utilizzano l'indice e il codice indexUnusedReasons nella vectorSearchStatistics sezione della risorsa Job è BASE_TABLE_TOO_SMALL. Senza l'indice, VECTOR_SEARCH ricorre automaticamente all'uso della forza bruta per trovare i coinquilini più vicini degli embedding.

Le query che utilizzano la funzioneVECTOR_SEARCH restituisce sempre risultati corretti, anche se una parte dei dati non è ancora indicizzata.

Ricevere informazioni sugli indici vettoriali

Puoi verificare l'esistenza e l'idoneità di un indice di vettori eseguendo una query su INFORMATION_SCHEMA. Le seguenti visualizzazioni contengono metadati sugli indici vettoriali:

• La visualizzazione INFORMATION_SCHEMA.VECTOR_INDEXES contiene informazioni sugli indici vettoriali in un set di dati.

  Al termine dell'istruzione CREATE VECTOR INDEX, l'indice deve essere ancora compilato prima di poter essere utilizzato. Puoi utilizzare le colonne last_refresh_time e coverage_percentage per verificare l'idoneità di un indice di vettori. Se l'indice vettoriale non è pronto, puoi comunque utilizzare la funzione VECTOR_SEARCH in una tabella, ma potrebbe funzionare più lentamente senza l'indice.

• La visualizzazione INFORMATION_SCHEMA.VECTOR_INDEX_COLUMNS contiene informazioni sulle colonne con indicizzazione vettoriale per tutte le tabelle di un set di dati.

• La visualizzazione INFORMATION_SCHEMA.VECTOR_INDEX_OPTIONS contiene informazioni sulle opzioni utilizzate dagli indici di vettori in un set di dati.

Esempi di indici vettoriali

L'esempio seguente mostra tutti gli indici di vettori attivi nelle tabelle del set di datimy_dataset, nel progetto my_project. Sono inclusi i nomi, le istruzioni DDL utilizzate per crearli e la percentuale di copertura. Se una tabella di base indicizzata è inferiore a 10 MB, il relativo indice non viene compilato, nel qual caso il valore coverage_percentage è 0.

SELECT table_name, index_name, ddl, coverage_percentage
FROM my_project.my_dataset.INFORMATION_SCHEMA.VECTOR_INDEXES
WHERE index_status = 'ACTIVE';

Il risultato è simile al seguente:

+------------+------------+-------------------------------------------------------------------------------------------------+---------------------+
| table_name | index_name | ddl                                                                                             | coverage_percentage |
+------------+------------+-------------------------------------------------------------------------------------------------+---------------------+
| table1     | indexa     | CREATE VECTOR INDEX `indexa` ON `my_project.my_dataset.table1`(embeddings)                      | 100                 |
|            |            | OPTIONS (distance_type = 'EUCLIDEAN', index_type = 'IVF', ivf_options = '{"num_lists": 100}')   |                     |
+------------+------------+-------------------------------------------------------------------------------------------------+---------------------+
| table2     | indexb     | CREATE VECTOR INDEX `indexb` ON `my_project.my_dataset.table2`(vectors)                         | 42                  |
|            |            | OPTIONS (distance_type = 'COSINE', index_type = 'IVF', ivf_options = '{"num_lists": 500}')      |                     |
+------------+------------+-------------------------------------------------------------------------------------------------+---------------------+
| table3     | indexc     | CREATE VECTOR INDEX `indexc` ON `my_project.my_dataset.table3`(vectors)                         | 98                  |
|            |            | OPTIONS (distance_type = 'DOT_PRODUCT', index_type = 'TREE_AH',                                 |                     |
|            |            |          tree_ah_options = '{"leaf_node_embedding_count": 1000, "normalization_type": "NONE"}') |                     |
+------------+------------+-------------------------------------------------------------------------------------------------+---------------------+

Esempi di colonne di indici di vettori

La seguente query estrae informazioni sulle colonne con indici di vettori:

SELECT table_name, index_name, index_column_name, index_field_path
FROM my_project.dataset.INFORMATION_SCHEMA.VECTOR_INDEX_COLUMNS;

Il risultato è simile al seguente:

+------------+------------+-------------------+------------------+
| table_name | index_name | index_column_name | index_field_path |
+------------+------------+-------------------+------------------+
| table1     | indexa     | embeddings        | embeddings       |
| table2     | indexb     | vectors           | vectors          |
| table3     | indexc     | vectors           | vectors          |
+------------+------------+-------------------+------------------+

Esempi di opzioni di indice vettoriale

La seguente query estrae informazioni sulle opzioni dell'indice di vettori:

SELECT table_name, index_name, option_name, option_type, option_value
FROM my_project.dataset.INFORMATION_SCHEMA.VECTOR_INDEX_OPTIONS;

Il risultato è simile al seguente:

+------------+------------+------------------+------------------+-------------------------------------------------------------------+
| table_name | index_name | option_name      | option_type      | option_value                                                      |
+------------+------------+------------------+------------------+-------------------------------------------------------------------+
| table1     | indexa     | index_type       | STRING           | IVF                                                               |
| table1     | indexa     | distance_type    | STRING           | EUCLIDEAN                                                         |
| table1     | indexa     | ivf_options      | STRING           | {"num_lists": 100}                                                |
| table2     | indexb     | index_type       | STRING           | IVF                                                               |
| table2     | indexb     | distance_type    | STRING           | COSINE                                                            |
| table2     | indexb     | ivf_options      | STRING           | {"num_lists": 500}                                                |
| table3     | indexc     | index_type       | STRING           | TREE_AH                                                           |
| table3     | indexc     | distance_type    | STRING           | DOT_PRODUCT                                                       |
| table3     | indexc     | tree_ah_options  | STRING           | {"leaf_node_embedding_count": 1000, "normalization_type": "NONE"} |
+------------+------------+------------------+------------------+-------------------------------------------------------------------+

Utilizzo dell'indice vettoriale

Le informazioni sull'utilizzo dell'indice di vettori sono disponibili nei metadati del job che ha eseguito la query di ricerca di vettori. Puoi visualizzare i metadati dei job utilizzando la console Google Cloud, lo strumento a riga di comando bq, l'API BigQuery o le librerie client.

Quando utilizzi la console Google Cloud, puoi trovare informazioni sull'utilizzo dell'indice vettoriale nei campi Modalità di utilizzo dell'indice vettoriale e Motivi del mancato utilizzo dell'indice vettoriale.

Quando utilizzi lo strumento bq o l'API BigQuery, puoi trovare informazioni sull'utilizzo degli indici di vettori nella sezione VectorSearchStatistics della risorsa Job.

La modalità di utilizzo dell'indice indica se è stato utilizzato un indice vettoriale fornendo uno dei seguenti valori:

• UNUSED: non è stato utilizzato alcun indice di vettore.
• PARTIALLY_USED: alcune funzioni VECTOR_SEARCH nella query hanno utilizzato indici vettoriali, altre no.
• FULLY_USED: ogni funzione VECTOR_SEARCH nella query ha utilizzato un indice di vettore.

Quando il valore della modalità di utilizzo dell'indice è UNUSED o PARTIALLY_USED, i motivi del mancato utilizzo dell'indice indicano perché gli indici vettoriali non sono stati utilizzati nella query.

Ad esempio, i seguenti risultati restituiti da bq show --format=prettyjson -j my_job_id mostrano che l'indice non è stato utilizzato perché l'opzione use_brute_force è stata specificata nella funzione VECTOR_SEARCH:

"vectorSearchStatistics": {
  "indexUnusedReasons": [
    {
      "baseTable": {
        "datasetId": "my_dataset",
        "projectId": "my_project",
        "tableId": "my_table"
      },
      "code": "INDEX_SUPPRESSED_BY_FUNCTION_OPTION",
      "message": "No vector index was used for the base table `my_project:my_dataset.my_table` because use_brute_force option has been specified."
    }
  ],
  "indexUsageMode": "UNUSED"
}

Opzioni di gestione degli indici

Per creare indici e gestirli con BigQuery, hai due opzioni:

• Utilizza il pool di slot condiviso predefinito: se i dati che prevedi di indicizzare sono al di sotto del limite per organizzazione, puoi utilizzare il pool di slot condiviso gratuito per la gestione degli indici.
• Utilizza la tua prenotazione: per ottenere un avanzamento dell'indicizzazione più prevedibile e coerente sui carichi di lavoro di produzione più grandi, puoi utilizzare le tue prenotazioni per la gestione dell'indice.

Utilizzare gli slot condivisi

Se non hai configurato il progetto per utilizzare una prenotazione dedicata per l'indicizzazione, la gestione dell'indice viene gestita nel pool di slot condivisi gratuito, in base ai seguenti vincoli.

Se aggiungi dati a una tabella che causano il superamento del limite della tua organizzazione per le dimensioni totali delle tabelle indicizzate, BigQuery mette in pausa la gestione degli indici per tutte le tabelle indicizzate. In questo caso, il campo index_status nella visualizzazione INFORMATION_SCHEMA.VECTOR_INDEXES mostra PENDING DISABLEMENT e l'indice viene messo in coda per l'eliminazione. Mentre l'indice è in attesa di disattivazione, viene ancora utilizzato nelle query e ti viene addebitato lo spazio di archiviazione dell'indice. Dopo l'eliminazione di un indice, il campo index_status lo mostra come TEMPORARILY DISABLED. In questo stato, le query non utilizzano l'indice e non ti viene addebitato alcun costo per lo spazio di archiviazione dell'indice. In questo caso, il codice IndexUnusedReason è BASE_TABLE_TOO_LARGE.

Se elimini i dati dalla tabella e le dimensioni totali delle tabelle indicizzate rientrano nel limite per organizzazione, la gestione dell'indice viene ripresa per tutte le tabelle indicizzate. Il campo index_status nella INFORMATION_SCHEMA.VECTOR_INDEXES vista è ACTIVE, le query possono utilizzare l'indice e ti viene addebitato lo spazio di archiviazione dell'indice.

BigQuery non offre alcuna garanzia sulla capacità disponibile del pool condiviso o sul throughput dell'indicizzazione visualizzato. Per le applicazioni di produzione, ti consigliamo di utilizzare slot dedicati per l'elaborazione dell'indice.

Utilizzare la tua prenotazione

Anziché utilizzare il pool di slot condiviso predefinito, puoi scegliere di designare la tua prenotazione per indicizzare le tabelle. L'utilizzo di una prenotazione personale garantisce un rendimento prevedibile e coerente dei job di gestione degli indici, come creazione, aggiornamento e ottimizzazioni in background.

• Non ci sono limiti di dimensioni delle tabelle quando un job di indicizzazione viene eseguito nella prenotazione.
• L'utilizzo della tua prenotazione ti offre flessibilità nella gestione dell'indice. Se devi creare un indice di grandi dimensioni o eseguire un aggiornamento importante di una tabella indicizzata, puoi aggiungere temporaneamente altri slot all'assegnazione.

Per indicizzare le tabelle di un progetto con una prenotazione designata, crea una prenotazione nella regione in cui si trovano le tabelle. Quindi, assegna il progetto alla prenotazione con job_type impostato su BACKGROUND:

SQL

Utilizza l'istruzione DDL CREATE ASSIGNMENT.

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

   CREATE ASSIGNMENT
     `ADMIN_PROJECT_ID.region-LOCATION.RESERVATION_NAME.ASSIGNMENT_ID`
   OPTIONS (
     assignee = 'projects/PROJECT_ID',
     job_type = 'BACKGROUND');

   Sostituisci quanto segue:

   • ADMIN_PROJECT_ID: l'ID del progetto di amministrazione proprietario della risorsa di prenotazione
   • LOCATION: la posizione della prenotazione
   • RESERVATION_NAME: il nome della prenotazione

   • ASSIGNMENT_ID: l'ID del compito

     L'ID deve essere univoco per il progetto e la località, deve iniziare e terminare con una lettera minuscola o un numero e contenere solo lettere minuscole, numeri e trattini.

   • PROJECT_ID: l'ID del progetto contenente le tabelle da indicizzare. Questo progetto è assegnato alla prenotazione.

3. Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

bq

Utilizza il comando bq mk:

bq mk \
    --project_id=ADMIN_PROJECT_ID \
    --location=LOCATION \
    --reservation_assignment \
    --reservation_id=RESERVATION_NAME \
    --assignee_id=PROJECT_ID \
    --job_type=BACKGROUND \
    --assignee_type=PROJECT

Sostituisci quanto segue:

• ADMIN_PROJECT_ID: l'ID del progetto di amministrazione che possiede la risorsa di prenotazione
• LOCATION: la posizione della prenotazione
• RESERVATION_NAME: il nome della prenotazione
• PROJECT_ID: l'ID del progetto da assegnare a questa prenotazione

Visualizzare i job di indicizzazione

Ogni volta che viene creato o aggiornato un indice in una singola tabella, viene creato un nuovo job di indicizzazione. Per visualizzare le informazioni sul job, esegui una query sulle visualizzazioni INFORMATION_SCHEMA.JOBS*. Puoi filtrare i job di indicizzazione impostando job_type IS NULL AND SEARCH(job_id, '`search_index`') nella clausola WHERE della query. L'esempio seguente elenca i cinque job di indicizzazione più recenti nel progetto my_project:

SELECT *
FROM
 region-us.INFORMATION_SCHEMA.JOBS
WHERE
  project_id  = 'my_project'
  AND job_type IS NULL
  AND SEARCH(job_id, '`search_index`')
ORDER BY
 creation_time DESC
LIMIT 5;

Nota: non puoi visualizzare le informazioni sui job di indicizzazione eseguiti nel pool di slot condivisi predefinito.

Scegli le dimensioni della prenotazione

Per scegliere il numero corretto di slot per la prenotazione, devi considerare quando vengono eseguiti i job di gestione degli indici, quanti slot utilizzano e come si presenta il tuo utilizzo nel tempo. BigQuery attiva un job di gestione degli indici nelle seguenti situazioni:

• Creazione di un indice in una tabella.
• I dati vengono modificati in una tabella indicizzata.
• Lo schema di una tabella cambia e questo influisce sulle colonne sottoposte a indicizzazione.
• I dati e i metadati dell'indice vengono ottimizzati o aggiornati periodicamente.

Il numero di slot necessari per un job di gestione degli indici in una tabella dipende dai seguenti fattori:

• Le dimensioni della tabella
• La frequenza di importazione dati nella tabella
• La frequenza delle istruzioni DML applicate alla tabella
• Il ritardo accettabile per la creazione e la gestione dell'indice
• La complessità dell'indice, in genere determinata dagli attributi dei dati, come il numero di termini duplicati

Monitorare l'utilizzo e i progressi

Il modo migliore per valutare il numero di slot necessari per eseguire in modo efficiente i job di gestione degli indici è monitorare l'utilizzo degli slot e modificare di conseguenza le dimensioni della prenotazione. La seguente query genera l'utilizzo giornaliero degli slot per i job di gestione degli indici. Nella regione us-west1 sono inclusi solo gli ultimi 30 giorni:

SELECT
  TIMESTAMP_TRUNC(job.creation_time, DAY) AS usage_date,
  -- Aggregate total_slots_ms used for index-management jobs in a day and divide
  -- by the number of milliseconds in a day. This value is most accurate for
  -- days with consistent slot usage.
  SAFE_DIVIDE(SUM(job.total_slot_ms), (1000 * 60 * 60 * 24)) AS average_daily_slot_usage
FROM
  `region-us-west1`.INFORMATION_SCHEMA.JOBS job
WHERE
  project_id = 'my_project'
  AND job_type IS NULL
  AND SEARCH(job_id, '`search_index`')
GROUP BY
  usage_date
ORDER BY
  usage_date DESC
limit 30;

Quando gli slot non sono sufficienti per eseguire i job di gestione degli indici, un indice può essere out of sync con la relativa tabella e i job di indicizzazione potrebbero non riuscire. In questo caso, BigQuery ricostruisce l'indice da zero. Per evitare di avere un indice non sincronizzato, assicurati di disporre di slot sufficienti per supportare gli aggiornamenti dell'indice dall'importazione e dall'ottimizzazione dei dati. Per ulteriori informazioni sul monitoraggio dell'utilizzo degli slot, consulta i grafici delle risorse di amministrazione.

Eliminare un indice di vettori

Quando non hai più bisogno di un indice vettoriale o vuoi modificare la colonna adeguata, puoi eliminare l'indice utilizzando l'istruzione DDL DROP VECTOR INDEX.

Ad esempio:

DROP VECTOR INDEX my_index ON my_dataset.indexed_table;

Se viene eliminata una tabella indicizzata, il relativo indice viene eliminato automaticamente.

Passaggi successivi

• Per una panoramica dei casi d'uso, dei prezzi e delle limitazioni degli indici di vettori, consulta la sezione Introduzione alla ricerca di vettori.
• Prova il tutorial sulla ricerca di embedding con la ricerca vettoriale.