Usar índices de IA
Use a função
AI.SEARCH
para consultar seus dados enquanto o BigQuery processa automaticamente
a seleção de colunas, a otimização de índices e a manutenção contínua.
Neste documento, explicamos como criar, monitorar e excluir índices de IA e como consultar os dados indexados.
Papéis e permissões
Para receber as permissões necessárias para usar os índices de IA, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:
-
Criar ou descartar um índice de IA:
Proprietário de dados do BigQuery (
roles/bigquery.dataOwner) -
Consultar uma tabela:
- Visualizador de dados do BigQuery (
roles/bigquery.dataViewer) - Usuário de jobs do BigQuery (
roles/bigquery.jobUser)
- Visualizador de dados do BigQuery (
-
Acessar metadados do índice de IA:
Visualização de Dados do BigQuery (
roles/bigquery.dataViewer)
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.
Criar um índice de IA
É possível criar um índice de IA em uma tabela do BigQuery padrão usando a instrução de linguagem de definição de dados (DDL) CREATE AI INDEX. É possível especificar as colunas a serem indexadas ou fazer com que o BigQuery selecione automaticamente as colunas candidatas usando a opção AUTO COLUMNS.
Limitações na criação de índices de IA
Ao criar um índice de IA, as seguintes limitações se aplicam:
- Somente colunas STRING de nível superior e não repetidas são compatíveis.
ARRAY<STRING>,STRUCT,JSON,ObjectRef, campos aninhados, colunas que não sãoSTRINGe pseudocolunas não são compatíveis. - É possível indexar até 50 colunas em um único índice de IA.
- Só é possível criar um índice de IA em uma tabela padrão do BigQuery. Não há suporte para visualizações, visualizações materializadas, tabelas externas, tabelas do BigLake, tabelas do Apache Iceberg e snapshots de tabela.
- Não é possível criar índices de IA em conjuntos de dados que têm réplicas entre regiões.
- Quando você executa
CREATE AI INDEX, a tabela base pode ter no máximo 1.000.000 de linhas para projetos on demand ou até 100.000.000 de linhas se o projeto que contém a tabela tiver uma atribuição de reservaBACKGROUND. AUTO COLUMNSseleciona colunas quando a instruçãoCREATE AI INDEXé executada. Se você adicionar colunas à tabela mais tarde, elas não serão indexadas automaticamente. Para incluir novas colunas, remova o índice de IA e crie-o novamente.- Cada tabela aceita no máximo um índice de IA. Uma tabela com um índice de IA não pode ter um índice vetorial ou uma coluna de embedding gerada automaticamente.
Para uma lista completa de limitações, consulte Limitações em índices de IA.
Criar um índice de IA com AUTO COLUMNS
Quando você cria um índice de IA com AUTO COLUMNS, o BigQuery
verifica automaticamente o esquema da tabela e seleciona até 50 colunas qualificadas.
Para criar um índice de IA com AUTO COLUMNS, use a instrução DDL
CREATE AI INDEX:
Acesse o BigQuery Studio no console do Cloud de Confiance .
No editor de consultas, execute a seguinte instrução SQL:
CREATE AI INDEX INDEX_NAME ON DATASET_NAME.TABLE_NAME(AUTO COLUMNS);
Substitua:
INDEX_NAME: o nome do índice de IA que você está criando. Como o índice é sempre criado no mesmo projeto e conjunto de dados da tabela base, não é necessário especificá-los no nome do índice. O nome do índice precisa ser exclusivo entre todos os índices da tabela.DATASET_NAME: o nome do conjunto de dados que contém a tabela.TABLE_NAME: o nome da tabela padrão a ser indexada.
No exemplo a seguir, um índice de IA é criado com AUTO COLUMNS em mydataset.products:
CREATE AI INDEX products_ai_index ON mydataset.products(AUTO COLUMNS);
Criar um índice de IA em colunas específicas
É possível criar um índice de IA em uma única coluna ou em um subconjunto específico de colunas. Por exemplo, quando a tabela tem mais de 50 colunas qualificadas ou quando você quer excluir colunas sensíveis ou com muito ruído, como IDs opacos, UUIDs, hashes ou registros brutos. Se você especificar várias colunas, coloque as mais informativas, como uma coluna de título ou nome, primeiro na lista de colunas.
No exemplo a seguir, um índice de IA é criado apenas nas colunas name e description de mydataset.products:
CREATE AI INDEX products_ai_index ON mydataset.products(name, description);
No exemplo a seguir, um índice de IA é criado apenas na coluna description
de mydataset.products:
CREATE AI INDEX products_ai_index ON mydataset.products(description);
Pesquisar uma tabela com um índice de IA
É possível consultar uma tabela que tenha um índice de IA usando a função AI.SEARCH.
Quando uma tabela tem um índice de IA, apenas dois argumentos são obrigatórios:
base_table ou base_table_query e query_value.
Pesquisar em todas as colunas indexadas
Para pesquisar em todas as colunas cobertas pelo índice de IA, omita o argumento column_to_search e transmita a tabela base e a string de consulta.
O exemplo a seguir pesquisa todas as colunas em mydataset.products que são
cobertas pelo índice de IA:
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;
Monitorar o status dos índices de IA
É possível monitorar o status, a cobertura e as colunas indexadas dos índices de IA
consultando as seguintes visualizações INFORMATION_SCHEMA:
INFORMATION_SCHEMA.AI_INDEXES: contém metadados sobre cada índice de IA em um conjunto de dados.INFORMATION_SCHEMA.AI_INDEX_COLUMNS: lista as colunas cobertas por cada índice de IA em um conjunto de dados, permitindo verificar quais colunas foram selecionadas ao usarAUTO COLUMNS.INFORMATION_SCHEMA.JOBS: contém informações sobre jobs em segundo plano, incluindo os usados para criar e manter índices de IA.
Exemplo de índice de IA
A consulta a seguir mostra a cobertura e o tamanho de armazenamento de todos os índices de IA em
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;
O resultado será semelhante ao seguinte:
+------------+-------------------+---------------------+---------------------+---------------------------+-----------------------+
| 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 |
+------------+-------------------+---------------------+---------------------+---------------------------+-----------------------+
Exemplo de colunas de índice de IA
A consulta a seguir lista as colunas indexadas para índices de IA em
my_project.my_dataset:
SELECT table_name, index_name, index_column_name FROM my_project.my_dataset.INFORMATION_SCHEMA.AI_INDEX_COLUMNS;
O resultado será semelhante ao seguinte:
+------------+-------------------+-------------------+
| 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 |
+------------+-------------------+-------------------+
Exemplo de rastreamento de custos de jobs em segundo plano
Para acompanhar os valores de total_slot_ms e total_bytes_billed para jobs de tratamento de dados de índice de IA em segundo plano em uma tabela, consulte a visualização INFORMATION_SCHEMA.JOBS para jobs com um prefixo job_id de 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;
Substitua:
REGION: a região do conjunto de dados que contém a tabela, por exemplo, us.PROJECT_ID: o ID do projeto que contém a tabela.DATASET_ID: o nome do conjunto de dados que contém a tabela.TABLE: o nome da tabela que contém o índice de IA.
Excluir um índice de IA
Quando você exclui uma tabela indexada, o índice de IA dela também é excluído. Para excluir um índice de IA sem excluir a tabela, use a instrução DDL DROP AI INDEX:
DROP AI INDEX IF EXISTS INDEX_NAME ON DATASET_NAME.TABLE_NAME;
Substitua:
INDEX_NAME: o nome do índice de IA que você está excluindo.DATASET_NAME: o nome do conjunto de dados que contém a tabela.TABLE_NAME: o nome da tabela que contém o índice de IA.
A seguir
- Saiba mais sobre a função
AI.SEARCH. - Saiba mais sobre embeddings no BigQuery.