Resolver problemas de descoberta de dados do Knowledge Catalog

Este guia ajuda a solucionar problemas comuns com verificações de descoberta de dados do Knowledge Catalog (também chamada de descoberta independente), incluindo falhas de publicação de tabelas e erros de incompatibilidade de esquema.

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

Quando uma verificação de descoberta é executada, ela pode falhar ao publicar 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 da tabela: a criação ou modificação da tabela aplica configurações incorretas ou não aceitas.

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

  • Verificar os papéis da conta de serviço: Confirme se a conta de serviço do Knowledge Catalog service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com tem o papel de agente de serviço de publicação do BigLake do Dataplex Discovery (roles/dataplex.discoveryBigLakePublishingServiceAgent) role.
  • Verificar 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 roles/storage.objectViewer ou roles/dataplex.discoveryServiceAgent).
  • Verificar a conexão e o local do conjunto de dados: verifique se a conexão e o conjunto de dados do BigQuery existem na mesma região e se são compatíveis com o local do bucket do Cloud Storage.
  • Inspecionar registros para mais detalhes: explore os registros de jobs 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.

A criação da tabela do BigLake falha 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), a verificação pode criar o conjunto de dados do BigQuery, mas falha ao publicar as tabelas do BigLake.

Quando isso ocorre, você pode 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 falha ao registrar tabelas externas ou não detecta arquivos em determinadas pastas.

Esse problema ocorre se as pastas do Cloud Storage contiverem arquivos com esquemas incompatíveis ou formatos diferentes. A verificação de descoberta agrupa 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 em pastas sejam consistentes. A verificação sinaliza uma ação se detectar qualquer um dos seguintes:

  • Formato de dados inválido (INVALID_DATA_FORMAT): formatos de dados inconsistentes são encontrados na mesma pasta ou em partições (por exemplo, misturar 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 fortemente tipados, 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 int ou boolean tipo 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 de esquema, impedindo a evolução correta do esquema.
  • Formato de arquivo corrompido: um ou mais arquivos estão malformados ou corrompidos, fazendo com que a verificação falhe ao ler e extrair o esquema.

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

  • Organizar 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.
  • Usar 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).
  • Seguir 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 de esquema.
  • Identificar arquivos corrompidos: verifique a saída ou os registros da verificação para identificar se um arquivo específico falha ao decodificar. Mova arquivos temporariamente para descobrir se um arquivo específico faz com que a verificação falhe.

As tabelas descobertas não são atualizadas com as 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, será necessário mudar 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 Google Cloud console, acesse a página BigQuery.
  2. No painel Explorer , abra 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 retome o gerenciamento e a atualização do esquema, clique em Editar detalhes e mude o valor para discovery_managed.

Receber suporte

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