Resolver problemas de descoberta de dados do Knowledge Catalog

A descoberta de dados do Knowledge Catalog (antigo Dataplex Universal Catalog), também chamada de descoberta independente, permite verificar automaticamente os buckets do Cloud Storage para extrair metadados e publicar tabelas no BigQuery. É possível resolver problemas e erros comuns de verificação de descoberta, como falhas de publicação de tabelas do BigQuery e do BigLake, incompatibilidades de esquema de pastas e tabelas que não são atualizadas após mudanças de esquema. Para mais informações, consulte Descobrir e catalogar dados do Cloud Storage.

Se você precisar de ajuda para resolver um problema que não é abordado neste documento, entre em contato com o Cloud Customer Care.

Falha na publicação da tabela do BigQuery (FAILED_BIGQUERY_TABLE_PUBLISH)

Quando uma verificação de descoberta é executada, pode haver falha na publicação de tabelas no BigQuery. Nesse caso, a verificação registra uma ação FAILED_BIGQUERY_TABLE_PUBLISH no Cloud Logging.

Esse problema ocorre devido às seguintes condições:

  • Permissões insuficientes do IAM: a conta de serviço do Knowledge Catalog ou a conta de serviço de conexão do BigQuery não tem os papéis necessários para delegar conexões, acessar o Cloud Storage ou gravar no conjunto de dados de destino.
  • Incompatibilidade de conexão ou conjunto de dados do BigQuery: o ID de conexão especificado é inválido ou a conexão e o conjunto de dados de destino estão localizados em regiões diferentes.
  • Erros de configuração de tabela: a criação ou modificação de tabelas aplica configurações incorretas ou sem suporte.

Para resolver esse problema, faça as seguintes verificações:

  • Verifique os papéis da conta de serviço: confirme se a conta de serviço do Knowledge Catalog service-PROJECT_NUMBER@gcp-sa-dataplex. tem o papel de Agente de serviço de publicação do BigLake do Dataplex Discovery (roles/dataplex.discoveryBigLakePublishingServiceAgent).
  • Verifique as permissões de conexão: se você criar tabelas do BigLake, verifique se a conta de serviço de conexão do BigQuery tem acesso de leitura ao bucket do Cloud Storage usando o papel de Leitor de objetos do Storage (roles/storage.objectViewer) ou Agente de serviço do Dataplex Discovery (roles/dataplex.discoveryServiceAgent).
  • Verifique a conexão e o local do conjunto de dados: verifique se a conexão e o conjunto de dados do BigQuery estão na mesma região e se são compatíveis com o local do bucket do Cloud Storage.
  • Inspecione os registros para mais detalhes: confira os registros do job do DataScan no Cloud Logging. Se o erro contiver BigQuery: Permission denied, verifique as permissões da conta de serviço. Se ele contiver TABLE_CONFIG, verifique se os arquivos de dados estão em conformidade com os requisitos do BigQuery.

Falha na criação de tabelas do BigLake para buckets grandes do Cloud Storage

Quando uma verificação de descoberta processa buckets do Cloud Storage com um grande volume de dados ou arquivos individuais grandes (por exemplo, arquivos Avro maiores que 30 MB), ela pode criar o conjunto de dados do BigQuery, mas não publicar as tabelas do BigLake.

Quando isso ocorre, é possível observar os seguintes erros no Cloud Logging:

  • FAILED_BIGQUERY_TABLE_PUBLISH
  • com.google.cloud.bigquery.BigQueryException: Read timed out

Esse problema é uma limitação de escalonabilidade conhecida. Se você precisar de provisionamento imediato de tabelas, configure a verificação de descoberta para incluir um subconjunto menor e filtrado dos dados do bucket.

Incompatibilidades de esquema de pastas do Cloud Storage

Uma verificação de descoberta de dados não registra tabelas externas ou não detecta arquivos em determinadas pastas.

Esse problema ocorre quando as pastas do Cloud Storage contêm arquivos com esquemas incompatíveis ou formatos diferentes. A verificação de descoberta agrupa os arquivos em uma única tabela somente se eles estiverem na mesma pasta e tiverem um esquema compatível.

Quando uma verificação de descoberta de dados analisa um caminho do Cloud Storage, ela espera que os arquivos em uma pasta e a estrutura de partição entre as pastas sejam consistentes. A verificação sinaliza uma ação se detectar qualquer um dos seguintes itens:

  • Formato de dados inválido (INVALID_DATA_FORMAT): formatos de dados inconsistentes são encontrados na mesma pasta ou em partições (por exemplo, misturando arquivos .csv e .parquet no mesmo diretório).
  • Definição de partição inválida (INVALID_PARTITION_DEFINITION): as chaves de partição são inconsistentes ou estão ausentes. Por exemplo, usar Year=2023/Mon=Jan em um caminho e Year=2023/Dept=Sales em outro.
  • Esquema de dados incompatível (INCOMPATIBLE_DATA_SCHEMA): esquemas inconsistentes ou incompatíveis são detectados em arquivos na mesma pasta ou tabela.

Para formatos com tipos bem definidos, como Avro e Parquet, as incompatibilidades de esquema ocorrem devido a:

  • Tipos de dados incompatíveis: uma coluna tem um tipo string em um arquivo e um tipo int ou boolean em outro.
  • Valores padrão ausentes: novos campos são adicionados ou excluídos em arquivos mais recentes sem especificar valores padrão na definição do esquema, impedindo a evolução correta do esquema.
  • Formato do arquivo corrompido: um ou mais arquivos estão corrompidos ou malformados, o que impede a verificação de ler e extrair o esquema.

Para resolver esse problema, verifique a estrutura do arquivo e as definições do esquema:

  • Organize os arquivos por esquema e formato: verifique se todos os arquivos em uma única pasta compartilham o mesmo formato e estrutura de esquema. Mova arquivos com colunas, tipos primitivos ou formatos diferentes para pastas ou prefixos separados para que possam ser registrados como tabelas separadas.
  • Use definições de partição consistentes: verifique se as chaves e estruturas de partição são consistentes em todas as pastas de partição (por exemplo, usando Year=YYYY/Month=MM/ de forma consistente).
  • Siga as regras de evolução do esquema: ao atualizar esquemas (como adicionar ou remover campos de arquivos Avro), sempre defina valores padrão para que o serviço de descoberta possa mesclar as variantes do esquema.
  • Identificar arquivos corrompidos: verifique a saída ou os registros da verificação para identificar se um arquivo específico não foi decodificado. Mova os arquivos temporariamente para descobrir se um arquivo específico está causando a falha na verificação.

As tabelas descobertas não são atualizadas com mudanças de esquema

Depois de modificar arquivos no Cloud Storage ou executar uma nova verificação, o esquema atualizado não é refletido nas tabelas publicadas do BigQuery.

Esse problema ocorre se a tabela publicada tiver o rótulo metadata-managed-mode definido como user_managed. Por padrão, a descoberta publica tabelas como discovery_managed. Se você ou outro usuário editar manualmente as propriedades do esquema da tabela, mude o rótulo para user_managed para bloquear atualizações automáticas.

Para resolver esse problema, verifique os rótulos da tabela no BigQuery:

  1. No console do Google Cloud , acesse a página BigQuery.
  2. No painel Explorer, expanda o projeto, selecione o conjunto de dados e clique na tabela afetada.
  3. Clique na guia Detalhes.
  4. Na seção Rótulos, verifique o valor da chave metadata-managed-mode.
  5. Se você quiser que a verificação de descoberta volte a gerenciar e atualizar o esquema, clique em Editar > Editar detalhes, mude o valor para discovery_managed e clique em Salvar.