Gerar insights de tabelas

Com os insights de tabela do BigQuery, é possível entender rapidamente a estrutura e o conteúdo de tabelas padrão do BigQuery, tabelas externas do BigQuery e tabelas do BigLake sem escrever consultas complexas. É possível gerar consultas SQL com base em perguntas em linguagem natural, o que reduz o tempo e o esforço necessários para escrever consultas manualmente.

Para uma visão geral dos insights de tabelas e conjuntos de dados, consulte Visão geral dos insights de dados.

Modos para gerar insights de dados de tabela

Ao gerar insights de tabelas, o BigQuery oferece dois modos:

Modo Descrição Uso
Gerar e publicar (pré-lançamento)

Mantém os insights de tabela gerados no Knowledge Catalog como aspectos de metadados. Você precisa ter as permissões necessárias para publicar. Quando você usa Gerar e publicar, as seguintes ações ocorrem:

  • Armazena descrições de tabelas e colunas no Knowledge Catalog.
  • Captura consultas e perguntas sugeridas como aspectos reutilizáveis.
  • Disponibiliza os insights publicados para todos os usuários que têm o acesso adequado ao Knowledge Catalog, garantindo o compartilhamento do conhecimento organizacional.
  • Permite editar e salvar descrições diretamente no Knowledge Catalog.

Use esse modo para documentação de dados em toda a empresa que seja persistente e reutilizável ou ao criar fluxos de trabalho de governança orientados por catálogo.
Gerar sem publicar

Cria insights de tabela, como descrições, perguntas em linguagem natural e consultas SQL sob demanda. A opção Gerar sem publicar não publica insights no Knowledge Catalog.

Use esse modo para uma análise rápida e ad hoc para evitar sobrecarregar o catálogo.

Antes de começar

Os insights de dados são gerados usando o Gemini no BigQuery. Para começar a gerar insights, primeiro você precisa configurar o Gemini no BigQuery.

Ativar APIs

Para usar insights de dados, ative as seguintes APIs no seu projeto: API Dataplex, API BigQuery e API Gemini para Google Cloud.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Para mais informações sobre como ativar a API Gemini para Google Cloud, consulte Ativar a API Gemini para Google Cloud em um projeto do Google Cloud .

Papéis e permissões

Para criar, gerenciar e recuperar insights de dados, peça ao administrador para conceder os seguintes papéis do Identity and Access Management (IAM):

Para ter acesso somente leitura aos insights gerados, peça ao administrador para conceder a você o seguinte papel do IAM:

Para publicar insights de dados no Knowledge Catalog, peça ao administrador para conceder a você os seguintes papéis do IAM no recurso:

Para ativar as APIs, peça ao administrador para conceder a você o seguinte papel do IAM:

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 receber as permissões necessárias com papéis personalizados ou outros papéis predefinidos. Para conferir as permissões exatas necessárias para gerar insights, abra a seção Permissões necessárias:

Permissões necessárias

  • bigquery.jobs.create
  • bigquery.tables.get
  • bigquery.tables.getData
  • dataplex.datascans.create
  • dataplex.datascans.get
  • dataplex.datascans.getData
  • dataplex.datascans.run

Gerar insights para uma tabela do BigQuery

Para gerar insights de tabelas do BigQuery, use o console doGoogle Cloud ou o tipo de verificação DATA_DOCUMENTATION compatível com a API DataScans do Knowledge Catalog. Essas verificações geram metadados, consultas SQL para análise de dados, descrições de esquema e resumos no nível da tabela.

Console

Para gerar insights de uma tabela do BigQuery, acesse a entrada da tabela no BigQuery usando o BigQuery Studio.

  1. No console do Google Cloud , acesse o BigQuery Studio.

    Acessar o BigQuery Studio

  2. No painel Explorer, selecione o projeto, o conjunto de dados e a tabela para gerar insights.

  3. Clique na guia Insights.

    Se a guia estiver vazia, os insights ainda não foram gerados para essa tabela.

  4. Para gerar insights, clique em Gerar.

  5. Selecione a condição de publicação:

    • Para gerar e anexar permanentemente insights ao recurso como aspectos de metadados, ative a opção Condição de publicação. Isso torna os insights indexáveis, pesquisáveis e visíveis para outros usuários na sua organização.

    • Para gerar e visualizar insights temporariamente durante a sessão atual, desative a opção Condição de publicação.

    Para mais informações sobre as diferenças entre os modos Gerar e publicar e Gerar sem publicar, consulte Modos para gerar insights de dados.

  6. Opcional: no campo Instruções personalizadas, forneça orientações e contexto de domínio para personalizar como o Gemini gera insights.

    Por exemplo, é possível aplicar convenções de nomenclatura, especificar definições de negócios ou descrever chaves de mesclagem:

    LANGUAGE: Always write column descriptions in uppercase.

DOMAIN_CONTEXT:
- This dataset supports the Order-to-Cash process for the EMEA commercial
  sales team.
- Primary consumers are finance analysts and regional sales managers, not
  engineers.

RELATIONSHIPS:
- returns.order_item_id → order_items.id (one-to-one; use LEFT JOIN to
  preserve unreturned items)

  7. Selecione uma região para gerar insights e clique em Gerar.

    Leva alguns minutos para que os insights sejam preenchidos.

    Se os resultados publicados da criação de perfil de dados da tabela estiverem disponíveis, eles serão usados para gerar insights. Caso contrário, os insights são gerados com base nos nomes e descrições das colunas. Para mais informações, consulte Práticas recomendadas para gerar insights de dados.

  8. Na guia Insights, confira as perguntas em linguagem natural geradas.

  9. Para ver a consulta SQL que responde a uma pergunta, clique nela.

  10. Para abrir uma consulta no BigQuery, clique em Copiar para consulta.

  11. Para fazer perguntas complementares, siga estas etapas:

    1. Clique em Faça outra pergunta. A consulta é aberta em uma nova tela de dados.

    2. Clique em Executar e em Consultar estes resultados.

    3. Para fazer uma pergunta complementar, insira um comando no campo de comando de linguagem natural ou edite o SQL no editor de consultas.

  12. Para gerar um novo conjunto de consultas, clique em Gerar insights e acione o pipeline novamente.

Depois de gerar insights para uma tabela, qualquer pessoa com a permissão dataplex.datascans.getData e acesso à tabela poderá visualizar esses insights.

REST

Para gerar insights de forma programática, use a API DataScans do Knowledge Catalog. Para isso, siga as seguintes etapas:

  1. Opcional: criar uma verificação do perfil de dados para a tabela
  2. Gerar uma verificação de documentação de dados para a tabela do BigQuery
  3. Verificar o status do scanner de documentos
  4. Publicar os resultados da verificação da documentação de dados na tabela do BigQuery

Opcional: criar uma verificação do perfil de dados para a tabela

A presença de verificações do perfil de dados reduz as alucinações e aproximações do Gemini, já que elas fundamentam a saída em valores reais presentes nos dados.

Para criar e executar uma verificação do perfil de dados, siga estas etapas:

  1. Crie uma verificação do perfil de dados usando o método dataScans.create.

  2. Execute a verificação do perfil de dados usando o método dataScans.run. Aguarde a conclusão da execução.

  3. Publique os resultados da verificação na tabela do BigQuery anexando os seguintes rótulos de criação de perfil de dados à tabela:

    • dataplex-dp-published-scan:DATASCAN_ID
    • dataplex-dp-published-project:PROJECT_ID
    • dataplex-dp-published-location:LOCATION

    Para mais informações, consulte Adicionar rótulos a tabelas e visualizações.

Gerar uma verificação de documentação de dados para a tabela do BigQuery

Você pode executar uma verificação gerenciada padrão ou uma verificação única simplificada.

Opção A: verificação gerenciada padrão (criar + executar)

Use esse método se quiser gerenciar o recurso de verificação ao longo do tempo.

  1. Crie uma verificação de documentação de dados usando o método dataScans.create.

É possível personalizar o escopo da geração para incluir esquemas, descrições, consultas ou uma combinação usando o parâmetro generation_scopes. Se quiser, publique esses insights no Knowledge Catalog definindo o parâmetro catalogPublishingEnabled como true.

  • Para gerar esquemas, descrições de tabelas e consultas SQL, deixe data_documentation_spec vazio ou defina generation_scopes como ALL. Exemplo:

      gcurl -X POST \
  https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
  dataScans?dataScanId=DATASCAN_ID \
  -d '{
    "data": {
      "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
  datasets/DATASET_ID/tables/TABLE_ID"
    },
    "executionSpec": {
      "trigger": { "onDemand": {} }
    },
    "type": "DATA_DOCUMENTATION",
    "dataDocumentationSpec": {
      "generationScopes": "ALL"
      "catalogPublishingEnabled": true
    }
  }'

    Substitua:

    • PROJECT_ID: o ID do projeto do Google Cloud em que o conjunto de dados reside.
    • LOCATION: a região em que a verificação de dados é executada.
    • DATASCAN_ID: um nome exclusivo que você fornece para esta verificação
    • DATASET_ID: o ID do conjunto de dados do BigQuery que está sendo verificado.
    • TABLE_ID: o ID da tabela do BigQuery que está sendo verificada.

  • Para gerar o esquema, as descrições de tabelas e as descrições de colunas, sem consultas SQL, defina generation_scopes como TABLE_AND_COLUMN_DESCRIPTIONS. Exemplo:

      gcurl -X POST \
  https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
  dataScans?dataScanId=DATASCAN_ID \
  -d '{
    "data": {
      "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
  datasets/DATASET_ID/tables/TABLE_ID"
    },
    "executionSpec": {
      "trigger": { "onDemand": {} }
    },
    "type": "DATA_DOCUMENTATION",
    "dataDocumentationSpec": {
      "generationScopes": "TABLE_AND_COLUMN_DESCRIPTIONS"
      "catalogPublishingEnabled": true
    }
  }'

  • Para gerar consultas SQL sem descrições, defina generation_scopes como SQL_QUERIES. Exemplo:

      gcurl -X POST \
  https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
  dataScans?dataScanId=DATASCAN_ID \
  -d '{
    "data": {
      "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
  datasets/DATASET_ID/tables/TABLE_ID"
    },
    "executionSpec": {
      "trigger": { "onDemand": {} }
    },
    "type": "DATA_DOCUMENTATION",
    "dataDocumentationSpec": {
      "generationScopes": "SQL_QUERIES"
      "catalogPublishingEnabled": true
    }
  }'

  1. Inicie o job de verificação de documentação de dados usando o método dataScans.run.

    Exemplo:

    gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans/DATASCAN_ID:run

    Essa solicitação retorna um ID da tarefa exclusivo com o estado inicial.

Opção B: verificação única (simplificada)

Use esse método para iniciar e concluir uma verificação em uma única chamada de API. Esse método elimina a necessidade de chamar o método run separadamente e permite a exclusão automática do recurso de verificação usando a funcionalidade de time to live (TTL).

Crie e acione a verificação usando o método dataScans.create. Exemplo:

gcurl -X POST \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?\
dataScanId=DATASCAN_ID" \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/\
    tables/TABLE_ID"
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generationScopes": "ALL",
    "catalogPublishingEnabled": true
  }
  "executionSpec": {
    "trigger": {
      "one_time": {
        "ttl_after_scan_completion": { "seconds": TTL_TIME }
      }
    }
  }
}'

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud em que o conjunto de dados reside.
  • LOCATION: a região em que a verificação de dados é executada.
  • DATASCAN_ID: um nome exclusivo que você fornece para esta verificação
  • DATASET_ID: o ID do conjunto de dados do BigQuery que está sendo verificado.
  • TABLE_ID: o ID da tabela do BigQuery que está sendo verificada
  • TTL_TIME: a duração em segundos após a qual o recurso de verificação deve ser excluído automaticamente (por exemplo, 3600 para uma hora)

Verificar o status do scanner de documentos

Verifique a conclusão da execução do job de verificação usando o método dataScans.get.

Use o ID da tarefa para buscar o status dela. Exemplo:

gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN_ID/jobs/JOB_ID

O job é concluído quando o status é SUCCEEDED ou FAILURE.

Publicar os resultados da verificação de documentação de dados na tabela do BigQuery

Para publicar os resultados da verificação na tabela do BigQuery, anexe os seguintes rótulos de documentação de dados à tabela:

  • dataplex-data-documentation-published-scan:DATASCAN_ID
  • dataplex-data-documentation-published-project:PROJECT_ID
  • dataplex-data-documentation-published-location:LOCATION

Gerar insights para uma tabela externa do BigQuery

Os insights de dados do BigQuery oferecem suporte à geração de insights para tabelas externas do BigQuery com dados no Cloud Storage. Você e a conta de serviço do Knowledge Catalog para o projeto atual precisam ter o papel de Leitor de objetos do Storage (roles/storage.objectViewer) no bucket do Cloud Storage que contém os dados. Para mais informações, consulte Adicionar um principal a uma política no nível do bucket.

Para gerar insights de uma tabela externa do BigQuery, siga as instruções descritas na seção Gerar insights de uma tabela do BigQuery deste documento.

Gerar insights para uma tabela do BigLake

Para gerar insights para uma tabela do BigLake, siga estas etapas:

  1. Ative a API BigQuery Connection no projeto.

    Ative a API BigQuery Connection.

  2. Criar uma conexão do BigQuery. Para mais informações, consulte Gerenciar conexões.

  3. Conceda o papel do IAM de Leitor de objetos do Storage (roles/storage.objectViewer) à conta de serviço correspondente à conexão do BigQuery que você criou.

    Você pode recuperar o ID da conta de serviço nos detalhes da conexão.

  4. Para gerar insights, siga as instruções descritas na seção Gerar insights para uma tabela do BigQuery deste documento.

Gerar descrições de tabelas e colunas

O Gemini no BigQuery gera automaticamente descrições de tabelas e colunas quando você gera insights de dados. É possível editar essas descrições conforme necessário e salvá-las nos metadados da tabela. As descrições salvas são usadas para gerar insights futuros.

Idioma de geração de controle

Você pode orientar o Gemini para gerar descrições de tabelas e colunas em um idioma específico. Para fazer isso, use o campo Instrução personalizada para adicionar uma diretiva curta (por exemplo, "Gerar descrições de tabelas e colunas usando o idioma francês") à descrição atual da tabela antes de gerar os insights de dados.

Ao gerar insights gerados, o Gemini interpreta essas instruções e produz os metadados no idioma solicitado. Esse mecanismo funciona porque o Gemini usa as descrições de tabela atuais como contexto ao gerar novas.

Para uma lista de idiomas compatíveis, consulte Compatibilidade com idiomas do Gemini.

Gerar descrições

Para gerar descrições de tabelas e colunas, siga estas etapas:

  1. Gere insights seguindo as instruções descritas na seção relevante deste documento:

  2. Clique na guia Detalhes.

  3. Ao lado de Informações da tabela, clique em Ver descrições.

    As descrições geradas para a tabela e as colunas são exibidas.

  4. Para editar e salvar a descrição da tabela gerada, faça o seguinte:

    1. Na seção Descrição da tabela, clique em Salvar nos detalhes.

    2. Para substituir a descrição atual pela gerada, clique em Copiar descrição sugerida.

    3. Edite a descrição da tabela conforme necessário e clique em Salvar nos detalhes.

      A descrição da tabela é atualizada imediatamente.

  5. Para editar e salvar as descrições de coluna geradas, faça o seguinte:

    1. Na seção Descrições de colunas, clique em Salvar no esquema.

      As descrições de coluna geradas são preenchidas no campo Nova descrição de cada coluna.

    2. Edite as descrições das colunas conforme necessário e clique em Salvar.

      As descrições das colunas são atualizadas imediatamente.

  6. Para fechar o painel de visualização, clique em Fechar.

Práticas recomendadas para gerar insights de dados

Para melhorar a precisão dos insights gerados, siga estas recomendações:

  • Forneça descrições abrangentes. Verifique se as tabelas e colunas no conjunto de dados têm descrições claras e detalhadas.

  • Embasar insights com a criação de perfil. Se as descrições não estiverem disponíveis, verifique se uma verificação de perfil está vinculada a cada tabela no conjunto de dados para ajudar a fundamentar os insights gerados.

  • Defina regras de forma explícita. Inclua todas as relações ou lógica de negócios que o módulo de insights usa para influenciar a geração de relações na descrição da respectiva tabela.

Basear insights nos resultados da criação de perfil de dados

Na IA generativa, embasamento é a capacidade de conectar a saída do modelo a fontes de informações verificáveis. É possível embasar os insights de tabela gerados nos resultados da criação de perfil de dados. A criação de perfil de dados analisa as colunas nas tabelas do BigQuery e identifica características estatísticas comuns, como valores de dados típicos e distribuição de dados.

Ao criar uma verificação do perfil de dados em uma tabela, é possível publicar os resultados da verificação nas páginas do BigQuery e do Knowledge Catalog no console do Google Cloud . Os insights usam os resultados da criação de perfil de dados para criar consultas mais precisas e relevantes, fazendo o seguinte:

  1. Analisa os resultados da criação de perfil de dados para identificar padrões, tendências ou outliers interessantes nos dados.

  2. Gera consultas focadas nesses padrões, tendências ou outliers para descobrir insights.

  3. Valida as consultas geradas em relação aos resultados da criação de perfil de dados para garantir que as consultas retornem resultados significativos.

Sem as verificações do perfil de dados, acontece o seguinte:

  • As consultas geradas têm mais chances de incluir cláusulas imprecisas ou produzir resultados sem sentido.

  • As descrições de coluna geradas são baseadas apenas no nome da coluna.

Verifique se a verificação do perfil de dados da tabela está atualizada e se os resultados foram publicados no BigQuery.

É possível ajustar as configurações de criação de perfil de dados para aumentar o tamanho da amostra e filtrar linhas e colunas. Depois de executar uma nova verificação do perfil de dados, gere novamente os insights.

A qualidade dos insights do conjunto de dados também melhora significativamente se as tabelas no conjunto de dados tiverem resultados de criação de perfil de dados.

Adicionar uma descrição de tabela

Descrições detalhadas que descrevem o que você quer analisar na tabela podem ajudar o Gemini no BigQuery a produzir insights mais relevantes para insights de tabelas e conjuntos de dados. Depois de adicionar uma descrição de tabela, gere os insights novamente.

Por exemplo, é possível adicionar a seguinte descrição a uma tabela telco_churn, como a usada em Exemplo de insights de dados de tabela:

This table tracks customer churn data, including subscription details, tenure,
and service usage, to predict customer churn behavior.

Se você salvar a descrição da tabela gerada pelo Gemini, ela será usada para gerar insights futuros.

Adicionar uma descrição de coluna

As descrições de colunas que explicam o que cada coluna é ou como uma coluna se relaciona com outra podem melhorar a qualidade dos insights para insights de tabelas e conjuntos de dados. Depois de atualizar as descrições das colunas na tabela, gere os insights novamente.

Por exemplo, é possível adicionar as seguintes descrições a colunas específicas de uma tabela telco_churn, como a usada em Exemplo de insights de dados de tabela:

Para a coluna tenure:

The number of months the customer has been with the service.

Para a coluna churn:

Whether the customer has stopped using the service. TRUE indicates the customer
no longer uses the service, FALSE indicates the customer is active.

Se você salvar as descrições de coluna geradas pelo Gemini, elas serão usadas para gerar insights futuros.

Gerenciar insights gerados

Depois de gerar insights para uma tabela, é possível gerenciá-los, atualizá-los ou excluí-los no Knowledge Catalog. Para mais informações, consulte Gerenciar insights de tabelas.

A seguir