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 de 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 de execução do job. Use o Google Cloud 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 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 de dados, armazenamento, segurança e gerenciamento de custos. Para mais informações, consulte Introdução às práticas recomendadas.

Ferramentas de diagnósticos

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 Google Cloud console.

  • Explorador 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 a computação, distorção de dados ou atrasos de entrada/saída. Para mais informações, consulte Receber insights de desempenho de consultas.
  • 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 de erro, destaca a sintaxe SQL problemática e sugere etapas de correção diretamente no Google Cloud 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 erros detalhadas, IDs de solicitação e metadados de job usando o comando bq show -j <var>JOB_ID</var> 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 Google Cloud 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 falhas 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 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 execução quando os tipos de dados ou os limites de matriz não corresponderem. A maioria das funções escalares é compatível com o 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 da execução de operações downstream. 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 de 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 têm 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, limites 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.

  • Resolver erros de limites e cotas. Identifique cotas ajustáveis versus não ajustáveis, processe limites de consultas simultâneas e resolva erros de limite de taxa de API.
  • Resolver problemas com reservas. Diagnostique a falta de slots, incompatibilidades de atribuição de reserva e deficiências de capacidade de linha de base.

Ingestão de dados, streaming e transferências

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

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 recursos a seguir para otimizar a latência de solicitações 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.

A seguir