Ingerir dados em seu warehouse usando a API BCP (versão prévia)

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

A API BCP fornece um caminho de ingestão direto do lado do cliente para carregar dados no Warehouse sem arquivos de preparo no armazenamento externo.

Importante

Esse recurso está na versão prévia.

A ferramenta BCP (utilitário bcp), a classe .NET SqlBulkCopy e a classe Java SQLServerBulkCopy são métodos de ingestão consolidados usados em cargas de trabalho do SQL Server, do SQL do Azure e do pool de SQL dedicado do Azure Synapse. Essas interfaces usam a API BCP e o protocolo de carregamento em massa do TDS, que normalmente é mais eficiente do que as instruções INSERT executadas linha por linha para ingestão em alto volume.

Importante

Para obter a maior taxa de ingestão em cenários de produção nos quais seja possível armazenar temporariamente os arquivos primeiro, use COPY INTO.

Use a API BCP quando os dados já estiverem na camada de cliente ou aplicativo e você precisar de ingestão direta em tabelas de warehouse por meio de uma conexão SQL.

Quando usar a API BCP

Use a API BCP para cenários de ingestão direta, como:

  • Serviços de aplicativo que mantêm dados na memória e gravam em lotes.
  • Scripts operacionais e runbooks que carregam arquivos por meio da automação de linha de comando.
  • Ferramentas de integração de dados que usam semântica de cópia em massa do SQL.
  • Ferramentas de cliente existentes ou integrações que já usam a semântica da API BCP e não podem ser refatoradas para um padrão de staging COPY INTO.
  • Cargas de trabalho de microlotes em que os clientes enviam pequenos lotes frequentes diretamente pela conexão SQL do data warehouse.

Pré-requisitos

  • Use a autenticação do Microsoft Entra ID. A autenticação SQL (nome de usuário e senha) não tem suporte no Warehouse.

Opção 1: usar bcp.exe para ingestão baseada em script

Use o utilitário bcp quando precisar de ingestão repetível pela linha de comando a partir de scripts, trabalhos agendados ou runbooks. Essa opção é uma boa opção para importações baseadas em arquivo em que você deseja um controle explícito sobre delimitadores, codificação, tamanho do lote e saída de erro.

Essa opção também é recomendada quando os arquivos de origem foram criados por meio de bcp ... out do SQL Server, do SQL do Azure ou de endpoints SQL semelhantes, e você deseja preservar convenções compatíveis de arquivos de cópia em massa.

Fluxo típico:

  1. Prepare uma tabela de destino em seu armazém.
  2. Prepare um arquivo de origem (por exemplo, CSV) com ordem de coluna que corresponda ao destino ou use um arquivo de formato.
  3. Execute bcp ... in com o endpoint SQL e o banco de dados do seu warehouse.
  4. Ajuste opções como tamanho do lote e delimitadores com base no tamanho e no formato do arquivo.

Exemplo:

bcp dbo.Sales in sales.csv -S <workspace-endpoint> -d <database> -G -U <user@domain.com> -c -t ,

Opções úteis na documentação do bcp:

  • -S define o endpoint SQL ou a cadeia de conexão do warehouse.
  • -d define o banco de dados de destino.
  • -G usa a autenticação do Microsoft Entra. Essa é a única opção de autenticação com suporte para este cenário de visualização.
  • -U especifica o nome principal do usuário do Microsoft Entra para padrões de entrada interativa.
  • -c usa o formato de dados de caracteres.
  • -t define o terminador de campo (, neste exemplo).
  • -b pode definir o tamanho do lote para cargas grandes.

Para obter sintaxe completa e opções específicas da plataforma, consulte Cópia em massa com o utilitário bcp.

Opção 2: Usar o SqlBulkCopy em C#

Use Microsoft.Data.SqlClient.SqlBulkCopy para serviços e aplicativos .NET que já têm dados na memória (por exemplo, DataTable ou DbDataReader). SqlBulkCopy transmite linhas com eficiência para uma tabela de destino em uma conexão SQL. É uma opção melhor do que usar muitas declarações individuais INSERT.

Fluxo típico:

  1. Abra uma conexão SQL com a cadeia de conexão do warehouse usando a autenticação do Microsoft Entra.
  2. Criar uma SqlBulkCopy instância e definir DestinationTableName.
  3. (Opcional) Adicione mapeamentos de coluna se os nomes ou a ordem das colunas de origem e de destino forem diferentes.
  4. Definir propriedades relacionadas ao desempenho, como BatchSize e BulkCopyTimeout.
  5. Chame WriteToServer ou WriteToServerAsync para carregar o lote.

Exemplo:

using Microsoft.Data.SqlClient;

using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();

using var bulk = new SqlBulkCopy(connection);
bulk.DestinationTableName = "dbo.Sales";
await bulk.WriteToServerAsync(dataTable);

As opções de ajuste comuns incluem BatchSize, BulkCopyTimeout e mapeamentos explícitos de colunas, quando os esquemas de origem e de destino diferem.

Opção 3: Usar Java SQLServerBulkCopy

Use SQLServerBulkCopy em serviços Java que ingerem dados de fontes JDBC ou de fluxos de dados em memória. Ele fornece um comportamento de carregamento em massa semelhante a bcp.exe, mas diretamente no código do aplicativo.

Fluxo típico:

  1. Abra uma conexão JDBC com o warehouse cadeia de conexão usando Microsoft Entra autenticação.
  2. Criar uma SQLServerBulkCopy instância e definir setDestinationTableName.
  3. (Opcional) Configurar SQLServerBulkCopyOptions e mapear colunas.
  4. Forneça os dados de origem como ResultSet, RowSetou ISQLServerBulkRecord.
  5. Chame writeToServer para ingerir dados.

Exemplo:

try (SQLServerBulkCopy bulkCopy = new SQLServerBulkCopy(connectionString)) {
    bulkCopy.setDestinationTableName("dbo.Sales");
    bulkCopy.writeToServer(resultSet);
}

A API de cópia em massa do JDBC oferece suporte à gravação de fontes ResultSet, RowSet e ISQLServerBulkRecord.

Comentários sobre o suporte à opção de cópia em massa

Esta seção explica como as opções comuns de cópia em massa se comportam em Fabric Data Warehouse. Os nomes das opções correspondem a configurações no .NET SqlBulkCopyOptions, Java SQLServerBulkCopyOptions e a dicas relacionadas de carregamento em massa do bcp.

Opções não aplicáveis

As APIs comuns do cliente aceitam as seguintes opções, mas a cópia em massa no Fabric Data Warehouse as ignora e usa o comportamento de serviço padrão:

  • CheckConstraints
  • TableLock
  • KeepNulls
  • FireTriggers

Considerações sobre desempenho

O desempenho da cópia em massa depende muito do dimensionamento em lote e da qualidade da rede de upload do cliente.

Tamanho do lote

O tamanho do lote tem um grande impacto na taxa de transferência. Cada lote tem sobrecarga de processamento fixa, portanto, enviar lotes muito pequenos (por exemplo, dezenas ou centenas de linhas) pode reduzir significativamente o desempenho ao carregar grandes conjuntos de dados.

Para cargas maiores, use lotes maiores. Uma meta prática é aproximadamente 150 MB a 1 GB por lote.

Um bom ponto de partida para muitas cargas de trabalho é de 250 MB a 500 MB por lote e, em seguida, ajustar com base na taxa de transferência e nos limites de memória do cliente.

Qualidade da conexão de upload do cliente

A cópia em lote transfere dados do cliente para o endpoint do warehouse. Se a largura de banda de upload for limitada ou a latência da rede for alta, a vazão de ingestão pode diminuir mesmo quando os recursos do data warehouse estiverem disponíveis.

Para obter melhor desempenho, execute o aplicativo cliente na mesma região Azure que o warehouse e use um caminho de rede de alta largura de banda e baixa latência.

API BCP em comparação com COPY INTO

  • Use a API BCP quando os dados forem gerados ou mantidos na camada cliente/aplicativo e a ingestão direta for necessária.
  • Use COPY INTO quando puder preparar arquivos no armazenamento e quiser usar o caminho principal no servidor para ingestão com a maior taxa de transferência.

Conteúdo relacionado

  • Last updated on