使用 版本 下拉選單切換服務。 了解更多關於導航的資訊。
適用於： ✅ Microsoft Fabric ✅ Azure Data Explorer
這些命令會執行查詢或管理命令，並將查詢的結果內嵌到數據表中。 這些命令之間的差異在於它們如何處理現有或不存在的數據表和數據。
| Command | 如果數據表存在 | 如果數據表不存在 |
|---|---|---|
.set |
命令失敗了。 | 資料表會建立並被匯入資料。 |
.append |
資料會附加在表格上。 | 命令失敗了。 |
.set-or-append |
資料會附加在表格上。 | 資料表會建立並被匯入資料。 |
.set-or-replace |
資料取代了表格中的資料。 | 資料表會建立並被匯入資料。 |
若要取消從查詢命令擷取，請參閱 cancel operation。
注意
從查詢擷取是 直接擷取。 因此，它不包含自動重試。 透過數據管理服務擷取時，可以使用自動重試。
權限
要在表格上執行不同動作，你需要特定的權限：
- 若要使用
.append命令將數據列新增至現有的數據表，您需要最少的數據表擷取器許可權。 - 若要使用各種
.set命令建立新的資料表，您至少需要資料庫用戶權力。 - 若要使用
.set-or-replace命令取代現有資料表中的數據列，您需要最少的數據表管理員許可權。
如需許可權的詳細資訊，請參閱 Kusto 角色型訪問控制。
語法
（.set | .append | .set-or-append | .set-or-replace） [async] with [( ...]] =
深入瞭解 語法慣例。
參數
| 姓名 | 類型 | 必要 | 描述 |
|---|---|---|---|
| async | string |
如果指定，命令會立即傳回，並繼續在背景中擷取。 使用 搭配 命令傳 OperationId 回的 .show operations 來擷取擷取完成狀態和結果。 |
|
| tableName | string |
✔️ | 要內嵌數據之數據表的名稱。 tableName 一律與內容中的資料庫相關。 |
| propertyName、 propertyValue | string |
一或多個 支援的擷取屬性 ，用來控制擷取程式。 | |
| queryOrCommand | string |
✔️ | 查詢或管理命令的文字，其結果會做為擷取的數據。 僅 .show 支援管理命令。 |
效能祕訣
- 若查詢產生的資料量大、超過 1 GB，且不需要序列化，則設定
distributedtrue屬性為 然後，多個節點可以平行產生輸出。 當查詢結果很小時，請勿使用此旗標，因為它可能會不必要地產生許多小型數據分區。 - 數據擷取是資源密集型作業，可能會影響資料庫上的並行活動，包括執行查詢。 避免同時執行太多擷取命令。
- 每次資料擷取操作限制在少於 1 GB。 如有必要，請使用多個擷取命令。
支援的擷取屬性
| 屬性 | 類型 | 描述 |
|---|---|---|
distributed |
bool |
如果 true為 ，則命令會從所有平行執行查詢的節點擷取。 預設值為 false。 請參閱 效能秘訣。 |
creationTime |
string |
datetime該值以ISO8601string格式化，於擷取資料區段建立時使用。 如果未指定， 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，表格上啟用了 Addestion Time Policy 。 預設值為 true。 |
tags |
string |
一個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
退貨
傳回因為 或 .set 命令而.append建立的範圍資訊。
範例
從查詢來源建立並更新資料表
以下查詢會建立與 相同結構RecentErrors的表格。LogsTable 它會更新 RecentErrors 過去一小時內的所有錯誤日誌 LogsTable 。
.set RecentErrors <|
LogsTable
| where Level == "Error" and Timestamp > now() - time(1h)
利用 分散 式旗標從查詢來源建立並更新資料表
以下範例在資料庫中建立一個非同步呼叫 OldExtents 的新資料表。 資料集預期會大於 1 GB（超過 ~100 萬列），因此採用 分散 式旗標。 它會更新OldExtentsExtentId超過 30 天前建立的表格條目MyExtents。
.set async OldExtents with(distributed=true) <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
將資料附加到表格
以下範例篩選ExtentId超過 30 天前建立的表格MyExtents條目，並附加相關標籤。OldExtents
.append OldExtents with(tags='["TagA","TagB"]') <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
建立或附加一個包含可能已標記資料的資料表
以下範例會非同步地附加於該表格或建立該 OldExtents 表格。 它會過濾 ExtentId 超過 30 天前建立的表格條 MyExtents 目，並指定要附加到新區段 ingest-by:myTag的標籤。 這個 ingestIfNotExists 參數確保只有在資料表中尚未包含指定標籤的資料時，才會進行擷取。
.set-or-append async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
建立表格或以相關資料取代資料
以下查詢會替換表格中的OldExtents資料，或如果表格尚未存在，則建立ExtentIdMyExtents超過 30 天前建立的資料。 如果資料表中還沒有該標籤，就用該標籤標記新的範圍 ingest-by:myTag 。
.set-or-replace async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
將資料附加於相關資料
以下範例以非同步方式將資料附加到 OldExtents 資料表，使用 ExtentId 超過 30 天前建立的資料 MyExtents 表條目。 它會為新擴展設定特定的建立時間。
.append async OldExtents with(creationTime='2017-02-13T11:09:36.7992775Z') <|
MyExtents
| where CreatedOn < now() - time(30d)
| project ExtentId
範例輸出
以下是您可能從查詢中看到的輸出類型範例。
| ExtentId | OriginalSize | ExtentSize | CompressedSize | IndexSize | RowCount |
|---|---|---|---|---|---|
| 23a05ed6-376d-4119-b1fc-6493bcb05563 | 1291 | 5882 | 1568 | 4314 | 10 |