Introdução à solução de problemas

Neste documento, você terá 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ê encontra falhas de consulta, gargalos de desempenho, erros de permissão, limites de cota ou problemas de ingestão de dados, o BigQuery oferece ferramentas integradas para ajudar a identificar as causas principais 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 performance (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 explorador de jobs do console Cloud de Confiance , o gráfico de execução de consultas ou as ferramentas de linha de comando para examinar os tempos no nível da etapa, 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 telemetria e 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 disputa 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 de defesa para corrigir a causa subjacente.

Diferenciar solução de problemas e 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. O foco é diagnosticar e resolver falhas inesperadas, erros de execução, pipelines corrompidos, esgotamento de cota ou comportamento não intencional que impede a conclusão dos jobs.
  • Otimização de desempenho. Focado 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 com sucesso. Para mais informações, consulte Otimizar o desempenho da consulta.
  • Práticas recomendadas. Foco 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 você a diagnosticar problemas nas cargas de trabalho.

Ferramentas visuais e de console

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

  • Explorador de jobs. Pesquise, filtre e inspecione jobs anteriores e em execução em projetos ou organizações sem escrever consultas SQL. É possível conferir mensagens de erro, uso de slots, cronogramas de execução e metadados de jobs. Para mais informações, consulte Monitorar jobs no Análise de jobs.
  • Gráfico de execução da consulta. Inspecione o plano de execução visual etapa por etapa de uma consulta. O gráfico de execução ajuda a identificar gargalos, como derramamentos de embaralhamento para 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 consulta.
  • Query Insights e gráficos de recursos. Consulte gráficos em tempo real e históricos de utilização de slots, simultaneidade de jobs e 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 uma análise contextual, assistida por IA, de consultas com falha e gargalos de desempenho. O Gemini Cloud Assist explica códigos de erro, destaca sintaxes SQL problemáticas e sugere etapas de correção diretamente no consoleCloud de Confiance . 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 você 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 do job usando o comando bq show -j <var>JOB_ID</var> ou adicionando a flag --format=prettyjson aos comandos de consulta. Para mais informações, consulte Solução de problemas com comandos da CLI.
  • Ferramenta gcpdiag. Execute diagnósticos automatizados na linha de comando para detectar problemas comuns de configuração do Cloud de Confiance , 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

Com as visualizações do esquema de informações, é possível 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 de administrador e de acesso a dados para rastrear quem iniciou operações específicas, inspecionar identidades de chamadores e diagnosticar erros de PERMISSION_DENIED. Para mais informações, consulte Referência de geração de registros de auditoria do BigQuery.
  • Cloud Monitoring. Acompanhe métricas como uso de slots, durações de execução de consultas e bytes enviados, além de configurar políticas de alertas para notificar sua equipe quando os limites ou as cotas forem excedidos. Para mais informações, consulte Monitorar o BigQuery usando o Cloud Monitoring.

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

Para evitar falhas inesperadas nas consultas devido a erros de dados de tempo 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 tipos de dados ou 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 Prefixo SAFE..
  • Declarações SQL. Use a instrução ASSERT em transações ou scripts com 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 principais e guias de resolução com instruções detalhadas.

Execução e desempenho da consulta

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

Identity and Access Management (IAM) e segurança

Diagnosticar falhas de controle de acesso, atribuições de função ausentes e bloqueios de política 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.

Ingestão de dados, streaming e transferências

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

Migração de data warehouse

Diagnosticar problemas ao avaliar, traduzir ou migrar armazenamentos de dados 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 na extração de metadados.

Fontes de dados externas e consultas federadas

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

Discrepâncias de faturamento e custo

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 sua janela de viagem no tempo. Para mais informações, consulte Restaurar dados.
  • Viagem no tempo. Mantenha os 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 a função 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 forma programática, use os seguintes recursos para otimizar a latência de 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. Solucione 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 da API.

A seguir