Inserire i dati nel warehouse usando l'API BCP (anteprima)

si applica a:✅ Magazzino di dati in Microsoft Fabric

L'API BCP fornisce un percorso di inserimento diretto sul lato client per caricare i dati in Warehouse senza file di staging nell'archiviazione esterna.

Important

Questa funzionalità si trova in Anteprima.

Lo strumento BCP (utilità bcp),la classe .NET SqlBulkCopye la classe Java SQLServerBulkCopy vengono definiti metodi di inserimento usati in SQL Server, Azure SQL e Azure Synapse carichi di lavoro del pool SQL dedicato. Queste interfacce usano l'API BCP e il protocollo di caricamento bulk TDS, che in genere sono più efficienti delle istruzioni INSERT eseguite riga per riga per l'acquisizione di grandi volumi di dati.

Important

Per la massima velocità effettiva di acquisizione negli scenari di produzione in cui è possibile preparare temporaneamente i file, utilizzare COPY INTO.

Usare l'API BCP quando i dati sono già presenti nel livello client o dell'applicazione ed è necessario inserire direttamente nelle tabelle del warehouse tramite una connessione SQL.

Quando usare l'API BCP

Usare l'API BCP per scenari di inserimento diretto, ad esempio:

  • Servizi dell'applicazione che mantengono i dati in memoria e scrivono in batch.
  • Script operativi e runbook che caricano i file tramite l'automazione della riga di comando.
  • Strumenti di integrazione dei dati che utilizzano la semantica di copia in blocco di SQL.
  • Strumenti client o integrazioni esistenti che utilizzano già la semantica dell'API BCP e che non possono essere ristrutturati secondo un pattern di staging COPY INTO.
  • Carichi di lavoro di micro-batch in cui i client inviano frequentemente piccoli batch direttamente tramite la connessione SQL del warehouse.

Prerequisites

  • Usare l'autenticazione Microsoft Entra ID. L'autenticazione SQL (nome utente e password) non è supportata in Warehouse.

Opzione 1: Usare bcp.exe per l'inserimento basato su script

Usa l'utilità bcp quando è necessaria un'acquisizione ripetibile da riga di comando da script, processi pianificati o runbook. Questa opzione è ideale per le importazioni basate su file in cui si vuole un controllo esplicito sui delimitatori, la codifica, le dimensioni del batch e l'output degli errori.

Questa opzione è consigliata anche quando i file di origine sono stati creati da bcp ... out SQL Server, Azure SQL o endpoint SQL simili e si vogliono mantenere convenzioni di file di copia bulk compatibili.

Flusso tipico:

  1. Preparare una tabella di destinazione nel magazzino.
  2. Preparare un file di origine (ad esempio CSV) con ordine di colonna corrispondente alla destinazione o usare un file di formato.
  3. Esegui bcp ... in con l'endpoint SQL e il database del warehouse.
  4. Regola opzioni come la dimensione del batch e i delimitatori in base alle dimensioni e al formato del file.

Esempio:

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

Opzioni utili dalla documentazione di bcp:

  • -S imposta l'endpoint SQL o la stringa di connessione del warehouse.
  • -d imposta il database di destinazione.
  • -Gusa l'autenticazione Microsoft Entra. Questa è l'unica opzione di autenticazione supportata per questo scenario di anteprima.
  • -Uspecifica il nome dell'entità utente Microsoft Entra per i modelli di accesso interattivi.
  • -c usa il formato dati carattere.
  • -t imposta il carattere di terminazione del campo (, in questo esempio).
  • -b può impostare le dimensioni del batch per carichi di grandi dimensioni.

Per la sintassi completa e le opzioni specifiche della piattaforma, vedere Copia bulk con l'utilità bcp.

Opzione 2: Usare C# SqlBulkCopy

Usare Microsoft. Data.SqlClient.SqlBulkCopy per .NET servizi e applicazioni che contengono già dati in memoria (ad esempio, DataTable o DbDataReader). SqlBulkCopy trasmette le righe in modo efficiente a una tabella di destinazione tramite una connessione SQL. È una scelta migliore rispetto all'emissione di molte singole INSERT istruzioni.

Flusso tipico:

  1. Apri una connessione SQL con la stringa di connessione del data warehouse utilizzando l'autenticazione Microsoft Entra.
  2. Creare un'istanza SqlBulkCopy e impostare DestinationTableName.
  3. (Facoltativo) Aggiungere mappature delle colonne se i nomi o l'ordine delle colonne di origine e di destinazione sono diversi.
  4. Impostare le proprietà correlate alle prestazioni, BatchSize ad esempio e BulkCopyTimeout.
  5. Chiamare WriteToServer o WriteToServerAsync per caricare il batch.

Esempio:

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

Le opzioni di ottimizzazione comuni includono BatchSize, BulkCopyTimeout e mapping di colonne espliciti nei casi in cui gli schemi di origine e di destinazione differiscono.

Opzione 3: Usare Java SQLServerBulkCopy

Usare SQLServerBulkCopy nei servizi Java che inseriscono dati da origini JDBC o flussi di dati in memoria. Fornisce un comportamento di caricamento bulk simile a bcp.exe, ma direttamente nel codice dell'applicazione.

Flusso tipico:

  1. Aprire una connessione JDBC con il warehouse stringa di connessione usando l'autenticazione Microsoft Entra.
  2. Creare un'istanza SQLServerBulkCopy e impostare setDestinationTableName.
  3. (Facoltativo) Configurare SQLServerBulkCopyOptions e le mappature delle colonne.
  4. Specificare i dati di origine come ResultSet, RowSeto ISQLServerBulkRecord.
  5. Chiamare writeToServer per inserire i dati.

Esempio:

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

L'API JDBC per la copia in blocco supporta la scrittura a partire dalle origini dati ResultSet, RowSet e ISQLServerBulkRecord.

Osservazioni sul supporto delle opzioni di copia bulk

Questa sezione illustra il comportamento delle opzioni comuni di copia bulk in Fabric Data Warehouse. I nomi delle opzioni corrispondono alle impostazioni in .NET SqlBulkCopyOptions, Java SQLServerBulkCopyOptions e ai relativi hint per il caricamento bulk di bcp.

Opzioni non applicabili

Le API client più comuni accettano le opzioni seguenti, ma la copia in blocco in Fabric Data Warehouse le ignora e usa il comportamento predefinito del servizio:

  • CheckConstraints
  • TableLock
  • KeepNulls
  • FireTriggers

Considerazioni sulle prestazioni

Le prestazioni di copia bulk dipendono principalmente dal dimensionamento batch e dalla qualità della rete di caricamento client.

Dimensioni dei batch

Le dimensioni del batch hanno un impatto significativo sulla velocità effettiva. Ogni batch ha un sovraccarico di elaborazione fisso, quindi l'invio di batch molto piccoli (ad esempio, decine o centinaia di righe) può ridurre significativamente le prestazioni durante il caricamento di set di dati di grandi dimensioni.

Per carichi più grandi, usare batch di dimensioni maggiori. Un obiettivo pratico è da circa 150 MB a 1 GB per batch.

Un buon punto di partenza per molti carichi di lavoro è da 250 MB a 500 MB per batch, quindi modificare in base ai limiti di velocità effettiva e memoria client.

Qualità della connessione di caricamento del client

Bulk copy trasferisce i dati in streaming dal client all'endpoint del data warehouse. Se la larghezza di banda del caricamento è limitata o la latenza di rete è elevata, la velocità effettiva di inserimento può diminuire anche quando sono disponibili risorse del warehouse.

Per ottenere prestazioni ottimali, eseguire l'applicazione client nella stessa area Azure del warehouse e usare un percorso di rete a bassa latenza e larghezza di banda elevata.

API BCP confrontata con COPY INTO

  • Usare l'API BCP quando i dati vengono generati o mantenuti nel livello client/applicazione e l'inserimento diretto è obbligatorio.
  • Usa COPY INTO quando puoi caricare i file nell'archiviazione e vuoi il percorso primario lato server per l'acquisizione con la massima velocità effettiva.

Contenuti correlati

  • Last updated on