Solução de problemas do Snowpipe

Este tópico descreve uma abordagem metódica para a solução de problemas com o carregamento de dados usando Snowpipe.

Neste tópico:

Os passos para solucionar problemas com o Snowpipe diferem dependendo do fluxo de trabalho usado para carregar arquivos de dados.

Carregamento automático de dados usando notificações de eventos de armazenamento em nuvem

Notificações de erro

Configure notificações de erro do Snowpipe. Quando o Snowpipe encontra erros durante uma carga, o recurso envia uma notificação para um serviço de mensagens em nuvem configurado, permitindo a análise de seus arquivos de dados. Para obter mais informações, consulte Notificações de erro do Snowpipe.

Etapas gerais de solução de problemas

Complete as seguintes etapas para identificar a causa da maioria dos problemas que impedem o carregamento automático de arquivos.

Etapa 1: Verificar o status do canal

Recuperação do status atual do canal. Os resultados são exibidos no formato JSON. Para obter mais informações, consulte SYSTEM$PIPE_STATUS.

Verifique os seguintes valores:

lastReceivedMessageTimestamp

Especifica o carimbo de data/hora da última mensagem de evento recebida da fila de mensagens. Observe que esta mensagem pode não se aplicar ao canal específico, por exemplo, se o caminho associado à mensagem não corresponder ao caminho na definição do canal. Além disso, apenas mensagens acionadas por objetos de dados criados são consumidas por canais com ingestão automática.

Se o carimbo de data/hora for anterior ao esperado, isso provavelmente indica um problema com a configuração do serviço (ou seja, Amazon SQS ou Amazon SNS ou Azure Event Grid) ou com o próprio serviço. Se o campo estiver vazio, verifique as definições de sua configuração de serviço. Se o campo contiver um carimbo de data/hora mas for anterior ao esperado, verifique se alguma configuração foi alterada em sua configuração de serviço.

lastForwardedMessageTimestamp

Especifica o carimbo de data/hora da última mensagem do evento “criar objeto” com um caminho correspondente que foi encaminhado para o canal.

Se mensagens de eventos estão sendo recebidas da fila de mensagens mas não são encaminhadas para o canal, então é provável que haja uma incoerência entre o caminho de armazenamento de blobs onde os novos arquivos de dados são criados e o caminho combinado especificado no estágio do Snowflake e definições do canal. Verifique os caminhos especificados no estágio e nas definições dos canais. Observe que um caminho especificado na definição do canal é anexado a qualquer caminho na definição do estágio.

Etapa 2. Consulte o histórico de COPY da tabela

Se mensagens de eventos estão sendo recebidas e encaminhadas, consulte o histórico de atividades de carregamento para a tabela de destino. Para obter mais informações, consulte COPY_HISTORY.

A coluna STATUS indica se um determinado conjunto de arquivos foi carregado, parcialmente carregado, ou não foi carregado. A coluna FIRST_ERROR_MESSAGE apresenta uma razão quando uma tentativa é parcialmente carregada ou quando não há carregamento.

Observe que se um conjunto de arquivos tiver vários problemas, a coluna FIRST_ERROR_MESSAGE indica apenas o primeiro erro encontrado. Para visualizar todos os erros nos arquivos, execute uma instrução COPY INTO <tabela> com a opção de cópia VALIDATION_MODE definida como RETURN_ALL_ERRORS. A opção de cópia VALIDATION_MODE instrui uma instrução COPY para validar os dados a serem carregados e retornar resultados com base na opção de validação especificada. Nenhum dado é carregado quando essa opção de cópia é especificada. Na instrução, faça referência ao conjunto de arquivos que você tentou carregar usando o Snowpipe. Para obter mais informações sobre a opção de cópia, consulte COPY INTO <tabela>.

Se a saída COPY_HISTORY não incluir um conjunto de arquivos esperados, consulte um período anterior. Se os arquivos fossem duplicatas de arquivos anteriores, o histórico de carregamento pode ter registrado a atividade quando foi feita a tentativa de carregar os arquivos originais.

Etapa 3: Validar os arquivos de dados

Se a operação de carregamento encontrar erros nos arquivos de dados, a função de tabela COPY_HISTORY descreve o primeiro erro encontrado em cada arquivo. Para validar os arquivos de dados, consulte a função VALIDATE_PIPE_LOAD.

Arquivos gerados no armazenamento do Microsoft Azure Data Lake Storage Gen2 não carregados

Atualmente, alguns clientes de terceiros não chamam FlushWithClose na API REST do ADLS Gen 2. Esta etapa é necessária para acionar eventos que notificam o Snowpipe para carregar os arquivos. Tente chamar a API REST manualmente para acionar o Snowpipe para carregar esses arquivos.

Para obter mais informações sobre o método Flush com o argumento close, consulte https://docs.microsoft.com/en-us/dotnet/api/azure.storage.files.datalake.datalakefileclient.flush. Para informações adicionais de referência da API REST sobre o carregamento do parâmetro close, consulte https://docs.microsoft.com/en-us/rest/api/storageservices/datalakestoragegen2/path/update.

O Snowpipe para de carregar arquivos depois que a assinatura do tópico do Amazon SNS é excluída

A primeira vez que um usuário cria um objeto de canal que faz referência a um tópico específico do Amazon Simple Notification Service (SNS), o Snowflake inscreve no tópico uma fila do Amazon Simple Queue Service (SQS) de propriedade do Snowflake. Se um administrador AWS apagar a assinatura SQS do tópico SNS, qualquer canal que faça referência ao tópico não receberá mais mensagens de eventos do Amazon S3.

Para resolver o problema:

  1. Aguarde 72 horas a partir do momento em que a assinatura do tópico SNS foi excluída.

    Após 72 horas, o Amazon SNS apaga a assinatura excluída. Para obter mais informações, consulte a documentação do Amazon SNS.

  2. Recrie canais que façam referência ao tópico (usando CREATE OR REPLACE PIPE). Faça referência ao mesmo tópico SNS na definição do canal. Para obter instruções, consulte Etapa 3: criar um canal com ingestão automática habilitada.

Todos os canais que funcionavam antes da exclusão da assinatura do tópico SNS devem agora começar a receber novamente mensagens de eventos do S3.

Para contornar a espera de 72 horas, você pode criar um tópico SNS com um nome diferente. Recrie canais que façam referência ao tópico usando o comando CREATE OR REPLACE PIPE e especifique o novo nome do tópico.

Carregamentos do Google Cloud Storage atrasados ou arquivos perdidos

Quando o carregamento automático de dados do Google Cloud Storage (GCS) usando mensagens Pub/Sub é configurado, a mensagem de evento para apenas um único arquivo preparado pode ser lida. Alternativamente, os carregamentos de dados do GCS podem ser atrasados de vários minutos a um dia ou mais. Em geral, qualquer um dos problemas é causado quando um administrador GCS não concedeu a função Monitoring Viewer à conta do serviço Snowflake.

Para instruções, consulte “Etapa 2: Conceder acesso do Snowflake à assinatura Pub/Sub” em Configuração de acesso seguro ao armazenamento em nuvem.

Chamada de pontos de extremidade REST do Snowpipe para carregar dados

Notificações de erro

O suporte a notificações de erro do Snowpipe está disponível para contas Snowflake hospedadas na Amazon Web Services (AWS). Os erros encontrados durante um carregamento de dados acionam notificações que permitem a análise de seus arquivos de dados. Para obter mais informações, consulte Notificações de erro do Snowpipe.

Etapas gerais de solução de problemas

Complete as seguintes etapas para identificar a causa da maioria dos problemas que impedem o carregamento de arquivos.

Etapa 1: Verificar problemas de autenticação

Os pontos de extremidade REST do Snowpipe usam autenticação de par de chaves com Web Token JSON (JWT).

Os SDKs de ingestão do Python/Java geram o JWT para você. Ao chamar a API REST diretamente, você precisa gerá-la. Se nenhum token JWT for fornecido na solicitação, o erro 400 é retornado pelo ponto de extremidade REST. Se um token inválido for fornecido, será retornado um erro semelhante a este:

snowflake.ingest.error.IngestResponseError: Http Error: 401, Vender Code: 390144, Message: JWT token is invalid.
Copy

Etapa 2. Visualizar o histórico de COPY da tabela

Consulte o histórico de atividade de carregamento de uma tabela, incluindo tentativas de carregamentos de dados usando o Snowpipe. Para obter mais informações, consulte COPY_HISTORY. A coluna STATUS indica se um determinado conjunto de arquivos foi carregado, parcialmente carregado, ou não foi carregado. A coluna FIRST_ERROR_MESSAGE apresenta uma razão quando uma tentativa é parcialmente carregada ou quando não há carregamento.

Observe que se um conjunto de arquivos tiver vários problemas, a coluna FIRST_ERROR_MESSAGE indica apenas o primeiro erro encontrado. Para visualizar todos os erros nos arquivos, execute uma instrução COPY INTO <tabela> com a opção de cópia VALIDATION_MODE definida como RETURN_ALL_ERRORS. A opção de cópia VALIDATION_MODE instrui uma instrução COPY para validar os dados a serem carregados e retornar resultados com base na opção de validação especificada. Nenhum dado é carregado quando essa opção de cópia é especificada. Na instrução, faça referência ao conjunto de arquivos que você tentou carregar usando o Snowpipe. Para obter mais informações sobre a opção de cópia, consulte COPY INTO <tabela>.

Etapa 3: Verificar o status do canal

Se a função de tabela COPY_HISTORY retorna 0 resultados para o carregamento de dados que você está investigando, recupere o estado atual do canal. Os resultados são exibidos no formato JSON. Para obter mais informações, consulte SYSTEM$PIPE_STATUS.

A chave executionState identifica o estado de execução do canal. Por exemplo, PAUSED indica que o canal está atualmente em pausa. O proprietário do canal pode retomar a execução do canal usando ALTER PIPE.

Se o valor executionState indicar um problema ao iniciar o canal, verifique a chave error para obter mais informações.

Etapa 4: Validar os arquivos de dados

Se a operação de carregamento encontrar erros nos arquivos de dados, a função de tabela COPY_HISTORY descreve o primeiro erro encontrado em cada arquivo. Para validar os arquivos de dados, consulte a função VALIDATE_PIPE_LOAD.

Outros problemas

Conjunto de arquivos não carregados

Registro COPY_HISTORY ausente para o carregamento

Verifique se a instrução COPY INTO <tabela> no canal inclui a cláusula PATTERN. Em caso afirmativo, verifique se a expressão regular especificada como o valor PATTERN está filtrando todos os arquivos preparados para carregar.

Para modificar o valor PATTERN, é necessário recriar o canal usando a sintaxe CREATE OR REPLACE PIPE.

Para obter mais informações, consulte CREATE PIPE.

O registro COPY_HISTORY indica o subconjunto de arquivos descarregados

Se a saída da função COPY_HISTORY indicar que um subconjunto de arquivos não foi carregado, você pode tentar recarregar o canal.

Essa situação pode surgir em qualquer uma das seguintes situações:

  • O estágio externo era usado anteriormente para carregar dados em massa usando o comando COPY INTO tabela.

  • REST API:

    • A funcionalidade orientada a eventos externos é usada para chamar as APIs REST e uma lista de pendências de arquivos de dados já existia no estágio externo antes dos eventos serem configurados.

  • Ingestão automática:

    • Uma lista de pendências de arquivos de dados já existia no estágio externo antes das notificações de eventos serem configuradas.

    • Uma falha na notificação de eventos impediu que um conjunto de arquivos ficasse em fila.

Para carregar os arquivos de dados em seu estágio externo usando o canal configurado, execute uma instrução ALTER PIPE … REFRESH.

Dados duplicados nas tabelas de destino

Compare as instruções COPY INTO <tabela> nas definições de todos os canais da conta executando SHOW PIPES ou consultando a exibição PIPES no Account Usage ou a exibição PIPES no Information Schema. Se vários canais fizerem referência ao mesmo local de armazenamento em nuvem nas instruções COPY INTO <tabela>, verifique se os caminhos do diretório não se sobrepõem. Caso contrário, vários canais poderiam carregar o mesmo conjunto de arquivos de dados nas tabelas de destino. Por exemplo, esta situação pode ocorrer quando múltiplas definições de canais fazem referência ao mesmo local de armazenamento com diferentes níveis de granularidade, como <local_de_armazenamento>/path1/ e <local_de_armazenamento>/path1/path2/. Neste exemplo, se os arquivos fossem preparados em <local_armazenamento>/path1/path2/, ambos os canais carregariam uma cópia dos arquivos.

Incapaz de recarregar dados modificados, dados modificados carregados involuntariamente

O Snowflake usa metadados de carregamento de arquivos para evitar recarregar os mesmos arquivos (e duplicar dados) em uma tabela. O Snowpipe impede o carregamento de arquivos com o mesmo nome, mesmo que tenham sido modificados posteriormente (ou seja, tenham uma eTag diferente).

Os metadados de carregamento de arquivo estão associados ao objeto de canal e não à tabela. Como resultado:

  • Arquivos preparados com o mesmo nome dos arquivos que já foram carregados são ignorados, mesmo que tenham sido modificados, por exemplo, se novas linhas tiverem sido adicionadas ou se erros no arquivo tiverem sido corrigidos.

  • O truncamento da tabela usando o comando TRUNCATE TABLE não elimina o arquivo Snowpipe carregando metadados.

Entretanto, observe que os canais só mantêm os metadados do histórico de carregamento durante 14 dias. Portanto:

Arquivos modificados e preparados novamente dentro de 14 dias

O Snowpipe ignora os arquivos modificados que são preparados novamente. Para recarregar arquivos de dados modificados, atualmente é necessário recriar o objeto de canal usando a sintaxe CREATE OR REPLACE PIPE.

O exemplo a seguir recria o canal mypipe com base no exemplo na Etapa 1 de Preparação para carregamento de dados usando a API REST Snowpipe:

create or replace pipe mypipe as copy into mytable from @mystage;
Copy
Arquivos modificados e preparados novamente após 14 dias

O Snowpipe carrega novamente os dados, o que pode resultar em registros duplicados na tabela de destino.

Além disso, registros duplicados podem ser carregados na tabela de destino se forem executadas instruções COPY INTO <tabela> que façam referência ao mesmo bucket/contêiner, caminho e tabela de destino que em seus carregamentos ativos do Snowpipe. Os históricos de carregamento do comando COPY e Snowpipe são armazenados separadamente no Snowflake. Depois de ter carregado dados históricos preparados, se você precisar carregar dados manualmente usando a configuração do canal, execute uma instrução ALTER PIPE … REFRESH. Consulte Conjunto de arquivos não carregados neste tópico para obter mais informações.

Tempos de carregamento inseridos usando CURRENT_TIMESTAMP antes dos valores LOAD_TIME na exibição COPY_HISTORY

Os criadores de tabelas podem adicionar uma coluna de carimbo de data/hora que insere o carimbo de data/hora atual como o valor padrão à medida que os registros são carregados em uma tabela. A intenção é capturar o tempo em que cada registro foi carregado na tabela; entretanto, os carimbos de data/hora são anteriores aos valores da coluna LOAD_TIME retornados pela função COPY_HISTORY (Information Schema) ou a exibição COPY_HISTORY (Account Usage). O motivo é que CURRENT_TIMESTAMP é avaliado quando a operação de carregamento é compilada em serviços de nuvem e não quando o registro é inserido na tabela (ou seja, quando a transação para a operação de carregamento é confirmada).

Nota

Atualmente não recomendamos o uso das seguintes funções no copy_statement para Snowpipe:

  • CURRENT_DATE

  • CURRENT_TIME

  • CURRENT_TIMESTAMP

  • GETDATE

  • LOCALTIME

  • LOCALTIMESTAMP

  • SYSDATE

  • SYSTIMESTAMP

É um problema conhecido que valores de tempo inseridos usando essas funções podem estar algumas horas antes dos valores LOAD_TIME retornados pela função COPY_HISTORY ou pela exibição COPY_HISTORY.

Recomenda-se consultar METADATA$START_SCAN_TIME em vez disso, o que fornece uma representação mais precisa do carregamento de registros.

Erro: Integration {0} associated with the stage {1} cannot be found

003139=SQL compilation error:\nIntegration ''{0}'' associated with the stage ''{1}'' cannot be found.
Copy

Esse erro pode ocorrer quando a associação entre o estágio externo e a integração de armazenamento vinculada ao estágio foi interrompida. Isso acontece quando o objeto de integração de armazenamento foi recriado (usando CREATE OR REPLACE STORAGE INTEGRATION). Um estágio se liga a uma integração de armazenamento usando uma ID oculta em vez do nome da integração de armazenamento. Nos bastidores, a sintaxe CREATE OR REPLACE descarta o objeto e o recria com uma ID oculta diferente.

Se você precisar recriar uma integração de armazenamento após ter sido vinculada a um ou mais estágios, será necessário restabelecer a associação entre cada estágio e a integração de armazenamento executando ALTER STAGE stage_name SET STORAGE_INTEGRATION = storage_integration_name, em que:

  • stage_name é o nome do estágio.

  • storage_integration_name é o nome da integração de armazenamento.

Erros do Snowpipe referenciando regiões governamentais

Você pode receber um erro quando o Snowpipe fizer referência a um bucket em uma região governamental enquanto a conta estiver em uma região comercial. Observe que as regiões governamentais dos provedores de nuvem não permitem o envio de notificações de eventos de ou para outras regiões comerciais. Para obter mais informações, consulte AWS GovCloud (US) e Azure Government.