Charger des données dans votre entrepôt à l’aide de l’API BCP (version préliminaire)

S’applique à :✅Entrepôt dans Microsoft Fabric

L’API BCP fournit un chemin d’ingestion direct côté client pour charger des données dans l’entrepôt sans fichiers intermédiaires dans le stockage externe.

Important

Cette fonctionnalité est en version préliminaire.

L’outil BCP (utilitaire bcp),.NET SqlBulkCopy classe et Java SQLServerBulkCopy classe sont des méthodes d’ingestion établies utilisées dans SQL Server, Azure SQL et Azure Synapse charges de travail de pool SQL dédiées. Ces interfaces utilisent l’API BCP et le protocole tdS de chargement en bloc, qui est généralement plus efficace que les instructions de ligne par ligne INSERT pour l’ingestion à volume élevé.

Important

Pour le débit d’ingestion le plus élevé dans les scénarios de production où vous pouvez d’abord mettre en scène des fichiers, utilisez COPY INTO.

Utilisez l’API BCP lorsque les données se trouvent déjà dans votre niveau client ou application et que vous avez besoin d’une ingestion directe dans des tables d’entrepôt via une connexion SQL.

Quand utiliser l’API BCP

Utilisez l’API BCP pour des scénarios d’ingestion directe tels que :

  • Services d’application qui conservent les données en mémoire et écrivent par lots.
  • Scripts opérationnels et procédures opérationnelles permettant de charger des fichiers à l’aide d’une automatisation en ligne de commande.
  • Outils d’intégration de données qui utilisent la sémantique de copie en bloc SQL.
  • Outils clients existants ou intégrations utilisant déjà la sémantique de l’API BCP et ne pouvant pas être refactorisés vers un modèle intermédiaire COPY INTO.
  • Charges de travail en micro-lots où les clients envoient directement de petits lots fréquents via la connexion SQL de l’entrepôt de données.

Prerequisites

  • Utilisez l’authentification Microsoft Entra ID. L’authentification SQL (nom d’utilisateur et mot de passe) n’est pas prise en charge dans Warehouse.

Option 1 : Utiliser bcp.exe pour l’ingestion basée sur des scripts

Utilisez l’utilitaire bcp lorsque vous avez besoin d’une ingestion de ligne de commande reproductible à partir de scripts, de travaux planifiés ou de runbooks. Cette option est adaptée aux importations basées sur des fichiers où vous souhaitez un contrôle explicite sur les délimiteurs, l’encodage, la taille du lot et la sortie d’erreur.

Cette option est également recommandée lorsque des fichiers sources ont été créés à bcp ... out partir de SQL Server, de Azure SQL ou de points de terminaison SQL similaires et que vous souhaitez conserver les conventions de fichier de copie en bloc compatibles.

Flux classique :

  1. Préparez une table cible dans votre entrepôt.
  2. Préparez un fichier source (par exemple CSV) avec l’ordre de colonne qui correspond à la cible ou utilisez un fichier de format.
  3. Exécutez bcp ... in avec votre point de terminaison et votre base de données SQL de l’entrepôt.
  4. Paramétrez les options telles que la taille du lot et les délimiteurs en fonction de la taille et du format de fichier.

Exemple :

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

Options utiles tirées de la documentation bcp :

  • -S définit le point de terminaison SQL ou la chaîne de connexion de l’entrepôt.
  • -d définit la base de données de destination.
  • -Gutilise l’authentification Microsoft Entra. Il s’agit de la seule option d’authentification prise en charge pour ce scénario d’aperçu.
  • -Uspécifie votre nom d’utilisateur principal Microsoft Entra pour les modèles de connexion interactive.
  • -c utilise le format de données de type caractère.
  • -t définit la marque de fin de champ (, dans cet exemple).
  • -b peut définir la taille du lot pour les charges volumineuses.

Pour obtenir des options complètes spécifiques à la syntaxe et à la plateforme, consultez Copie en bloc avec l’utilitaire bcp.

Option 2 : Utiliser C# SqlBulkCopy

Utilisez Microsoft. Data.SqlClient.SqlBulkCopy pour .NET services et applications qui contiennent déjà des données en mémoire (par exemple, DataTable ou DbDataReader). SqlBulkCopy diffuse efficacement des lignes vers une table de destination sur une connexion SQL. C’est un meilleur choix que d’émettre de nombreuses déclarations individuelles INSERT .

Flux classique :

  1. Ouvrez une connexion SQL avec la chaîne de connexion de l’entrepôt à l’aide de l’authentification Microsoft Entra.
  2. Créez une SqlBulkCopy instance et définissez DestinationTableName.
  3. (Facultatif) Ajoutez des mappages de colonnes si les noms de colonnes source et cible ou l’ordre diffèrent.
  4. Définir des propriétés liées aux performances telles que BatchSize et BulkCopyTimeout.
  5. Appelez WriteToServer ou WriteToServerAsync pour charger le lot.

Exemple :

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

Les options de réglage courantes incluent BatchSize, BulkCopyTimeoutet les mappages de colonnes explicites où les schémas source et cible diffèrent.

Option 3 : Utiliser Java SQLServerBulkCopy

Utilisez SQLServerBulkCopy dans Java services qui ingèrent des données à partir de sources JDBC ou de flux de données en mémoire. Il fournit un comportement de chargement en bloc similaire à bcp.exe, mais directement dans le code de l’application.

Flux classique :

  1. Ouvrez une connexion JDBC avec la chaîne de connexion de l’entrepôt à l’aide de l’authentification Microsoft Entra.
  2. Créez une SQLServerBulkCopy instance et définissez setDestinationTableName.
  3. (Facultatif) Configurer SQLServerBulkCopyOptions et mapper des colonnes.
  4. Fournissez les données sources en tant que ResultSet, RowSetou ISQLServerBulkRecord.
  5. Appelez writeToServer pour ingérer des données.

Exemple :

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

L’API de copie en bloc JDBC prend en charge l’écriture à partir de sources ResultSet, RowSet et ISQLServerBulkRecord.

Remarques sur la prise en charge des options de copie en bloc

Cette section explique comment les options de copie en bloc courantes se comportent dans Fabric Data Warehouse. Les noms d’options correspondent aux paramètres de .NET SqlBulkCopyOptions, de Java SQLServerBulkCopyOptions et aux indications bcp associées pour le chargement en bloc.

Options non disponibles

Les API clientes courantes acceptent les options suivantes, mais la copie en bloc dans Fabric Data Warehouse les ignore et utilise le comportement de service par défaut :

  • CheckConstraints
  • TableLock
  • KeepNulls
  • FireTriggers

Considérations relatives aux performances

Les performances de copie en bloc dépendent fortement du dimensionnement par lots et de la qualité du réseau de chargement du client.

Taille du lot

La taille du lot a un impact majeur sur le débit. Chaque lot a une surcharge de traitement fixe. Par conséquent, l’envoi de lots très petits (par exemple, des dizaines ou des centaines de lignes) peut réduire considérablement les performances lors du chargement de jeux de données volumineux.

Pour les charges plus volumineuses, utilisez des lots plus volumineux. Une cible pratique est d’environ 150 Mo à 1 Go par lot.

Un bon point de départ pour de nombreuses charges de travail est de 250 Mo à 500 Mo par lot, puis ajustez en fonction du débit et des limites de mémoire client.

Qualité de la connexion de téléversement du client

La copie en bloc transfère les données du client vers le point de terminaison de l’entrepôt de données. Si la bande passante de chargement est limitée ou que la latence réseau est élevée, le débit d’ingestion peut diminuer même lorsque les ressources de l’entrepôt sont disponibles.

Pour des performances optimales, exécutez l’application cliente dans la même région Azure que l’entrepôt et utilisez un chemin réseau à bande passante élevée et à faible latence.

API BCP par rapport à COPY INTO

  • Utilisez l’API BCP lorsque les données sont générées ou conservées dans la couche client/application et que l’ingestion directe est requise.
  • Utilisez COPY INTO quand vous pouvez mettre en scène des fichiers dans le stockage et souhaitez que le chemin côté serveur principal soit utilisé pour l’ingestion à débit le plus élevé.

Contenu connexe

  • Last updated on