Copy アクティビティで Lakehouse を構成する方法
この記事では、データ パイプラインのコピー アクティビティを使用して、Fabric Lakehouse との間でデータをコピーする方法について説明します。 デフォルトでは、データは V オーダーで Lakehouse テーブルに書き込まれます。詳細については、「Delta Lake テーブルの最適化と V オーダー」を参照してください。
サポートされている形式
Lakehouse では、次のファイル形式がサポートされています。 形式ベースの設定については、各記事を参照してください。
サポートされている構成
Copy アクティビティの下の各タブの構成については、それぞれ次のセクションを参照してください。
全般
[全般] タブの構成については、全般に関するページを参照してください。
Source
コピー アクティビティの [ソース] タブのLakehouse では、次のプロパティがサポートされています。
![[ソース] タブとプロパティのリストを示すスクリーンショット。](media/connector-lakehouse/lakehouse-source.png#lightbox)
次のプロパティは必須です。
接続: 接続リストから Lakehouse 接続を選択します。 接続が存在しない場合は、接続リストの下部にある [詳細] を選択して、新規 Lakehouse 接続を作成します。 動的コンテンツを使用して Lakehouse を指定する場合は、パラメーターを追加し、パラメーター値として Lakehouse オブジェクト ID を指定します。 Lakehouse オブジェクト ID を取得するには、ワークスペースで Lakehouse を開きます。ID は URL の
/lakehouses/の後にあります。
ルート フォルダー: [テーブル] または [ファイル] を選択します。これは、レイク内のマネージドまたはアンマネージドの領域の仮想ビューを示します。 詳しくは、Lakehouse の概要に関するページをご覧ください。
[テーブル] を選択した場合:
テーブル名: テーブルの一覧から既存のテーブルを選択するか、ソースとしてテーブル名を指定します。 または、 新規 を選択して新規テーブルを作成することもできます。
テーブル: 接続にスキーマを含む Lakehouse を適用する場合は、テーブルの一覧からスキーマを持つ既存のテーブルを選択するか、スキーマをソースとして持つテーブルを指定します。 または、 新規 を選択して、スキーマを含む新規テーブルを作成することもできます。 スキーマ名を指定しない場合、サービスはデフォルトのスキーマとして dbo を使用します。
[詳細設定] では、次のフィールドを指定できます。
- タイムスタンプ: タイムスタンプによって古いスナップショットに対してクエリを実行するように指定します。
- バージョン: バージョンによって古いスナップショットに対してクエリを実行するように指定します。
- 追加の列: ソース ファイルの相対パスまたは静的な値を保存するための追加のデータ列を追加します。 後者では式がサポートされています。
リーダー バージョン 1 がサポートされています。 この記事では、対応するサポートされている Delta Lake 機能を確認できます。
[ファイル] を選択した場合:
ファイル パスの種類: ファイル パスの種類として、[ファイル パス]、[ワイルドカード ファイル パス]、または [ファイルの一覧] を選択できます。 次の一覧で、各設定の構成について説明します。
ファイル パス: [参照] を選択して、コピーするファイルを選択するか、パスを手動で入力します。
ワイルドカード ファイル パス: ソース フォルダーまたはファイルをフィルター処理するために、指定されたLakehouse のアンマネージド領域 ([ファイル] の下) でワイルドカード文字を含むフォルダーまたはファイル パスを指定します。 使用できるワイルドカードは、
*(ゼロ文字以上の文字に一致) と?(ゼロ文字または 1 文字に一致) です。 フォルダーまたはファイルの名前にワイルドカードまたはこのエスケープ文字が含まれている場合は、^を使用してエスケープします。ワイルドカード フォルダー パス: 指定されたコンテナーの下のフォルダーへのパス。 ワイルドカードを使用してフォルダーをフィルター処理する場合は、この設定をスキップし、アクティビティのソース設定でこの情報を指定します。
ワイルドカード ファイル名: 指定されたLakehouse のアンマネージド領域 ([ファイル] の下) のファイル名とフォルダー パス。
ファイルの一覧: 指定されたファイル セットをコピーすることを示します。
- フォルダー パス: コピーするファイルを含むフォルダーをポイントします。
- ファイル リストへのパス: コピーするファイルの一覧を含むテキスト ファイルをポイントします。構成されているパスへの相対パスであるファイルを 1 行につき 1 つずつ指定します。
![[ファイル リストへのパス] を示すスクリーンショット。](media/connector-lakehouse/list-of-files.png)
Recursively: データをサブフォルダーから再帰的に読み取るか、指定したフォルダーからのみ読み取るかを指定します。 有効にすると、入力フォルダーとそのサブフォルダー内のすべてのファイルが再帰的に処理されます。 ファイル パスの種類を [ファイルの一覧] として構成する場合、このプロパティは適用されません。
ファイル形式: ドロップダウン リストからファイル形式を選択します。 [設定] ボタンを選択して、ファイル形式を構成します。 さまざまなファイル形式の設定については、「サポートされている形式」を参照してください。
[詳細設定] では、次のフィールドを指定できます。
- 最終更新日でフィルター処理: 最後に変更された日付に基づいてファイルがフィルター処理されます。 ファイル パスの種類を [ファイルの一覧] として構成する場合、このプロパティは適用されません。
- 開始時刻: 最終変更日時が構成された時刻以降のファイルが選択されます。
- 終了時]: 最終変更日時が構成された時刻以前のファイルが選択されます。
- パーティション検出を有効にする: パーティション分割されているファイルの場合は、ファイル パスのパーティションを解析し、それを追加のソース列として追加するかどうかを指定します。
- パーティションのルート パス: パーティション検出が有効になっている場合は、パーティション分割されたフォルダーをデータ列として読み取るための絶対ルート パスを指定します。
- 最大コンカレント接続数: アクティビティの実行中にデータ ストアに対して確立されるコンカレント接続数の上限を示します。 コンカレント接続を制限する場合にのみ、値を指定します。
- 最終更新日でフィルター処理: 最後に変更された日付に基づいてファイルがフィルター処理されます。 ファイル パスの種類を [ファイルの一覧] として構成する場合、このプロパティは適用されません。
![[ファイル リストへのパス] を示すスクリーンショット。](media/connector-lakehouse/list-of-files.png#lightbox)
宛先
コピー アクティビティの [コピー先] タブのLakehouse では、次のプロパティがサポートされています。
![[コピー先] タブを示すスクリーンショット。](media/connector-lakehouse/lakehouse-destination.png#lightbox)
次のプロパティは必須です。
接続: 接続リストから Lakehouse 接続を選択します。 接続が存在しない場合は、接続リストの下部にある [詳細] を選択して、新規 Lakehouse 接続を作成します。 動的コンテンツを使用して Lakehouse を指定する場合は、パラメーターを追加し、パラメーター値として Lakehouse オブジェクト ID を指定します。 Lakehouse オブジェクト ID を取得するには、ワークスペースで Lakehouse を開きます。ID は URL の
/lakehouses/の後にあります。
ルート フォルダー: [テーブル] または [ファイル] を選択します。これは、レイク内のマネージドまたはアンマネージドの領域の仮想ビューを示します。 詳しくは、Lakehouse の概要に関するページをご覧ください。
[テーブル] を選択した場合:
テーブル名: テーブルの一覧から既存のテーブルを選択するか、コピー先としてテーブル名を指定します。 または、 新規 を選択して新規テーブルを作成することもできます。
テーブル: 接続にスキーマを含む Lakehouse を適用する場合は、テーブルの一覧からスキーマを含む既存のテーブルを選択するか、スキーマを含むテーブルを宛先として指定します。 または、 新規 を選択して、スキーマを含む新規テーブルを作成することもできます。 スキーマ名を指定しない場合、サービスはデフォルトのスキーマとして dbo を使用します。
[詳細設定] では、次のフィールドを指定できます。
テーブル アクション: 選択したテーブルに対する操作を指定します。
追加: 既存のテーブルに新規値を追加します。
- パーティションを有効にする: これを選択すると、1 つまたは複数の列に基づいてフォルダー構造にパーティションを作成できます。 それぞれの個別の列値 (ペア) が新規パーティションです。 たとえば、"year=2000/month=01/file" などです。
- パーティション列名: 新規テーブルにデータを追加するときに、スキーマ マッピングの宛先列から選択します。 既にパーティションがある既存のテーブルにデータを追加すると、パーティション列は既存のテーブルから自動的に派生します。 サポートされるデータ型は string、integer、boolean、datetime です。 形式では、[マッピング] タブの型変換設定が考慮されます。
- パーティションを有効にする: これを選択すると、1 つまたは複数の列に基づいてフォルダー構造にパーティションを作成できます。 それぞれの個別の列値 (ペア) が新規パーティションです。 たとえば、"year=2000/month=01/file" などです。
上書き: 新規値を使用してテーブル内の既存のデータとスキーマを上書きします。 この操作が選択されている場合は、ターゲット テーブルでパーティションを有効にできます。
- パーティションを有効にする: これを選択すると、1 つまたは複数の列に基づいてフォルダー構造にパーティションを作成できます。 それぞれの個別の列値 (ペア) が新規パーティションです。 たとえば、"year=2000/month=01/file" などです。
- パーティション列名: スキーマ マッピングのコピー先列から選択します。 サポートされるデータ型は string、integer、boolean、datetime です。 形式では、[マッピング] タブの型変換設定が考慮されます。
Delta Lake のタイム トラベルをサポートします。 上書きされたテーブルには、以前のバージョンの Delta ログがあり、Lakehouse でアクセスできます。 Copy アクティビティのソースで [バージョン] を指定して、Lakehouse から以前のバージョンのテーブルをコピーすることもできます。
- パーティションを有効にする: これを選択すると、1 つまたは複数の列に基づいてフォルダー構造にパーティションを作成できます。 それぞれの個別の列値 (ペア) が新規パーティションです。 たとえば、"year=2000/month=01/file" などです。
最大コンカレント接続数: アクティビティの実行中にデータ ストアに対して確立されるコンカレント接続数の上限。 コンカレント接続を制限する場合にのみ、値を指定します。
Writer バージョン 2 がサポートされています。 この記事では、対応するサポートされている Delta Lake 機能を確認できます。
[ファイル] を選択した場合:
ファイル パス: [参照] を選択して、コピーするファイルを選択するか、パスを手動で入力します。
ファイル形式: ドロップダウン リストからファイル形式を選択します。 [設定] を 選択してファイル形式を構成します。 さまざまなファイル形式の設定については、「サポートされている形式」を参照してください。
[詳細設定] では、次のフィールドを指定できます。
コピー動作: ソースがファイル ベースのデータ ストアのファイルの場合は、コピー動作を定義します。 コピー動作として、階層のフラット化、ファイルの結合、階層の保持、または動的コンテンツの追加を選択できます。 各設定の構成は次のとおりです。
階層のフラット化: ソース フォルダーのすべてのファイルがコピー先フォルダーの第一レベルに配置されます。 コピー先のファイルは、自動生成された名前になります。
ファイルのマージ: ソース フォルダーのすべてのファイルを 1 つのファイルにマージします。 ファイル名を指定した場合、マージされたファイル名は指定した名前になります。 それ以外は自動生成されたファイル名になります。
階層の保持: ターゲット フォルダー内でファイル階層を保持します。 ソース フォルダーへのソース ファイルの相対パスはターゲット フォルダーへのターゲット ファイルの相対パスと同じになります。
動的なコンテンツの追加: プロパティ値の式を指定するには、[動的なコンテンツの追加] を選択します。 このフィールドを選択すると、式ビルダーが開き、サポートされているシステム変数、アクティビティの出力、関数、ユーザー指定の変数またはパラメーターから式を作成できます。 式言語について詳しくは、式と関数に関するページを参照してください。
![[コピー動作] を示すスクリーンショット。](media/connector-lakehouse/copy-behavior.png)
最大コンカレント接続数: アクティビティの実行中にデータ ストアに対して確立されるコンカレント接続数の上限。 コンカレント接続を制限する場合にのみ、値を指定します。
ブロック サイズ (MB): Lakehouse にデータを書き込む場合のブロック サイズを MB 単位で指定します。 指定できる値は、4 MB から 100 MB です。
メタデータ: コピー先のデータ ストアにコピーする場合のカスタム メタデータを設定します。
metadata配列の各オブジェクトは追加列を表します。nameではメタデータ キー名を定義し、valueでは、そのキーのデータ値を指定します。 属性の保持機能が使用されている場合は、ソース ファイルのメタデータを使用して、指定されたメタデータの和集合の作成や上書きが行われます。 使用できるデータ値は次のとおりです。$$LASTMODIFIED: 予約済みの変数によって、ソース ファイルの最終更新時刻を保存することを指定します。 バイナリ形式のファイルベースのソースにのみ適用されます。Expression
静的な値
![[コピー動作] を示すスクリーンショット。](media/connector-lakehouse/copy-behavior.png#lightbox)
マッピング
[マッピング] タブの構成で、宛先データ ストアとして Lakehouse テーブルを適用しない場合は、[マッピング] に移動します。
マッピングの構成を除き、Lakehouse テーブルをコピー先データ ストアとして適用する場合は、コピー先列の型を編集できます。 [スキーマのインポート] を選択した後、コピー先で列の種類を指定できます。
たとえば、ソースの PersonID 列の型は int ですが、コピー先列にマッピングするときには文字列型に変更できます。
Note
現在、コピー先の型の編集は、ソースが 10 進型の場合はサポートされていません。
ファイル形式として [バイナリ] を選択した場合、マッピングはサポートされません。
設定
[設定] タブの構成については、設定に関するページを参照してください。
表の概要
次の表に、Lakehouse でのコピー アクティビティの詳細を示します。
ソース情報
| 名前 | Description | Value | 必須 | JSON スクリプト プロパティ |
|---|---|---|---|---|
| 接続 | 接続を選択するセクション。 | <Lakehouse 接続> | はい | workspaceId artifactId |
| ルート フォルダー | ルート フォルダーの種類。 | • テーブル • ファイル |
いいえ | rootFolder: テーブルまたはファイル |
| テーブル名 | データを読み取るテーブルの名前。 | <実際のテーブル名> | はい (ルート フォルダー内のテーブルを選択する場合) | テーブル |
| Table | 接続としてスキーマを持つ Lakehouse を適用するときにデータを読み取るスキーマを持つテーブルの名前。 | <スキーマを含むテーブル> | はい (ルート フォルダー内のテーブルを選択する場合) | / |
| テーブルの場合 | ||||
| スキーマ名 | スキーマの名前です。 | < スキーマ名 > (デフォルトはdbo) |
いいえ | (source ->datasetSettings ->typeProperties の下)schema |
| table name | テーブルの名前です。 | <実際のテーブル名> | はい | テーブル |
| Timestamp | 古いスナップショットに対してクエリを実行するタイムスタンプ。 | <timestamp> | いいえ | timestampAsOf |
| バージョン | 古いスナップショットに対してクエリを実行するバージョン。 | <version> | いいえ | versionAsOf |
| 追加の列 | ソース ファイルの相対パスまたは静的な値を保存するための追加のデータ列。 後者では式がサポートされています。 | • 名前 • 値 |
いいえ | additionalColumns: •名前 • value |
| ファイル パスの種類 | 使用するファイル パスの種類。 | • ファイル パス • ワイルドカード ファイル パス • ファイルの一覧 |
はい (ルートフォルダ内のファイルを選択した場合) | / |
| ファイル パス | パスからソース データ ストアのフォルダーまたはファイルにコピーします。 | <file path> | はい ([ファイル パス] を選択する場合) | • folderPath • fileName |
| ワイルドカード パス | ソース フォルダーをフィルター処理するように構成されたソース データ ストアの下のワイルドカード文字を含むフォルダーのパス。 | <ワイルドカード パス> | はい ([ワイルドカード ファイル パス] を選択する場合) | • ワイルドカードフォルダパス • wildcardFileName |
| フォルダー パス | コピーするファイルを含むフォルダーをポイントします。 | <フォルダー パス> | いいえ | folderPath |
| ファイル リストへのパス | 指定されたファイル セットをコピーすることを示します。 コピーするファイルの一覧を含むテキスト ファイルをポイントします。構成されているパスへの相対パスであるファイルを 1 行につき 1 つずつ指定します。 | <ファイル リストへのパス> | いいえ | fileListPath |
| Recursively | 入力フォルダーとそのサブフォルダー内のすべてのファイルを再帰的に処理するか、選択したフォルダー内のファイルだけを処理します。 この設定は、1 つのファイルが選択されている場合は無効になります。 | オンまたはオフ | いいえ | recursive: true または false |
| ファイル形式 | ソース データのファイル形式。 さまざまなファイル形式の詳細については、「サポートされている形式」の各記事を参照してください。 | / | はい (ルートフォルダ内のファイルを選択した場合) | / |
| 最終更新日時でフィルター処理 | 最終変更時刻が [開始時刻] から [終了時刻] の範囲内にあるファイルは、さらに処理するためにフィルター処理されます。 時刻は、 yyyy-mm-ddThh:mm:ss.fffZ の形式で UTC タイム ゾーンに適用されます。このプロパティはスキップできます。つまり、ファイル属性フィルターは適用されません。 ファイル パスの種類を [ファイルの一覧] として構成する場合、このプロパティは適用されません。 |
• 開始時刻 • 終了時刻 |
いいえ | modifiedDatetimeStart modifiedDatetimeEnd |
| パーティション検出を有効にする | ファイル パスからパーティションを解析し、それを追加のソース列として追加するかどうかを指定します。 | オンまたはオフ | いいえ | enablePartitionDiscovery: true または false (デフォルト値) |
| パーティションのルート パス | パーティション分割されたフォルダーをデータ列として読み取るパーティションの絶対ルート パス。 | <実際のパーティションのルート パス> | いいえ | partitionRootPath |
| [最大コンカレント接続数] | アクティビティの実行中にデータ ストアに対して確立されたコンカレント接続数の上限。 値は、コンカレント接続数を制限する場合にのみ必要です。 | <最大コンカレント接続数> | いいえ | maxConcurrentConnections |
コピー先の情報
| 名前 | Description | Value | 必須 | JSON スクリプト プロパティ |
|---|---|---|---|---|
| 接続 | 接続を選択するセクション。 | <Lakehouse 接続> | はい | workspaceId artifactId |
| ルート フォルダー | ルート フォルダーの種類。 | • テーブル • ファイル |
はい | rootFolder: テーブルまたはファイル |
| テーブル名 | データを書き込むテーブルの名前。 | <実際のテーブル名> | はい (ルート フォルダー内のテーブルを選択する場合) | テーブル |
| Table | スキーマを接続として Lakehouse に適用するときにデータを書き込むスキーマを含むテーブルの名前。 | <スキーマを含むテーブル> | はい (ルート フォルダー内のテーブルを選択する場合) | / |
| テーブルの場合 | ||||
| スキーマ名 | スキーマの名前です。 | < スキーマ名 > (デフォルトはdbo) |
いいえ | (sink ->datasetSettings ->typeProperties の下)schema |
| table name | テーブルの名前です。 | <実際のテーブル名> | はい | テーブル |
| Table action (テーブル アクション) | 新規値を既存のテーブルに追加するか、新規値を使用してテーブル内の既存のデータとスキーマを上書きします。 | • 追加 • 上書き |
いいえ | tableActionOption: 追加または上書きスキーマ |
| パーティションを有効にする | これを選択すると、1 つまたは複数の列に基づいてフォルダー構造内にパーティションを作成できます。 それぞれの個別の列値 (ペア) が新規パーティションです。 たとえば、"year=2000/month=01/file" などです。 | オンまたはオフ | いいえ | partitionOption: PartitionByKey または None |
| パーティション列 | スキーマ マッピングの変換先列。 | < パーティション列 > | いいえ | partitionNameList |
| ファイル パス | コピー先データ ストアのフォルダーまたはファイルへのパスにデータを書き込みます。 | <file path> | いいえ | • folderPath • fileName |
| ファイル形式 | 送信先データのファイル形式。 さまざまなファイル形式の詳細については、「サポートされている形式」の各記事を参照してください。 | / | はい (ルートフォルダ内のファイルを選択した場合) | / |
| コピー動作 | ソースがファイル ベースのデータ ストアのファイルの場合に定義されるコピー動作。 | • 階層のフラット化 • ファイルのマージ • 階層の保持 • [動的なコンテンツの追加] |
いいえ | copyBehavior: • FlattenHierarchy • MergeFiles • PreserveHierarchy |
| 最大コンカレント接続数 | アクティビティの実行中にデータ ストアに対して確立されたコンカレント接続数の上限。 コンカレント接続を制限する場合にのみ、値を指定します。 | <最大コンカレント接続数> | いいえ | maxConcurrentConnections |
| ブロック サイズ (MB) | Lakehouse にデータを書き込むために使用するブロック サイズ (MB 単位)。 指定できる値は、4 MB から 100 MB です。 | <ブロック サイズ> | いいえ | blockSizeInMB |
| Metadata | コピー先にコピーするときのカスタム メタデータ セット。 | • $$LASTMODIFIED• 式 • 静的な値 |
いいえ | metadata |