Gegevens opnemen in uw magazijn met behulp van BCP API (preview)

Van toepassing op:✅ Warehouse in Microsoft Fabric

De BCP-API biedt een direct invoerpad aan clientzijde om gegevens in Warehouse te laden zonder bestanden eerst in externe opslag te plaatsen.

Important

Deze functie is beschikbaar als preview-versie.

Het BCP-hulpprogramma (bcp-hulpprogramma), .NET SqlBulkCopy klasse en Java-klasse SQLServerBulkCopy zijn tot stand gebrachte opnamemethoden die worden gebruikt voor SQL Server, Azure SQL en Azure Synapse toegewezen SQL-poolworkloads. Deze interfaces maken gebruik van het BCP-API- en TDS-protocol voor bulksgewijs laden. Dit is doorgaans efficiënter dan rij-per-rij-instructies INSERT voor opname van grote volumes.

Important

Gebruik COPY INTO voor de hoogste opnamedoorvoer in productiescenario's waarin u bestanden eerst kunt fasen.

Gebruik de BCP-API wanneer gegevens zich al in uw client- of toepassingslaag bevinden en u directe opname in magazijntabellen nodig hebt via een SQL-verbinding.

Wanneer gebruikt u de BCP-API?

BCP-API gebruiken voor scenario's voor directe opname, zoals:

  • Toepassingsservices die gegevens in het geheugen bewaren en schrijven in batches.
  • Operationele scripts en runbooks die bestanden inladen met opdrachtregelautomatisering.
  • Hulpmiddelen voor gegevensintegratie die gebruikmaken van de semantiek van SQL-bulkkopiëren.
  • Bestaande clienthulpprogramma's of -integraties die al gebruikmaken van de Semantiek van de BCP-API en die niet kunnen worden geherstructureerd naar een COPY INTO faseringspatroon.
  • Microbatchworkloads waarbij clients frequente kleine batches rechtstreeks via de SQL-verbinding van het magazijn pushen.

Prerequisites

  • Gebruik Microsoft Entra ID-verificatie. SQL-verificatie (gebruikersnaam en wachtwoord) wordt niet ondersteund in Warehouse.

Optie 1: gebruik bcp.exe voor opname op basis van scripts

Gebruik het hulpprogramma bcp wanneer u herhaalbare opdrachtregelopname van scripts, geplande taken of runbooks nodig hebt. Deze optie is geschikt voor importbewerkingen op basis van bestanden, waar u expliciete controle wilt over scheidingstekens, codering, batchgrootte en foutuitvoer.

Deze optie wordt ook aanbevolen wanneer bronbestanden zijn gemaakt op bcp ... out basis van SQL Server, Azure SQL of vergelijkbare SQL-eindpunten en u compatibele bestandsconventies voor bulksgewijs kopiëren wilt behouden.

Typisch verloop:

  1. Bereid een doeltabel voor in uw magazijn.
  2. Bereid een bronbestand (bijvoorbeeld CSV) voor met kolomvolgorde die overeenkomt met het doel of gebruik een indelingsbestand.
  3. Voer bcp ... in uit met uw SQL-eindpunt en -database van uw magazijn.
  4. Opties afstemmen, zoals batchgrootte en scheidingstekens op basis van bestandsgrootte en indeling.

Example:

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

Nuttige opties uit bcp-documentatie:

  • -Sstelt het SQL-eindpunt of het warehouse-verbindingsreeks in.
  • -d stelt de doeldatabase in.
  • -Gmaakt gebruik van Microsoft Entra verificatie. Dit is de enige ondersteunde verificatieoptie voor dit preview-scenario.
  • -Ugeeft uw Microsoft Entra user principal name op voor interactieve aanmeldingspatronen.
  • -c maakt gebruik van tekengegevensindeling.
  • -t stelt het veldeindteken (, in dit voorbeeld) in.
  • -b kan de batchgrootte instellen voor grote hoeveelheden gegevens.

Zie Bulk copy met bcp Utility voor volledige syntaxis en platformspecifieke opties.

Optie 2: C# SqlBulkCopy gebruiken

Gebruik Microsoft. Data.SqlClient.SqlBulkCopy voor .NET services en toepassingen die al gegevens in het geheugen bevatten (bijvoorbeeld DataTable ).DbDataReader SqlBulkCopy streamt rijen efficiënt naar een doeltabel via één SQL-verbinding. Het is een betere keuze dan het uitgeven van veel afzonderlijke INSERT instructies.

Typisch verloop:

  1. Open een SQL-verbinding met de warehouse-verbindingsreeks met behulp van Microsoft Entra-verificatie.
  2. Maak een SqlBulkCopy-exemplaar en stel DestinationTableName in.
  3. (Optioneel) Voeg kolomtoewijzingen toe als de bron- en doelkolomnamen of -volgorde verschillen.
  4. Prestatiegerelateerde eigenschappen instellen, zoals BatchSize en BulkCopyTimeout.
  5. Roep WriteToServer de batch aan of WriteToServerAsync laad deze.

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

Algemene afstemmingsopties zijn onder andere BatchSize, BulkCopyTimeouten expliciete kolomtoewijzingen waarbij bron- en doelschema's verschillen.

Optie 3: Java SQLServerBulkCopy gebruiken

Gebruik SQLServerBulkCopy in Java services die gegevens opnemen uit JDBC-bronnen of in-memory gegevensstromen. Het biedt bulksgewijs laadgedrag dat vergelijkbaar is met bcp.exe, maar rechtstreeks in toepassingscode.

Typisch verloop:

  1. Open een JDBC-verbinding met de warehouse-verbindingsreeks met Microsoft Entra-verificatie.
  2. Maak een SQLServerBulkCopy-exemplaar en stel setDestinationTableName in.
  3. (Optioneel) Configureer SQLServerBulkCopyOptions en kolomtoewijzingen.
  4. Geef de brongegevens op als ResultSet, RowSetof ISQLServerBulkRecord.
  5. Roep writeToServer aan om gegevens in te lezen.

Example:

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

De JDBC-api voor bulksgewijs kopiëren ondersteunt het schrijven van ResultSet, RowSeten ISQLServerBulkRecord bronnen.

Opmerkingen over ondersteuning voor de optie voor bulkkopiëren

In deze sectie wordt uitgelegd hoe algemene opties voor bulksgewijs kopiëren zich gedragen in Fabric Data Warehouse. De optienamen komen overeen met instellingen in .NET SqlBulkCopyOptions, Java SQLServerBulkCopyOptions en verwante bcp-hints voor bulkladen.

Niet van toepassing zijnde opties

Algemene client-API's accepteren de volgende opties, maar bulksgewijs kopiëren in Fabric Data Warehouse negeert ze en gebruikt standaardservicegedrag:

  • CheckConstraints
  • TableLock
  • KeepNulls
  • FireTriggers

Prestatie-overwegingen

De prestaties van bulksgewijs kopiëren zijn sterk afhankelijk van batchgrootte en uploadnetwerkkwaliteit van clients.

Batchgrootte

Batchgrootte heeft een grote invloed op de doorvoer. Elke batch heeft vaste verwerkingsoverhead, dus het verzenden van zeer kleine batches (bijvoorbeeld tientallen of honderden rijen) kan de prestaties aanzienlijk verminderen bij het laden van grote gegevenssets.

Voor grotere belastingen gebruikt u grotere batches. Een praktisch doel is ongeveer 150 MB tot 1 GB per batch.

Een goed uitgangspunt voor veel workloads is 250 MB tot 500 MB per batch en pas vervolgens aan op basis van doorvoer- en clientgeheugenlimieten.

Kwaliteit van clientuploadverbinding

Bulkkopie streamt gegevens van de client naar het warehouse-eindpunt. Als de uploadbandbreedte beperkt is of de netwerklatentie hoog is, kan de opnamedoorvoer afnemen, zelfs wanneer er magazijnbronnen beschikbaar zijn.

Voor de beste prestaties voert u de clienttoepassing uit in dezelfde Azure regio als het magazijn en gebruikt u een netwerkpad met hoge bandbreedte en lage latentie.

BCP-API vergeleken met COPY INTO

  • Gebruik de BCP-API wanneer gegevens worden gegenereerd of bewaard in de client-/toepassingslaag en directe opname is vereist.
  • Gebruik COPY INTO wanneer u bestanden in opslag kunt klaarzetten en het primaire server-sidepad wilt voor gegevensopname met de hoogste doorvoer.

Verwante onderwerpen

  • Last updated on