從查詢內嵌 (.set、.append、.set-or-append、.set-or-replace)

  • 發行項

這些命令會執行查詢或管理命令，並將查詢的結果擷取至數據表。 這些命令之間的差異在於它們如何處理現有或不存在的數據表和數據。

命令 如果資料表存在 如果資料表不存在
.set 命令會失敗 建立資料表並內嵌資料
.append 資料會附加至資料表 命令會失敗
.set-or-append 資料會附加至資料表 建立資料表並內嵌資料
.set-or-replace 資料會取代資料表中的資料 建立資料表並內嵌資料

若要從查詢指令取消擷取，請參閱 cancel operation。

注意

此擷取方法適用於探索和原型設計。 請勿在生產或大量案例中使用。

權限

若要對數據表執行不同的動作，需要特定許可權：

  • 若要使用 .append 命令將數據列新增至現有的數據表，您至少需要數據表擷取器許可權。
  • 若要使用各種 .set 命令建立新的資料表，您至少需要資料庫用戶權力。
  • 若要使用 .set-or-replace 命令取代現有資料表中的數據列，您需要至少具有 Table 管理員 許可權。

如需許可權的詳細資訊，請參閱 Kusto 角色型訪問控制。

Syntax

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

深入瞭解 語法慣例。

參數

名稱 類型 必要 描述
async string 如果指定，命令會傳回並繼續在背景中擷取。 使用 搭配 命令傳 OperationId 回的 .show operations ，擷取擷取完成狀態和結果。
tableName string ✔️ 要內嵌數據的數據表名稱。 tableName 一律與內容中的資料庫相關。
propertyName， propertyValue string 一或多個 支援的擷取屬性 ，用來控制擷取程式。
queryOrCommand string ✔️ 查詢或管理命令的文字，其結果會當做擷取的數據使用。

注意

僅 .show 支援管理命令。

支援的擷取屬性

屬性 類型 描述
creationTime string 日期時間值 (格式為 ISO8601 字串)，在建立內嵌資料範圍的時間時使用。 如果未指定， now() 則會使用 。 指定時，請確定 Lookback 目標數據表的有效 Extents 合併原則 中的 屬性與指定的值一致。
extend_schema bool 如果 true為 ，此命令可能會擴充數據表的架構。 預設為 false。 此選項僅適用於 .append、.set-or-append 和 set-or-replace 命令。 此選項至少需要資料表 管理員許可權。
recreate_schema bool 如果 true為 ，命令可能會重新建立數據表的架構。 預設為 false。 此選項僅適用於 .set-or-replace 命令。 如果兩者都已設定， extend_schema 此選項優先於 屬性。 此選項至少需要資料表 管理員許可權。
folder string 要指派給資料表的資料夾。 如果數據表已經存在，這個屬性會覆寫數據表的資料夾。
ingestIfNotExists string 如果指定，則如果數據表已經有具有相同 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 除非其中 extend_schema 一個 或 recreate_schema 擷取屬性設定為 true，否則會保留架構。
  • .set-or-append 和 .append 命令會保留架構， extend_schema 除非擷取屬性設定為 true。
  • 根據數據行類型，比對結果集架構與目標數據表的結果集架構。 沒有相符的資料行名稱。 請確定查詢結果架構數據行的順序與數據表相同，否則數據會擷取到錯誤的數據行。

警告

如果修改架構，則會在實際數據擷取之前，於個別的交易中發生。 這表示即使無法擷取數據，也可以修改架構。

效能秘訣

  • 資料內嵌是需要大量資源的作業，因此可能會影響叢集上的並行活動，包括執行查詢。 避免同時執行太多擷取命令。
  • 將擷取的數據限製為每個擷取作業少於 1 GB。 如有必要，請使用多個擷取命令。
  • distributed如果查詢所產生的數據量很大、超過 1 GB，而且不需要串行化，請將旗標設定為 true 。 然後，多個節點可以平行產生輸出。 當查詢結果很小時，請勿使用此旗標，因為它可能不需要產生許多小型數據分區。

字元限制

如果查詢產生具有 字元的 $ 實體名稱，此命令將會失敗。 實體名稱必須符合命名規則，因此$必須移除字元，才能成功擷取命令。

例如，在下列查詢中， search 運算子會產生資料行 $table。 若要儲存查詢結果，請使用 專案重新命名 來重新命名數據行。

.set Texas <| search State has 'Texas' | project-rename tableName=$table

範例

在資料庫中建立名為 RecentErrors 的新資料表，其架構與 LogsTable 相同且保留過去一小時的所有錯誤記錄。

.set RecentErrors <|
   LogsTable
   | where Level == "Error" and Timestamp > now() - time(1h)

在資料庫中建立名為 "OldExtents" 的新資料表，其具有單一資料行 "ExtentId"，並保留資料庫中已建立超過 30 天的所有範圍的範圍識別碼。 資料庫具有名為 "MyExtents" 的現有資料表。 由於數據集預期大於 1 GB (超過 1 百萬個數據列，) 使用 分散式 旗標

.set async OldExtents with(distributed=true) <|
   MyExtents 
   | where CreatedOn < now() - time(30d)
   | project ExtentId

在目前資料庫中的 "OldExtents" 資料表中附加資料，其具有單一資料行 "ExtentId"，並保留資料庫中已建立超過 30 天的所有範圍的範圍識別碼。 以名為 "MyExtents" 的現有資料表為基礎，使用 tagA 和 tagB 標記來標示新的範圍。

.append OldExtents with(tags='["TagA","TagB"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

將資料附加至目前資料庫中的 "OldExtents" 資料表，或建立資料表 (如果尚未存在的話)。 使用 ingest-by:myTag 標記新的範圍。 只有在資料表尚未包含以 ingest-by:myTag 標記的範圍時，才執行此動作 (以名為 "MyExtents" 的現有資料表為基礎)。

.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