クエリからの取り込み (.set、.append、.set-or-append、.set-or-replace)

  • [アーティクル]

これらのコマンドは、クエリまたは管理コマンドを実行し、クエリの結果をテーブルに取り込みます。 これらのコマンドの違いは、既存のテーブルまたは存在しないテーブルとデータを扱う方法です。

コマンド テーブルが存在する場合 テーブルが存在しない場合
.set コマンドは失敗します テーブルが作成され、データは取り込まれます
.append データはテーブルに追加されます コマンドは失敗します
.set-or-append データはテーブルに追加されます テーブルが作成され、データは取り込まれます
.set-or-replace テーブル内のデータはデータによって置き換えられます テーブルが作成され、データは取り込まれます

クエリ コマンドからの取り込みを取り消すには、cancel operation を参照してください。

注意

このインジェスト方法は、探索とプロトタイプ作成を目的としています。 運用環境や大量のシナリオでは使用しないでください。

アクセス許可

テーブルに対してさまざまなアクションを実行するには、特定のアクセス許可が必要です。

  • コマンドを使用して既存のテーブルに行を .append 追加するには、少なくとも Table Ingestor アクセス許可が必要です。
  • さまざまな .set コマンドを使用して新しいテーブルを作成するには、少なくともデータベース ユーザーのアクセス許可が必要です。
  • コマンドを使用して既存のテーブルの行を.set-or-replace置き換えるには、少なくとも Table 管理 権限が必要です。

アクセス許可の詳細については、「 Kusto のロールベースのアクセス制御」を参照してください。

構文

(.set | .set-or-append.set-or-replace.append | | ) [async] tableName [with(propertyName= propertyValue [, ...]] <|)queryOrCommand

構文規則について詳しく知る。

パラメーター

名前 型 必須 説明
async string 指定した場合、コマンドはバックグラウンドでインジェストを返して続行します。 コマンドで返された OperationId を .show operations 使用して、インジェスト完了の状態と結果を取得します。
tableName string ✔️ データを取り込むテーブルの名前。 tableName は、常にコンテキスト内のデータベースに関連付けられます。
propertyName、 propertyValue string インジェスト プロセスの制御に使用される 1 つ以上のサポートされるインジェスト プロパティ。
queryOrCommand string ✔️ 取り込むデータとして結果が使用されるクエリまたは管理コマンドのテキスト。

注意

管理コマンドのみが .show サポートされています。

サポートされるインジェストのプロパティ

プロパティ Type [説明]
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、テーブルで インジェスト時間ポリシー が有効になります。 既定値は、true です。
tags string 作成されたエクステントに関連付ける タグ の一覧を表す JSON 文字列。
docstring string テーブルの文書化に使用される説明。
distributed bool の場合 true、コマンドはクエリを並列で実行しているすべてのノードから取り込みます。 既定値は false です。 パフォーマンスに関するヒントを参照してください。
persistDetails 指定した場合、コマンドが .show 操作 の詳細コマンドによって取得するために詳細な結果を保持する必要があることを示すブール値。 既定値は false です。 with (persistDetails=true)

スキーマに関する考慮事項

  • .set-or-replaceまたは recreate_schema インジェスト プロパティのいずれかが extend_schema にtrue設定されていない限り、スキーマが保持されます。
  • .set-or-append コマンドと .append コマンドは、インジェスト プロパティが extend_schema に設定されていない限り、スキーマを true保持します。
  • 結果セット スキーマとターゲット テーブルのスキーマの照合は、列の種類に基づいています。 列名の照合はありません。 クエリ結果のスキーマ列がテーブルと同じ順序であることを確認します。それ以外の場合は、データが間違った列に取り込まれます。

注意事項

スキーマが変更された場合、実際のデータ インジェストの前に別のトランザクションで行われます。 つまり、データの取り込みに失敗した場合でも、スキーマが変更される可能性があります。

パフォーマンスに関するヒント

  • データの取り込みはリソースを大量に消費する操作であり、クエリの実行など、クラスターでの同時実行アクティビティに影響する可能性があります。 同時に実行するインジェスト コマンドが多くなりすぎないようにしてください。
  • インジェスト操作ごとにインジェストのデータを 1 GB 未満に制限します。 必要に応じて、複数のインジェスト コマンドを使用します。
  • distributedクエリによって生成されるデータの量が大きく、1 GB を超え、シリアル化を必要としない場合は、 フラグを にtrue設定します。 その後、複数のノードが並列で出力を生成できます。 クエリ結果が小さい場合は、このフラグを使用しないでください。これは、多くの小さなデータ シャードを不必要に生成する可能性があるためです。

文字の制限

クエリで 文字を含むエンティティ名が生成された場合、コマンドは $ 失敗します。 エンティティ名は名前付け規則に準拠している必要があるため、ingest コマンドを$成功させるには文字を削除する必要があります。

たとえば、次のクエリでは、 演算子によって 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)

データベースに "OldExtents" という名前の新しいテーブルを作成します。このテーブルには、"extent ID" という 1 つの列があり、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