從查詢擷取 （.set、 .append、 .set-or-append、 .set-or-replace）
適用於： ✅Microsoft網狀架構✅Azure 數據總管
這些命令會執行查詢或管理命令，並將查詢的結果內嵌到數據表中。 這些命令之間的差異在於它們如何處理現有或不存在的數據表和數據。
| Command | 如果數據表存在 | 如果數據表不存在 |
|---|---|---|
.set |
命令失敗 | 建立數據表並內嵌數據 |
.append |
數據會附加至數據表 | 命令失敗 |
.set-or-append |
數據會附加至數據表 | 建立數據表並內嵌數據 |
.set-or-replace |
數據會取代數據表中的數據 | 建立數據表並內嵌數據 |
若要取消從查詢命令擷取，請參閱 cancel operation。
權限
若要在資料表上執行不同的動作，需要特定許可權：
- 若要使用
.append命令將數據列新增至現有的數據表，您需要最少的數據表擷取器許可權。 - 若要使用各種
.set命令建立新的資料表，您至少需要資料庫用戶權力。 - 若要使用
.set-or-replace命令取代現有資料表中的數據列，您需要最少的數據表管理員許可權。
如需許可權的詳細資訊，請參閱 Kusto 角色型訪問控制。
語法
（.set.append.set-or-replace | | .set-or-append | ） [async] tableName [with( propertyName = propertyValue [, ...]] <| )queryOrCommand
深入瞭解 語法慣例。
參數
| 姓名 | 類型 | 必要 | 描述 |
|---|---|---|---|
| async | string |
如果指定，命令會立即傳回，並繼續在背景中擷取。 使用 搭配 命令傳 OperationId 回的 .show operations 來擷取擷取完成狀態和結果。 |
|
| tableName | string |
✔️ | 要內嵌數據之數據表的名稱。 tableName 一律與內容中的資料庫相關。 |
| propertyName、 propertyValue | string |
一或多個 支援的擷取屬性 ，用來控制擷取程式。 | |
| queryOrCommand | string |
✔️ | 查詢或管理命令的文字，其結果會做為擷取的數據。 僅 .show 支援管理命令。 |
效能祕訣
distributed如果查詢所產生的數據量很大，且超過 1 GB，而且不需要串行化，請將 屬性true設定為 。 然後，多個節點可以平行產生輸出。 當查詢結果很小時，請勿使用此旗標，因為它可能會不必要地產生許多小型數據分區。- 數據擷取是資源密集型作業，可能會影響資料庫上的並行活動，包括執行查詢。 避免同時執行太多擷取命令。
- 將擷取的數據限製為每個擷取作業少於 1 GB。 如有必要，請使用多個擷取命令。
支援的擷取屬性
| 屬性 | 類型 | 描述 |
|---|---|---|
distributed |
bool |
如果 true為 ，則命令會從所有平行執行查詢的節點擷取。 預設值為 false。 請參閱 效能秘訣。 |
creationTime |
string |
格式化為ISO8601字串的 datetime 值，在擷取的數據範圍建立時間使用。 如果未指定， now() 則會使用 。 指定時，請確定目標資料表的有效範圍合併原則中的 Lookback 屬性與指定的值一致。 |
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 |
用來記錄數據表的描述。 |
persistDetails |
布爾值，如果指定，表示命令應該保存詳細的結果，以供 .show 作業詳細數據命令擷取。 預設為 false。 |
with (persistDetails=true) |
架構考慮
.set-or-replace除非其中一個extend_schema或recreate_schema擷取屬性設定為true，否則會保留架構。.set-or-append和.append命令會保留架構，extend_schema除非擷取屬性設定為true。- 比對結果集架構與目標數據表的結果集架構是以數據行類型為基礎。 數據行名稱沒有相符專案。 請確定查詢結果架構數據行的順序與數據表相同，否則數據會內嵌到錯誤的數據行中。
警告
如果修改架構，則會在實際數據擷取之前，在不同的交易中發生。 這表示即使無法擷取數據，也可能修改架構。
字元限制
如果查詢產生具有 字元的實體名稱， $ 則命令會失敗。 實體名稱必須符合命名規則，因此$必須移除字元，才能成功擷取命令。
例如，在下列查詢中， search 運算子會產生資料行 $table。 若要儲存查詢結果，請使用 project-rename 來重新命名數據行。
.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」 的現有數據表，使用標籤tagAtagB新的範圍。
.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
傳回輸出
傳回因為 或 .append 命令而.set建立的範圍資訊。
範例輸出
| ExtentId | OriginalSize | ExtentSize | CompressedSize | IndexSize | RowCount |
|---|---|---|---|---|---|
| 23a05ed6-376d-4119-b1fc-6493bcb05563 | 1291 | 5882 | 1568 | 4314 | 10 |