Como solucionar problemas de erros de cota do BigQuery

O BigQuery tem várias cotas que limitam a taxa e o volume das solicitações recebidas. Essas cotas protegem os sistemas de back-end e ajudam na proteção contra o faturamento inesperado caso você envie jobs muito grandes. Neste documento, você verá como diagnosticar e mitigar erros resultantes de cotas.

Visão geral

Se uma operação do BigQuery falhar devido a um limite de cota, a API retornará o código de status HTTP 403 Forbidden. O corpo da resposta contém mais informações sobre o limite que foi atingido. O corpo da resposta será semelhante a este:

{
  "code" : 403,
  "errors" : [ {
    "domain" : "global",
    "message" : "Quota exceeded: ...",
    "reason" : "quotaExceeded"
  } ],
  "message" : "Quota exceeded: ..."
}

O campo message no payload descreve o limite que foi excedido. Por exemplo, o campo message exibirá Exceeded rate limits: too many table update operations for this table.

Em geral, os limites de cota se enquadram em duas categorias, indicadas pelo campo reason no payload de resposta.

  • rateLimitExceeded: esse valor indica um limite de curto prazo. Normalmente, é possível resolver as questões com esses limites ao repetir a operação após alguns segundos. Use a espera exponencial no intervalo das tentativas de repetição. Ou seja, aumente exponencialmente o atraso entre cada nova tentativa.

  • quotaExceeded: esse valor indica um limite de longo prazo. Se você atingir um limite de cota de longo prazo, aguarde 10 minutos ou mais antes de tentar novamente. Se você alcançar um desses limites de cota de longo prazo frequentemente, analise sua carga de trabalho para encontrar formas de minimizar o problema. Isso pode incluir a otimização da carga de trabalho ou a solicitação de um aumento de cota.

Para erros quotaExceeded, analise a mensagem de erro para entender qual limite de cota foi excedido. Em seguida, analise sua carga de trabalho e veja se é possível evitar atingir a cota ao otimizar o desempenho da consulta, por exemplo. Em alguns casos, é possível aumentar a cota ao entrar em contato com o suporte do BigQuery ou com a equipe de vendas do Google Cloud.

Use as visualizações INFORMATION_SCHEMA para analisar o problema original. Essas visualizações contêm metadados sobre seus recursos do BigQuery, incluindo jobs, reservas e inserções por streaming. Por exemplo, na consulta a seguir, a visualização JOBS_BY_PROJECT é usada para listar todos os erros relacionados a cotas que ocorreram no dia anterior.

SELECT
 job_id,
 creation_time,
 error_result
FROM `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP, INTERVAL 1 DAY) AND
      error_result.reason IN ('rateLimitExceeded', 'quotaExceeded')

Também é possível visualizar erros nos registros de auditoria do Cloud. Por exemplo, com o visualizador de registros, a consulta a seguir encontra erros com Quota exceeded na string da mensagem:

resource.type = ("bigquery_project" OR "bigquery_dataset")
protoPayload.status.code ="7"
protoPayload.status.message: "Quota exceeded"

O código de status 7 é PERMISSION_DENIED, que corresponde ao código de status HTTP 403.

Erros de cota de inserção de streaming

Nesta seção, você verá algumas dicas para solucionar erros de cota relacionados ao streaming de dados no BigQuery.

Em algumas regiões, as inserções de streaming têm uma cota maior se você não preencher o campo insertId de cada linha. Para mais informações sobre cotas para inserções de streaming, consulte Inserções de streaming. Os erros relacionados à cota de streaming do BigQuery dependem da presença ou da ausência de insertId.

Se o campo insertId estiver vazio, o seguinte erro pode acontecer:

Limite de cota Mensagem de erro
Bytes por segundo, por projeto Sua entidade com gaia_id: GAIA_ID no projeto PROJECT_ID na região REGION excedeu a cota de bytes de inserção por segundo.

Se o campo insertId estiver preenchido, os seguintes erros de cota podem acontecer:

Limite de cota Mensagem de erro
Linhas por segundo por projeto Seu projeto PROJECT_ID em REGION excedeu a cota de linhas de inserção de streaming por segundo.
Linhas por segundo por tabela Sua tabela: TABLE_ID excedeu a cota de linhas de inserção de streaming por segundo.
Bytes por segundo por tabela Sua tabela: TABLE_ID excedeu a cota de inserção de streaming de bytes por segundo.

O campo insertId tem como objetivo eliminar a duplicação de linhas inseridas. Se várias inserções com o mesmo insertId chegarem em uma janela dentro de alguns minutos, o BigQuery gravará uma única versão do registro. No entanto, essa eliminação automática não é garantida. Para a capacidade máxima de streaming, recomendamos que você não inclua insertId e use a eliminação de duplicação manual. Para mais informações, consulte Como garantir a consistência dos dados.

Diagnóstico

Use as visualizações STREAMING_TIMELINE_BY_* para analisar o tráfego de streaming. Essas visualizações agregam estatísticas de streaming em intervalos de um minuto, agrupadas por código de erro. Erros de cota aparecem nos resultados com error_code igual a RATE_LIMIT_EXCEEDED ou QUOTA_EXCEEDED.

De acordo com o limite de cotas específico que foi alcançado, confira total_rows ou total_input_bytes. Se o erro estiver relacionado com as cotas no nível da tabela, filtre por table_id. Por exemplo, a consulta a seguir mostra o total de bytes ingerido por minuto e o número total de erros de cota.

SELECT
 start_timestamp,
 error_code,
 SUM(total_input_bytes) as sum_input_bytes,
 SUM(IF(error_code IN ('QUOTA_EXCEEDED', 'RATE_LIMIT_EXCEEDED'),
     total_requests, 0)) AS quota_error
FROM
 `region-us`.INFORMATION_SCHEMA.STREAMING_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP, INTERVAL 1 DAY)
GROUP BY
 start_timestamp,
 error_code
ORDER BY 1 DESC

Solução

Se você estiver usando o campo insertId para eliminação de duplicação e seu projeto estiver em uma região compatível com a maior cota de streaming, recomendamos remover o campo insertId. Essa solução pode exigir algumas etapas a mais para eliminar a duplicação dos dados manualmente. Para mais informações, consulte Remoção manual de duplicatas.

Se você não estiver usando insertId ou se não for possível removê-lo, monitore o tráfego de streaming durante um período de 24 horas e analise os erros de cota:

  • Se houver mais erros RATE_LIMIT_EXCEEDED do que QUOTA_EXCEEDED, e o tráfego geral estiver abaixo de 80% da cota, os erros provavelmente indicam picos temporários. Gerencie esses erros repetindo a operação usando a espera exponencial no intervalo das novas tentativas.

  • Se você perceber erros QUOTA_EXCEEDED ou se o tráfego geral exceder constantemente 80% da cota, envie uma solicitação para aumentar a cota. Para mais informações, consulte Como solicitar um limite de cota maior.