Introdução à solução de problemas

Este documento oferece uma visão geral das ferramentas de diagnóstico, interfaces de telemetria e recursos de documentação disponíveis para ajudar a resolver problemas no BigQuery.

Quando você encontrar falhas de consulta, gargalos de desempenho, erros de permissão, limites de cota ou problemas de ingestão de dados, o BigQuery vai oferecer ferramentas integradas para ajudar a identificar as causas raiz e resolver problemas rapidamente.

Como resolver problemas do fluxo de trabalho

Para resolver um problema no BigQuery de maneira eficaz, considere os seguintes critérios de diagnóstico:

  1. Identifique o sintoma e o modo de falha. Analise os resultados da tarefa para determinar se o problema é uma falha grave (como um código do erro ou falha de job), uma degradação de desempenho (como uma consulta lenta ou falta de slots), uma negação de permissão ou uma discrepância de custo inesperada.
  2. Inspecione os detalhes da execução do job. Use o Cloud de Confiance Explorador de jobs do console, o gráfico de execução de consultas ou as ferramentas de linha de comando para examinar os tempos de estágio, a alocação de slots e os detalhes do erro. Você também pode pedir ao Gemini Cloud Assist para investigar o problema.
  3. Analise a telemetria e os metadados. Consulte as visualizações do esquema de informações ou inspecione os registros de auditoria do Cloud para correlacionar o comportamento do job com a contenção de recursos, os limites de reserva ou as mudanças administrativas.
  4. Aplique mitigações direcionadas. Use guias de solução de problemas específicos da categoria ou funções SQL defensivas para corrigir a causa subjacente.

Diferenciar a solução de problemas da otimização

Ao trabalhar com o BigQuery, é importante distinguir entre solução de problemas, otimização de desempenho e práticas recomendadas:

  • Solução de problemas. Concentra-se no diagnóstico e na resolução de falhas inesperadas, erros de tempo de execução, pipelines quebrados, esgotamento de cotas ou comportamento não intencional que impede a conclusão dos jobs.
  • Otimização de desempenho. Concentra-se em melhorar a velocidade de execução, a latência ou a eficiência de recursos de consultas e cargas de trabalho que já estão sendo executadas. Para mais informações, consulte Otimizar o desempenho da consulta.
  • Práticas recomendadas. Concentra-se em padrões arquitetônicos e de design para modelagem, armazenamento, segurança e gerenciamento de custos de dados. Para mais informações, consulte Introdução às práticas recomendadas.

Ferramentas de diagnóstico

As seções a seguir descrevem várias interfaces do BigQuery e ferramentas automatizadas para ajudar a diagnosticar problemas nas cargas de trabalho.

Ferramentas visuais e de console

As ferramentas a seguir ajudam a resolver problemas do BigQuery no Cloud de Confiance console.

  • Análise de jobs. Pesquise, filtre e inspecione jobs anteriores e em execução em projetos ou organizações sem escrever consultas SQL. É possível visualizar mensagens de erro, uso de slots, cronogramas de execução e metadados de jobs. Para mais informações, consulte Monitorar jobs na Análise de jobs.
  • Gráfico de execução de consultas. Inspecione o plano de execução visual estágio por estágio de uma consulta. O gráfico de execução ajuda a identificar gargalos, como derramamentos de embaralhamento no disco, estágios vinculados à computação, distorção de dados ou atrasos de entrada/saída. Para mais informações, consulte Receber insights de desempenho de consulta.
  • Query Insights e gráficos de recursos. Visualize gráficos históricos e em tempo real da utilização de slots, da simultaneidade de jobs e das alocações de reserva para diagnosticar restrições de capacidade. Para mais informações, consulte Usar gráficos de recursos administrativos.
  • Gemini Cloud Assist no BigQuery. Receba análises contextuais assistidas por IA de consultas com falha e gargalos de desempenho. O Gemini Cloud Assist explica códigos do erro, destaca a sintaxe SQL problemática e sugere etapas de correção diretamente noCloud de Confiance console. Para mais informações, consulte Resolver problemas de consultas usando o Gemini Cloud Assist.

Ferramentas de diagnóstico automatizadas e de linha de comando

As ferramentas a seguir podem ajudar a diagnosticar problemas do BigQuery em uma interface de linha de comando.

  • Ferramenta de linha de comando bq. Inspecione estruturas de erro detalhadas, IDs de solicitação e metadados de job usando o bq show -j <var>JOB_ID</var> comando ou adicionando a --format=prettyjson flag aos comandos de consulta. Para mais informações, consulte Resolver problemas de comandos da CLI.
  • Ferramenta gcpdiag. Execute diagnósticos automatizados na linha de comando para detectar problemas de configuração Cloud de Confiance comuns, incluindo lacunas de permissão do IAM, restrições de rede e erros de conta de serviço. Para mais informações, consulte Resolver problemas de falha de consulta usando gcpdiag.

Visualizações de metadados e telemetria

As visualizações do esquema de informações permitem consultar metadados históricos e em tempo real sobre jobs, capacidade, ingestão de streaming e conjuntos de dados usando o SQL padrão. Essas visualizações incluem o seguinte:

Para mais informações, consulte Introdução ao BigQuery INFORMATION_SCHEMA.

Cloud Monitoring e registros de auditoria do Cloud

  • Registros de auditoria do Cloud. Analise os registros de auditoria de atividades administrativas e de auditoria de acesso a dados para rastrear quem iniciou operações específicas, inspecionar identidades de chamadores e diagnosticar erros PERMISSION_DENIED. Para mais informações, consulte Referência de registro de auditoria do BigQuery.
  • Cloud Monitoring. Acompanhe métricas como uso de slots, durações de execução de consultas e bytes enviados e configure políticas de alertas para notificar sua equipe quando os limites ou cotas forem excedidos. Para mais informações, consulte Monitorar o BigQuery usando o Cloud Monitoring.

Funções SQL defensivas e instruções de depuração

Para evitar que as consultas falhem inesperadamente devido a erros de dados de execução, use o seguinte:

  • Expressões seguras. Use SAFE_CAST(), SAFE_DIVIDE(), SAFE_OFFSET() e SAFE_ORDINAL() para retornar NULL em vez de gerar erros de tempo de execução quando os tipos de dados ou os limites de matriz não corresponderem. A maioria das funções escalares oferece suporte ao prefixo SAFE.. Para mais informações, consulte Funções de depuração e SAFE. prefixo.
  • Declarações SQL. Use a instrução ASSERT em transações ou scripts de várias instruções para aplicar condições de validação de dados e falhar com mensagens de erro personalizadas antes que as operações downstream sejam executadas. Para mais informações, consulte Instruções de depuração.

Resolver problemas por categoria

Selecione uma categoria nas seções a seguir para conferir códigos do erro detalhados, causas raiz e guias de resolução passo a passo.

Desempenho e execução de consultas

Diagnostique consultas que não são executadas, atingem o tempo limite, encontram restrições de recursos ou apresentam atrasos inesperados.

Identity and Access Management (IAM) e segurança

Diagnostique falhas de controle de acesso, atribuições de papéis ausentes e blocos de políticas de governança de dados.

Cotas, limitação de taxa e reservas

Resolva problemas quando as cargas de trabalho excederem os limites de serviço ou as alocações de capacidade do BigQuery.

Ingestão de dados, streaming e transferências

Diagnostique falhas ao carregar dados, transmitir registros ou sincronizar fontes externas.

  • Resolver problemas de transferência de dados. Diagnostique problemas do serviço de transferência de dados do BigQuery, conectividade de rede para transferências particulares e erros de carregamento de dados CSV.
  • Resolver problemas nas configurações de transferência. Resolva erros de configurações de serviço do serviço de transferência de dados do BigQuery em fontes como Amazon Simple Storage Service (Amazon S3), Salesforce, Google Ads e Cloud Storage.
  • Resolver problemas da API BigQuery Storage. Depure falhas de ingestão de streaming da API BigQuery Storage Read, da API BigQuery Storage Write (gRPC) e da API BigQuery Storage Write (REST), erros de inserção no nível da linha e cotas de capacidade.

Migração de data warehouse

Diagnostique problemas ao avaliar, traduzir ou migrar data warehouses externos para o BigQuery.

  • Resolver problemas de migração. Resolva erros de avaliação de migração, problemas de tradução de SQL interativa e em lote e falhas de extração de metadados.

Fontes de dados externas e consultas federadas

Diagnostique erros de conectividade, autenticação e execução ao consultar dados fora do BigQuery.

Discrepâncias de faturamento e custos

Investigue cobranças inesperadas e discrepâncias de faturamento em computação e armazenamento.

Mitigação de perda de dados

Para recuperar dados históricos que foram alterados ou excluídos ou para manter a continuidade dos negócios durante uma interrupção regional, use as seguintes ferramentas de recuperação de desastres e retenção de dados:

  • Restaurar dados. Consulte ou restaure dados de tabelas que foram alterados ou excluídos na janela de viagem no tempo. Para mais informações, consulte Restaurar dados.
  • Viagem no tempo. Mantenha dados atualizados ou excluídos em um conjunto de dados por um período de armazenamento configurado para ajudar a proteger contra modificações acidentais. Para mais informações, consulte Viagem no tempo.
  • Failover regional. Promova uma réplica secundária para o papel principal durante uma interrupção regional ao usar a recuperação de desastres gerenciada pelo BigQuery. Para mais informações, consulte Failover regional.

Como usar APIs

Ao interagir com o BigQuery de maneira programática, use os seguintes recursos para otimizar a latência da solicitação e gerenciar fluxos de trabalho de upload:

  • Dicas de desempenho da API. Siga as práticas recomendadas para fazer chamadas de API, como gerenciar pools de conexão, usar operações em lote e processar novas tentativas. Para mais informações, consulte Dicas de desempenho da API.
  • Uploads de API. Resolva problemas e gerencie a ingestão de dados usando solicitações de upload retomáveis e multipartes da API REST. Para mais informações, consulte Uploads de API.

Autenticação e ADC

Para receber ajuda na solução de problemas comuns que podem ocorrer ao usar o Application Default Credentials (ADC), consulte Resolver problemas na configuração do ADC.

A seguir