Utilizza gli indici AI
Puoi utilizzare la funzione AI.SEARCH per eseguire query sui dati, mentre BigQuery gestisce automaticamente la selezione delle colonne, l'ottimizzazione degli indici e la manutenzione continua.
Questo documento spiega come creare, monitorare ed eliminare gli indici AI e come eseguire query sui dati indicizzati.
Ruoli e autorizzazioni
Per ottenere le autorizzazioni necessarie per utilizzare gli indici AI, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:
-
Creare o eliminare un indice AI:
BigQuery Data Owner (
roles/bigquery.dataOwner) -
Esegui una query su una tabella:
- Visualizzatore dati BigQuery (
roles/bigquery.dataViewer) - BigQuery Job User (
roles/bigquery.jobUser)
- Visualizzatore dati BigQuery (
-
Visualizza i metadati dell'indice AI:
Visualizzatore dati BigQuery (
roles/bigquery.dataViewer)
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Crea un indice AI
Puoi creare un indice AI su una tabella BigQuery standard utilizzando l'istruzione Data Definition Language (DDL) CREATE AI INDEX. Puoi specificare le colonne da indicizzare o fare in modo che BigQuery selezioni automaticamente le colonne candidate utilizzando l'opzione AUTO COLUMNS.
Limitazioni alla creazione di indici AI
Quando crei un indice AI, si applicano le seguenti limitazioni:
- Sono supportate solo le colonne STRING di primo livello non ripetute.
ARRAY<STRING>,STRUCT,JSON,ObjectRef, i campi nidificati, le colonne nonSTRINGe le pseudocolonne non sono supportati. - Puoi indicizzare fino a 50 colonne in un singolo indice AI.
- Puoi creare un indice AI solo su una tabella BigQuery standard. Le viste, le viste materializzate, le tabelle esterne, le tabelle BigLake, le tabelle Apache Iceberg e gli snapshot delle tabelle non sono supportati.
- Non puoi creare indici AI in set di dati con repliche tra regioni.
- Quando esegui
CREATE AI INDEX, la tabella di base può avere al massimo 1.000.000 di righe per i progetti on demand o fino a 100.000.000 di righe se il progetto che contiene la tabella ha un'assegnazione di prenotazioneBACKGROUND. AUTO COLUMNSseleziona le colonne quando viene eseguita l'istruzioneCREATE AI INDEX. Se aggiungi colonne alla tabella in un secondo momento, queste non vengono indicizzate automaticamente. Per includere nuove colonne, elimina l'indice AI e crealo di nuovo.- Ogni tabella supporta al massimo un indice AI. Una tabella con un indice AI non può avere anche un indice vettoriale o una colonna di embedding generata automaticamente.
Per un elenco completo delle limitazioni, consulta Limitazioni degli indici AI.
Crea un indice AI con AUTO COLUMNS
Quando crei un indice AI con AUTO COLUMNS, BigQuery
analizza automaticamente lo schema della tabella e seleziona fino a 50 colonne idonee.
Per creare un indice AI con AUTO COLUMNS, utilizza l'istruzione DDL CREATE AI INDEX:
Vai a BigQuery Studio nella console Cloud de Confiance .
Nell'editor di query, esegui la seguente istruzione SQL:
CREATE AI INDEX INDEX_NAME ON DATASET_NAME.TABLE_NAME(AUTO COLUMNS);
Sostituisci quanto segue:
INDEX_NAME: il nome dell'indice AI che stai creando. Poiché l'indice viene sempre creato nello stesso progetto e set di dati della tabella di base, non è necessario specificare il progetto o il set di dati nel nome dell'indice. Il nome dell'indice deve essere univoco tra tutti gli indici della tabella.DATASET_NAME: il nome del set di dati che contiene la tabella.TABLE_NAME: il nome della tabella standard da indicizzare.
Nell'esempio seguente, viene creato un indice AI con AUTO COLUMNS su
mydataset.products:
CREATE AI INDEX products_ai_index ON mydataset.products(AUTO COLUMNS);
Crea un indice AI su colonne specifiche
Puoi creare un indice AI su una singola colonna o su un sottoinsieme specifico di colonne. Ad esempio, quando la tabella contiene più di 50 colonne idonee o quando vuoi escludere colonne sensibili o con un elevato livello di rumore, come ID opachi, UUID, hash o log non elaborati. Se specifichi più colonne, inserisci quelle più informative, ad esempio una colonna del titolo o del nome, all'inizio dell'elenco delle colonne.
Nell'esempio seguente, viene creato un indice AI solo sulle colonne name e description di mydataset.products:
CREATE AI INDEX products_ai_index ON mydataset.products(name, description);
Nell'esempio seguente, viene creato un indice AI solo nella colonna description di mydataset.products:
CREATE AI INDEX products_ai_index ON mydataset.products(description);
Cerca in una tabella con un indice AI
Puoi eseguire una query su una tabella con un indice AI utilizzando la funzione AI.SEARCH.
Quando una tabella ha un indice AI, sono necessari solo due argomenti:
base_table o base_table_query e query_value.
Cerca in tutte le colonne indicizzate
Per eseguire la ricerca in tutte le colonne coperte dall'indice AI, ometti l'argomento column_to_search e passa la tabella di base e la stringa di query.
L'esempio seguente esegue una ricerca in tutte le colonne di mydataset.products coperte dall'indice AI:
SELECT base.id, base.name, base.description, distance FROM AI.SEARCH( TABLE mydataset.products, 'shoes that keep your feet dry in the rain', top_k => 5) ORDER BY distance;
Monitora lo stato degli indici AI
Puoi monitorare lo stato, la copertura e le colonne indicizzate degli indici AI eseguendo query sulle seguenti viste INFORMATION_SCHEMA:
INFORMATION_SCHEMA.AI_INDEXES: contiene i metadati relativi a ogni indice AI di un set di dati.INFORMATION_SCHEMA.AI_INDEX_COLUMNS: elenca le colonne coperte da ogni indice AI in un set di dati, consentendoti di verificare quali colonne sono state selezionate quando utilizziAUTO COLUMNS.INFORMATION_SCHEMA.JOBS: contiene informazioni sui job in background, inclusi quelli utilizzati per creare e gestire gli indici AI.
Esempio di indice AI
La seguente query mostra la copertura e le dimensioni di archiviazione di tutti gli indici AI in my_project.my_dataset:
SELECT table_name, index_name, creation_time, coverage_percentage, unindexed_row_count, total_logical_bytes FROM my_project.my_dataset.INFORMATION_SCHEMA.AI_INDEXES;
Il risultato è simile al seguente:
+------------+-------------------+---------------------+---------------------+---------------------------+-----------------------+
| table_name | index_name | creation_time | coverage_percentage | unindexed_row_count | total_logical_bytes |
+------------+-------------------+---------------------+---------------------+---------------------------+-----------------------+
| products | products_ai_index | 2026-10-01 18:02:11 | 100 | 0 | 25344 |
+------------+-------------------+---------------------+---------------------+---------------------------+-----------------------+
Esempio di colonne indice AI
La seguente query elenca le colonne indicizzate per gli indici AI in my_project.my_dataset:
SELECT table_name, index_name, index_column_name FROM my_project.my_dataset.INFORMATION_SCHEMA.AI_INDEX_COLUMNS;
Il risultato è simile al seguente:
+------------+-------------------+-------------------+
| table_name | index_name | index_column_name |
+------------+-------------------+-------------------+
| products | products_ai_index | name |
| products | products_ai_index | description |
| products | products_ai_index | category |
| products | products_ai_index | review |
+------------+-------------------+-------------------+
Esempio di monitoraggio dei costi dei job in background
Per monitorare i valori total_slot_ms e total_bytes_billed per i job di trattamento dati di indicizzazione AI in background su una tabella, esegui una query sulla vista INFORMATION_SCHEMA.JOBS per i job con un prefisso job_id di gc_:
SELECT job_id, creation_time, reservation_id, total_slot_ms, total_bytes_processed, total_bytes_billed FROM `region-REGION`.INFORMATION_SCHEMA.JOBS j WHERE EXISTS ( SELECT 1 FROM UNNEST(j.referenced_tables) t WHERE j.project_id = 'PROJECT_ID' AND t.dataset_id = 'DATASET_ID' AND t.table_id = 'TABLE' ) AND STARTS_WITH(job_id, 'gc_') ORDER BY j.creation_time DESC;
Sostituisci quanto segue:
REGION: la regione del set di dati che contiene la tabella, ad esempio us.PROJECT_ID: l'ID del progetto che contiene la tabella.DATASET_ID: il nome del set di dati che contiene la tabella.TABLE: il nome della tabella che contiene l'indice AI.
Elimina un indice AI
Quando elimini una tabella indicizzata, viene eliminato anche il relativo indice AI. Per eliminare un indice AI senza eliminare la tabella, utilizza l'istruzione DDL DROP AI INDEX:
DROP AI INDEX IF EXISTS INDEX_NAME ON DATASET_NAME.TABLE_NAME;
Sostituisci quanto segue:
INDEX_NAME: il nome dell'indice AI che stai eliminando.DATASET_NAME: il nome del set di dati che contiene la tabella.TABLE_NAME: il nome della tabella che contiene l'indice AI.
Passaggi successivi
- Scopri di più sulla funzione
AI.SEARCH. - Scopri di più sugli embedding in BigQuery.