Gerar insights da tabela

Este documento descreve como gerar insights de tabelas do BigQuery, do BigLake e externas. Com os insights de tabela, você entende os dados em uma única tabela gerando perguntas em linguagem natural e consultas SQL com base nos metadados da tabela.

Os insights da tabela ajudam a acelerar a análise de dados, permitindo que você entenda rapidamente a estrutura e o conteúdo de uma tabela nova ou desconhecida sem escrever consultas complexas. Também é 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. Os insights da tabela também podem ajudar usuários que não usam SQL a entender e analisar dados com essas consultas em linguagem natural.

Para uma visão geral das informações sobre tabelas e conjuntos de dados, consulte Visão geral das informações de dados.

Modos para gerar insights de dados da tabela

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

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

Persiste insights de tabelas gerados no Dataplex Universal 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 Dataplex Universal Catalog.
  • Captura consultas e perguntas sugeridas como aspectos reutilizáveis.
  • Torna os insights publicados acessíveis a todos os usuários com acesso adequado ao Dataplex Universal Catalog, garantindo o conhecimento organizacional compartilhado.
  • Permite editar e salvar descrições diretamente no Dataplex Universal Catalog.

Use esse modo para documentação de dados em toda a empresa que persista e seja 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 Dataplex Universal Catalog.

Use esse modo para uma análise rápida e ad hoc e evite poluir 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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

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 Dataplex Universal Catalog, peça ao administrador para conceder a você os seguintes papéis do IAM no recurso:

Para ativar 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 consoleGoogle Cloud ou o tipo de verificação DATA_DOCUMENTATION compatível com o Universal Catalog do Dataplex API DataScans. 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, isso significa que os insights da tabela ainda não foram gerados.

  4. Para gerar insights e publicá-los no Dataplex Universal Catalog, clique em Gerar e publicar (Prévia).

    Para gerar insights sem publicá-los no Dataplex Universal Catalog, clique em Gerar sem publicar.

    Para mais informações sobre as diferenças entre os modos Gerar e publicar e Gerar sem publicar, consulte Modos de geração de insights.

  5. 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 para a 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 melhorar os insights gerados.

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

  7. Para conferir a consulta SQL que responde a uma pergunta, clique nela.

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

  9. Para fazer perguntas complementares, faça o seguinte:

    1. Clique em Fazer outra pergunta. A consulta é aberta em uma nova tela de dados.

    2. Clique em Executar e depois em Consultar estes resultados.

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

  10. 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 maneira programática, use a API DataScans do Dataplex Universal 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 dados de documentação de dados para a tabela do BigQuery
  3. Verificar o status da verificação da documentação de dados
  4. Publicar os resultados da verificação de documentação de dados na tabela do BigQuery

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

A presença de verificações de 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:

    • 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 dados 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 dados de documentação de dados usando o método dataScans.create. É possível personalizar o escopo da geração para incluir esquema, descrições, consultas ou uma combinação usando o parâmetro generation_scopes:

    • Para gerar esquema, 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": {
    "generation_scopes": "ALL"
  }
}'

      Substitua:

      • PROJECT_ID: o ID do seu projeto Google Cloud em que o conjunto de dados está localizado
      • LOCATION: a região em que a verificação de dados é executada.
      • DATASCAN_ID: um nome exclusivo que você fornece para essa 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": {
    "generation_scopes": "TABLE_AND_COLUMN_DESCRIPTIONS"
  }
}'

    • 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": {
    "generation_scopes": "SQL_QUERIES"
  }
}'

  2. Inicie o job de verificação da 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 de job exclusivo e 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 tempo de vida (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": { "generation_scopes": "ALL" },
  "executionSpec": {
    "trigger": {
      "one_time": {
        "ttl_after_scan_completion": { "seconds": TTL_TIME }
      }
    }
  }
}'

Substitua:

  • PROJECT_ID: o ID do seu projeto Google Cloud em que o conjunto de dados está localizado
  • LOCATION: a região em que a verificação de dados é executada.
  • DATASCAN_ID: um nome exclusivo que você fornece para essa 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 será excluído automaticamente (por exemplo, 3600 para uma hora)

Verificar o status da verificação da documentação de dados

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

Use o ID do job para buscar o status dele. 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 da 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 Dataplex Universal 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.

Controlar o idioma da geração

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

Quando você gera insights, o Gemini interpreta essa diretiva e produz os metadados no idioma solicitado. Esse mecanismo funciona porque o Gemini usa as descrições de tabelas 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. Para gerar insights, siga as instruções descritas na seção relevante deste documento:

  2. Clique na guia Esquema.

  3. Clique em Abrir descrições de coluna.

    A descrição da tabela e das colunas geradas são mostradas.

  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 em 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 colunas geradas, faça o seguinte:

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

      As descrições de colunas 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 de coluna são atualizadas imediatamente.

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

Práticas recomendadas para gerar insights de dados

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

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

  • Embasar insights com 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.

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

Fundamentar 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 usar os resultados da criação de perfil de dados como base para os insights de tabela gerados. A criação de perfil de dados analisa as colunas nas tabelas do BigQuery e identifica características estatísticas comuns, como valores e distribuição de dados típicos.

Ao criar uma verificação de criação de perfil de dados em uma tabela, é possível publicar os resultados da verificação nas páginas do BigQuery e do Dataplex Universal Catalog no console 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 de criação de perfil de dados, o seguinte acontece:

  • É mais provável que as consultas geradas incluam cláusulas imprecisas ou produzam 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 sua tabela está atualizada e se os resultados foram publicados no BigQuery.

Ajuste as configurações de criação de perfil de dados para aumentar o tamanho da amostragem 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 tiverem resultados de criação de perfil de dados.

Adicionar uma descrição da tabela

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

Por exemplo, você pode 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 da coluna

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

Por exemplo, você pode 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.

A seguir