Solucionar problemas de erros de ingestão de Transact-SQL com arquivos de erro

Aplica-se a:✅Armazém de dados no Microsoft Fabric

Este artigo descreve como solucionar problemas de falhas de ingestão em padrões de ingestão T-SQL.

A ingestão em um armazém usando as funções COPY INTO, BULK INSERT, OPENROWSET em declarações CTAS, INSERT, UPDATE e MERGE pode falhar por vários motivos. Os valores do arquivo de origem podem não corresponder ao esquema da tabela. Os valores necessários podem estar ausentes. As opções de ingestão também podem estar configuradas incorretamente.

Este guia de solução de problemas usa as informações de diagnóstico de linha rejeitada para resolver falhas, capturar erros de nível de linha e inspecionar linhas rejeitadas com metadados de erro.

Ao examinar os arquivos de erro gerados por COPY INTO e outros comandos de ingestão, você pode identificar exatamente quais linhas falharam na ingestão e por quê. Essas informações ajudam você a identificar problemas de qualidade de dados ou ajustar as configurações de ingestão, corrigir os dados de origem e executar novamente a carga com confiança.

Criar a tabela de destino

Antes de executar comandos de ingestão, crie uma tabela de destino com tipos e NOT NULL restrições estritos para capturar problemas de conversão e qualidade de dados antecipadamente.

1. No seu espaço de trabalho do Warehouse, abra seu armazém.

2. Na guia Página Inicial , selecione Nova consulta SQL.

   

3. Execute a seguinte instrução:

   DROP TABLE IF EXISTS dbo.TaxiTrips;
   GO
   CREATE TABLE dbo.TaxiTrips
   (
       vendorID         int    NOT NULL,
       startLat         float  NOT NULL,
       startLon         float  NOT NULL,
       endLat           float  NOT NULL,
       endLon           float  NOT NULL,
       passengerCount   int    NOT NULL,
       tripDistance     float  NOT NULL,
       fareAmount       float  NOT NULL,
       mtaTax           float  NOT NULL,
       totalAmount      float  NOT NULL
   );
   

Você pode usar vários métodos com suporte, incluindo ingestão com COPY INTO ou ingestão com Transact-SQL. Escolha o método de ingestão que melhor se ajusta aos requisitos de fonte de dados, formato e automação. O exemplo COPY INTO a seguir ilustra um padrão de ingestão comum para carregar dados de arquivos externos em uma tabela.

COPY INTO [dbo].[TaxiTrips]
FROM 'https://{storage-path}.blob.core.windows.net/Files/yellow/'
WITH ( FILE_TYPE = 'CSV' );

Essa instrução poderá falhar ao ingerir dados se os arquivos de origem não corresponderem ao esquema da tabela de destino. As causas comuns incluem contagens de colunas incompatíveis, tipos de dados incompatíveis ou valores que não podem ser armazenados na tabela de destino. Se a ingestão encontrar valores que não podem ser convertidos no esquema de destino, a instrução retornará um erro semelhante ao seguinte:

Msg 13812, Level 16, State 1, Line 2
Bulk load data conversion error (type mismatch or invalid character for the specified codepage)
for row starting at byte offset 0, column 1 (vendorID).
Underlying data description:
file 'https://....blob.core.windows.net/Files/yellow/tripdata.csv'.

Esse erro indica que uma ou mais linhas não podem ser convertidas nos tipos de coluna de destino.

Investigar erros com MAXERRORS e ERRORFILE

Use as opções a seguir para continuar a ingestão quando o número de erros de nível de linha estiver abaixo de um limite definido e armazenar detalhes de diagnóstico em um local especificado.

• MAXERRORS define o número máximo de falhas de nível de linha toleradas durante a ingestão.
• ERRORFILE especifica onde o banco de dados grava linhas rejeitadas e detalhes de erro.

COPY INTO [dbo].[TaxiTrips]
FROM 'https://{storage-path}.blob.core.windows.net/Files/yellow/'
WITH (
    FILE_TYPE = 'CSV',
    MAXERRORS = 10,
    ERRORFILE = 'https://{storage-path}.blob.core.windows.net/Files/yellow/'
);

A operação de carga só é bem-sucedida quando o número de linhas rejeitadas é menor que MAXERRORS. Quando os erros são capturados, a operação de ingestão grava:

• error.jsonl para diagnóstico estruturado
• row.csv para linhas de origem rejeitadas

Localizar e consultar linhas rejeitadas

O banco de dados grava informações de erro em uma hierarquia de pasta estruturada no local de erro configurado. Essas pastas ajudam você a rastrear uma execução específica e correlacionar o diagnóstico a uma instrução de ingestão:

ERRORFILE/
+-- _rejectedrows/
    +-- <timestamp>/
        +-- <statement_id>/
            +-- error.jsonl
            +-- row.csv or rows.jsonl

Use OPENROWSET para ler o diagnóstico error.jsonl estruturado para que você possa identificar qual valor falhou, qual coluna de destino foi afetada e onde a linha com falha se originou:

SELECT *
FROM OPENROWSET(
    BULK 'https://{storage-path}.blob.core.windows.net/Files/yellow/_rejectedrows/*/*/error.jsonl'
);

O conjunto de resultados normalmente inclui uma linha por registro rejeitado, por exemplo:

O error.jsonl arquivo contém um objeto JSON por linha. Cada objeto inclui as propriedades listadas na tabela anterior. A tabela a seguir descreve cada propriedade em detalhes.

Examinar linhas rejeitadas

Depois de examinar as informações de diagnóstico estruturadas, você pode inspecionar os dados de origem originais que o banco de dados não pôde ingerir. A saída de linhas rejeitadas contém cópias dos registros de origem, preservadas exatamente como aparecem nos arquivos de entrada. O diagnóstico de linhas rejeitadas gera arquivos que contêm apenas os registros que falharam na ingestão:

• Se você ingerir arquivos CSV usando COPY INTO (FILE_TYPE = 'CSV'), a saída rejeitada incluirá um row.csv arquivo. Esse arquivo corresponde à estrutura do arquivo de origem e contém as linhas CSV originais com valores inválidos.
• Se você ingerir arquivos JSONL usando OPENROWSET(FORMAT = 'JSONL'), a saída rejeitada incluirá um row.jsonl arquivo. Esse arquivo preserva os objetos JSON originais que causaram falhas de ingestão.

Use esses arquivos para validar a causa raiz dos erros, como valores malformados, valores inesperados NULL ou linhas de cabeçalho que foram analisadas incorretamente como dados.

SELECT *
FROM OPENROWSET(
    BULK 'https://{storage-path}.blob.core.windows.net/Files/yellow/_rejectedrows/*/*/row.csv'
);

O row.csv esquema corresponde à forma CSV de origem e contém apenas linhas que falharam na ingestão.

Exemplo de saída de linha rejeitada:

Com base nessas informações de diagnóstico, você pode identificar os seguintes problemas de ingestão:

• A linha de cabeçalho no arquivo de origem é analisada erroneamente como uma linha de dados. Para resolver, a instrução COPY INTO deve usar a opção FIRSTROW = 2 .
• Uma linha no arquivo de origem da vendorID coluna (C1) contém NULL valores, mas a coluna correspondente na tabela de destino TaxiTrips é definida como NOT NULL.
• Uma linha no arquivo de origem da passengerCount coluna contém um valor inválido (N/A) que não pode ser convertido na coluna int de destino.

Corrigir problemas de ingestão e reingestão de dados

Depois de identificar a causa das falhas de ingestão, corrija o problema e reingira os dados afetados. A abordagem de correção depende de onde o erro se origina.

Corrigir o esquema da tabela de destino

Se os dados de origem não estiverem em conformidade com o esquema da tabela de destino, atualize a definição da tabela. Correções comuns incluem alterar tipos de dados de coluna ou remover restrições restritivas, como NOT NULL.

Em alguns cenários, talvez seja necessário remover e recriar a tabela de destino antes de ingerir novamente os dados.

Corrigir dados de origem e reprocessar arquivos

Se a ingestão falhar devido a valores inválidos ou inconsistentes nos arquivos de origem, corrija esses valores e reingira os dados. Por exemplo, substitua valores de espaço reservado, como N/A, por valores vazios ou padrões válidos.

COPY INTO [dbo].[TaxiTrips]
FROM 'https://{storage-path}.blob.core.windows.net/Files/yellow/tripdata_corrected.csv'
WITH ( FILE_TYPE = 'CSV' );

Ao ingerir novamente os dados corrigidos, use um caminho de arquivo explícito que aponte para o novo arquivo que contém apenas dados corrigidos, em vez de um caminho de pasta que faça referência aos arquivos originais. Essa abordagem impede a ingestão nova de linhas que foram carregadas com êxito e evita dados duplicados.

Reprocessar linhas rejeitadas usando uma tabela intermediária

Você pode carregar linhas rejeitadas em uma tabela de estágio, corrigir os dados usando instruções de modificação de dados Transact-SQL e, em seguida, reimportar as linhas corrigidas.

A instrução a seguir CREATE TABLE AS SELECT carrega linhas rejeitadas em uma tabela para processamento adicional:

CREATE TABLE TaxiTrip_RejectedRows AS
SELECT *
FROM OPENROWSET(
    BULK 'https://{storage-path}.blob.core.windows.net/Files/yellow/_rejectedrows/*/*/row.csv'
);

Depois de corrigir os dados, insira as linhas limpas na tabela de destino.

Conteúdo relacionado

• Ingerir dados usando COPY INTO
• Ingerir dados usando Transact-SQL