クエリからの取り込み (.set、.append、.set-or-append、.set-or-replace)
これらのコマンドは、クエリまたは管理コマンドを実行し、クエリの結果をテーブルに取り込みます。 これらのコマンドの違いは、既存または存在しないテーブルとデータを扱う方法です。
| command | テーブルが存在する場合 | テーブルが存在しない場合 |
|---|---|---|
.set |
コマンドは失敗します | テーブルが作成され、データは取り込まれます |
.append |
データはテーブルに追加されます | コマンドは失敗します |
.set-or-append |
データはテーブルに追加されます | テーブルが作成され、データは取り込まれます |
.set-or-replace |
テーブル内のデータはデータによって置き換えられます | テーブルが作成され、データは取り込まれます |
クエリ コマンドからの取り込みを取り消すには、cancel operation を参照してください。
Note
クエリからの取り込みは、 方向のインジェストです。 そのため、自動再試行は含まれません。 自動再試行は、データ管理サービスを介して取り込むときに使用できます。 ingestion の概要ドキュメントを使用して、シナリオに最適なインジェスト オプションを決定します。
アクセス許可
テーブルに対して異なるアクションを実行するには、特定のアクセス許可が必要です。
.appendコマンドを使用して既存のテーブルに行を追加するには、最小限の Table Ingestor アクセス許可が必要です。- さまざまな
.setコマンドを使用して新しいテーブルを作成するには、最小限のデータベース ユーザーアクセス許可が必要です。 .set-or-replaceコマンドを使用して既存のテーブル内の行を置き換えるには、最小限のテーブル管理者アクセス許可が必要です。
アクセス許可の詳細については、「 Kusto ロールベースのアクセス制御を参照してください。
構文
(.set | .append | .set-or-append | .set-or-replace) [async] tableName [with (propertyName = propertyValue [, ...])] <| queryOrCommand
構文規則について詳しく知る。
パラメーター
| 件名 | タイプ | Required | 説明 |
|---|---|---|---|
| async | string |
指定した場合、コマンドはすぐに戻り、バックグラウンドで取り込みを続行します。 .show operations コマンドで返されたOperationIdを使用して、インジェストの完了状態と結果を取得します。 |
|
| tableName | string |
✔️ | データを取り込むテーブルの名前。 tableNameは、常にコンテキスト内のデータベースに関連付けられます。 |
| propertyName, propertyValue | string |
1 つ以上の サポートされるインジェスト プロパティ インジェスト プロセスの制御に使用されます。 | |
| queryOrCommand | string |
✔️ | 取り込むデータとして結果が使用されるクエリまたは管理コマンドのテキスト。 .show管理コマンドのみがサポートされています。 |
パフォーマンスに関するヒント
- クエリによって生成されるデータの量が大きく、1 GB を超え、シリアル化を必要としない場合は、
distributedプロパティをtrueに設定します。 その後、複数のノードが並列で出力を生成できます。 クエリ結果が小さい場合は、このフラグを使用しないでください。これは、多数の小さなデータ シャードを不必要に生成する可能性があるためです。 - データ インジェストは、クエリの実行など、データベース上の同時アクティビティに影響する可能性がある、リソースを集中的に使用する操作です。 同時に実行するインジェスト コマンドが多くなりすぎないようにします。
- インジェスト操作ごとにインジェストのデータを 1 GB 未満に制限します。 必要に応じて、複数のインジェスト コマンドを使用します。
サポートされるインジェストのプロパティ
| プロパティ | タイプ | 説明 |
|---|---|---|
distributed |
bool |
true場合、コマンドはクエリを並列で実行しているすべてのノードから取り込みます。 既定値は false です。 パフォーマンス ヒントを参照してください。 |
creationTime |
string |
取り込まれたデータ エクステントの作成時刻に使用する datetime 値 (ISO8601 文字列の形式)。 指定しない場合は now() が使用されます。 指定する場合、ターゲット テーブルの有効なエクステント マージ ポリシーの Lookback プロパティが、指定した値と整合していることを確認します。 |
extend_schema |
bool |
true場合、コマンドによってテーブルのスキーマが拡張される可能性があります。 既定値は false です。 このオプションは、.append、.set-or-append、set-or-replace コマンドにのみ適用されます。 このオプションには、少なくとも Table 管理者 アクセス許可が必要です。 |
recreate_schema |
bool |
true場合、コマンドはテーブルのスキーマを再作成できます。 既定値は false です。 このオプションは、.set-or-replace コマンドにのみ適用されます。 両方が設定されている場合、このオプションは extend_schema プロパティよりも優先されます。 このオプションには、少なくとも Table 管理者 アクセス許可が必要です。 |
folder |
string |
テーブルに割り当てるフォルダー。 テーブルが既に存在する場合、このプロパティはテーブルのフォルダーを上書きします。 |
ingestIfNotExists |
string |
指定した場合、テーブルに同じ値の ingest-by: タグでタグ付けされたデータが既に存在する場合、インジェストは失敗します。 詳細については、ingest-by: タグに関する記事を参照してください。 |
policy_ingestiontime |
bool |
true場合、テーブルで Ingestion 時間ポリシーが有効になります。 既定値は、true です。 |
tags |
string |
作成されたエクステントに関連付ける タグ の一覧を表す JSON 文字列。 |
docstring |
string |
テーブルの文書化に使用する説明。 |
persistDetails |
指定した場合、コマンドが .show 操作の詳細 コマンドで取得するための詳細な結果を保持する必要があることを示すブール値。 既定値は false です。 |
with (persistDetails=true) |
スキーマに関する考慮事項
.set-or-replaceは、extend_schemaまたはrecreate_schemaインジェストプロパティのいずれかがtrueに設定されていない限り、スキーマを保持します。.set-or-appendextend_schemaインジェスト プロパティがtrueに設定されていない限り、.appendコマンドはスキーマを保持します。- 結果セット スキーマとターゲット テーブルのスキーマの照合は、列の種類に基づいています。 列名の照合はありません。 クエリ結果のスキーマ列がテーブルと同じ順序であることを確認します。それ以外の場合は、データが間違った列に取り込まれます。
注意事項
スキーマが変更された場合、実際のデータ インジェストの前に別のトランザクションで発生します。 つまり、データの取り込みエラーが発生した場合でも、スキーマが変更される可能性があります。
文字制限
クエリで $ 文字を持つエンティティ名が生成された場合、コマンドは失敗します。 名は名前付け規則に準拠している必要があるため、取り込みコマンドを成功させるには$文字を削除する必要があります。
たとえば、次のクエリでは、 search 演算子によって列 $tableが生成されます。 クエリ結果を格納するには、 project-rename を使用して列の名前を変更します。
.set Texas <| search State has 'Texas' | project-rename tableName=$table
例
LogsTable と同じスキーマを持ち、過去 1 時間のすべてのエラー レコードを保持する RecentErrors という名前の新しいテーブルをデータベースに作成します。
.set RecentErrors <|
LogsTable
| where Level == "Error" and Timestamp > now() - time(1h)
"ExtentId" という 1 つの列を持つデータベースに "OldExtents" という名前の新しいテーブルを作成し、30 日以上前に作成されたデータベース内のすべてのエクステントのエクステント ID を保持します。 データベースには、"MyExtents" という名前の既存のテーブルがあります。 データセットは 1 GB (約 100 万行を超える) を超えると予想されるため、 分散 フラグを使用します
.set async OldExtents with(distributed=true) <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
現在のデータベース内の "OldExtents" という名前の既存のテーブルにデータを追加します。このテーブルには、"extent ID" という 1 つの列があり、30 日よりも前に作成されたデータベース内のすべてのエクステントのエクステント ID が保持されます。
"MyExtents" という名前の既存のテーブルに基づいて、タグ tagA と tagB を使用して新しいエクステントにマークします。
.append OldExtents with(tags='["TagA","TagB"]') <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
現在のデータベース内の "OldExtents" テーブルにデータを追加するか、テーブルがまだ存在しない場合は作成します。 新しいエクステントに ingest-by:myTag を使用してタグを付けます。 これは、"MyExtents" という名前の既存のテーブルに基づいて、ingest-by:myTag を使用してタグ付けされたエクステントがテーブルにまだ存在しない場合にのみ行います。
.set-or-append async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
現在のデータベース内の "OldExtents" テーブルのデータを置き換えるか、テーブルがまだ存在しない場合は作成します。 新しいエクステントに ingest-by:myTag を使用してタグを付けます。
.set-or-replace async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
エクステントの作成時間を過去の特定の日時に設定しながら、現在のデータベースの "OldExtents" テーブルにデータを追加します。
.append async OldExtents with(creationTime='2017-02-13T11:09:36.7992775Z') <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
出力を返す
.set または .append コマンドによって作成されたエクステントに関する情報を返します。
出力例
| ExtentId | OriginalSize | ExtentSize | CompressedSize | IndexSize | RowCount |
|---|---|---|---|---|---|
| 23a05ed6-376d-4119-b1fc-6493bcb05563 | 1291 | 5882 | 1568 | 4314 | 10 |