Descobrir e catalogar dados do Cloud Storage

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Este documento explica como usar a descoberta automática de dados do Cloud Storage.

A descoberta automática do Dataplex é um recurso do BigQuery que permite verificar dados em buckets do Cloud Storage para extrair e catalogar metadados. Como parte da verificação, a descoberta automática cria tabelas do BigLake ou externas para dados estruturados e tabelas de objetos para dados não estruturados, que podem ser usados para análises e IA. As tabelas são automaticamente catalogadas no Dataplex Catalog, que pode ser pesquisado ou navegado.

Para usar a descoberta automática de dados do Cloud Storage, crie e execute uma verificação de descoberta.

Visão geral

Uma verificação de descoberta faz o seguinte:

• Verifica os dados no bucket ou caminho do Cloud Storage.
• Agrupe arquivos estruturados e semiestruturados em tabelas.
• Coleta metadados, como o nome da tabela, o esquema e a definição da partição.
• Cria e atualiza tabelas do BigLake, externas ou de objetos no BigQuery usando a definição de esquema e partição.

Para dados não estruturados, como imagens e vídeos, a verificação de descoberta detecta e registra grupos de arquivos que compartilham o mesmo tipo de mídia das tabelas de objetos do BigLake. Por exemplo, se gs://images/group1 contiver imagens GIF e gs://images/group2 imagens JPEG, a verificação de descoberta detectará e registrará dois conjuntos de arquivos.

Para dados estruturados, como o Avro, a verificação de descoberta registra grupos de arquivos como tabelas externas do BigLake e detecta arquivos apenas se eles estiverem localizados em pastas que contêm o mesmo formato de dados e esquema compatível.

A verificação de descoberta oferece suporte aos seguintes formatos de dados estruturados e semiestruturados:

• Parquet
• Avro
• ORC
• JSON (apenas o formato delimitado por nova linha)
• CSV (mas não arquivos CSV com linhas de comentários)

Observação: os formatos de tabela Iceberg e Delta Lake não são compatíveis com a verificação de descoberta.

A verificação de descoberta oferece suporte aos seguintes formatos de compactação para dados estruturados e semiestruturados:

• Compactação interna para os seguintes formatos:

  Compactação	Exemplo de extensão de arquivo	Formato aceito
  gzip	.gz.parquet	Parquet
  lz4	.lz4.parquet	Parquet
  Snappy	.snappy.parquet	Parquet, ORC, Avro
  lzo	.lzo.parquet	Parquet, ORC

• Compactação externa para arquivos JSON e CSV:

  • gzip
  • bzip2

Observação: a verificação de descoberta oferece suporte a até 1.000 tabelas do BigQuery por bucket do Cloud Storage.

As tabelas descobertas são registradas no BigQuery como tabelas externas, tabelas de objetos ou tabelas externas do BigLake. Isso disponibiliza os dados para análise no BigQuery. O armazenamento em cache de metadados para tabelas do BigLake e de objetos também é ativado. Todas as tabelas do BigLake são automaticamente incluídas no Dataplex Catalog para pesquisa e descoberta.

Antes de começar

Verifique se você tem as permissões necessárias do Identity and Access Management (IAM) para realizar as tarefas neste documento.

Papéis necessários para a conta de serviço

Antes de começar, atribua as permissões do IAM à conta de serviço do Dataplex no seu projeto:

  [e-mail]
  

Substitua PROJECT_NUMBER pelo projeto em que a API Dataplex está ativada.

Para garantir que a conta de serviço do Dataplex tenha as permissões necessárias para executar uma verificação de descoberta, peça ao administrador para conceder à conta de serviço do Dataplex os seguintes papéis do IAM:

• Usuário do BigQuery (roles/bigquery.user) no projeto da fonte de dados
• Leitor de objetos do Storage (roles/storage.objectViewer) no bucket da origem de dados
• Forneça uma conexão: Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para executar uma verificação de descoberta. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para executar uma verificação de descoberta:

• bigquery.datasets.create no projeto da fonte de dados
• storage.buckets.get no bucket da fonte de dados
• storage.objects.get no bucket da fonte de dados
• storage.objects.list no bucket da fonte de dados
• bigquery.datasets.get no projeto da fonte de dados
• Forneça uma conexão:
  • bigquery.connections.delegate
  • bigquery.connections.use

O administrador também pode conceder essas permissões à conta de serviço do Dataplex com papéis personalizados ou outros papéis predefinidos.

Observação: se você quiser usar uma conexão do BigQuery em tabelas do BigLake criadas pela descoberta automática, conceda o papel Storage Objects Reader à conta de serviço de conexão do BigQuery.

Funções obrigatórias para usuários finais

Para garantir que você tenha as permissões necessárias para usar a API DataScan, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Acesso total aos recursos do DataScan: Administrador do DataScan Dataplex (roles/dataplex.dataScanAdmin) no seu projeto
• Acesso de gravação aos recursos do DataScan: Editor do DataScan Dataplex (roles/dataplex.dataScanEditor) no seu projeto
• Acesso de leitura aos recursos do DataScan, excluindo os resultados: Leitor de dados do DataScan Dataplex (roles/dataplex.dataScanViewer) no seu projeto
• Acesso de leitura aos recursos do DataScan, incluindo os resultados: Leitor de dados do DataScan Dataplex (roles/dataplex.dataScanDataViewer) no seu projeto

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para usar a API DataScan. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para usar a API DataScan:

• Crie uma verificação de dados: dataplex.datascans.create no projeto
• Excluir uma verificação de dados: dataplex.datascans.delete no projeto ou em um recurso de verificação de dados
• Para conferir os detalhes da verificação de dados sem os resultados: dataplex.datascans.get no projetor um recurso de verificação de dados
• Acesse os detalhes do DataScan, incluindo os resultados: dataplex.datascans.getData no seu projeto ou em um recurso do DataScan
• Listar verificações de dados: dataplex.datascans.list no projeto ou em um recurso de verificação de dados
• Execute uma verificação de dados: dataplex.datascans.run no seu projeto ou em um recurso de verificação de dados
• Atualize a descrição de uma verificação de dados: dataplex.datascans.update no projetor um recurso de verificação de dados
• Confira as permissões do IAM do DataScan: dataplex.datascans.getIamPolicy no seu projeto ou em um recurso do DataScan
• Defina as permissões do IAM no DataScan: dataplex.datascans.setIamPolicy no seu projeto ou em um recurso do DataScan

O administrador também pode conceder essas permissões com papéis personalizados ou outros papéis predefinidos.

Criar uma verificação de descoberta

Para descobrir dados, você precisa criar e executar uma verificação de descoberta. É possível programar a verificação ou executá-la sob demanda. Para criar e executar uma verificação de descoberta, você precisa ter a permissão dataplex.datascans.create.

Quando a verificação de descoberta é executada, ela cria um novo conjunto de dados no BigQuery que corresponde ao bucket do Cloud Storage que foi verificado. O nome do conjunto de dados do BigQuery é o mesmo do bucket do Cloud Storage. Os caracteres inválidos no nome do bucket são substituídos por um sublinhado. Se o nome do conjunto de dados não estiver disponível, um sufixo será anexado (por exemplo, _discovered_001). O conjunto de dados contém as tabelas externas do BigLake ou que não são do BigLake que foram criadas pela verificação de descoberta para análise posterior.

Console

1. No Console do Google Cloud, acesse a página BigQuery.

   Acessar o BigQuery

2. No Explorer, clique em Adicionar.

3. No painel Add, na seção Popular sources, clique em Auto-create external and BigLake tables from GCS.

4. No painel Criar tabela, na seção Origem, configure os seguintes detalhes sobre os dados a serem verificados:

   1. Digite um nome para a verificação.
   2. No campo ID do scanner, insira um ID exclusivo que siga a convenção de nomenclatura de recursos. Se você não fornecer um ID, a verificação de descoberta vai gerar o ID da verificação.
   3. Opcional: forneça uma descrição da verificação.
   4. Para especificar o bucket do Cloud Storage que contém os arquivos a serem verificados, no campo Bucket, procure e selecione o bucket.

   5. Opcional: defina os dados a serem incluídos ou excluídos da verificação de descoberta fornecendo uma lista de padrões glob.

      • Incluir: se apenas um subconjunto dos dados precisar ser verificado, forneça uma lista de padrões de glob que correspondam aos objetos a serem incluídos.
      • Excluir: forneça uma lista de padrões glob que correspondem aos objetos a serem excluídos.

      Por exemplo, se você quiser excluir gs://test_bucket/foo/.. da verificação de descoberta, insira **/foo/* como o caminho de exclusão. As aspas causam erros. Insira **/foo/* em vez de "**/foo/*".

      Se você fornecer padrões de inclusão e exclusão, os padrões de exclusão serão aplicados primeiro.

   6. Para criar tabelas do BigLake com base nos dados digitalizados, no campo ID da conexão, forneça o ID da conexão de recursos do Google Cloud. Para mais informações, consulte Conexões de recursos do Google Cloud.

      Se você não fornecer um ID de conexão de recurso, o recurso de descoberta vai criar tabelas externas que não sejam do BigLake.

5. Na seção Frequência de descoberta, configure quando você quer que a verificação de descoberta seja executada:

   • Repetir: a verificação é executada em uma programação predefinida. Informe o horário de início, os dias para executar a verificação e a frequência, como a cada hora.

   • Sob demanda: a verificação é executada sob demanda.

6. Opcional: na seção Especificações JSON ou CSV, especifique como a verificação vai processar arquivos JSON e CSV. Clique em Especificações JSON ou CSV.

   1. Para configurar as opções JSON, selecione Ativar opções de análise JSON.
      • Desativar inferência de tipo: se a verificação de descoberta precisa inferir tipos de dados ao verificar dados. Se você desativar a inferência de tipo para dados JSON, todas as colunas serão registradas como tipos primitivos, como string, número ou booleano.
      • Formato de codificação: a codificação de caracteres dos dados, como UTF-8, US-ASCII ou ISO-8859-1. Se você não especificar um valor, o UTF-8 será usado como padrão.
   2. Para configurar as opções de CSV, marque Ativar opções de análise de CSV.
      • Desativar inferência de tipo: se a verificação de descoberta precisa inferir tipos de dados ao verificar dados. Se você desativar a inferência de tipo para dados CSV, todas as colunas serão registradas como strings.
      • Linhas de cabeçalho: o número de linhas de cabeçalho, 0 ou 1. Se você especificar o valor 0, a verificação de descoberta vai inferir os títulos e extrair os nomes das colunas do arquivo. O padrão é 0.
      • Caracter delimitador de coluna: o caractere usado para separar valores. Forneça um único caractere, \r (retorno de carro) ou \n (nova linha). O padrão é uma vírgula (,).
      • Formato de codificação: a codificação de caracteres dos dados, como UTF-8, US-ASCII ou ISO-8859-1. Se você não especificar um valor, o UTF-8 será usado como padrão.

7. Quando terminar de configurar a verificação de descoberta de dados, clique em Criar (para uma verificação programada) ou Executar agora (para uma verificação sob demanda).

   Uma verificação programada é executada de acordo com a programação que você definir.

   Uma verificação sob demanda é executada uma vez inicialmente quando você a cria e pode ser executada a qualquer momento. A verificação pode levar alguns minutos para ser concluída.

REST

Para criar uma verificação de descoberta, use o método dataScans.create.

Monitorar uma verificação de descoberta

Para monitorar os resultados de uma verificação de descoberta, consulte os registros criados quando uma verificação é executada.

Console

1. No console do Google Cloud, acesse a página do Explorador de registros.

   Acessar o "Explorador de registros"

2. Na visualização Análise de registros, encontre a guia Consulta.

3. Clique no menu Recurso.

4. Selecione DataScan do Cloud Dataplex. Clique em Aplicar.

5. Clique no menu Nome do registro.

6. No campo Pesquisar nomes de registros, insira dataplex.googleapis.com%2Fdata_scan. Selecione data_scan e clique em Aplicar.

7. Opcional: filtre os registros para um ID ou local de verificação de dados específico adicionando os seguintes filtros na consulta de registro:

   resource.type="dataplex.googleapis.com/DataScan"
   AND resource.labels.resource_container="projects/PROJECT_ID"
   AND resource.labels.datascan_id="DATA_SCAN_ID"
   

   Substitua:

   • PROJECT_ID: o ID do projeto do Google Cloud
   • DATA_SCAN_ID: o ID do DataScan

8. Clique em Executar consulta.

REST

Para monitorar uma verificação de descoberta, use o método dataScans.get.

Consultar tabelas publicadas do BigLake

Depois de executar a verificação de descoberta, as tabelas do BigLake são publicadas em um novo conjunto de dados no BigQuery e ficam disponíveis para análise no BigQuery usando SQL ou no Dataproc usando o Apache Spark, o Dataproc ou o HiveQL.

Consultar usando SQL

É possível consultar ou consultar tabelas no BigQuery. Para mais informações sobre como executar consultas no BigQuery, consulte Executar uma consulta.

Consultar usando o Apache Spark

Para consultar tabelas do BigLake usando o Spark SQL em um job sem servidor do Dataproc, siga estas etapas:

1. Crie um script PySpark semelhante ao exemplo abaixo:

     from pyspark.sql import SparkSession
     session = (
       SparkSession.builder.appName("testing")
         .config("viewsEnabled","true")
         .config("materializationDataset", "DATASET_ID")
         .config("spark.hive.metastore.bigquery.project.id", "PROJECT_ID")
         .config("spark.hive.metastore.client.factory.class", "com.google.cloud.bigquery.metastore.client.BigQueryMetastoreClientFactory")
         .enableHiveSupport()
         .getOrCreate()
     )
   
     session.sql("show databases").show()
     session.sql("use TABLE_NAME").show()
     session.sql("show tables").show()
   
     sql = "SELECT * FROM DATASET_ID.TABLE_ID LIMIT 10"
     df = session.read.format("bigquery").option("dataset", "DATASET_ID").load(sql)
     df.show()

   Substitua:

   • DATASET_ID: ID do conjunto de dados para que os usuários têm permissão de criação
   • PROJECT_ID: ID do projeto com a tabela do BigLake
   • TABLE_NAME: nome da tabela do BigLake
   • TABLE_ID: ID da tabela do BigLake

2. Envie o job em lote.

Gerenciar tabelas do BigLake publicadas

As tabelas do BigLake publicadas são criadas no BigQuery pela verificação de descoberta. A menos que o rótulo metadata-managed-mode esteja definido como user_managed, a verificação de descoberta gerencia as tabelas do BigLake publicadas. A verificação de descoberta processa novas descobertas de dados, inferências de esquema e evolução de esquema sempre que as verificações de dados programadas ou sob demanda são executadas.

Observação: é possível aplicar políticas de acesso, como segurança no nível da coluna e segurança no nível da linha, mesmo que as tabelas sejam gerenciadas pela verificação de descoberta.

Atualizar tabelas publicadas do BigLake

Para tabelas do BigLake publicadas usando os jobs de verificação de descoberta com a configuração padrão, o esquema e outros metadados são atualizados automaticamente com cada execução de job de verificação de dados na frequência programada.

Para atualizar uma tabela do BigLake publicada, siga estas etapas:

1. No Console do Google Cloud, acesse a página BigQuery.

   Acessar o BigQuery

2. Atualize uma ou mais propriedades da tabela.

3. No painel Explorer, expanda o projeto e o conjunto de dados e selecione a tabela.

4. No painel Detalhes, na seção Rótulos, verifique se o metadata-managed-mode está definido como user_managed. Se estiver definido como um valor diferente, siga estas etapas:

   1. Clique em Editar detalhes.

   2. Ao lado da chave metadata-managed-mode, no campo value, insira user_managed.

Uma tabela com um esquema atualizado fica disponível para consultas SQL e Spark. Quando as próximas verificações de descoberta forem executadas, os metadados da tabela vão permanecer inalterados.

Excluir tabelas do BigLake publicadas

Para excluir uma tabela do BigLake publicada, siga estas etapas:

1. Exclua os arquivos de dados da tabela no bucket do Cloud Storage.

2. No Console do Google Cloud, acesse a página BigQuery.

   Acessar o BigQuery

3. No painel Explorer, expanda o projeto e o conjunto de dados e selecione a tabela.

4. No painel Detalhes, na seção Rótulos, verifique se o rótulo metadata-managed-mode não está definido como user_managed. Se estiver definido como user_managed, siga estas etapas:

   1. Clique em Editar detalhes .

   2. Ao lado da chave metadata-managed-mode, no campo value, insira um valor que não seja user_managed.

      Observação: se o rótulo metadata-managed-mode estiver definido como user_managed, a verificação de descoberta não vai substituir os metadados da tabela, o que faz com que a tabela não seja excluída.

5. Clique em Executar. A verificação de descoberta é executada sob demanda.

Depois que a verificação de descoberta é executada, a tabela do BigLake é excluída no BigQuery e não está disponível para listar ou consultar pelo Spark.

Executar uma verificação de descoberta sob demanda

Para executar uma verificação de descoberta sob demanda, use o método dataScans.run na API Dataplex.

Listar verificações de descobertas

Para recuperar a lista de verificações no projeto, use o método dataScans.list na API Dataplex.

Atualizar uma verificação de descoberta

Para mudar a programação de uma verificação, por exemplo, de "sob demanda" para "recorrente", é necessário atualizar o DataScan.

Para atualizar uma verificação de descoberta, use o método dataScans.patch na API Dataplex.

Excluir uma verificação de descoberta

Para excluir uma verificação de descoberta, use o método dataScans.delete na API Dataplex.