Registro de erros no Snowpipe Streaming com arquitetura de alto desempenho¶

O registro de erros para o Snowpipe Streaming se baseia no recurso de registro de erros DML do Snowflake para fornecer uma maneira robusta de gerenciar e se recuperar de erros de ingestão de dados. Esse recurso evita a perda silenciosa de dados e aumenta a visibilidade das linhas de dados com falha. Quando o registro de erros está ativado, os dados sem erros continuam sendo carregados na tabela de destino, enquanto as linhas que falham no processamento são automaticamente encaminhadas para uma tabela de erros dedicada para revisão e recuperação.

Importante

Os dados armazenados nas tabelas de erros são a carga útil original enviada para a API ou o SDK antes que qualquer transformação de canal seja aplicada. Mesmo que o seu canal descarte ou transforme campos, a carga útil original completa persiste na tabela de erros.

Visão geral¶

Ao usar a arquitetura de alto desempenho do Snowpipe Streaming, o processamento de dados ocorre no lado do servidor, no Snowflake. A arquitetura de alto desempenho opera implicitamente no modo ON_ERROR = CONTINUE, o que significa que as linhas válidas são ingeridas, enquanto as problemáticas são ignoradas.

Opções de tratamento de erros¶

É possível monitorar e tratar erros de ingestão das seguintes maneiras:

Sem tabelas de erros:

Use getChannelStatus() para monitorar a contagem agregada de erros, a última mensagem de erro e o carimbo de data/hora do último erro.
Consulte a exibição SNOWPIPE_STREAMING_CHANNEL_HISTORY para obter tendências e padrões de erros históricos.

Esses métodos informam que ocorreram erros e quantos, mas não quais linhas falharam ou as cargas úteis delas.

Com tabelas de erros:

As linhas que falham no processamento são capturadas automaticamente em uma tabela de erros dedicada.
Cada linha de erro inclui a carga útil original completa e metadados de erro detalhados.
Você pode consultar, analisar e reprocessar linhas com falha usando SQL padrão.

As tabelas de erros completam o quadro, mostrando exatamente quais linhas falharam e o motivo, permitindo depuração e recuperação completas.

Ativar registro de erros¶

Para ativar o registro de erros para o Snowpipe Streaming, defina a propriedade ERROR_LOGGING na tabela de destino. Para obter detalhes completos sobre como ativar e configurar o registro de erros, consulte Configurar registro de erros de DML para uma tabela.

-- For a new table:
CREATE TABLE my_streaming_table (...) ERROR_LOGGING = TRUE;

-- For an existing table:
ALTER TABLE my_streaming_table SET ERROR_LOGGING = TRUE;

Quando o registro de erros está ativado, a mesma tabela de erros captura erros tanto de instruções DML quanto de cargas de trabalho de ingestão do Snowpipe Streaming.

Consultar tabelas de erros¶

Para consultar a tabela de erros de uma tabela base, use a função de tabela ERROR_TABLE. Para obter detalhes completos sobre o esquema da tabela de erros, controle de acesso e operações compatíveis, consulte Registro de erros e tabelas de erros.

SELECT * FROM ERROR_TABLE(my_streaming_table) ORDER BY timestamp;

O resultado contém uma linha para cada linha com erro no fluxo de ingestão.

Campos de erro do Snowpipe Streaming¶

Os erros do Snowpipe Streaming são armazenados nas mesmas colunas da tabela de erros que os erros de DML (timestamp, query_id, error_code, error_metadata, error_data). Os objetos error_metadata e error_data incluem campos adicionais para o Snowpipe Streaming, descritos nas seções a seguir.

Identificar erros do Snowpipe Streaming¶

O campo error_metadata:service é preenchido com snowpipe_streaming para erros do Snowpipe Streaming. Use este campo para filtrar erros por origem:

SELECT * FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming';

Detalhes dos metadados do erro¶

Para erros do Snowpipe Streaming, o objeto error_metadata:details contém os seguintes campos adicionais:


Campo	Descrição
`pipe_name`	Nome do canal utilizado para ingerir a linha com erro.
`channel_name`	Nome do canal utilizado para ingerir a linha com erro.
`offset_token_upper_bound`	Token de deslocamento do limite superior que contém a linha com erro. A linha aparece na carga útil com esse token de deslocamento ou antes.
`error_data_truncated`	Indica se a carga útil bruta foi truncada para caber na tabela de erros (máximo de 128 MB).
`error_data_content_type`	Indica o tipo de conteúdo armazenado na coluna `error_data`. Consulte Tipos de conteúdo dos dados de erro.

Formato dos dados de erro¶

Para erros do Snowpipe Streaming, o campo error_data:$1 contém a carga útil bruta que representa a linha com erro.

Se a carga útil contiver caracteres UTF-8 inválidos, a carga útil bruta será armazenada como uma cadeia de caracteres binária codificada em base64.

Tipos de conteúdo dos dados de erro¶

O campo error_data_content_type indica o tipo de erro encontrado e sugere etapas de correção.

json¶

A linha com erro é uma cadeia de caracteres JSON sintaticamente válida, mas ocorreu um erro lógico ao ingerir os dados na tabela de destino.

Os erros lógicos comuns incluem:

Colunas não anuláveis ausentes: uma coluna obrigatória com uma restrição NOT NULL não foi fornecida na carga útil.
Erros de conversão de tipo: não é possível converter o tipo de dados JSON no tipo da coluna de destino. Por exemplo, não é possível converter um valor de cadeia de caracteres "abc" em uma coluna NUMBER.
Erros de transformação: ocorreu um erro ao avaliar uma expressão de transformação de canal, como divisão por zero.

Para resolver, inspecione a mensagem de erro em error_metadata:error_message e o nome da coluna em error_metadata:error_source que causou o erro de ingestão. Analise a carga útil com PARSE_JSON(error_data:$1), corrija os dados e reinsira-os na tabela de destino.

json-invalid¶

Um objeto JSON sintaticamente inválido foi ingerido.

Para resolver, inspecione a mensagem de erro em error_metadata:error_message, que contém detalhes sobre o erro de sintaxe. Corrija a carga útil armazenada em error_data:$1 e reinsira-a na tabela de destino.

binary-base64¶

Dados UTF-8 inválidos foram ingeridos. A carga útil com erro é armazenada na tabela de erros como uma cadeia de caracteres binária codificada em base64.

Esse tipo de erro geralmente indica uma incompatibilidade de formato ou um erro de codificação na fonte de dados upstream.

Para resolver, examine a fonte de dados e os formatos e codificações de dados que ela produz. Decodifique a carga útil armazenada em error_data:$1 com a função BASE64_DECODE_STRING para inspecionar os bytes brutos e identificar sequências UTF-8 incorretas.

Fluxo de trabalho de recuperação de erros¶

O exemplo a seguir demonstra como consultar erros, analisá-los e reinserir dados corrigidos.

Consultar erros recentes¶

SELECT
    timestamp,
    error_code,
    error_metadata:error_message::STRING AS error_message,
    error_metadata:details:channel_name::STRING AS channel,
    error_metadata:details:pipe_name::STRING AS pipe,
    error_metadata:details:error_data_content_type::STRING AS content_type,
    error_data:"$1"::STRING AS raw_payload
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming'
  AND timestamp >= DATEADD(hour, -1, CURRENT_TIMESTAMP())
ORDER BY timestamp DESC;

Analisar a distribuição de erros¶

SELECT
    error_code,
    error_metadata:error_message::STRING AS error_message,
    COUNT(*) AS error_count
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming'
  AND timestamp >= DATEADD(hour, -24, CURRENT_TIMESTAMP())
GROUP BY 1, 2
ORDER BY error_count DESC;

Corrigir e reinserir erros recuperáveis¶

Para erros com cargas úteis JSON válidas, você pode analisar, corrigir e reinserir os dados:

INSERT INTO my_streaming_table (col1, col2, col3)
SELECT
    TRY_CAST(PARSE_JSON(error_data:"$1"):col1 AS NUMBER),
    PARSE_JSON(error_data:"$1"):col2::STRING,
    TRY_CAST(PARSE_JSON(error_data:"$1"):col3 AS TIMESTAMP)
FROM ERROR_TABLE(my_streaming_table)
WHERE error_metadata:service = 'snowpipe_streaming'
  AND error_metadata:details:error_data_content_type = 'json'
  AND timestamp >= DATEADD(hour, -24, CURRENT_TIMESTAMP());

Após o reprocessamento bem-sucedido dos erros, você pode truncar a tabela de erros:

TRUNCATE ERROR_TABLE(my_streaming_table);

Faturamento¶

A ingestão do Snowpipe Streaming é cobrada pela taxa padrão do Snowpipe Streaming. Ativar o registro de erros não altera seus custos de ingestão. Não há cobranças adicionais de ingestão para o roteamento de linhas com falha para a tabela de erros.

O Snowflake cobra pelos dados armazenados na tabela de erros pela taxa de armazenamento padrão, a mesma de qualquer outra tabela. A tabela de erros armazena a carga útil bruta e os metadados de erro para cada linha com falha.

Para obter mais informações sobre os custos do Snowpipe Streaming, consulte Snowpipe Streaming high-performance architecture: Understand your costs.

Limitações¶

As tabelas de erros capturam erros que ocorrem durante o processamento de dados no servidor (análise e transformação). Erros de outras etapas (validação de SDK, falhas de API e outros erros assíncronos do lado do servidor) não são capturados nas tabelas de erros. Monitore erros assíncronos do lado do servidor usando getChannelStatus().
Uma alta taxa de falhas nas linhas recebidas pode aumentar a latência de processamento devido à sobrecarga de armazenamento de informações de erro.
Cargas úteis maiores que 128 MB são truncadas. O campo error_data_truncated indica quando ocorreu o truncamento.
As tabelas de erros estão disponíveis apenas para a arquitetura de alto desempenho do Snowpipe Streaming. Para a arquitetura clássica, o tratamento de erros é gerenciado no lado do cliente por meio do SDK.