Como solucionar erros

Você encontrará dois tipos de erros ao trabalhar com o BigQuery: códigos dos erros HTTP ou erros de job. Os erros de job são representados no objeto status ao chamar jobs.get.

Tabela de erros

A tabela a seguir apresenta os possíveis códigos dos erros que são retornados ao fazer uma solicitação à API do BigQuery. As respostas da API incluem um código do erro HTTP e um objeto de erros. A coluna "Código do erro" a seguir é mapeada para a propriedade reason no objeto de erro.

Se você usar a ferramenta de linha de comando bq para consultar o status do job, o objeto de erro não será retornado por padrão. Para ver o objeto e a propriedade reason correspondente que é mapeada na tabela abaixo, use a sinalização -- format=prettyjson. Por exemplo, bq --format=prettyjson show -j <job id>.

Se você receber um código de resposta HTTP que não aparece na lista a seguir, ele indicará um problema ou resultado esperado na solicitação HTTP. Por exemplo, o erro 502 indica que há um problema na sua conexão de rede. Para ver a lista completa de códigos de resposta HTTP, consulte códigos de resposta HTTP.

Código do erro Código HTTP Descrição Solução de problemas
accessDenied 403 Esse erro é retornado quando você tenta acessar um recurso, como um conjunto de dados de tabela ou job, a que não tem acesso. Ele também é retornado quando você tenta modificar um objeto somente leitura. Entre em contato com o proprietário do recurso e solicite acesso a ele.
backendError 500 ou 503 Este erro é retornado quando há uma falha temporária no servidor, como problema de conexão de rede ou sobrecarga no servidor. Em geral, aguarde alguns segundos e tente novamente. No entanto, há dois casos especiais para resolver esse erro: chamadas jobs.get e jobs.insert.

Chamadas jobs.get

  • Se você recebeu o erro 503 ao pesquisar jobs.get, aguarde alguns segundos e pesquise novamente.
  • Se o job é concluído, mas inclui um objeto de erro com backendError, ele falhou. É possível repeti-lo seguramente sem se preocupar com a consistência de dados.

Chamadas jobs.insert

Se você receber esse erro ao fazer uma chamada jobs.insert, não estará claro se o job foi bem-sucedido. Nesta situação, você precisa repeti-lo.

billingNotEnabled 403 Este erro é retornado quando o faturamento não está ativado no projeto. Ative o faturamento no projeto no Console do Google Cloud Platform.
blocked 403 Este erro é retornado quando o BigQuery colocou temporariamente a operação que você tentou executar na lista negra, geralmente para evitar interrupção do serviço. Isso raramente ocorre. Entre em contato com o suporte para mais informações.
duplicate 409 Este erro é retornado ao tentar criar um job, um conjunto de dados ou uma tabela que já existe. Ele também é retornado quando a propriedade writeDisposition do job é definida como WRITE_EMPTY, e a tabela de destino acessada pelo job já existe. Renomeie o recurso que você está tentando criar ou altere o valor writeDisposition no job.
internalError 500 Este erro é retornado quando ocorre um erro interno no BigQuery. Entre em contato com o suporte ou registre um bug usando o rastreador de problemas do BigQuery.
invalid 400 Este erro é retornado quando há algum tipo de entrada inválida que não seja uma consulta, como campos obrigatórios ausentes ou esquema de tabela inválido. Em vez desse erro, as consultas inválidas retornam invalidQuery.
invalidQuery 400 Este erro é retornado quando você tenta executar uma consulta inválida. Verifique se não há erros de sintaxe na consulta. A referência de consulta contém descrições e exemplos de como criar consultas válidas.
notFound 404 Este erro é retornado quando você menciona um recurso (conjunto de dados, tabela ou job) que não existe. Isso também pode ocorrer ao usar decoradores de instantâneos para se referir a tabelas excluídas que receberam streaming recentemente. Corrija os nomes dos recursos ou aguarde pelo menos seis horas após o streaming antes de consultar uma tabela excluída.
notImplemented 501 Este erro de job é retornado quando você tenta acessar um recurso que não foi implementado. Entre em contato com o suporte para mais informações.
quotaExceeded 403 Este erro é retornado quando o projeto excede uma cota do BigQuery, uma cota personalizada ou quando o faturamento não foi configurado e excede o nível gratuito para consultas. Veja a propriedade message do objeto de erro para mais informações sobre a cota que foi excedida. Para redefinir ou aumentar a cota do BigQuery, entre em contato com o suporte. Para modificar uma cota personalizada, envie uma solicitação da página do Console do Google Cloud Platform. Se você receber esse erro usando a sandbox do BigQuery, poderá fazer upgrade.
rateLimitExceeded 403 Este erro é retornado quando o projeto excede o limite de taxa de simultaneidade ou o limite de solicitações de API ao enviar várias solicitações muito rapidamente. Reduza a taxa de solicitação.

Se você acredita que o projeto não excedeu nenhum desses limites, entre em contato com o suporte.

resourceInUse 400 Este erro é retornado quando você tenta excluir um conjunto de dados com tabelas ou um job que esteja em execução. Esvazie o conjunto de dados ou aguarde a conclusão do job antes de tentar excluí-lo.
resourcesExceeded 400 Este erro é retornado quando a consulta usa um número excessivo de recursos.
  • Tente dividir a consulta em tamanhos menores.
  • Tente remover a cláusula ORDER BY.
  • Se a consulta usa JOIN, verifique se a tabela maior está à esquerda da cláusula.
  • Se a consulta usa FLATTEN, determine se ele é necessário no caso de uso específico. Para mais informações, consulte dados aninhados e repetidos.
  • Se a consulta usa EXACT_COUNT_DISTINCT, pense em usar COUNT(DISTINCT) como alternativa.
  • Se sua consulta usar COUNT(DISTINCT <value>, <n>) com um grande valor de <n>, considere o uso de GROUP BY como alternativa. Para saber mais informações, consulte COUNT(DISTINCT).
  • Se a consulta usa UNIQUE, pense em usar GROUP BY como alternativa ou uma função de janela dentro de uma subseleção.
responseTooLarge 403 Este erro é retornado quando os resultados da consulta são maiores do que o tamanho máximo da resposta. Algumas consultas são executadas em vários cenários, e este erro é retornado quando qualquer cenário apresenta uma resposta muito grande, mesmo que o resultado final seja menor do que o máximo. Normalmente, ele é retornado quando as consultas usam uma cláusula ORDER BY. A adição da cláusula LIMIT ou a remoção da cláusula ORDER BY às vezes pode ajudar. Para garantir que resultados grandes sejam retornados, defina a propriedade allowLargeResults como true e especifique uma tabela de destino.
stopped 200 Este código de status é retornado quando um job é cancelado.
tableUnavailable 400 Algumas tabelas do BigQuery têm como base dados gerenciados por outras equipes de produto do Google. Este erro indica que uma dessas tabelas está indisponível. Ao encontrar essa mensagem de erro, é possível repetir a solicitação (consulte as sugestões de solução de problemas em internalError) ou entrar em contato com a equipe de produto do Google que lhe concedeu acesso aos dados.

Resposta de erro de amostra

GET https://www.googleapis.com/bigquery/v2/projects/12345/datasets/foo
Response:
[404]
{
  "error": {
  "errors": [
  {
    "domain": "global",
    "reason": "notFound",
    "message": "Not Found: Dataset myproject:foo"
  }],
  "code": 404,
  "message": "Not Found: Dataset myproject:foo"
  }
}

Erros de autenticação

Os erros emitidos pelo sistema de geração de tokens OAuth retornam o seguinte objeto JSON, conforme definido pela especificação OAuth2.

{"error" : "description_string"}

O erro vem acompanhado de um erro “HTTP 400 Solicitação inválida” ou “HTTP 401 Não autorizado”. O elemento description_string é um dos códigos de erro definidos pela especificação do OAuth2. Exemplo:

{"error":"invalid_client"}

Voltar ao início

Solução de problemas com inserções de streaming

As seguintes seções explicam como resolver erros que ocorrem ao fazer streaming de dados no BigQuery.

Códigos de resposta HTTP de falha

Se você receber um código de resposta HTTP de falha, como erro de rede, não terá como saber se a inserção de streaming foi bem-sucedida. Se você simplesmente tentar reenviar a solicitação, poderá acabar com linhas duplicadas na tabela. Para ajudar a proteger a tabela contra duplicação, defina a propriedade insertId ao enviar a solicitação. O BigQuery usa a propriedade insertId para remoção da duplicação.

Se você receber um erro de permissão, de nome de tabela inválido ou de cota excedida, nenhuma linha será inserida, e haverá falha na solicitação inteira.

Códigos de resposta HTTP de sucesso

Mesmo se você receber um código de resposta HTTP de sucesso, será necessário verificar a propriedade insertErrors da resposta para determinar se as inserções das linhas foram bem-sucedidas, porque talvez o BigQuery tenha inserido as linhas parcialmente.

Se a propriedade insertErrors for uma lista vazia, todas as linhas foram inseridas com sucesso. Do contrário, as linhas indicadas na propriedade insertErrors não foram inseridas, e todas as outras foram inseridas com sucesso (exceto nos casos em que houve incompatibilidade de esquema em qualquer uma delas). A propriedade errors apresenta informações detalhadas sobre o motivo da falha de cada linha malsucedida. A propriedade index indica o índice da linha de base zero da solicitação à qual o erro está relacionado.

Se o BigQuery encontrar uma incompatibilidade de esquema em linhas individuais na solicitação, nenhuma delas será inserida, e a entrada insertErrors será retornada para cada linha, mesmo que não apresente incompatibilidade de esquema. As linhas sem incompatibilidade de esquema terão um erro com a propriedade reason definida como stopped e poderão ser reenviadas como estão. As linhas com falha incluem informações detalhadas sobre a incompatibilidade de esquema.

Erros de metadados para inserções de streaming

Como a API de streaming do BigQuery foi projetada para altas taxas de inserção, as modificações na exibição de metadados da tabela subjacente têm consistência eventual durante a interação com o sistema de streaming. Na maioria dos casos, as alterações de metadados são propagadas em poucos minutos, mas, durante esse período, as respostas da API podem refletir o estado inconsistente da tabela.

Alguns cenários incluem:

  • Mudanças no esquema: a modificação do esquema de uma tabela que recebeu inserções de streaming recentemente pode responder com erros de incompatibilidade de esquema, porque o sistema de streaming pode não pegar imediatamente a alteração de esquema.
  • Exclusão/criação de tabelas: o streaming para uma tabela inexistente retorna uma variação de resposta notFound. A criação da tabela em resposta pode não ser reconhecida imediatamente pelas inserções de streaming subsequentes. Da mesma forma, excluir e/ou recriar uma tabela pode criar um período em que as inserções de streaming são entregues efetivamente à tabela antiga e não estão presentes na tabela recém-criada.
  • Truncamento da tabela: truncar os dados de uma tabela (por exemplo, por meio de um job de consulta que usa writeDisposition de WRITE_TRUNCATE) pode causar a eliminação de inserções subsequentes durante o período de consistência.

Dados ausentes/não disponíveis

As inserções de streaming residem temporariamente no buffer de streaming, que tem características de disponibilidade diferentes do armazenamento gerenciado. Certas operações no BigQuery não interagem com o buffer de streaming, como jobs de cópia de tabela e métodos de API como tabledata.list. Desse modo, os dados de streaming recentes não estarão presentes na tabela de destino ou na saída.

Voltar ao início

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.