.ingest into
.ingest into コマンドは、1 つ以上のクラウド ストレージ ファイルからデータを "プル" することによって、テーブルにデータを取り込みます。
たとえば、このコマンドでは、Azure Blob Storage から 1,000 個の CSV 形式の BLOB を取得し、それらを解析し、それらを 1 つのターゲット テーブルにまとめて取り込むことができます。
既存のレコードに影響を与えず、テーブルのスキーマを変更せずに、データがテーブルに追加されます。
手記
このインジェスト方法は、探索とプロトタイプ作成を目的としています。 運用環境や大量のシナリオでは使用しないでください。
手記
このインジェスト方法は、探索とプロトタイプ作成を目的としています。 運用環境や大量のシナリオでは使用しないでください。 インジェスト オプションの詳細については、「データ インジェストの概要」を参照してください。
権限
このコマンドを実行するには、少なくとも Table Ingestor アクセス許可が必要です。
構文
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )] ]
パラメーター
| 名前 | 種類 | 必須 | 形容 |
|---|---|---|---|
async |
string |
指定した場合、コマンドはすぐに戻り、バックグラウンドで取り込みを続行します。 コマンドの結果には、.show operation コマンドで使用してインジェストの完了状態と結果を取得できる OperationId 値が含まれます。 |
|
| TableName を |
string |
✔️ | データを取り込むテーブルの名前。 テーブル名は、コンテキスト内のデータベースに対して常に相対的です。 スキーマ マッピング オブジェクトが指定されていない場合は、コンテキスト内のデータベースのスキーマが使用されます。 |
| SourceDataLocator の |
string |
✔️ |
ストレージ接続文字列の単一またはコンマ区切りのリスト。 1 つの接続文字列は、ストレージ アカウントによってホストされる 1 つのファイルを参照する必要があります。 複数のファイルの取り込みを行うには、複数の接続文字列を指定するか、 |
手記
インジェストプロパティ
大事な
キューインジェストでは、データはインジェストプロパティを使用してバッチ処理されます。 異なる ConstValue 値など、使用されるインジェスト マッピング プロパティが異なるほど、インジェストの断片化が増え、パフォーマンスが低下する可能性があります。
次の表に、サポートされているプロパティの一覧と説明を示し、例を示します。
| 財産 | 形容 | 例 |
|---|---|---|
ingestionMapping |
ソース ファイルからテーブル内の実際の列にデータをマップする方法を示す文字列値。 関連するマッピングの種類を使用して format 値を定義します。 データ マッピング |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")(非推奨: avroMapping、csvMapping、jsonMapping) |
ingestionMappingReference |
名前付きマッピング ポリシー オブジェクトを使用して、ソース ファイルからテーブル内の実際の列にデータをマップする方法を示す文字列値。 関連するマッピングの種類を使用して format 値を定義します。 データ マッピング |
with (format="csv", ingestionMappingReference = "Mapping1")(非推奨: avroMappingReference、csvMappingReference、jsonMappingReference) |
creationTime |
取り込まれたデータ エクステントの作成時に使用する datetime 値 (ISO8601文字列として書式設定)。 指定しない場合は、現在の値 (now()) が使用されます。 保持ポリシーが正しく適用されるように、古いデータを取り込む場合は、既定値をオーバーライドすると便利です。 指定した場合は、ターゲット テーブルの有効な Extents マージ ポリシー の Lookback プロパティが、指定した値に揃っていることを確認します。 |
with (creationTime="2017-02-13") |
extend_schema |
指定した場合、テーブルのスキーマを拡張するようにコマンドに指示するブール値 (既定値は false)。 このオプションは、.append コマンドと .set-or-append コマンドにのみ適用されます。 許可されるスキーマ拡張機能の最後には、テーブルに追加される列が増えています。 |
元のテーブル スキーマが (a:string, b:int)されている場合、有効なスキーマ拡張機能は (a:string, b:int, c:datetime, d:string)されますが、(a:string, c:datetime) は有効ではありません |
folder |
取り込みクエリ コマンドの場合、テーブルに割り当てるフォルダー。 テーブルが既に存在する場合、このプロパティはテーブルのフォルダーをオーバーライドします。 | with (folder="Tables/Temporary") |
format |
データ形式 (サポートされているデータ形式 |
with (format="csv") |
ingestIfNotExists |
指定した場合、テーブルに同じ値を持つ ingest-by: タグでタグ付けされたデータが既に存在する場合、取り込みが成功しないようにする文字列値。 これにより、べき等データ インジェストが保証されます。 詳細については、「取り込み: タグ」を参照してください。 |
with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') プロパティは、タグを持つデータ ingest-by:Part0001 既に存在する場合は、現在のインジェストを完了しないことを示します。 まだ存在しない場合は、この新しいインジェストにこのタグが設定されている必要があります (将来のインジェストが同じデータを再度取り込もうとした場合)。 |
ignoreFirstRecord |
trueに設定されている場合、インジェストはすべてのファイルの最初のレコードを無視する必要があることを示すブール値です。 このプロパティは、ファイル内の最初のレコードが列名である場合に、CSVと同様の形式のファイルに役立ちます。 既定では、false が想定されます。 |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
指定した場合、このコマンドによって作成されたテーブルで インジェスト時間ポリシー を有効にするかどうかを示すブール値。 既定値は trueです。 |
with (policy_ingestiontime=false) |
recreate_schema |
指定した場合、コマンドがテーブルのスキーマを再作成できるかどうかを示すブール値。 このプロパティは、.set-or-replace コマンドにのみ適用されます。 両方が設定されている場合、このプロパティは extend_schema プロパティよりも優先されます。 |
with (recreate_schema=true) |
tags |
JSON 文字列として書式設定された取り込まれたデータに関連付ける タグの一覧 | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
trueに設定されている場合、拡張子が .gz のファイルが圧縮されていないことを示すブール値。 このフラグは、Amazon AWS S3 から取り込むときに必要になることがあります。 |
with (treatGzAsUncompressed=true) |
validationPolicy |
CSV 形式を使用して表されるデータの取り込み中に実行する検証を示す JSON 文字列。 さまざまなオプションの詳細については、「データ インジェストの」を参照してください。 |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (これが既定のポリシー) |
zipPattern |
ZIP アーカイブがあるストレージからデータを取り込む場合は、このプロパティを使用します。 これは、取り込む ZIP アーカイブ内のファイルを選択するときに使用する正規表現を示す文字列値です。 アーカイブ内の他のすべてのファイルは無視されます。 | with (zipPattern="*.csv") |
認証と承認
各ストレージ接続文字列は、ストレージへのアクセスに使用する承認方法を示します。 承認方法によっては、インジェストを実行するために、プリンシパルに外部ストレージに対するアクセス許可を付与する必要がある場合があります。
次の表に、サポートされている認証方法と、外部ストレージからデータを取り込むのに必要なアクセス許可を示します。
| 認証方法 | Azure Blob Storage / Data Lake Storage Gen2 | Data Lake Storage Gen1 |
|---|---|---|
| 偽装 の |
ストレージ BLOB データ 閲覧者 | リーダー |
| Shared Access (SAS) トークン | リスト + 読み取り | この認証方法は Gen1 ではサポートされていません。 |
| Microsoft Entra アクセス トークン を |
||
| ストレージ アカウントのアクセス キー を |
この認証方法は Gen1 ではサポートされていません。 | |
| マネージド ID の |
ストレージ BLOB データ 閲覧者 | リーダー |
収益
コマンドの結果は、コマンドによって生成されるデータ シャード ("エクステント") と同数のレコードを含むテーブルです。 データ シャードが生成されなかった場合は、空の (値が 0 の) エクステント ID で 1 つのレコードが返されます。
| 名前 | 種類 | 形容 |
|---|---|---|
| ExtentId | guid |
コマンドによって生成されたデータ シャードの一意識別子。 |
| ItemLoaded | string |
このレコードに関連する 1 つ以上のストレージ ファイル。 |
| 期間 | timespan |
インジェストの実行にかかった時間。 |
| HasErrors | bool |
このレコードがインジェストエラーを表しているかどうか。 |
| OperationId | guid |
操作を表す一意の ID。
.show operation コマンドで使用できます。 |
手記
このコマンドでは、取り込まれるテーブルのスキーマは変更されません。 必要に応じて、データは取り込み中にこのスキーマに "強制化" されます。逆の方法ではありません (余分な列は無視され、不足している列は null 値として扱われます)。
例
Shared Access Signature を使用した Azure Blob Storage
次の例では、Azure Blob Storage から 2 つの BLOB を CSV ファイルとして読み取り、その内容をテーブル Tに取り込むようデータベースに指示します。
... は、各 BLOB への読み取りアクセスを提供する Azure Storage Shared Access Signature (SAS) を表します。 難読化された文字列 (文字列値の前にある h) は、SAS が記録されないようにするために使用されます。
.ingest into table T (
h'https://contoso.blob.core.windows.net/container/file1.csv?...',
h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)
マネージド ID を使用した Azure Blob Storage
次の例は、マネージド ID 認証を使用して、Azure Blob Storage から CSV ファイルを読み取り、その内容をテーブル T に取り込む方法を示しています。 認証では、Azure の Azure Blob Storage に割り当てられたマネージド ID (オブジェクト ID) が使用されます。 詳細については、「ストレージ コンテナーのマネージド ID を作成する」を参照してください。
.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')
Azure Data Lake Storage Gen 2
次の例は、Azure Data Lake Storage Gen 2 (ADLSv2) からデータを取り込む場合の例です。 ここで使用される資格情報 (...) はストレージ アカウントの資格情報 (共有キー) であり、接続文字列のシークレット部分にのみ文字列難読化を使用します。
.ingest into table T (
'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)
Azure Data Lake Storage
次の例では、Azure Data Lake Storage (ADLS) から 1 つのファイルを取り込みます。 ユーザーの資格情報を使用して ADLS にアクセスします (そのため、ストレージ URI をシークレットを含むものとして扱う必要はありません)。 また、インジェスト プロパティを指定する方法も示します。
.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
with (format='csv')
アクセス キーを持つ Amazon S3
次の例では、アクセス キー ID とシークレット アクセス キーを使用して、Amazon S3 から 1 つのファイルを取り込みます。
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
with (format='csv')
署名済み URL を含む Amazon S3
次の例では、の署名済み URLを使用して、Amazon S3 から 1 つのファイルを取り込みます。
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')
関連コンテンツ
- インジェスト でサポートされているデータ形式の
- .ingest インライン の
- クエリからの取り込みの (.set、.append、.set-or-append、.set-or-replace)
- .show ingestion failures コマンド
- .show インジェスト マッピング