Ingire dados no seu armazém usando a API BCP (Pré-visualização)

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

A API do BCP fornece uma via direta de ingestão, do lado do cliente, para carregar dados no Warehouse sem preparar ficheiros em armazenamento externo.

Importante

Este recurso está em pré-visualização.

A ferramenta BCP (utilitário bcp),a classe .NET SqlBulkCopye a classe Java SQLServerBulkCopy são métodos de ingestão estabelecidos usados em cargas de trabalho dedicadas ao pool SQL do SQL Server, SQL do Azure e Azure Synapse. Estas interfaces utilizam a API BCP e o protocolo TDS de carregamento em massa, que é normalmente mais eficiente do que instruções INSERT linha a linha para o carregamento de grandes volumes.

Importante

Para o maior throughput de ingestão em cenários de produção onde podes preparar os ficheiros primeiro, usa COPY INTO.

Usa a API BCP quando os dados já estiverem no teu cliente ou aplicação e precisares de ingestão direta para tabelas de armazém através de uma ligação SQL.

Quando usar a BCP API

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

  • Serviços de aplicação que mantêm os dados em memória e escrevem em lotes.
  • Scripts operacionais e livros de execução que carregam ficheiros através de automação em linha de comandos.
  • Ferramentas de integração de dados que usam semântica de cópia em massa em SQL.
  • Ferramentas cliente existentes ou integrações que já utilizam as semânticas da API BCP e que não podem ser refatoradas para um padrão de preparação COPY INTO.
  • Processamento em microlotes em cargas de trabalho nas quais os clientes enviam frequentemente pequenos lotes diretamente através da ligação SQL ao armazém de dados.

Prerequisites

  • Use a autenticação do Microsoft Entra ID. A autenticação SQL (nome de utilizador e palavra-passe) não é suportada no Warehouse.

Opção 1: Usar bcp.exe para ingestão baseada em scripts

Usa a utilidade bcp quando precisares de ingestão repetível na linha de comandos a partir de scripts, trabalhos agendados ou runbooks. Esta opção é adequada para importações baseadas em ficheiros, onde se pretende controlo explícito sobre delimitadores, codificação, tamanho de lote e erro de saída.

Esta opção também é recomendada quando os ficheiros de origem foram criados por bcp ... out a partir do SQL Server, do SQL do Azure ou de pontos finais SQL semelhantes e pretende preservar convenções compatíveis dos ficheiros de cópia em massa.

Fluxo típico:

  1. Prepara uma tabela de alvos no teu armazém.
  2. Prepare um ficheiro fonte (por exemplo, CSV) com a ordem das colunas que corresponda ao destino, ou use um ficheiro de formatação.
  3. Execute bcp ... in com o endpoint SQL do armazém e a respetiva base de dados.
  4. Ajuste opções como o tamanho do lote e os delimitadores com base no tamanho e formato do ficheiro.

Example:

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:

  • -Sdefine o endpoint SQL ou a cadeia de ligação do warehouse.
  • -d define a base de dados de destino.
  • -Gutiliza autenticação Microsoft Entra. Esta é a única opção de autenticação suportada para este cenário de pré-visualização.
  • -Uespecifica o seu nome principal de utilizador Microsoft Entra para padrões interativos de início de sessão.
  • -c utiliza 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 sintaxe completa e opções específicas da plataforma, veja Bulk Copy with bcp Utility.

Opção 2: Usar C# SqlBulkCopy

Usa a Microsoft. Data.SqlClient.SqlBulkCopy para serviços e aplicações .NET que já armazenam dados em memória (por exemplo, DataTable ou DbDataReader). SqlBulkCopy Transmite linhas de forma eficiente para uma tabela de destino através de uma ligação SQL. É uma escolha melhor do que emitir muitas declarações individuais INSERT.

Fluxo típico:

  1. Abra uma ligação SQL com a cadeia de ligação do armazém de dados utilizando a autenticação Microsoft Entra.
  2. Crie uma SqlBulkCopy instância e defina DestinationTableName.
  3. (Opcional) Adicione mapeamentos de colunas se os nomes ou ordem das colunas de origem e destino diferirem.
  4. Defina propriedades relacionadas com o desempenho, como BatchSize e BulkCopyTimeout.
  5. Chame WriteToServer ou WriteToServerAsync para carregar o lote.

Example:

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);

Opções comuns de afinação incluem BatchSize, BulkCopyTimeout, e mapeamentos explícitos de colunas onde os esquemas de origem e destino diferem.

Opção 3: Utilizar Java SQLServerBulkCopy

Use SQLServerBulkCopy em serviços Java que ingeram dados de fontes JDBC ou fluxos de dados em memória. Proporciona um comportamento de carregamento em massa semelhante ao bcp.exe, mas diretamente no código da aplicação.

Fluxo típico:

  1. Abra uma ligação JDBC com a cadeia de ligação do armazém de dados utilizando a autenticação Microsoft Entra.
  2. Crie uma SQLServerBulkCopy instância e defina setDestinationTableName.
  3. (Opcional) Configurar SQLServerBulkCopyOptions e mapear colunas.
  4. Forneça os dados de origem como ResultSet, RowSet, ou ISQLServerBulkRecord.
  5. Chame writeToServer para ingerir dados.

Example:

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

A API de cópia em massa do JDBC suporta a gravação a partir das fontes ResultSet, RowSet e ISQLServerBulkRecord.

Observações sobre o suporte a opções de cópia em massa

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

Opções não aplicáveis

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

  • CheckConstraints
  • TableLock
  • KeepNulls
  • FireTriggers

Considerações sobre desempenho

O desempenho das cópias em massa depende fortemente do tamanho em lote e da qualidade da rede de upload do cliente.

Tamanho do lote

O tamanho do lote tem um grande impacto no rendimento. Cada lote tem uma sobrecarga de processamento fixa, por isso 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. Um objetivo prático é cerca de 150 MB a 1 GB por lote.

Um bom ponto de partida para muitas cargas de trabalho é entre 250 MB e 500 MB por lote, ajustando depois com base no rendimento e nos limites de memória do cliente.

Qualidade da ligação de upload do cliente

A cópia em massa transmite dados do cliente para o endpoint do armazém. Se a largura de banda de carregamento for limitada ou a latência da rede for elevada, a taxa de ingestão pode diminuir mesmo quando há recursos disponíveis no armazém.

Para obter o melhor desempenho, execute a aplicação cliente na mesma região Azure do armazém e utilize um caminho de rede de alta largura de banda e baixa latência.

API BCP comparada com COPY INTO

  • Use a API BCP quando os dados são gerados ou mantidos na camada cliente/aplicação e é necessária a ingestão direta.
  • Usa COPY INTO quando podes armazenar ficheiros e queres o caminho principal do lado do servidor para a maior ingestão de rendimento.

Conteúdo relacionado

  • Last updated on