Resolver problemas de consulta

Este documento tem como objetivo ajudar você a solucionar problemas comuns relacionados à execução de consultas, como identificar motivos para consultas lentas ou fornecer etapas de resolução para erros comuns retornados por consultas com falha.

Resolver problemas de consultas lentas

Para resolver problemas de desempenho de consultas lentas, faça o seguinte:

• Verifique na página Google Cloud Service Health se há interrupções conhecidas do serviço do BigQuery que possam afetar o desempenho da consulta.

• Analise a linha do tempo do job da sua consulta no explorador de jobs para ver quanto tempo cada estágio da consulta levou para ser executado.

  • Se a maior parte do tempo decorrido foi devido a longos tempos de criação, entre em contato com o Cloud Customer Care para receber ajuda.

  • Se a maior parte do tempo decorrido foi devido a tempos de execução longos, revise os insights de desempenho da consulta. Os insights de desempenho de consulta podem informar se a consulta foi executada por mais tempo do que o tempo médio de execução e sugerir possíveis causas. As possíveis causas incluem contenção de slots de consulta ou uma cota de embaralhamento insuficiente. Para mais informações sobre cada problema de desempenho de consulta e possíveis soluções, consulte Interpretar insights de desempenho de consulta.

• Revise o campo finalExecutionDurationMs no tipo de objeto JobStatistics do job de consulta. A consulta pode ter sido repetida. O campo finalExecutionDurationMs contém a duração em milissegundos da execução da tentativa final desse job.

• Revise os bytes processados na página de detalhes do job de consulta para ver se o valor é maior do que o esperado. Para isso, compare o número de bytes processados pela consulta atual com outro job de consulta que foi concluído em um período aceitável. Se houver uma grande discrepância de bytes processados entre as duas consultas, talvez a consulta tenha sido lenta devido a um grande volume de dados. Para saber como otimizar suas consultas para lidar com grandes volumes de dados, consulte Otimizar a computação de consultas.

  Também é possível identificar consultas no projeto que processam uma grande quantidade de dados pesquisando as consultas mais caras usando a visualização INFORMATION_SCHEMA.JOBS.

• Analise o uso da reserva e verifique se há contenção de slots. Para mais informações, consulte Análise de estatísticas de carga de trabalho.

• Verifique as execuções anteriores e recentes do mesmo hash de consulta para ver se novos insights de desempenho de consulta estão disponíveis para os jobs mais lentos, como uma mudança na escala de entrada de dados. É possível filtrar por hash de consulta no explorador de jobs administrativos.

Comparar uma execução lenta e uma rápida da mesma consulta

Se uma consulta que antes era executada rapidamente agora está lenta, examine a saída do objeto da API Job para identificar mudanças na execução.

Ocorrências em cache

Confirme se a execução rápida do job foi uma ocorrência em cache analisando o valor de cacheHit. Se o valor for true para a execução rápida da consulta, ela usou resultados armazenados em cache em vez de executar a consulta.

Se você espera que o job lento use resultados armazenados em cache, investigue por que a consulta não está mais usando resultados armazenados em cache. Se você não espera que a consulta recupere dados do cache, procure um exemplo de execução rápida de consulta que não tenha acessado o cache para a investigação.

Atrasos de cota

Para determinar se a lentidão foi causada por adiamentos de cota, verifique o campo quotaDeferments nos dois jobs. Compare os valores para determinar se o horário de início da consulta mais lenta foi atrasado por adiamentos de cota que não afetaram o job mais rápido.

Duração da execução

Para entender a diferença entre a duração da execução da última tentativa de ambos os jobs, compare os valores do campo finalExecutionDurationMs.

Se os valores de finalExecutionDurationMs forem bastante semelhantes, mas a diferença no tempo de execução real entre as duas consultas, calculada como startTime - endTime, for muito maior, isso significa que pode ter havido uma nova tentativa de execução de consulta interna para o job lento devido a um possível problema temporário. Se você notar esse padrão de diferença repetidamente, entre em contato com o Cloud Customer Care para receber ajuda.

Bytes processados

Revise os bytes processados na página de detalhes do job de consulta ou consulte o totalBytesProcessed de JobStatistics para ver se ele é maior do que o esperado. Se houver uma grande discrepância de bytes processados entre as duas consultas, talvez a consulta esteja lenta devido a uma mudança no volume de dados processados. Para informações sobre como otimizar consultas para lidar com grandes volumes de dados, consulte Otimizar a computação de consultas. Os motivos a seguir podem causar um aumento no número de bytes processados por uma consulta:

• O tamanho das tabelas referenciadas pela consulta aumentou.
• A consulta agora está lendo uma partição maior da tabela.
• A consulta faz referência a uma visualização cuja definição foi alterada.

Tabelas referenciadas

Verifique se as consultas leem as mesmas tabelas analisando a saída do campo referencedTables em JobStatistics2. As diferenças nas tabelas referenciadas podem ser explicadas pelo seguinte:

• A consulta SQL foi modificada para ler tabelas diferentes. Compare o texto da consulta para confirmar isso.
• A definição da visualização mudou entre as execuções da consulta. Verifique as definições das visualizações referenciadas nesta consulta e atualize-as, se necessário.

As diferenças nas tabelas referenciadas podem explicar as mudanças em totalBytesProcessed.

Uso de visualizações materializadas

Se a consulta fizer referência a visualizações materializadas, as diferenças de desempenho podem ser causadas por visualizações materializadas que foram escolhidas ou rejeitadas durante a execução da consulta. Inspecione MaterializedViewStatistics para entender se alguma visualização materializada usada na consulta rápida foi rejeitada na consulta lenta. Observe os campos chosen e rejectedReason no objeto MaterializedView.

Estatísticas de armazenamento em cache de metadados

Para consultas que envolvem tabelas do BigLake do Amazon S3 ou do Cloud Storage com o armazenamento em cache de metadados ativado, compare a saída de MetadataCacheStatistics para verificar se há uma diferença no uso do cache de metadados entre a consulta lenta e a rápida e os motivos correspondentes. Por exemplo, o cache de metadados pode estar fora do intervalo de tempo maxStaleness configurado para a tabela.

Como comparar estatísticas do BigQuery BI Engine

Se a consulta usar o BigQuery BI Engine, analise a saída de BiEngineStatistics para determinar se os mesmos modos de aceleração foram aplicados à consulta lenta e à rápida. Confira o campo BiEngineReason para entender o motivo geral da aceleração parcial ou da falta de aceleração, como memória insuficiente, falta de reserva ou entrada muito grande.

Analisar diferenças nos insights de desempenho da consulta

Compare os insights de desempenho de consulta de cada uma das consultas analisando o gráfico de execução no console do Google Cloud ou o objeto StagePerformanceStandaloneInsight para entender os seguintes problemas possíveis:

• Contenção de slot (slotContention)
• Mesclagens de alta cardinalidade (highCardinalityJoins)
• Cota de embaralhamento insuficiente (insufficientShuffleQuota)
• Desvio de dados (partitionSkew)

Preste atenção aos insights fornecidos para o job lento e às diferenças entre os insights produzidos para o job rápido para identificar mudanças de estágio que afetam o desempenho.

Atribuição de reserva

Verifique se há diferenças na reserva atribuída aos dois jobs. Uma mudança na reserva ou uma mudança de sob demanda para uma reserva pode afetar o desempenho. Para mais informações, consulte Modelos de gerenciamento do Workload Manager e tamanho da reserva.

Uma análise mais completa dos metadados de execução do job requer a análise das etapas individuais de execução da consulta, comparando os objetos ExplainQueryStage dos dois jobs.

Para começar, consulte as métricas Wait ms e Shuffle output bytes descritas na seção interpretar informações do estágio de consulta.

Avisos de recursos da visualização INFORMATION_SCHEMA.JOBS

Consulte o campo query_info.resource_warning da visualização INFORMATION_SCHEMA.JOBS para conferir se há uma diferença nos avisos analisados pelo BigQuery em relação aos recursos usados.

Análise de estatísticas de carga de trabalho

Os recursos de slot disponíveis e a contenção de slots podem afetar o tempo de execução da consulta. As seções a seguir ajudam a entender o uso e a disponibilidade de slots para uma execução específica de uma consulta.

Média de slots por segundo

Para calcular o número médio de slots usados por milissegundo pela consulta, divida o valor de milissegundos de slot do job, totalSlotMs de JobStatistics2, pela duração em milissegundos da execução da tentativa final desse job, finalExecutionDurationMs de JobStatistics.

Também é possível calcular o número médio de slots por milissegundo usados por um job consultando a visualização INFORMATION_SCHEMA.JOBS.

Um job que realiza uma quantidade semelhante de trabalho com uma quantidade maior de slots médios por segundo é concluído mais rapidamente. Um uso médio de slots por segundo menor pode ser causado pelo seguinte:

• Não havia outros recursos disponíveis devido a uma contenção de recursos entre jobs diferentes. A reserva estava no limite.
• O job não solicitou mais slots durante uma grande parte da execução. Por exemplo, isso pode acontecer quando há desvio de dados.

Modelos de gerenciamento de cargas de trabalho e tamanho da reserva

Se você usa o modelo de faturamento sob demanda, o número de slots que podem ser usados por projeto é limitado. Além disso, seu projeto talvez ocasionalmente tenha menos slots disponíveis se houver uma grande quantidade de contenção de capacidade on demand em um local específico.

O modelo baseado em capacidade é mais previsível e permite especificar um número confirmado de slots de referência.

Considere essas diferenças ao comparar uma execução de consulta que usa o modelo on demand com uma que usa uma reserva.

Usar uma reserva é recomendado para ter um desempenho de execução de consulta estável e previsível. Para mais informações sobre as diferenças entre cargas de trabalho sob demanda e baseadas em capacidade, consulte Introdução ao gerenciamento de cargas de trabalho.

Simultaneidade de jobs

A simultaneidade de jobs representa a competição entre jobs por recursos de slot durante a execução da consulta. Uma simultaneidade de jobs mais alta geralmente causa uma execução mais lenta, porque o job tem acesso a menos slots.

É possível consultar a visualização INFORMATION_SCHEMA.JOBS para encontrar o número médio de jobs simultâneos em execução ao mesmo tempo que uma consulta específica em um projeto.

Se houver mais de um projeto atribuído a uma reserva, modifique a consulta para usar JOBS_BY_ORGANIZATION em vez de JOBS_BY_PROJECT para receber dados precisos no nível da reserva.

Uma simultaneidade média mais alta durante a execução do job lento em comparação com o job rápido é um fator que contribui para a lentidão geral.

Reduza a simultaneidade no projeto ou na reserva distribuindo consultas que usam muitos recursos ao longo do tempo em uma reserva ou projeto ou em reservas ou projetos diferentes.

Outra solução é comprar uma reserva ou aumentar o tamanho de uma reserva atual. Considere permitir que a reserva use slots inativos.

Para entender quantos slots adicionar, leia sobre como estimar os requisitos de capacidade de slot.

Os jobs em execução em reservas com mais de um projeto atribuído podem ter resultados de atribuição de slots diferentes com a mesma simultaneidade média de jobs, dependendo de qual projeto os está executando. Leia sobre programação justa para saber mais.

Uso da reserva

Os gráficos de recursos do administrador e o Cloud Monitoring do BigQuery podem ser usados para monitorar a utilização da reserva. Para mais informações, consulte Monitore as reservas do BigQuery.

Para entender se um job solicitou slots adicionais, consulte a métrica de unidades executáveis estimadas, que é estimatedRunnableUnits da resposta da API Job ou period_estimated_runnable_units na visualização INFORMATION_SCHEMA.JOBS_TIMELINE. Se o valor dessa métrica for maior que 0, o job poderá ter se beneficiado de slots adicionais naquele momento. Para estimar a porcentagem do tempo de execução do job em que ele teria se beneficiado de slots adicionais, execute a seguinte consulta na visualização INFORMATION_SCHEMA.JOBS_TIMELINE:

SELECT
  ROUND(COUNTIF(period_estimated_runnable_units > 0) / COUNT(*) * 100, 1) AS execution_duration_percentage
FROM `myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE
WHERE job_id = 'my_job_id'
GROUP BY job_id;

O resultado será semelhante ao seguinte:

+---------------------------------+
|   execution_duration_percentage |
+---------------------------------+
|                            96.7 |
+---------------------------------+

Uma porcentagem baixa significa que a disponibilidade de recursos de slot não é uma das principais influências para a lentidão da consulta nesse cenário.

Se a porcentagem for alta e a reserva não tiver sido totalmente utilizada durante esse período, entre em contato com o Cloud Customer Care para investigar.

Se a reserva foi totalmente utilizada durante a execução lenta do job e a porcentagem é alta, o job foi limitado em recursos. Reduza a simultaneidade, aumente o tamanho da reserva, permita que ela use slots inativos ou compre uma reserva se o job tiver sido executado sob demanda.

Os metadados do job e as descobertas da análise de carga de trabalho são inconclusivos

Se você ainda não conseguir encontrar o motivo para explicar o desempenho de consulta mais lento do que o esperado, entre em contato com o Cloud Customer Care para receber ajuda.

Resolver problemas de consultas usando o Gemini Cloud Assist

Para usar o Gemini Cloud Assist para ajudar a resolver uma falha de consulta ou um problema de desempenho, faça o seguinte:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. Na barra de ferramentas do Google Cloud , clique em spark Abrir ou fechar o chat do Gemini Cloud Assist.

3. No painel do Cloud Assist, insira um comando que inclua o ID da tarefa para investigar a execução, as métricas de performance ou os motivos da falha. Exemplo:

   • Por que o JOB_ID falhou?
   • Por que este job está demorando tanto? JOB_ID
   • Resuma meu desempenho no trabalho nas últimas 24 horas.

Resolver falhas de consulta usando gcpdiag

gcpdiag é uma ferramenta de código aberto. Não é um produto do Google Cloud oficialmente compatível. Use a ferramenta gcpdiag para identificar e corrigir problemas no projeto do Google Cloud. Para mais informações, consulte o projeto gcpdiag no GitHub.

A ferramenta gcpdiag ajuda a analisar consultas do BigQuery com falha para entender se há uma causa raiz conhecida e uma mitigação para a falha específica.

Execute o comando gcpdiag.

Execute o comando gcpdiag na Google Cloud CLI:

Console doGoogle Cloud

1. Preencha e copie o comando a seguir.

gcpdiag runbook bigquery/failed-query \
   --parameter project_id=PROJECT_ID \
   --parameter bigquery_job_region=JOB_REGION \
   --parameter bigquery_job_id=JOB_ID \
   --parameter bigquery_skip_permission_check=SKIP_PERMISSION_CHECK

2. Abra o console do Google Cloud e ative o Cloud Shell.
Abrir Console do Cloud
3. Cole o comando copiado.
4. Execute o comando gcpdiag, que faz o download da imagem Docker gcpdiag. e realiza verificações de diagnóstico. Se aplicável, siga as instruções de saída para corrigir verificações com falha.

Docker

Você pode executar gcpdiag usando um wrapper que inicia gcpdiag em um contêiner do Docker. Docker ou Podman precisa ser instalado.

1. Copie e execute o seguinte comando na estação de trabalho local.

   curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag

2. Execute o comando gcpdiag.

   ./gcpdiag runbook bigquery/failed-query \
      --parameter project_id=PROJECT_ID \
      --parameter bigquery_job_region=JOB_REGION \
      --parameter bigquery_job_id=JOB_ID \
      --parameter bigquery_skip_permission_check=SKIP_PERMISSION_CHECK

Veja os parâmetros disponíveis para este runbook.

Substitua:

• PROJECT_ID: o ID do projeto que contém o recurso.
• JOB_REGION: a região em que o job do BigQuery foi executado.
• JOB_ID: o identificador do job do BigQuery.
• SKIP_PERMISSION_CHECK: (opcional) defina como True se quiser pular a verificação de permissões relevantes e acelerar a execução do runbook (o valor padrão é False).

Flags úteis

• --universe-domain: se aplicável, a Nuvem soberana de parceiro confiável que hospeda o recurso
• --parameter ou -p: parâmetros do runbook

Para conferir uma lista e descrição de todas as flags da ferramenta gcpdiag, consulte Instruções de uso do gcpdiag.

Resolução de esquema Avro

String de erro: Cannot skip stream

Esse erro pode ocorrer ao carregar vários arquivos Avro com esquemas diferentes, resultando em um problema de resolução de esquema e fazendo com que o job de importação falhe em um arquivo aleatório.

Para resolver esse erro, verifique se o último arquivo alfabético do job de carregamento contém o superconjunto (união) dos esquemas diferentes. Esse é um requisito baseado em como o Avro processa a resolução de esquemas.

Consultas simultâneas em conflito

Strings de erro:

• Resources exceeded during query execution: Another job JOB_ID is currently running in the session SESSION_ID. Concurrent jobs in the same session are not allowed.
• Session SESSION_ID has expired and is no longer available.

Esse erro ocorre quando várias consultas são executadas simultaneamente na mesma sessão, o que não é permitido, ou quando uma sessão é encerrada automaticamente após 24 horas de inatividade ou 7 dias após a criação. Consulte as limitações de sessão e encerre uma sessão automaticamente.

Para resolver o problema, siga um destes procedimentos:

• Separe as consultas que compartilham um session_id e inicie a próxima consulta somente depois que o job anterior (JOB_ID) for concluído ou execute consultas simultâneas em sessões separadas.
• Se a sessão tiver expirado ou sido encerrada, crie uma nova sessão e atualize --session_id em .bigqueryrc ou connectionProperties, se configurado. Consulte Criar uma sessão.

Instruções DML conflitantes

String de erro: Could not serialize access to table due to concurrent update

Esse erro ocorre quando instruções simultâneas de linguagem de manipulação de dados (DML) mutáveis (UPDATE, DELETE ou MERGE) tentam modificar dados na mesma partição de tabela simultaneamente ou quando a tabela é truncada enquanto uma instrução DML está em execução.

O BigQuery permite que instruções DML mutantes simultâneas sejam executadas na mesma tabela, desde que modifiquem partições diferentes. No entanto, se dois jobs tentarem modificar a mesma partição, o primeiro job a ser confirmado será bem-sucedido, e os jobs seguintes vão falhar com esse erro.

Para resolver esse erro, tente o seguinte:

• Repetir o job com falha: se o conflito foi causado por uma sobreposição temporária com outro job, repita a consulta depois que o job conflitante for concluído.
• Identificar e coordenar jobs conflitantes: execute a consulta de diagnóstico na seção a seguir para identificar o job concorrente e, em seguida, coordene as programações para que as operações de DML mutantes na mesma partição não sejam executadas ao mesmo tempo.
• Particione as tabelas: se jobs de DML simultâneos atualizarem segmentos de dados diferentes, particione a tabela por data ou intervalo de números inteiros. As instruções DML mutantes simultâneas são bem-sucedidas sem conflito se modificarem partições diferentes.
• Operações DML em lote: combine várias operações UPDATE ou DELETE individuais em uma única instrução MERGE ou job em lote para reduzir a simultaneidade e a sobrecarga de commit. Para mais informações, consulte Práticas recomendadas.

Identificar o job conflitante

Para identificar qual job estava atualizando a tabela simultaneamente quando o erro ocorreu, execute uma consulta na visualização INFORMATION_SCHEMA.JOBS:

SELECT
  job_id,
  query,
  start_time,
  end_time
FROM
  `region-REGION`.INFORMATION_SCHEMA.JOBS
WHERE
  creation_time BETWEEN
    TIMESTAMP_SUB(TIMESTAMP 'FAILED_JOB_START_TIME', INTERVAL 1 DAY)
    AND TIMESTAMP 'FAILED_JOB_END_TIME'
  AND destination_table.table_id = 'TABLE_NAME'
  AND destination_table.dataset_id = 'DATASET_NAME'
  AND statement_type IN ('UPDATE', 'DELETE', 'MERGE')
  AND start_time <= 'FAILED_JOB_END_TIME'
  AND (end_time >= 'FAILED_JOB_START_TIME' OR end_time IS NULL)
ORDER BY
  start_time;

Substitua:

• REGION: o nome da região em que o conjunto de dados está localizado, por exemplo, us.
• FAILED_JOB_START_TIME: o carimbo de data/hora de quando o job com falha começou, por exemplo, 2026-09-01 09:55:00 UTC.
• FAILED_JOB_END_TIME: o carimbo de data/hora em que o job com falha terminou, por exemplo, 2026-09-01 10:00:00 UTC.
• TABLE_NAME: o nome da tabela que a instrução DML com falha tentou atualizar.
• DATASET_NAME: o nome do conjunto de dados que contém a tabela.

Se a consulta não retornar jobs conflitantes iniciados pelo usuário, o conflito pode ter sido causado por outra operação em segundo plano, como a expiração da partição.

Outras causas de conflitos de atualização simultânea

• Expiração da partição: as tarefas do sistema em segundo plano que expiram as partições podem entrar em conflito com uma instrução DML se modificarem a mesma partição durante a execução do job. Se você usar a expiração de partição, programe jobs de DML fora dos horários em que as partições expiram.
• Transações com várias instruções: quando uma transação com várias instruções modifica uma tabela, ela bloqueia todas as outras instruções DML simultâneas nessa tabela até que a transação seja concluída.
• Instruções DML que afetam zero linhas: uma instrução UPDATE, DELETE ou MERGE adquire bloqueios em partições segmentadas e pode causar conflitos de serialização, mesmo que nenhuma linha corresponda às condições de filtro.

Para mais informações, consulte Conflitos de instruções DML.

Subconsultas correlacionadas

String de erro: Correlated subqueries that reference other tables are not supported unless they can be de-correlated

Esse erro pode ocorrer quando a consulta contém uma subconsulta que faz referência a uma coluna de fora dessa subconsulta, chamada de coluna de correlação. A subconsulta correlacionada é avaliada usando uma estratégia de execução aninhada e ineficiente, em que a subconsulta é avaliada para cada linha da consulta externa que produz as colunas de correlação. Às vezes, o BigQuery pode reescrever internamente consultas com subconsultas correlacionadas para que elas sejam executadas com mais eficiência. O erro de subconsultas correlacionadas ocorre quando o BigQuery não consegue otimizar a consulta de maneira suficiente.

Para resolver esse erro, tente o seguinte:

• Remova as cláusulas ORDER BY, LIMIT, EXISTS, NOT EXISTS ou IN da subconsulta.
• Use uma consulta de várias instruções para criar uma tabela temporária que será referenciada na subconsulta.
• Reescreva a consulta para usar um CROSS JOIN.

Permissões de controle de acesso insuficientes no nível da coluna

Strings de erro:

• Access denied: Requires fineGrainedGet permission on the read columns to execute the DML statements
• "Acesso negado: o usuário não tem permissão para acessar a tag de política projects/PROJECT_ID/locations/LOCATION/taxonomies/TAXONOMY_ID/policyTags/POLICY_TAG_ID na coluna PROJECT_ID.DATASET.TABLE.COLUMN."

Esses erros ocorrem quando você tenta executar uma consulta SQL ou uma instrução DML DELETE, UPDATE ou MERGE sem receber o papel de Leitor refinado nas colunas que usam o controle de acesso no nível da coluna. Esse papel é atribuído aos principais como parte da configuração de uma tag de política. Para mais informações, consulte Impacto nas gravações com controle de acesso no nível da coluna.

Para contornar esse problema, modifique a consulta para excluir colunas com tags de política ou conceda o papel Leitor de controle granular ao usuário. Esse papel é atribuído aos principais como parte da configuração de uma tag de política. Para mais informações, consulte Atualizar permissões em tags de política.

Resolver problemas de consultas programadas

Os problemas a seguir podem surgir durante a configuração ou execução da consulta programada.

A consulta programada aciona execuções duplicadas

Uma consulta programada pode ser acionada mais de uma vez no horário programado. Esse comportamento é mais provável de ocorrer em consultas programadas exatamente na hora (como 09:00). Isso pode levar a resultados inesperados, como dados duplicados se a consulta realizar operações INSERT.

Para minimizar o risco de execuções duplicadas, programe as consultas para um horário fora do horário de pico, como alguns minutos antes ou depois da hora (por exemplo, 08:58 ou 09:03). Para mais informações, consulte Como programar consultas.

Credenciais inválidas para consultas programadas

Strings de erro:

• Error code: INVALID_USERID
• Error code 5: Authentication failure: User Id not found
• PERMISSION_DENIED: BigQuery: Permission denied while getting Drive credentials

Esse erro pode ocorrer quando uma consulta programada falha devido a credenciais desatualizadas, principalmente ao consultar dados do Google Drive.

Para corrigir esse erro, siga estas etapas:

• Verifique se você ativou o serviço de transferência de dados do BigQuery, que é um pré-requisito para usar consultas programadas.
• Atualize as credenciais de consultas programadas.

Credenciais de conta de serviço inválidas

String de erro: HttpError 403 when requesting returned: The caller does not have permission

Esse erro pode aparecer quando você tenta configurar uma consulta programada com uma conta de serviço. Para resolver esse erro, consulte as etapas de solução de problemas em Problemas de autorização e permissão.

Tabela de destino excluída ou expirada

String de erro: Destination deleted/expired during operation: DETAILS

Esse erro HTTP 400 Bad Request (reason: invalid) ocorre quando um job de consulta, carregamento ou cópia tenta gravar em uma tabela de destino que é removida antes da conclusão da execução do job.

Diagnóstico

Esse erro geralmente ocorre por um dos seguintes motivos:

1. A expiração da tabela ou do conjunto de dados (TTL) foi atingida. A tabela de destino (ou a validade padrão da tabela do conjunto de dados) tem um carimbo de data/hora de validade configurado. Se um job de longa duração continuar sendo executado após o carimbo de data/hora de expiração da tabela, o BigQuery vai excluir a tabela expirada enquanto o job ainda estiver em execução.
2. Exclusão explícita simultânea. Outro usuário, conta de serviço ou fluxo de trabalho automatizado (como um DAG de orquestrador ou script de limpeza) executa uma instrução DROP TABLE ou uma chamada de API tables.delete na tabela de destino enquanto o job está em andamento.

Para determinar por que a tabela de destino foi excluída, consulte a visualização INFORMATION_SCHEMA.TABLE_STORAGE:

SELECT
  table_name,
  deleted,
  table_deletion_time,
  table_deletion_reason
FROM
  `PROJECT_ID`.`region-REGION`.INFORMATION_SCHEMA.TABLE_STORAGE
WHERE
  table_schema = "DATASET_ID"
  AND table_name = "TABLE_ID"

Substitua:

• PROJECT_ID: o ID do projeto.
• REGION: a região do conjunto de dados que continha a tabela.
• DATASET_ID: o ID do conjunto de dados que continha a tabela.
• TABLE_ID: o ID da tabela de destino.

A coluna table_deletion_reason contém TABLE_EXPIRATION se a tabela expirou, USER_DELETED se um usuário excluiu a tabela ou DATASET_DELETION se um usuário excluiu o conjunto de dados que continha a tabela. Para mais informações, consulte Identificar a causa da exclusão da tabela.

Se a causa for USER_DELETED, consulte os Registros de auditoria do Cloud na Análise de registros para descobrir quem excluiu a tabela. Filtre as entradas no horário em que o job falhou:

resource.type=("bigquery_resource" OR "bigquery_dataset")
protoPayload.methodName=("tableservice.delete" OR "google.cloud.bigquery.v2.TableService.DeleteTable")
protoPayload.resourceName:"YOUR_TABLE_NAME"

Substitua YOUR_TABLE_NAME pelo ID da tabela de destino.

Inspecione o campo protoPayload.authenticationInfo.principalEmail nas entradas de registro correspondentes para identificar o usuário ou a conta de serviço que excluiu a tabela.

Se a causa for DATASET_DELETION, use o filtro do conjunto de dados em Identificar quando uma tabela foi excluída.

Resolução

Para resolver esse erro, faça o seguinte:

• Aumente os prazos de validade da tabela e do conjunto de dados. Inspecione o prazo de validade da tabela de destino e a configuração de validade padrão da tabela do conjunto de dados. Verifique se o TTL configurado é longo o suficiente para durar mais que o tempo de execução máximo esperado (incluindo o tempo de fila e as novas tentativas) dos jobs que gravam nessa tabela. Para instruções, consulte Atualizar o prazo de validade de uma tabela.
• Serializar tarefas de pipeline. Se um pipeline de ETL automatizado (como o Serviço Gerenciado para Apache Airflow, Apache Airflow ou Dataform) recriar ou limpar tabelas de preparo, configure dependências de tarefas estritas para que as tarefas de DROP TABLE ou limpeza nunca sejam executadas simultaneamente com jobs de gravação ativos direcionados à mesma tabela.
• Use nomes exclusivos para as tabelas de preparo. Ao executar instâncias de pipeline paralelas, grave resultados intermediários em tabelas temporárias ou de preparo com nomes exclusivos (por exemplo, usando CREATE TEMP TABLE em uma consulta de várias instruções ou anexando um ID de execução exclusivo), em vez de compartilhar uma única tabela de preparo mutável entre execuções simultâneas.

Instruções DML em tabelas com um buffer de streaming

String de erro: UPDATE or DELETE statement over table PROJECT_ID.DATASET_ID.TABLE_NAME would affect rows in the streaming buffer, which is not supported

Esse erro de HTTP 400 Bad Request (reason: invalidQuery) ocorre quando uma instrução DML mutável (UPDATE, DELETE ou MERGE) tenta modificar ou excluir linhas que foram ingeridas recentemente usando a API de streaming tabledata.insertAll legada e ainda estão no buffer de streaming. As linhas podem permanecer no buffer de streaming por alguns minutos ou até 90 minutos em casos raros. Para mais informações, consulte Disponibilidade de dados de streaming e Limitações da DML.

Para resolver esse erro, siga um destes procedimentos:

• Migre para a API BigQuery Storage Write (gRPC). Faça streaming de dados usando a API BigQuery Storage Write (gRPC), que disponibiliza imediatamente as linhas gravadas recentemente para instruções DML mutáveis (UPDATE, DELETE e MERGE) sem restrições de buffer de streaming.
• Aguarde a limpeza do buffer de streaming ou filtre as linhas recentes. Verifique a resposta tables.get para a seção streamingBuffer. Se streamingBuffer estiver ausente, todas as linhas estarão disponíveis para DML. Também é possível inspecionar streamingBuffer.oldestEntryTime e adicionar um filtro WHERE à instrução DML para que ela segmente apenas linhas mais antigas que a janela do buffer de streaming.

Erros de consulta inválida

Quando o BigQuery retorna um erro HTTP 400 Bad Request com o motivo de erro invalidQuery, a consulta SQL falhou nas verificações de validação ou execução. Use a mensagem de erro específica retornada pelo BigQuery para diagnosticar o problema nas quatro categorias a seguir:

Erros de sintaxe e gramática

Strings de erro:

• Syntax error: Expected TOKEN but got INPUT at [LINE:COLUMN]
• Syntax error: Unexpected keyword KEYWORD at [LINE:COLUMN]
• Unrecognized name: IDENTIFIER at [LINE:COLUMN] ou Function not found: FUNCTION_NAME at [LINE:COLUMN]

Para resolver erros de sintaxe e identificador, faça o seguinte:

• Inspecione o local [LINE:COLUMN]. Verifique a linha e a coluna na mensagem de erro (e o token imediatamente anterior) para ver se há parênteses não fechados, vírgulas ausentes, vírgulas à direita, aspas sem escape ou palavras-chave END ausentes em expressões CASE.
• Verifique a ordem e o dialeto da cláusula SQL. Confirme se as cláusulas SQL seguem a ordem necessária da sintaxe de consulta do GoogleSQL (SELECT → FROM → WHERE → GROUP BY → HAVING → QUALIFY → ORDER BY → LIMIT) e verifique se a solicitação usa o GoogleSQL (useLegacySql=false). Para erros de SQL legado, consulte Erros de SQL legado.
• Verifique o escopo da coluna, do alias e da função. Se o erro informar Unrecognized name ou Function not found, verifique os seguintes casos:
  • Identificador com erro de ortografia ou incompatibilidade de maiúsculas e minúsculas. Verifique a ortografia e as letras maiúsculas e minúsculas da coluna ou tabela em relação ao esquema da tabela.
  • Alias SELECT referenciado em WHERE. Não faça referência a aliases definidos na lista SELECT dentro da mesma cláusula WHERE. Repita a expressão, use uma subconsulta ou CTE ou filtre em QUALIFY (para funções de janela).
  • Função definida pelo usuário (UDF) permanente não qualificada. Qualifique UDFs permanentes com PROJECT_ID.DATASET_ID.FUNCTION_NAME.
  • Caracteres especiais ou palavras-chave reservadas. Coloque nomes de tabelas ou colunas que contenham caracteres especiais ou palavras-chave reservadas entre acentos graves (`). Também é possível usar o validador de consulta no BigQuery Studio para detectar problemas de sintaxe antes de executar a consulta.

Erros de compatibilidade de tipo de dados

Strings de erro:

• No matching signature for operator OPERATOR for argument types: TYPE_A, TYPE_B
• No matching signature for function FUNCTION_NAME for argument types: ARG_TYPES
• Query column COLUMN_NUMBER has type SOURCE_TYPE which cannot be inserted into column TARGET_COLUMN, which has type TARGET_TYPE
• Unsupported type TYPE

Para resolver incompatibilidades de tipo de dados, faça o seguinte:

• Alinhe os tipos em comparações, mesclagens e funções. Consulte INFORMATION_SCHEMA.COLUMNS ou inspecione o esquema da tabela no console doGoogle Cloud para verificar se todas as entradas usam tipos de dados do GoogleSQL compatíveis nos seguintes locais:
  • WHERE filtros e JOIN ... ON chaves
  • Argumentos COALESCE e IFNULL
  • Posições das colunas UNION e INSERT ... SELECT
  • Argumentos e tipos de retorno de UDF (incluindo tipos RETURNS de UDF em JavaScript)
  • Funções do BigQuery ML (ML.EVALUATE, ML.PREDICT)
• Aplicar conversões de tipo explícitas. Use CAST() ou SAFE_CAST() ou funções de análise de data e hora (como PARSE_DATE, PARSE_TIMESTAMP e TIMESTAMP_SECONDS) para converter valores explicitamente, em vez de depender de coerção implícita.
• Processar tipos de exportação ou federados não compatíveis. Ao executar EXPORT DATA ou consultas federadas em tipos geográficos ou complexos não compatíveis (como GEOGRAPHY, INTERVAL ou BIGNUMERIC), escolha uma das seguintes opções:
  • Converta a coluna em STRING na lista SELECT.
  • Mude o formato EXPORT DATA para AVRO ou PARQUET para preservar a fidelidade do tipo.

Restrições de recursos e arquitetura

Strings de erro:

• Invalid table-valued function FUNCTION_NAME ou Missing required option OPTION_NAME
• Unsupported aggregate function in materialized view
• Cannot query over table 'TABLE_NAME' without a filter over column(s) 'COLUMN_NAME' that can be used for partition elimination
• UPDATE/MERGE must match at most one source row for each target row
• Invalid snapshot time
• Too many nested views/persistent user-defined functions...

Para resolver erros de recursos, DDL e restrição de consulta, faça o seguinte:

• Verifique o OPTIONS(...) obrigatório nas instruções DDL. Ao criar tabelas externas, funções remotas ou modelos, verifique se todas as opções necessárias (como format e uris para tabelas externas) estão especificadas com tipos válidos na cláusula OPTIONS. Consulte Instruções de linguagem de definição de dados (DDL).
• Verifique as limitações de SQL da visualização materializada. As visualizações materializadas são compatíveis com um subconjunto restrito de agregações SQL e não podem referenciar funções não determinísticas, como CURRENT_DATE(), RAND() ou SESSION_USER(). Consulte Visualizações materializadas compatíveis.
• Inclua os filtros de partição necessários. Se a tabela de destino aplicar require_partition_filter = true, inclua um predicado WHERE na coluna de particionamento que pode remover partições. Consulte Consultar tabelas particionadas.
• Eliminar duplicação de UPDATE ou MERGE linhas de origem. Se uma instrução UPDATE ou MERGE falhar porque várias linhas de origem correspondem a uma única linha de destino, agregue ou elimine a duplicação da origem FROM ou USING (por exemplo, usando GROUP BY ou QUALIFY ROW_NUMBER() OVER (...) = 1). Consulte Limitações de DML.
• Verifique os limites de viagem no tempo, aninhamento de visualizações e subconsultas. Dependendo da mensagem de erro, consulte uma das seguintes seções:
  • FOR SYSTEM_TIME AS OF fora da janela de retenção. Consulte Hora inválida do snapshot.
  • Visualizações ou rotinas que excedem o limite de profundidade de aninhamento de 16 níveis. Consulte Muitas visualizações aninhadas ou funções definidas pelo usuário persistentes.
  • Subconsultas correlacionadas não compatíveis. Consulte Subconsultas correlacionadas.

Estado de execução e restrições de simultaneidade

Strings de erro:

• Concurrent conflicting update to DML transaction conflict ou Could not serialize access to table TABLE_NAME due to concurrent update
• Transaction is aborted due to concurrent update against table TABLE_NAME
• UPDATE or DELETE statement over table TABLE_NAME would affect rows in the streaming buffer, which is not supported

Para resolver erros de estado de execução e simultaneidade, consulte a seção dedicada à sua mensagem de erro:

• Conflitos de transação ou DML simultâneos. Consulte Instruções DML conflitantes e Transação cancelada devido à atualização simultânea.
• DML em tabelas com buffers de streaming ativos. Consulte Instruções DML em tabelas com um buffer de streaming.

Hora inválida do snapshot

String de erro: Invalid snapshot time

Esse erro pode ocorrer ao tentar consultar dados históricos que estão fora da janela de viagem no tempo para o conjunto de dados. Para solucionar esse erro, mude a consulta para acessar dados históricos na janela de viagem no tempo do conjunto de dados.

Esse erro também pode aparecer se uma das tabelas usadas na consulta for descartada e recriada depois que a consulta for iniciada. Verifique se há uma consulta programada ou um aplicativo que execute essa operação que foi executada ao mesmo tempo que a consulta com falha. Se houver, tente mover o processo que executa a operação de soltar e recriar para ser executado em um horário que não entre em conflito com as consultas que leem essa tabela.

O job já existe

String de erro: Already Exists: Job <job name>

Esse erro pode ocorrer em jobs de consulta que precisam avaliar matrizes grandes. Assim, a criação de um job de consulta leva mais tempo que a média. Por exemplo, uma consulta com uma cláusula WHERE como WHERE column IN (<2000+ elements array>).

Para corrigir esse erro, siga estas etapas:

• Permita que o BigQuery gere um valor jobId aleatório em vez de especificar um.
• Use uma consulta parametrizada para carregar a matriz.

Esse erro também pode ocorrer quando você define manualmente um ID da tarefa, mas a tarefa não retorna sucesso dentro de um período de tempo limite. Nesse caso, é possível adicionar um gerenciador de exceções para verificar se o job existe. Se sim, é possível extrair os resultados da consulta do job.

Job não localizado

String de erro: Job not found

Esse erro pode ocorrer em resposta a uma chamada getQueryResults, em que nenhum valor é especificado para o campo location. Se esse for o caso, tente ligar novamente e forneça um valor location.

Para mais informações, consulte Evitar várias avaliações das mesmas expressões de tabela comum (CTEs).

Local não encontrado

String de erro: Dataset [project_id]:[dataset_id] was not found in location [region]

Esse erro é retornado quando você se refere a um recurso de conjunto de dados que não existe ou quando o local na solicitação não corresponde ao local do conjunto de dados.

Para resolver esse problema, especifique o local do conjunto de dados na consulta ou confirme se ele está disponível no mesmo local.

A consulta excede o limite de tempo de execução

String de erro: Query fails due to reaching the execution time limit ou Operation timed out after 6.0 hours. Consider reducing the amount of work performed by your operation so that it can complete within this limit.

Se a consulta estiver atingindo o limite de tempo de execução da consulta, verifique a duração das execuções anteriores consultando a visualização INFORMATION_SCHEMA.JOBS com uma consulta semelhante ao seguinte exemplo:

SELECT TIMESTAMP_DIFF(end_time, start_time, SECOND) AS runtime_in_seconds
FROM `region-us`.INFORMATION_SCHEMA.JOBS
WHERE statement_type = 'QUERY'
AND query = "my query string";

Se as execuções anteriores da consulta tiverem demorado muito menos tempo, use os insights de desempenho da consulta para determinar e resolver o problema.

A consulta excede o limite máximo de bytes faturados

String de erro: Query exceeded limit for bytes billed: LIMIT_BYTES. REQUIRED_BYTES or higher required.

Esse erro HTTP 400 Bad Request (reason: bytesBilledLimitExceeded) ocorre quando a estimativa de pré-execução de bytes a serem faturados para uma consulta (REQUIRED_BYTES) excede o limite de bytes configurado em maximumBytesBilled (LIMIT_BYTES). O BigQuery falha no job antes da execução e não cobra pela consulta.

Como os preços sob demanda aplicam um mínimo de 10 MB (10,485,760 bytes) por tabela referenciada e a estimativa de pré-execução para tabelas em cluster calcula um limite superior em todas as partições correspondentes antes da remoção do cluster, REQUIRED_BYTES pode ser maior do que os bytes reais verificados quando a consulta é executada.

Para resolver o problema, siga um destes procedimentos:

• Visualize os bytes estimados com uma simulação. Faça uma simulação (bq query --dry_run na CLI bq ou configuration.dryRun = true na API) ou verifique o validador de consulta no console do Google Cloud para inspecionar totalBytesProcessed antes de executar a consulta.
• Otimize a consulta para verificar menos bytes. Selecione apenas as colunas necessárias para a consulta em vez de executar SELECT * e filtre as colunas particionadas para que o BigQuery possa remover partições durante a estimativa de pré-execução. A filtragem em colunas em cluster reduz os bytes reais cobrados quando a consulta é executada, mas não reduz a estimativa de limite superior pré-execução verificada em relação a maximumBytesBilled. Para mais informações, consulte Reduzir tratamento de dados.
• Aumente o limite de maximumBytesBilled. Defina o limite de bytes de maximumBytesBilled como um valor igual ou superior ao valor de REQUIRED_BYTES informado na mensagem de erro usando Máximo de bytes cobrados (em Configurações de consulta > Opções avançadas) no console do Google Cloud , a flag --maximum_bytes_billed na CLI bq ou a propriedade de configuração de job configuration.query.maximumBytesBilled na API.

A resposta da consulta é muito grande

String de erro: responseTooLarge

Esse erro ocorre quando os resultados da consulta são maiores do que o tamanho máximo da resposta ou quando uma única linha excede o limite de tamanho de linha da API REST.

Algumas consultas são executadas em várias etapas, e esse erro ocorre quando qualquer etapa retorna um tamanho de resposta muito grande, mesmo que o resultado final seja menor que o máximo. Esse erro costuma ocorrer quando as consultas usam uma cláusula ORDER BY. Remover a cláusula ORDER BY ou adicionar uma cláusula LIMIT às vezes pode ser útil. Para garantir que resultados grandes retornem, especifique uma tabela de destino na configuração do job. Para consultas SQL legadas, também é necessário definir a propriedade configuration.query.allowLargeResults como true. Para mais informações, consulte Como gravar resultados de consulta extensos.

O limite de tamanho da resposta de linha única foi excedido

Strings de erro:

• Response too large to return. Message before conversion exceeds max row limit, limit: LIMIT actual: ACTUAL
• Response too large to return. single row too big to return due to byte limit, actual: ACTUAL limit: LIMIT

Esse erro HTTP 403 Forbidden (reason: responseTooLarge) ocorre quando você lê resultados de consulta ou linhas de tabela usando os métodos da API REST jobs.getQueryResults ou tabledata.list (incluindo a exibição de resultados no console do Google Cloud ou na ferramenta de linha de comando bq), e uma única linha serializada não aninhada excede o tamanho máximo de linha compatível com o endpoint de paginação REST (20 MB para jobs.getQueryResults ou 100 MB para tabledata.list). Isso geralmente acontece em tabelas com esquemas amplos, campos ARRAY ou STRUCT repetidos profundamente aninhados ou valores STRING ou BYTES grandes.

Para ler linhas que excedem os limites de tamanho de linha da API REST, faça o seguinte:

• Use a API BigQuery Storage Read. Leia a tabela ou a tabela de destino da consulta temporária usando a API Storage Read, que transmite dados no formato binário Apache Arrow ou Avro e é compatível com leituras de alta capacidade de processamento de estruturas de linha grandes e complexas.
• Exportar a tabela para o Cloud Storage. Exporte os resultados da tabela ou da consulta para o Cloud Storage usando uma instrução EXPORT DATA ou um job de extração (por exemplo, no formato Avro, Parquet ou JSON) e leia os arquivos exportados do Cloud Storage.
• Projete ou agregue menos colunas. Em vez de executar SELECT *, selecione apenas as colunas ou subcampos específicos exigidos pelo aplicativo ou remova o aninhamento de matrizes repetidas na consulta para que as linhas de saída individuais permaneçam abaixo do limite de tamanho.

Parâmetro obrigatório ausente

String de erro: Required parameter is missing: PARAMETER_NAME

Esse erro de HTTP 400 Bad Request (reason: required) é um erro de validação de API pré-execução que ocorre quando um campo obrigatório em um payload de solicitação de API ou URL não é fornecido ou quando uma propriedade obrigatória em um objeto de configuração da biblioteca de cliente é null ou None.

Para resolver esse erro, faça o seguinte:

• Consulte a referência da API REST. Inspecione o PARAMETER_NAME na mensagem de erro e revise o corpo da solicitação e os parâmetros de consulta obrigatórios para o método na referência da API REST do BigQuery para garantir que o código preencha todos os campos obrigatórios.
• Verifique os parâmetros da biblioteca de cliente. Se você usa uma biblioteca de cliente do BigQuery (como a biblioteca de cliente Java ou Python), verifique a documentação da biblioteca de cliente para ver os parâmetros necessários do método que você está chamando.
• Inspecione o objeto de configuração antes de chamar a API. Use um depurador ou uma log statement para inspecionar o objeto de configuração do job ou da solicitação imediatamente antes da execução da chamada de API e verifique se há valores None ou null atribuídos a propriedades obrigatórias, como destinationTable.

A reserva não foi encontrada ou não tem slots

String de erro: Cannot run query: project does not have the reservation in the data region or no slots are configured

Esse erro ocorre quando a reserva atribuída ao projeto na região da consulta tem zero slots atribuídos. É possível adicionar slots à reserva, permitir que ela use slots inativos, usar uma reserva diferente ou remover a atribuição e executar a consulta sob demanda.

Tabela não encontrada

String de erro: Not found: Table [project_id]:[dataset].[table_name] was not found in location [region]

Esse erro ocorre quando uma tabela na consulta não é encontrada no conjunto de dados ou na região que você especificou. Para resolver esse erro, faça o seguinte:

• Verifique se a consulta contém o projeto, o conjunto de dados e o nome da tabela corretos e se o identificador usa as maiúsculas e minúsculas exatas (consulte Diferenciação de maiúsculas e minúsculas). Se a consulta omitir o ID do projeto, o BigQuery vai usar como padrão o projeto de faturamento que está executando o job. Especifique o PROJECT_ID.DATASET_ID.TABLE_NAME totalmente qualificado ao consultar tabelas em outro projeto.
• Verifique se a tabela existe no local em que a consulta é executada. Por padrão, todos os conjuntos de dados em que uma consulta lê ou grava precisam estar no mesmo local que o job de consulta. Se você definir o local do job (por exemplo, com a sinalização --location ou a propriedade location na referência do job), verifique se ele corresponde ao local dos conjuntos de dados. Uma região única, como us-central1, não corresponde a uma multirregião, como US. Para mais informações, consulte Especificar locais.
• Para consultar tabelas em locais diferentes em uma única consulta, use consultas globais (pré-lançamento). As consultas globais precisam ser ativadas para o projeto que executa a consulta e para o projeto que contém os dados, e não são compatíveis com o modo sandbox.
• Verifique se a tabela ou o conjunto de dados expirou ou foi excluído consultando INFORMATION_SCHEMA.TABLE_STORAGE ou inspecionando os Registros de auditoria do Cloud em busca de eventos DeleteTable ou InternalTableExpired. Se a tabela tiver sido excluída dentro da janela de viagem no tempo (até sete dias), será possível restaurar a tabela excluída. Se o conjunto de dados pai também tiver sido excluído, recrie um conjunto de dados vazio com o mesmo nome e local antes de copiar o snapshot histórico.
• Se você estiver consultando uma tabela de resultados em cache anônima em um conjunto de dados oculto que começa com um sublinhado (_), as tabelas de resultados em cache expiram após aproximadamente 24 horas. Execute novamente a consulta original ou grave a saída em uma tabela de destino persistente.
• Se você estiver consultando uma tabela externa com suporte do Cloud Storage ou do Google Drive, verifique se os arquivos de origem subjacentes ainda existem no caminho do URI configurado (Not found: URI, Not found: Uris ou Not found: Files).
• Verifique se a tabela não foi descartada e recriada durante a execução do job. Caso contrário, a propagação incompleta de metadados pode causar esse erro.

Muitas instruções DML

String de erro: Too many DML statements outstanding against <table-name>, limit is 20

Esse erro ocorre quando você excede o limite de 20 instruções DML mutantes no status PENDING em uma fila para uma única tabela. Esse erro geralmente ocorre quando você envia jobs DML em uma única tabela mais rapidamente do que o BigQuery pode processar.

Para verificar os jobs no status PENDING que preenchem a fila, além dos jobs RUNNING que podem estar impedindo que eles sejam removidos da fila, consulte a visualização INFORMATION_SCHEMA.JOBS:

SELECT
  project_id,
  job_id,
  creation_time,
  user_email,
  statement_type,
  state
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS
WHERE
  statement_type IN ('UPDATE', 'DELETE', 'MERGE', 'TRUNCATE_TABLE')
  AND state IN ('RUNNING', 'PENDING')
ORDER BY
  creation_time DESC;

Observação :o tamanho da fila limit is 20 se aplica especificamente à mutação de DML (UPDATE, DELETE e MERGE) e às instruções TRUNCATE TABLE. INSERT mantêm uma fila separada com um limite de 100.

Uma solução possível é agrupar várias operações DML menores em jobs maiores, mas com menos jobs. Por exemplo, agrupando atualizações e inserções em lote. Quando você agrupa jobs menores em jobs maiores, o custo para executá-los é amortizado e a execução é mais rápida. A consolidação de instruções DML que afetam os mesmos dados geralmente melhora a eficiência dos jobs DML e tem menor probabilidade de exceder o limite de cota de tamanho de fila. Para mais informações sobre como otimizar suas operações DML, consulte Evitar instruções DML que atualizam ou inserem linhas únicas.

Outras soluções para melhorar a eficiência da DML podem ser particionar ou agrupar as tabelas. Para saber mais, consulte Práticas recomendadas.

Erro 403: cota excedida

String de erro: 403 Quota exceeded: Your table exceeded quota for total number of DML jobs writing to a table, pending + running.

Esse erro ocorre quando o número total de jobs de DML (INSERT, UPDATE, DELETE e MERGE) que gravam em uma única tabela, nos estados PENDING e RUNNING, excede a cota de simultaneidade da tabela.

Enquanto o erro limit is 20 restringe especificamente a fila PENDING para instruções DML de mutação (UPDATE, DELETE e MERGE), o erro 403 Quota exceeded se aplica ao total combinado de todos os jobs de DML (INSERT mais DML de mutação) que gravam em uma tabela simultaneamente. Como a DML de mutação já está limitada pelo limite de fila de 20 jobs, esse erro de cota 403 ocorre com mais frequência quando você envia muitas consultas INSERT simultâneas em uma única tabela. Para resolver esse erro, faça o seguinte:

• Aumentar os slots de reserva: aumente o número de slots na sua reserva para ajudar os jobs a serem concluídos mais rapidamente e reduzir a simultaneidade de jobs. Isso reduz o número de jobs pendentes na fila e ajuda a evitar que o limite seja atingido.
• Otimize a orquestração do fluxo de trabalho: limite o número de tarefas DML simultâneas na ferramenta de orquestração para evitar exceder os limites de simultaneidade no nível da tabela (incluindo consultas INSERT de alta frequência que segmentam a mesma tabela).
• Operações DML em lote: combine várias instruções DML menores em menos instruções maiores para reduzir o número total de jobs na fila da tabela.

Muitas visualizações aninhadas ou funções definidas pelo usuário persistentes

String de erro: Too many nested views/persistent user-defined functions or possible circular reference of views/persistent user-defined functions referenced in query. Only 16 levels of nested views/persistent user-defined functions are allowed.

Esse erro de HTTP 400 Bad Request (reason: invalidQuery) ocorre quando uma consulta ou uma criação de visualização faz referência a uma cadeia de visualizações ou funções definidas pelo usuário (UDFs) permanentes que excede a profundidade máxima de aninhamento de 16 níveis ou quando uma consulta faz referência a visualizações ou UDFs que se referem umas às outras em um loop de dependência circular (por exemplo, view_a consulta view_b, que consulta view_a). Para detalhes sobre os limites de visualização e rotina, consulte Limites de visualização e Limites de UDF. Para erros causados por exceder o limite de 15 níveis de aninhamento em colunas STRUCT (RECORD), arquivos de carregamento ou tipos de retorno e argumentos de rotina aninhados, consulte Resolver erros de limite de aninhamento de esquema, arquivo e rotina.

É possível criar visualizações aninhadas em até 16 níveis, mas as consultas só podem referenciar visualizações aninhadas em até 15 níveis.

Esse limite não pode ser aumentado. Para resolver esse erro, faça o seguinte:

• Verifique se há referências circulares. Inspecione as definições das visualizações e UDFs persistentes na cadeia de consultas para verificar se nenhuma visualização ou função faz referência direta ou indireta a si mesma.
• Consolidar visualizações aninhadas. Refatore cadeias de visualizações aninhadas combinando a lógica intermediária em expressões de tabela comuns (cláusulas WITH) em uma única visualização ou consulta.
• Materializar camadas intermediárias. Substitua as camadas intermediárias em uma hierarquia de visualização profunda por consultas programadas que gravam em tabelas físicas ou use visualizações materializadas, quando compatíveis.

Transação cancelada devido a uma atualização simultânea

String de erro: Transaction is aborted due to concurrent update against table [table_name]

Esse erro pode ocorrer quando duas instruções DML mutantes diferentes tentam atualizar simultaneamente a mesma tabela. Por exemplo, suponha que você inicie uma transação em uma sessão que contenha uma instrução DML mutante seguida por um erro. Se não houver um gerenciador de exceções, o BigQuery reverterá automaticamente a transação quando a sessão terminar, o que leva até 24 horas. Durante esse período, outras tentativas de executar uma instrução DML de mutação na tabela vão falhar.

Para resolver esse erro, liste suas sessões ativas e verifique se alguma delas contém um job de consulta com o status ERROR que executou uma instrução DML de mutação na tabela. Reverta a transação não confirmada executando ROLLBACK TRANSACTION; nessa sessão ou encerre essa sessão executando CALL BQ.ABORT_SESSION(SESSION_ID);. Para evitar que transações com várias instruções com falha mantenham bloqueios de tabela até que a sessão expire, inclua um gerenciador EXCEPTION WHEN ERROR THEN ROLLBACK TRANSACTION; nas suas transações com várias instruções.

Erro 412: o job faz referência a uma tabela que pertence a um conjunto de dados de failover

String de erro: Error 412: The job references a table that belongs to a failover dataset in the ... region (PROJECT_ID:DATASET_ID). However, only jobs that run on a reservation with the "ENTERPRISE_PLUS" edition can modify or write to failover datasets. Please also make sure that the job that is writing to the failover dataset is running in the current primary location.

Isso significa que o job não foi executado em uma edição BigQuery Enterprise Plus ou foi executado em uma região diferente do local principal do conjunto de dados de failover. Consulte recuperação de desastres gerenciada para mais detalhes.

Erro ao carregar a visualização ao usar resultados armazenados em cache

String de erro: BigQuery data export: There was an error loading this view. IAM setPolicy failed for Dataset <PROJECT_ID>. One or more users named in the policy do not belong to a permitted customer.

Esse erro indica que os ID de cliente do Google Workspace não receberam acesso na restrição da política da organização. Para informações sobre como usar a restrição iam.allowedPolicyMemberDomains, consulte Usar a restrição iam.allowedPolicyMemberDomains para implementar o compartilhamento restrito de domínio.

Erros do SQL legado

Os erros a seguir podem surgir ao usar o SQL legado.

Cannot be queried with legacy SQL

String de erro: cannot be queried with legacy SQL. Please consider switching to standard SQL

Esse erro pode ocorrer em um dos dois cenários:

• A consulta foi escrita em SQL padrão, mas a opção de usar explicitamente o SQL legado foi provisionada. Siga a documentação pública para executar a consulta usando o SQL padrão. Por exemplo, forneça --use_legacy_sql=false usando a ferramenta de linha de comando bq.

• Você está tentando consultar uma tabela com ordenação usando o SQL legado, que não é compatível.

Não é possível consultar tabelas com colunas renomeadas usando o SQL legado.

String de erro: Table project:dataset.table with renamed columns cannot be queried with legacy SQL. Please consider switching to standard SQL or dropping column my_column

Esse erro ocorre se você consultar uma tabela com uma coluna renomeada usando o SQL legado. Em vez disso, use o SQL padrão.

O usuário não tem permissão

Strings de erro:

• Access Denied: Project [project_id]: User does not have bigquery.jobs.create permission in project [project_id].
• User does not have permission to query table project-id:dataset.table.
• Access Denied: User does not have permission to query table or perhaps it does not exist.

Esses erros podem ocorrer quando você executa uma consulta sem a permissão bigquery.jobs.create no projeto em que está executando a consulta, independentemente das suas permissões no projeto que contém os dados.

Você também poderá receber esses erros se a conta de serviço, o usuário ou o grupo não tiver a permissão bigquery.tables.getData em todas as tabelas e visualizações referenciadas pela consulta. Para mais informações sobre as permissões necessárias para executar uma consulta, consulte Papéis necessários.

Esse erro também poderá ocorrer se a tabela não existir na região consultada, como asia-south1. Para verificar a região, examine o local do conjunto de dados.

Ao corrigir esses erros, considere o seguinte:

• Contas de serviço: as contas de serviço precisam ter a permissão bigquery.jobs.create no projeto em que são executadas e a permissão bigquery.tables.getData em todas as tabelas e visualizações referenciadas pela consulta.

• Papéis personalizados: os papéis personalizados do IAM precisam ter a permissão bigquery.jobs.create explicitamente incluída no papel relevante e a permissão bigquery.tables.getData em todas as tabelas e visualizações referenciadas pela consulta.

• Conjuntos de dados compartilhados: ao trabalhar com conjuntos de dados compartilhados em um projeto separado, talvez você ainda precise da permissão bigquery.jobs.create no projeto para executar consultas ou jobs nesse conjunto de dados.

Para conceder permissão de acesso a uma tabela ou visualização, consulte Conceder acesso a uma tabela ou visualização.

Observação: se a conta de usuário ou de serviço for afetada por uma política de negação, talvez você receba um erro Access denied, mesmo que a conta tenha as permissões corretas. Para mais informações, consulte Políticas de negação.

Permissão bigquery.reservations.use negada na reserva

String de erro:

• Access Denied: Reservation projects/project/locations/region/reservations/reservation_name: Permission bigquery.reservations.use denied on reservation projects/project/locations/region/reservations/reservation_name (or it may not exist)

Esse erro ocorre quando uma consulta é atribuída para ser executada em uma reserva específica usando a instrução SET @@reservation e a conta de usuário ou de serviço não tem a permissão bigquery.reservations.use. É possível inspecionar a falha no Cloud Logging ou na página de jobs do BigQuery para identificar qual principal tentou realizar essa operação.

Outros erros de Access Denied

Strings de erro:

• Access Denied: Dataset project_id:dataset_id: Permission bigquery.datasets.get denied on dataset project_id:dataset_id (or it may not exist).
• Access Denied: Dataset project_id:dataset_id: Permission bigquery.datasets.update denied on dataset project_id:dataset_id (or it may not exist).
• Access Denied: BigQuery BigQuery: User does not have permission to access data protected by policy tag

Para resolver problemas gerais de Access Denied no BigQuery, use a ferramenta Análise de políticas para determinar o acesso de um principal a um recurso.

Na Análise de Políticas, forneça o recurso do BigQuery que você está tentando acessar (por exemplo, //bigquery.googleapis.com/projects/YOUR_PROJECT/datasets/YOUR_DATASET/tables/YOUR_TABLE) e o e-mail do usuário ou da conta de serviço que está recebendo o erro Access Denied como principal. A análise mostra as permissões do principal no recurso, que podem ser comparadas com as permissões ausentes na mensagem de erro.

A criptografia de destino não é compatível com scripts

String de erro: configuration.query.destinationEncryptionConfiguration cannot be set for scripts

Esse erro ocorre ao tentar definir a configuração de criptografia de destino para um job de script do BigQuery, que não é compatível.

Acesso negado pela política da organização

String de erro: IAM setPolicy failed for Dataset DATASET: Operation denied by org policy on resource.

Esse erro ocorre quando uma política da organização impede que o principal consulte um recurso do BigQuery. O serviço de políticas da organização permite que você aplique restrições aos recursos compatíveis em toda a hierarquia da organização.

Se o principal precisar ter acesso ao recurso, use as ferramentas de solução de problemas de VPC disponíveis para diagnosticar o problema com a política da organização.

Problemas com recursos excedidos

Os seguintes problemas ocorrem quando o BigQuery não tem recursos suficientes para concluir sua consulta.

A consulta excede os recursos da CPU

String de erro: Query exceeded resource limits. This query used CPU_SECONDS_USED CPU seconds but would charge only ANALYSIS_MEGABYTES_BILLEDM Analysis bytes. This exceeds the ratio supported by the on-demand pricing model. Please consider moving this workload to a capacity-based pricing model, which does not have this limit. CPU_SECONDS_USED CPU seconds were used, and this query must use less than CPU_SECONDS_LIMIT CPU seconds.

Esse erro (billingTierLimitExceeded) ocorre quando uma consulta que usa preços on demand excede o limite máximo de uso da CPU por dados verificados de aproximadamente 256 segundos de CPU por MiB de dados verificados. Isso acontece quando uma consulta sob demanda realiza operações que exigem muita CPU, como operações CROSS JOIN sem restrições, condições de mesclagem inexatas, expressões regulares complexas, funções de janela analítica não particionadas ou UDFs de JavaScript computacionalmente pesadas, em uma quantidade relativamente pequena de dados verificados.

Para resolver esse erro, siga um destes procedimentos:

• Otimize a consulta. Refatore o SQL para reduzir a sobrecarga de computação em relação aos dados verificados, por exemplo, removendo produtos cartesianos não intencionais (operações CROSS JOIN sem filtragem), substituindo predicados de mesclagem imprecisos, simplificando expressões regulares complexas, adicionando cláusulas PARTITION BY a funções de janela em grandes janelas não particionadas ou otimizando UDFs do JavaScript. Para mais informações, consulte Evitar padrões anti-SQL, Introdução à otimização do desempenho da consulta e Resolver problemas de recursos excedidos.
• Mudar para os preços baseados em capacidade. Execute a carga de trabalho usando preços com base na capacidade (slots). No preço baseado em capacidade, as consultas não estão sujeitas ao limite de proporção de CPU por byte sob demanda.

A consulta excede os recursos de memória

String de erro: Resources exceeded during query execution: The query could not be executed in the allotted memory

Para instruções SELECT, esse erro ocorre quando a consulta usa muitos recursos. Para corrigir esse erro, consulte Resolver problemas de recursos excedidos.

Espaço de pilha insuficiente

String de erro: Out of stack space due to deeply nested query expression during query resolution.

Esse erro pode ocorrer quando uma consulta contém muitas chamadas de função aninhadas. Às vezes, partes de uma consulta são traduzidas para chamadas de função durante a análise. Por exemplo, uma expressão com operadores de concatenação repetidos, como A || B || C || ..., se torna CONCAT(A, CONCAT(B, CONCAT(C, ...))).

Para resolver esse erro, reescreva a consulta para reduzir o número de aninhamentos.

Recursos excedidos durante a execução da consulta

String de erro: Resources exceeded during query execution: The query could not be executed in the allotted memory. Peak usage: [percentage]% of limit. Top memory consumer(s): ORDER BY operations.

Isso pode acontecer com consultas ORDER BY ... LIMIT ... OFFSET .... Devido a detalhes de implementação, a classificação pode ocorrer em uma única unidade de computação, que pode ficar sem memória se precisar processar muitas linhas antes que LIMIT e OFFSET sejam aplicados, principalmente com um OFFSET grande.

Para corrigir esse erro, evite valores OFFSET grandes em consultas ORDER BY ... LIMIT. Como alternativa, use a função de janela escalonável ROW_NUMBER() para atribuir classificações com base na ordem escolhida e, em seguida, filtre essas classificações em uma cláusula WHERE. Exemplo:

SELECT ...
FROM (
  SELECT ROW_NUMBER() OVER (ORDER BY ...) AS rn
  FROM ...
)
WHERE rn > @start_index AND rn <= @page_size + @start_index  -- note that row_number() starts with 1

Worker do TensorFlow sem memória

String de erro: Resources exceeded during query execution: TensorFlow worker out of memory.

Modelos que excedem o limite de memória (normalmente 250 MB), principalmente ao usar funções que consomem muitos recursos, como ML.EXPLAIN_PREDICT, podem acionar esse erro.

Para resolver esse erro, faça o seguinte:

1. Usar modelos remotos da Gemini Enterprise Agent Platform: para modelos que excedem os limites de memória, implante o modelo na Agent Platform usando as etapas do SDK da Vertex AI para Python para implantar um modelo e, em seguida, acesse-o usando modelos remotos. Isso transfere os requisitos de memória para a infraestrutura dedicada da Plataforma de Agentes.

2. Otimizar o modelo: reduza o consumo de RAM do modelo usando simplificação, quantização ou remoção de arquitetura.

3. Use funções menos intensivas: se o erro ocorrer durante uma chamada ML.EXPLAIN_PREDICT, tente executar o job com ML.PREDICT para determinar se o modelo pode ser executado sem a sobrecarga extra dos recursos de explicabilidade.

4. Analise o tamanho dos dados de entrada: linhas individuais grandes podem contribuir para o esgotamento da memória. Verifique o tamanho das maiores linhas usando:

   SELECT BYTE_LENGTH(TO_JSON_STRING(t)) AS row_size
   FROM your_table AS t
   ORDER BY row_size DESC
   LIMIT 10

A consulta excede os recursos de embaralhamento

String de erro: Resources exceeded during query execution: Your project or organization exceeded the maximum disk and memory limit available for shuffle operations

Esse erro ocorre quando uma consulta não pode acessar recursos suficientes do embaralhamento.

Para solucionar esse erro, provisione mais slots ou reduza a quantidade de dados processados pela consulta. Para mais informações sobre como fazer isso, consulte Cota de embaralhamento insuficiente.

Se você estiver usando o modelo de preços sob demanda, o limite é de 2.000 slots. Para aumentar o número de slots, mude para um modelo de preços baseado em capacidade.

Para mais informações sobre como resolver esses problemas, consulte Resolver problemas de recursos excedidos.

A consulta é muito complexa

Strings de erro:

• Resources exceeded during query execution: Not enough resources for query planning - too many subqueries or query is too complex.
• Resources exceeded during query execution: Not enough resources for query planning - too many fields accessed or query is too complex.
• Resources exceeded during query execution: Not enough resources for query planning - query is too complex.
• Resources exceeded during query execution: The query is too complex.

Esse erro ocorre quando uma consulta é muito complexa depois que as visualizações, as cláusulas WITH e as funções definidas pelo usuário (UDFs) do SQL são expandidas durante o planejamento da consulta. As principais causas de complexidade são:

• Cláusulas WITH que estão muito aninhadas ou são usadas de forma repetida.
• Visualizações muito aninhadas ou usadas de forma repetida.
• Uso repetido do operador UNION ALL.
• UDFs SQL complexas ou tabelas referenciadas amplas em que muitas colunas foram adicionadas.

Para resolver esse erro, tente as seguintes opções:

• Divida a consulta em várias consultas e use a linguagem processual para executar essas consultas em uma sequência, com estado compartilhado.
• Use tabelas temporárias em vez de cláusulas WITH ou visualizações muito aninhadas. Consulte Evitar várias avaliações dos mesmos CTEs.
• Reescreva sua consulta para reduzir o número de objetos, colunas e comparações referenciados.

É possível monitorar de maneira proativa as consultas que estão se aproximando do limite de complexidade usando o campo query_info.resource_warning na visualização INFORMATION_SCHEMA.JOBS. O exemplo a seguir retorna consultas com alto uso de recursos nos últimos três dias:

SELECT
  ANY_VALUE(query) AS query,
  MAX(query_info.resource_warning) AS resource_warning
FROM
  <your_project_id>.`region-us`.INFORMATION_SCHEMA.JOBS
WHERE
  creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 3 DAY)
  AND query_info.resource_warning IS NOT NULL
GROUP BY
  query_info.query_hashes.normalized_literals
LIMIT
  1000

Para mais informações sobre como resolver esses problemas, consulte Resolver problemas de recursos excedidos.

Resolver problemas de recursos excedidos

Para jobs de consulta:

Para otimizar suas consultas, siga estas etapas:

• Tente remover uma cláusula ORDER BY (especialmente dentro de subconsultas ou cláusulas WITH), adicione uma cláusula LIMIT ou pagine com ROW_NUMBER() OVER (ORDER BY ...) em vez de um OFFSET grande quando Top memory consumer(s): ORDER BY operations for relatado. Consulte A consulta excede os recursos de memória.
• Se a consulta falhar com Top memory consumer(s): sort operations used for analytic OVER() clauses ou analytic OVER() clauses, reescreva-a para reduzir a quantidade de dados em cada partição de janela (adicione ou refine a chave PARTITION BY) ou substitua RANGE BETWEEN por um frame de janela ROWS BETWEEN limitado, quando aplicável.
• Se a consulta usa JOIN (ou falha com Top memory consumer(s): JOIN operations), verifique se a tabela maior está à esquerda da cláusula e se os dados não contêm chaves de mesclagem duplicadas. Se um CROSS JOIN seguido por GROUP BY exceder a memória, salve o resultado intermediário do CROSS JOIN em uma tabela temporária antes de executar GROUP BY.
• Se uma instrução DML de mutação falhar com Top memory consumer(s): sort operation used for table update (UPDATE/DELETE/MERGE), divida a instrução UPDATE ou MERGE para atualizar menos linhas ou colunas por vez (ou substitua um MERGE que use ON FALSE por um INSERT e DELETE dentro de uma transação de várias instruções).
• Se a consulta falhar com Top memory consumer(s): query parsing and optimization, armazene listas literais codificadas grandes em uma tabela temporária, em vez de inline no texto da consulta, ou divida a consulta em consultas menores.
• Se a consulta falhar com UDF out of memory ou Top memory consumer(s): non-SQL user-defined functions, evite acumular estado local excessivo em UDFs do JavaScript, processe dados de entrada em blocos menores ou reescreva a UDF usando UDFs do SQL ou funções integradas do GoogleSQL. Consulte Práticas recomendadas para UDFs em JavaScript.
• 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, considere usar COUNT(DISTINCT).
• Se a consulta usa COUNT(DISTINCT <value>, <n>) com um grande valor <n>, use GROUP BY em vez disso. Para ver mais informações, consulte COUNT(DISTINCT).
• Se a consulta usa UNIQUE, utilize GROUP BY em vez disso, ou use a função de janela dentro de uma subseleção.
• Se a consulta materializar muitas linhas usando uma cláusula LIMIT, considere filtrar em outra coluna, por exemplo, ROW_NUMBER(), ou remover a cláusula LIMIT completamente para permitir o carregamento em paralelo de gravação.
• Se a consulta usou visualizações profundamente aninhadas e uma cláusula WITH, isso pode causar um crescimento exponencial na complexidade, o que causará o atingimento dos limites.
• Use tabelas temporárias em vez de cláusulas WITH. Uma cláusula WITH pode precisar ser recalculada várias vezes, o que pode tornar a consulta complexa e, portanto, lenta. Manter os resultados intermediários em tabelas temporárias reduz a complexidade.
• Evite usar consultas UNION ALL.
• Se a consulta usar MATCH_RECOGNIZE, modifique a cláusula PARTITION BY para reduzir o tamanho das partições ou adicione uma cláusula PARTITION BY, se não houver uma.
• Se o job falhar com Table TABLE_NAME will have N partitions when the job finishes, exceeding limit 10000, verifique a contagem de partições da tabela em INFORMATION_SCHEMA.PARTITIONS, configure uma expiração de partição ou exclua explicitamente as partições desnecessárias (porque as partições expiradas recentemente podem levar tempo para serem refletidas, a menos que sejam explicitamente excluídas). Consulte cotas de tabelas particionadas.
• Se o job falhar com Too many DML statements outstanding against table TABLE_NAME, limit is 20, agrupe várias instruções UPDATE, DELETE ou MERGE menores em jobs maiores ou particione e agrupe a tabela de destino. Consulte Muitas instruções DML e Muitas instruções DML pendentes na tabela.
• Se o job falhar com All our servers are busy processing data transferred between regions. Please try again shortly., tente novamente a consulta ou reduza a taxa simultânea de consultas de mesclagem entre nuvens (BigQuery Omni), CREATE TABLE AS SELECT, INSERT INTO SELECT ou LOAD DATA (ou entre em contato com o suporte para solicitar um limite de taxa de consulta de transferência entre regiões mais alto). Consulte Limitações de mesclagem do BigQuery Omni e Carregar dados usando uma transferência entre nuvens.
• Se o job falhar com Google Sheets service overloaded for spreadsheet id: SPREADSHEET_ID, tente novamente a sobrecarga temporária das Planilhas Google ou copie os dados da planilha para uma tabela permanente do BigQuery (e reestruture as visualizações ou escalone as consultas programadas para reduzir as leituras simultâneas na mesma planilha).
• Se uma consulta do BigQuery Omni falhar com Response too large. Query returned ACTUAL_MBMB, and limit is LIMIT_MBMB., a saída da consulta excedeu o tamanho máximo do resultado da consulta do BigQuery Omni ou o limite de transferência entre nuvens. Filtre ou agregue sua consulta para retornar resultados menores ou use a instrução EXPORT DATA para exportar resultados grandes diretamente para o armazenamento externo em vez de uma tabela de destino.

Para saber mais, acesse os recursos a seguir:

• Otimizar a computação em consultas.
• Confira mais detalhes sobre o aviso de recurso
• Monitorar a integridade, a utilização de recursos e os jobs

Para jobs de carregamento:

Se você estiver carregando arquivos Avro ou Parquet, reduza o tamanho da linha. Verifique se há restrições de tamanho específicas para o formato do arquivo que você está carregando:

• Requisitos do arquivo de entrada Avro
• Requisitos do arquivo de entrada Parquet

Se você receber esse erro ao carregar arquivos ORC, entre em contato com o suporte.

Para a API Storage:

String de erro: Stream memory usage exceeded

Durante uma chamada ReadRows da API Storage Read, alguns streams com alto uso da memória podem receber um erro RESOURCE_EXHAUSTED com essa mensagem. Isso pode acontecer na leitura de tabelas largas ou com um esquema complexo. Como resolução, reduza o tamanho da linha de resultado selecionando menos colunas para ler (usando o parâmetro selected_fields) ou simplificando o esquema da tabela. ,

Resolver problemas de conectividade

As seções a seguir descrevem como resolver problemas de conectividade ao tentar interagir com o BigQuery:

DNS do Google na lista de permissões

Use a ferramenta Google IP Dig para resolver o endpoint DNS do BigQuery bigquery.googleapis.com em um único IP de registro "A". Verifique se esse IP não está bloqueado nas configurações do firewall.

Em geral, recomendamos que você coloque os nomes de DNS do Google na lista de permissões. Os intervalos de IP compartilhados nos arquivos https://www.gstatic.com/ipranges/goog.json e https://www.gstatic.com/ipranges/cloud.json mudam com frequência. Por isso, recomendamos que você inclua os nomes de DNS do Google na lista de permissões. Confira uma lista de nomes DNS comuns que recomendamos adicionar à lista de permissões:

• *.1e100.net
• *.google.com
• *.gstatic.com
• *.googleapis.com
• *.googleusercontent.com
• *.appspot.com
• *.gvt1.com

Identificar o proxy ou o firewall que está descartando pacotes

Para identificar todos os saltos de pacotes entre o cliente e o Google Front End (GFE), execute um comando traceroute na máquina cliente que possa destacar o servidor que está descartando pacotes direcionados ao GFE. Confira um exemplo de comando traceroute:

traceroute -T -p 443 bigquery.googleapis.com

Também é possível identificar saltos de pacotes para endereços IP específicos do GFE se o problema estiver relacionado a um endereço IP específico:

traceroute -T -p 443 142.250.178.138

Se houver um problema de tempo limite do Google, a solicitação vai chegar até o GFE.

Se os pacotes nunca chegarem ao GFE, entre em contato com o administrador da rede para resolver o problema.

Gerar um arquivo PCAP e analisar o firewall ou proxy

Gere um arquivo de captura de pacotes (PCAP) e analise-o para garantir que o firewall ou o proxy não esteja filtrando pacotes para IPs do Google e esteja permitindo que os pacotes cheguem ao GFE.

Veja um exemplo de comando que pode ser executado com a ferramenta tcpdump:

tcpdump -s 0 -w debug.pcap -K -n host bigquery.googleapis.com

Configurar novas tentativas para problemas de conectividade intermitente

Há situações em que os balanceadores de carga do GFE podem descartar conexões de um IP de cliente. Por exemplo, se ele detectar padrões de tráfego de DDoS ou se a instância do balanceador de carga estiver sendo reduzida, o que pode resultar na reciclagem do IP do endpoint. Se os balanceadores de carga do GFE encerrarem a conexão, o cliente precisará capturar a solicitação que expirou e repetir a solicitação para o endpoint de DNS. Não use o mesmo endereço IP até que a solicitação seja bem-sucedida, porque o endereço IP pode ter mudado.

Se você identificou um problema com tempos limite consistentes do Google em que as novas tentativas não ajudam, entre em contato com o Cloud Customer Care e inclua um novo arquivo PCAP gerado pela execução de uma ferramenta de captura de pacotes, como tcpdump.

A seguir

• Receber insights de desempenho da consulta.
• Saiba mais sobre como otimizar consultas para melhorar o desempenho.
• Consulte Cotas e limites para consultas.
• Saiba mais sobre outras mensagens de erro do BigQuery.