Introdução à solução de problemas

Neste documento, apresentamos uma visão geral das ferramentas de diagnóstico, interfaces de telemetria e recursos de documentação disponíveis para ajudar você 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 raiz e resolver problemas rapidamente.

Observação :se você tiver um código de status HTTP específico, uma string de motivo ErrorProto ou uma mensagem de erro da API, consulte Mensagens de erro para ver descrições e ações recomendadas.

Como resolver problemas do fluxo de trabalho

Para resolver problemas 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. Inspecionar detalhes da execução do job. Use o explorador de jobs do console do Google Cloud , o gráfico de execução de consultas ou as ferramentas de linha de comando para examinar os tempos de nível de estágio, a alocação de slots e os detalhes de erro. Você também pode pedir ao Gemini Cloud Assist para investigar o problema.
3. Analisar 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 contenção de recursos, os limites de reserva ou as mudanças administrativas.
4. Aplicar 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. Foca no diagnóstico e na resolução de falhas inesperadas, erros de tempo de execução, pipelines corrompidos, esgotamento de cotas ou comportamentos não intencionais que impedem a conclusão dos jobs.
• Otimização de desempenho. Foca 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 em execução. Para mais informações, consulte Otimizar o desempenho da consulta.
• Práticas recomendadas. Foco em padrões de arquitetura e 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 suas cargas de trabalho.

Ferramentas visuais e de console

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

• 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 ver mensagens de erro, uso de slots, cronogramas de execução e metadados de jobs. Para mais informações, consulte Monitorar jobs no Explorador de jobs.
• Gráfico de execução de consulta. Inspecione o plano de execução visual por etapas de uma consulta. O gráfico de execução ajuda a identificar gargalos, como derramamentos de embaralhamento no disco, estágios de computação, desvio de dados ou atrasos de entrada/saída. Para mais informações, acesse Receber insights de desempenho de consulta.
• Query Insights e gráficos de recursos. Veja 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 análises contextuais assistidas por IA de consultas com falha e gargalos de desempenho. O Gemini Cloud Assist explica códigos do erro, destaca sintaxes SQL problemáticas e sugere etapas de correção diretamente no console doGoogle Cloud . 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 jobs 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 Como resolver problemas de comandos da CLI.
• Ferramenta gcpdiag. Execute diagnósticos automatizados na linha de comando para detectar problemas comuns de configuração do Google Cloud , 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 de 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:

• Telemetria de execução de jobs. Consulte INFORMATION_SCHEMA.JOBS e INFORMATION_SCHEMA.JOBS_TIMELINE para analisar o consumo de milissegundos de slot, bytes transferidos, tempos de fila e códigos de erro em todos os jobs.
• Reservas e capacidade. Consulte INFORMATION_SCHEMA.RESERVATIONS e INFORMATION_SCHEMA.CAPACITY_COMMITMENTS para diagnosticar a alocação de slots, os limites de reserva e os comportamentos de escalonamento automático.
• Streaming e ingestão. Consulte INFORMATION_SCHEMA.STREAMING_TIMELINE para identificar a latência de ingestão e os limites de limitação de taxa de streaming.
• Integridade do armazenamento e da partição. Consulte INFORMATION_SCHEMA.TABLE_STORAGE para inspecionar os tamanhos das tabelas físicas, o armazenamento ativo versus o de longo prazo e a distribuição de partições.

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 do administrador e de auditoria de acesso a dados para rastrear quem iniciou operações específicas, inspecionar identidades de autores de chamadas e diagnosticar erros de PERMISSION_DENIED. Para mais informações, consulte a 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, e configure políticas de alerta para notificar sua equipe quando 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 ambiente 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 é 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 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 ver códigos do erro detalhados, causas raiz e guias de resolução detalhados.

Desempenho e execução de consultas

Diagnostique consultas que não são executadas, expiram, encontram restrições de recursos ou sofrem atrasos inesperados.

• Resolver problemas de consulta. Resolva erros resourcesExceeded, execução lenta de consultas, vazamento de embaralhamento, condições de falta de memória e falhas de consulta programada.
• Resolver problemas de tempos longos de fila de consulta. Diagnostique gargalos de simultaneidade e consultas em fila devido a limites de fila interativa ou em lote.
• Referência de mensagens de erro. Procure códigos de erro HTTP específicos, strings de motivo de erro e ações recomendadas.

Identity and Access Management (IAM) e segurança

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

• Resolver problemas de permissões do IAM no BigQuery. Diagnosticar erros de permissão negada, conceder papéis do IAM ausentes e usar o Solucionador de problemas de políticas.
• Resolver problemas do VPC Service Controls. Identificar e resolver violações de perímetro e bloqueios de regras de entrada ou saída.
• Resolver problemas de segurança no nível da linha e da coluna. Resolva problemas de acesso relacionados a políticas de dados, tags de política e filtros de acesso por linha.

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.

• Resolver erros de limites e cotas. Identificar cotas ajustáveis e não ajustáveis, lidar com limites de consultas simultâneas e resolver erros de limite de taxa de API.
• Resolver problemas de gerenciamento de cargas de trabalho do BigQuery. Diagnostique a falta de slots, incompatibilidades de atribuição de reserva, atrasos no compromisso de capacidade, contenção de slots e problemas de monitoramento de reservas.

Ingestão de dados, streaming e transferências

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

• Resolver problemas de transferências de dados. Diagnosticar 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ção de serviço do serviço de transferência de dados do BigQuery em origens 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, erros de inserção no nível da linha e cotas de capacidade de processamento da API BigQuery Storage Read, da API BigQuery Storage Write (gRPC) e da API BigQuery Storage Write (REST).
• Resolver erros de esquema. Resolva erros de incompatibilidade de esquema em operações de carregamento, consulta, cópia e atualização de esquema (como alterações de coluna ausentes, duplicadas ou incompatíveis) e limites de profundidade de aninhamento de esquema, arquivo e rotina de 15 níveis.

Migração de data warehouse

Diagnosticar 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

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

• Resolver problemas de consultas federadas do Cloud SQL. Resolver tempos limite de conexão, problemas de configuração de instância e falhas de credenciais.

Discrepâncias de faturamento e custo

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

• Resolver discrepâncias de custo do BigQuery. Identificar a origem de cobranças inesperadas, analisar os bytes sob demanda faturados e verificar o uso do compromisso de capacidade.

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. Consultar ou restaurar dados de tabela que foram alterados ou excluídos dentro da janela de viagem no tempo. Para mais informações, consulte Restaurar dados.
• Viagem no tempo. Retenha 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 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. Resolver problemas e gerenciar a ingestão de dados usando solicitações de upload retomável e de várias partes da API REST. Para mais informações, consulte Uploads de API.

Autenticação e ADC

Para receber ajuda com problemas comuns que você pode encontrar ao usar o Application Default Credentials (ADC), consulte Resolver problemas de configuração do ADC.

A seguir

• Saiba mais sobre o monitoramento do BigQuery.
• Confira a referência do BigQuery INFORMATION_SCHEMA.
• Entre em contato com o Cloud Customer Care para receber suporte com problemas de produção persistentes ou críticos.