BCP API を使用してウェアハウスにデータを取り込む (プレビュー)

適用対象:✅ Warehouse in Microsoft Fabric

BCP API は、外部ストレージ内のステージング ファイルを使用せずに Warehouse にデータを読み込む、クライアント側のダイレクト インジェスト パスを提供します。

Important

この機能は プレビュー段階です。

BCP ツール (bcp ユーティリティ)、.NET SqlBulkCopy クラス、および Java SQLServerBulkCopy クラスは、SQL Server、Azure SQL、およびAzure Synapse専用 SQL プール ワークロード間で使用される確立されたインジェスト 方法です。 これらのインターフェイスでは、BCP API と TDS の一括読み込みプロトコルが使用されます。これは通常、大量のインジェストのために行単位の INSERT ステートメントよりも効率的です。

Important

最初にファイルをステージングできる運用シナリオでインジェスト スループットが最も高い場合は、 COPY INTO を使用します。

データがクライアント層またはアプリケーション層に既にあり、SQL 接続経由でウェアハウス テーブルに直接取り込む必要がある場合は、BCP API を使用します。

BCP API を使用する場合

BCP API は、次のような直接インジェスト シナリオに使用します。

  • データをメモリに保持し、バッチで書き込むアプリケーション サービス。
  • コマンドライン自動化によってファイルを読み込む運用スクリプトとランブック。
  • SQL 一括コピー セマンティクスを使用するデータ統合ツール。
  • BCP API セマンティクスを既に使用しており、 COPY INTO ステージング パターンにリファクタリングできない既存のクライアント ツールまたは統合。
  • クライアントが頻繁に小さなバッチをウェアハウス SQL 接続経由で直接プッシュするマイクロバッチワークロード。

Prerequisites

  • Microsoft Entra ID認証を使用します。 WAREHOUSE では、SQL 認証 (ユーザー名とパスワード) はサポートされていません。

オプション 1: スクリプト ベースのインジェストに bcp.exe を使用する

スクリプト、スケジュールされたジョブ、または Runbook からの繰り返し可能なコマンド ライン インジェストが必要な場合は、 bcp ユーティリティ を使用します。 このオプションは、区切り記号、エンコード、バッチ サイズ、エラー出力を明示的に制御するファイル ベースのインポートに適しています。

このオプションは、SQL Server、Azure SQL、または同様の SQL エンドポイントからbcp ... outによってソース ファイルが作成され、互換性のある一括コピー ファイル規則を保持する場合にも推奨されます。

一般的なフロー:

  1. ウェアハウス内に対象テーブルを準備してください。
  2. ターゲットと一致する列の順序でソース ファイル (CSV など) を準備するか、フォーマット ファイルを使用します。
  3. ウェアハウス SQL エンドポイントとデータベースを使用して bcp ... in を実行します。
  4. ファイルのサイズと形式に基づいて、バッチ サイズや区切り記号などのオプションを調整します。

Example:

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

bcp ドキュメントの便利なオプション:

  • -Sは、SQL エンドポイントまたはウェアハウス接続文字列を設定します。
  • -d は、コピー先データベースを設定します。
  • -Gでは、Microsoft Entra認証が使用されます。 これは、このプレビュー シナリオでサポートされている唯一の認証オプションです。
  • -Uは、対話型サインイン パターンのMicrosoft Entraユーザー プリンシパル名を指定します。
  • -c は文字データ形式を使用します。
  • -t はフィールド ターミネータを設定します (この例では, )。
  • -b は、大きな負荷に対してバッチ サイズを設定できます。

完全な構文とプラットフォーム固有のオプションについては、「 bcp ユーティリティを使用した一括コピー」を参照してください。

オプション 2: C# SqlBulkCopy を使用する

データを既にメモリ内に保持している .NET サービスおよびアプリケーション (たとえば、DataTable や DbDataReader) には、Microsoft.Data.SqlClient.SqlBulkCopy を使用します。 SqlBulkCopy は、1 つの SQL 接続を介して行を宛先テーブルに効率的にストリーミングします。 これは、多数の個別の INSERT ステートメントを発行するよりも良い選択です。

一般的なフロー:

  1. Microsoft Entra 認証を使用して、ウェアハウス接続文字列で SQL 接続を開きます。
  2. SqlBulkCopy インスタンスを作成し、DestinationTableNameを設定します。
  3. (省略可能)ソースとターゲットの列名または順序が異なる場合は、列マッピングを追加します。
  4. BatchSizeやBulkCopyTimeoutなどのパフォーマンス関連のプロパティを設定します。
  5. WriteToServerまたはWriteToServerAsyncを呼び出してバッチを読み込みます。

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

一般的なチューニング オプションには、ソース スキーマとターゲット スキーマが異なる BatchSize、 BulkCopyTimeout、および明示的な列マッピングが含まれます。

オプション 3: SQLServerBulkCopy Java使用する

JDBC ソースまたはインメモリ データ ストリームからデータを取り込むJava サービスで SQLServerBulkCopy を使用します。 bcp.exeに似た一括読み込み動作が提供されますが、アプリケーション コードでは直接提供されます。

一般的なフロー:

  1. Microsoft Entra 認証を使用して、ウェアハウス接続文字列で JDBC 接続を開きます。
  2. SQLServerBulkCopy インスタンスを作成し、setDestinationTableNameを設定します。
  3. （省略可）SQLServerBulkCopyOptions と列マッピングを設定します。
  4. ソース データを ResultSet、 RowSet、または ISQLServerBulkRecordとして指定します。
  5. writeToServerを呼び出してデータを取り込む。

Example:

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

JDBC 一括コピー API では、 ResultSet、 RowSet、および ISQLServerBulkRecord ソースからの書き込みがサポートされています。

一括コピー オプションのサポートに関する解説

このセクションでは、Fabric Data Warehouseでの一般的な一括コピー オプションの動作について説明します。 オプション名は、.NET SqlBulkCopyOptions、Java SQLServerBulkCopyOptions、および関連する bcp 一括読み込みヒントの設定にマップされます。

該当しないオプション

一般的なクライアント API は次のオプションを受け入れますが、Fabric Data Warehouseの一括コピーではそれらを無視し、既定のサービス動作を使用します。

  • CheckConstraints
  • TableLock
  • KeepNulls
  • FireTriggers

パフォーマンスに関する考慮事項

一括コピーのパフォーマンスは、バッチサイズ設定とクライアントアップロードネットワーク品質に大きく依存します。

バッチ サイズ

バッチ サイズはスループットに大きな影響を与えます。 各バッチには処理オーバーヘッドが固定されているため、非常に小さなバッチ (たとえば、数十行または数百行) を送信すると、大規模なデータセットを読み込むときにパフォーマンスが大幅に低下する可能性があります。

負荷が大きい場合は、より大きなバッチを使用します。 実際のターゲットは、 バッチあたり約 150 MB から 1 GB です。

多くのワークロードに適した出発点は 、バッチあたり 250 MB から 500 MB です。次に、スループットとクライアント のメモリ制限に基づいて調整します。

クライアント アップロード接続の品質

一括コピーでは、クライアントからウェアハウス エンドポイントにデータがストリームされます。 アップロード帯域幅が制限されている場合、またはネットワーク待機時間が長い場合は、ウェアハウス リソースが使用可能な場合でもインジェスト スループットが低下する可能性があります。

パフォーマンスを最大限に高めるには、ウェアハウスと同じAzure リージョンでクライアント アプリケーションを実行し、高帯域幅で待機時間の短いネットワーク パスを使用します。

BCP API と COPY INTO の比較

  • データがクライアント/アプリケーション層で生成または保持され、直接インジェストが必要な場合は 、BCP API を 使用します。
  • COPY INTOストレージ内のファイルをステージングでき、プライマリ サーバー側のパスで最高スループットのインジェストが必要な場合に使用します。

関連するコンテンツ

  • Last updated on