Como carregar dados com COPY INTO no Azure Synapse

O comando COPY INTO é a forma mais rápida e simples de carregar ficheiros CSV ou Parquet do teu Data Lake para uma tabela de um Dedicated SQL Pool no Azure Synapse. Numa única instrução T-SQL substituis pipelines complexos e obténs uma ingestão de alto desempenho, sem provisionar recursos extra. Vais aprender a preparar a tabela de destino, escrever o comando COPY INTO e validar os dados carregados.

Pré-requisitos

• Um Dedicated SQL Pool ativo no teu workspace do Azure Synapse.
• Ficheiros de dados (CSV ou Parquet) numa conta de Azure Data Lake Storage Gen2 ou Blob Storage.
• Permissões de escrita na base de dados e acesso de leitura ao armazenamento (por exemplo, através de uma Managed Identity).
• Um editor SQL: o Synapse Studio, o Azure Data Studio ou o SQL Server Management Studio (SSMS).

Passo 1: Criar a tabela de destino

Antes de carregar dados, precisas de uma tabela cujas colunas correspondam às do ficheiro, pela mesma ordem. Escolhe os tipos de dados com cuidado: colunas demasiado largas desperdiçam memória e degradam o desempenho no Dedicated SQL Pool. Neste exemplo usamos DISTRIBUTION = ROUND_ROBIN, que reparte as linhas de forma uniforme — uma boa escolha para tabelas de staging — e um CLUSTERED COLUMNSTORE INDEX, ideal para grandes volumes analíticos.

CREATE TABLE dbo.Sales
(
    SaleID      INT            NOT NULL,
    SaleDate    DATE           NOT NULL,
    Product     NVARCHAR(100)  NOT NULL,
    Quantity    INT            NOT NULL,
    Amount      DECIMAL(10,2)  NOT NULL
)
WITH
(
    DISTRIBUTION = ROUND_ROBIN,
    CLUSTERED COLUMNSTORE INDEX
);

Passo 2: Configurar o acesso ao armazenamento

O COPY INTO precisa de autenticação para ler os ficheiros. A opção mais simples e segura é a Managed Identity do workspace. Basta atribuir ao workspace o papel Storage Blob Data Contributor na conta de armazenamento, no portal do Azure. Assim não geres chaves nem segredos dentro do código.

Dica: a Managed Identity evita guardar chaves de armazenamento no teu SQL. É a abordagem recomendada em ambientes de produção.

Passo 3: Executar o COPY INTO

Com a tabela criada e as permissões atribuídas, corre o comando. Este exemplo carrega todos os ficheiros Parquet de uma pasta do Data Lake:

COPY INTO dbo.Sales
FROM 'https://mystorageaccount.dfs.core.windows.net/data/sales/'
WITH
(
    FILE_TYPE = 'PARQUET',
    CREDENTIAL = (IDENTITY = 'Managed Identity')
);

Quando aponta para uma pasta, o COPY INTO lê todos os ficheiros lá dentro; para um único ficheiro, indica o caminho completo. Se os teus dados estiverem em CSV com cabeçalho, indica o tipo de ficheiro e salta a primeira linha:

COPY INTO dbo.Sales
FROM 'https://mystorageaccount.dfs.core.windows.net/data/sales.csv'
WITH
(
    FILE_TYPE = 'CSV',
    FIRSTROW = 2,
    FIELDTERMINATOR = ',',
    ROWTERMINATOR = '0x0A'
);

FIRSTROW = 2 ignora a linha de cabeçalho; FIELDTERMINATOR define o separador de colunas e ROWTERMINATOR o fim de linha.

Passo 4: Lidar com linhas com erro

Ficheiros reais têm quase sempre valores inesperados. Usa a opção ERRORFILE para que as linhas rejeitadas sejam guardadas em vez de fazerem falhar todo o carregamento:

COPY INTO dbo.Sales
FROM 'https://mystorageaccount.dfs.core.windows.net/data/sales.csv'
WITH
(
    FILE_TYPE = 'CSV',
    FIRSTROW = 2,
    MAXERRORS = 10,
    ERRORFILE = 'https://mystorageaccount.dfs.core.windows.net/rejected/'
);

Com MAXERRORS = 10, o carregamento continua até 10 linhas inválidas; acima disso, falha. As linhas problemáticas ficam na pasta indicada em ERRORFILE, para que as possas analisar mais tarde.

Verificar o resultado

Depois de correr o comando, confirma quantas linhas entraram na tabela:

SELECT COUNT(*) AS TotalRows FROM dbo.Sales;

Compara o número com o total esperado dos ficheiros. Podes também espreitar alguns registos com SELECT TOP 10 * FROM dbo.Sales; para confirmar que as colunas ficaram alinhadas e os tipos corretos. Se vires um erro de conversão, revê os tipos da tabela ou o separador do CSV.

Conclusão

Com o COPY INTO tens um método de ingestão rápido, seguro e sem infraestrutura adicional para alimentar o teu Dedicated SQL Pool. A partir daqui, podes agendar este comando dentro de um Synapse Pipeline para automatizar cargas diárias, ou combiná-lo com uma tabela de staging antes de aplicares transformações. Já pensaste em que coluna do teu ficheiro daria a melhor chave de distribuição?