O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Resolver problemas com erros da API BigQuery Storage

Este documento explica como resolver problemas ao ler ou fazer streaming de dados no BigQuery usando a API BigQuery Storage Read, a API BigQuery Storage Write (gRPC) ou inserções de streaming com a API BigQuery Storage Write (REST) (método tabledata.insertAll).

Analisar a telemetria de streaming com visualizações INFORMATION_SCHEMA

É possível consultar visualizações de INFORMATION_SCHEMA para monitorar a integridade da ingestão de streaming, identificar gargalos de capacidade de processamento e inspecionar códigos de erro em intervalos de um minuto:

API Storage Write (gRPC): consulte as INFORMATION_SCHEMA.WRITE_API_TIMELINEviews para inspecionar solicitações de ingestão de streaming gRPC, total de bytes e linhas anexadas e contagens de erros por error_code.
API Storage Write (REST): consulte as INFORMATION_SCHEMA.STREAMING_TIMELINE visualizações para inspecionar solicitações de streaming tabledata.insertAll REST legadas e erros de cota ou limite de taxa.

O exemplo a seguir consulta INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT para recuperar contagens de erros e bytes ingeridos da API Storage Write (gRPC) nas últimas 24 horas:

SELECT
  start_timestamp,
  error_code,
  SUM(total_requests) AS request_count,
  SUM(total_input_bytes) AS input_bytes
FROM
  `region-REGION`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
  AND error_code IS NOT NULL
GROUP BY
  start_timestamp,
  error_code
ORDER BY
  start_timestamp DESC;

Substitua REGION pelo nome da região do conjunto de dados, como us ou europe-west1.

Resolver problemas de erros da API Storage Read

Confira a seguir erros comuns encontrados ao usar a API Storage Read:

Erro: Stream removed: Resolução:tente de novo a solicitação de API Storage Read. Esse é provavelmente um erro temporário que pode ser resolvido ao tentar novamente. Se o problema persistir, entre em contato com o Cloud Customer Care.
Erro: Stream expired: Causa:esse erro ocorre quando a sessão da API Storage Read atinge o tempo limite de seis horas.; Resolução:

Aumente o paralelismo do job.
Se a utilização da CPU dos nós de worker for relativamente consistente e não exceder 85%, considere executar o job em um tipo de máquina maior.
Divida o job em vários jobs ou consultas menores.

Para mais informações sobre gerenciamento de sessões e leitura de dados, consulte a visão geral da API Storage Read.

Resolver problemas de inserções por streaming

As seções a seguir explicam como resolver erros que ocorrem ao fazer streaming de dados para o BigQuery usando a API Storage Write (REST). Para mais informações sobre como resolver erros de cota para inserções por streaming, consulte Erros de cota de inserção por streaming.

Códigos de resposta HTTP de falha

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

Se você receber um erro de permissão, um erro de nome de tabela inválido ou um erro de cota excedida, nenhuma linha será inserida e toda a solicitação vai falhar.

Códigos de resposta HTTP de sucesso

Mesmo que você receba um código de resposta HTTP de sucesso, é necessário verificar a propriedade insertErrors da resposta para determinar se as inserções de linha foram bem-sucedidas, porque o BigQuery pode ter conseguido inserir as linhas apenas parcialmente. Você pode encontrar um dos seguintes cenários:

Todas as linhas foram inseridas com sucesso:se a propriedade insertErrors for uma lista vazia, todas as linhas foram inseridas com sucesso.
Algumas linhas foram inseridas com sucesso:exceto nos casos em que há uma incompatibilidade de esquema em qualquer uma das linhas, as linhas indicadas na propriedade insertErrors não são inseridas, e todas as outras são inseridas com sucesso. A propriedade errors contém informações detalhadas sobre o motivo de falha de cada linha malsucedida. A property index indica o índice de linha com base em 0 da solicitação à qual o erro se aplica.
Nenhuma linha inserida com sucesso:se o BigQuery encontrar uma incompatibilidade de esquema em linhas individuais na solicitação, nenhuma das linhas será inserida e uma entrada insertErrors será retornada para cada linha, mesmo para linhas que não tiveram uma incompatibilidade de esquema. As linhas que não tiveram incompatibilidade de esquema têm um erro com a propriedade reason definida como stopped, e você pode reenviá-las como estão. As linhas que falharam incluem informações detalhadas sobre a incompatibilidade de esquema. Para saber mais sobre os tipos de buffer de protocolo compatíveis com cada tipo de dado do BigQuery, consulte Tipos de dados compatíveis de buffer de protocolo e Arrow.

Erros de metadados para inserções de streaming

Como a API BigQuery Streaming foi projetada para altas taxas de inserção, as modificações nos metadados da tabela subjacente são eventualmente consistentes ao interagir com o sistema de streaming. Na maioria das vezes, as mudanças 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 de esquema:modificar o esquema de uma tabela que recebeu inserções de streaming recentemente pode causar respostas com erros de incompatibilidade de esquema porque o sistema de streaming pode não detectar imediatamente a mudança de esquema.
Criação ou exclusão de tabelas:o streaming para uma tabela inexistente retorna uma variação de uma resposta notFound. Uma tabela criada em resposta pode não ser reconhecida imediatamente por inserções de streaming subsequentes. Da mesma forma, excluir ou recriar uma tabela pode criar um período em que as inserções de streaming são entregues à tabela antiga. As inserções de streaming podem não estar presentes na nova tabela.
Truncamento de tabela:truncar os dados de uma tabela (usando um job de consulta que usa um valor writeDisposition de WRITE_TRUNCATE) pode fazer com que inserções subsequentes durante o período de consistência sejam descartadas.

Dados ausentes ou indisponíveis

As inserções por streaming ficam temporariamente no armazenamento otimizado para gravação, que tem características de disponibilidade diferentes do armazenamento gerenciado. Algumas operações no BigQuery não interagem com o armazenamento otimizado para gravação, como jobs de cópia de tabela e métodos de API, como tabledata.list. Os dados de streaming recentes não estão presentes na tabela de destino ou na saída.

Erros de cota de inserção de streaming

Nesta seção, você encontra dicas para resolver 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.

Mensagem de erro

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 bytes de inserção por streaming 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 maximizar a capacidade de processamento de streaming, recomendamos não incluir insertId e usar a deduplicação manual. Para mais informações, consulte Como garantir a consistência dos dados.

Quando você encontrar esse erro, diagnostique o problema e siga as etapas recomendadas para resolvê-lo.

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 error_code. Os 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-REGION_NAME`.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

Resolução

Para resolver esse erro, faça o seguinte:

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 adicionais para remover manualmente duplicidades dos dados. 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ê estiver usando um job do Dataflow para inserir dados, use jobs de carregamento em vez de inserções por streaming. Para mais informações, consulte Como configurar o método de inserção. Se você estiver usando o Dataflow com um conector de E/S personalizado, use um conector de E/S integrado. Para mais informações, consulte Padrões de E/S personalizados.
- Se você perceber erros QUOTA_EXCEEDED ou se o tráfego geral exceder constantemente 80% da cota, envie uma solicitação para aumentar xda cota. Para mais informações, consulte Solicitar um ajuste de cota.
- Considere também substituir as inserções por streaming pela API Storage Write mais recente, que tem maior capacidade de processamento, menor preço e muitos recursos úteis.