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:

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 non STRING e 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 prenotazione BACKGROUND.
  • AUTO COLUMNS seleziona le colonne quando viene eseguita l'istruzione CREATE 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:

  1. Vai a BigQuery Studio nella console Google Cloud .

    Vai a BigQuery Studio

  2. 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:

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