GitHub GitHub: 線上編輯

動態資料類型

dynamic 純量資料類型是特殊的，因為它可以採用下列清單中其他純量資料類型的任何值，以及陣列和內容工具袋。 具體而言， dynamic 值可以是:

  • 空值。
  • 任何初始純量資料類型的值: bool、 datetime、 guid、 int、 long、 real、 string及 timespan。
  • dynamic 值的陣列，使用以零為基礎的索引來保留零個以上值。
  • 將唯一 string 值對映至 dynamic 值的內容工具袋。 內容工具袋具有零或多個此類對映 (稱為 "slots") ，由唯一 string 值編製索引。 插槽未排序。

附註：

* Values of type `dynamic` are limited to 1MB (2^20), uncompressed.

* Although the `dynamic` type appears JSON-like, it can hold values that the JSON
model does not represent because they don't exist in JSON (e.g.,
`long`, `real`, `datetime`, `timespan`, and `guid`).

Therefore, in serializing `dynamic` values into a JSON representation, values that JSON can't represent
are serialized into `string` values. Conversely, KQL will parse strings
as strongly-typed values if they can be parsed as such.
This applies for `datetime`, `real`, `long`, and `guid` types.
For more about the JSON object model, see [json.org](https://json.org/).

* KQL doesn't attempt to preserve the order of name-to-value mappings in
a property bag, and so you can't assume the order to be preserved. It's entirely
possible for two property bags with the same set of mappings to yield different
results when they are represented as `string` values, for example.

動態文字

dynamic 類型的文字看起來如下:

dynamic( 值 )

值 可以是:

  • null，在此情況下，文字代表空值動態值: dynamic(null)。
  • 另一個純量資料類型文字，在此情況下，文字代表「內部」類型的 dynamic 文字。 例如， dynamic(4) 是一個動態值，保留長純量資料類型的值 4。
  • 動態或其他文字的陣列: [ ListOf值 ]。 例如， dynamic([1, 2, "hello"]) 是由三個元素組成的動態陣列，兩個 long 值和一個 string 值。
  • 內容工具袋: { 名稱 = 值 ... }。 例如， dynamic({"a":1, "b":{"a":2}}) 是具有兩個插槽 ( a和 b) 的內容工具袋，第二個插槽是另一個內容工具袋。
print o=dynamic({"a":123, "b":"hello", "c":[1,2,3], "d":{}})
| extend a=o.a, b=o.b, c=o.c, d=o.d

為了方便起見，查詢文字本身中出現的 dynamic 文字也可能包括具有下列類型的其他 Kusto 文字: datetime、 timespan、 real、 long、 guid、 bool及 dynamic。 剖析字串時 (例如使用 parse_json 函數或汲取資料時) ，無法使用 JSON 的這項延伸，但它可讓您執行下列動作:

print d=dynamic({"a": datetime(1970-05-11)})

若要將遵循 JSON 編碼規則的 string 值剖析為 dynamic 值，請使用 parse_json 函數。 例如：

  • parse_json('[43, 21, 65]') -數字陣列
  • parse_json('{"name":"Alan", "age":21, "address":{"street":432,"postcode":"JLK32P"}}') -字典
  • parse_json('21') -包含數字之動態類型的單一值
  • parse_json('"21"') -包含字串之動態類型的單一值
  • parse_json('{"a":123, "b":"hello", "c":[1,2,3], "d":{}}') -提供與上述範例中 o 相同的值。

附註：

與 JavaScript不同， JSON 會強制在字串和內容工具袋內容名稱周圍使用雙引號 ( ") 字元。 因此，通常更容易使用單引號 (') 字元來引用 JSON 編碼的字串文字。

下列範例顯示如何定義表格來保留 dynamic 直欄 (以及 datetime 直欄) ，然後汲取單一記錄。 它也示範如何將 CSV 檔中的 JSON 字串編碼:

// dynamic is just like any other type:
.create table Logs (Timestamp:datetime, Trace:dynamic)

// Everything between the "[" and "]" is parsed as a CSV line would be:
// 1. Since the JSON string includes double-quotes and commas (two characters
//    that have a special meaning in CSV), we must CSV-quote the entire second field.
// 2. CSV-quoting means adding double-quotes (") at the immediate beginning and end
//    of the field (no spaces allowed before the first double-quote or after the second
//    double-quote!)
// 3. CSV-quoting also means doubling-up every instance of a double-quotes within
//    the contents.
.ingest inline into table Logs
  [2015-01-01,"{""EventType"":""Demo"", ""EventValue"":""Double-quote love!""}"]

結果

時間戳記 追蹤
2015 -01-01 00:00:00.0000000 {"EventType":"Demo","EventValue":"Double-quote love!"}

動態物件存取元

若要為字典下標，請使用帶點表示法 (dict.key) 或方括弧表示法 (dict["key"])。 當下標是字串常數時，兩個選項都是相等的。

若要使用表示式作為下標，請使用方括弧表示法。 使用算術表示式時，方括弧內的表示式必須以括弧括住。

在下列範例中， dict 和 arr 是動態類型的直欄:

表示式 存取元表示式類型 意義 註解
dict [col] 實體名稱 (直欄) 使用直欄 col 的值作為索引鍵為字典下標 直欄必須是字串類型
arr [index] 實體索引 (直欄) 使用直欄 index 的值作為索引為陣列下標 直欄必須是整數或布林類型
arr [-index] 實體索引 (直欄) 從陣列結尾擷取 'index'-th 值 直欄必須是整數或布林類型
arr [(-1)] 實體索引 擷取陣列中的最後一個值
arr [toint (indexAsString)] 功能呼叫 將直欄 indexAsString 的值強制轉型為 int ，並使用它們來為陣列下標
dict [['where']] 用作實體名稱 (直欄) 的關鍵字 使用直欄 where 的值作為索引鍵為字典下標 必須以引號括住與部分查詢語言關鍵字相同的實體名稱
dict. ['where'] 或 dict ['where'] 常數 使用 where 字串作為索引鍵為字典下標

效能提示:

可能的話，偏好使用常數下標

存取 dynamic 值的子物件會產生另一個 dynamic 值，即使子物件具有不同的基礎類型也一樣。 使用 gettype 函數來探索值的實際基礎類型，以及下列任何強制轉型函數將它強制轉型為實際類型。

強制轉型動態物件

在訂閱動態物件之後，您必須將值強制轉型成簡式類型。

表示式 值 類型
X parse_json ('[100,101,102]') array
X [0] parse_json ('100') dynamic
toint (X [1]) 101 INT
Y parse_json ('{"a1":100, "a b c":"2015-01-01"}') 字典
Y.a1 parse_json ('100') dynamic
Y ["a b c"] parse_json ("2015 -01-01") dynamic
todate (Y ["a b c"]) datetime (2015 -01-01) 日期時間

強制轉型函數如下:

  • tolong()
  • todouble()
  • todatetime()
  • totimespan()
  • tostring()
  • toguid()
  • todynamic()

建置動態物件

數個功能可讓您建立新的 dynamic 物件:

  • zip () 會將兩個陣列中的「平行」值配對成單一陣列。

此外，還有數個聚集函數會建立 dynamic 陣列來保留聚集值:

動態類型的運算子和函數

如需純量動態/陣列函數的完整清單，請參閱 動態/陣列函數。

運算子或函數 動態資料類型的用法
value in 陣列 如果有 array 的元素 == value
where City in ('London', 'Paris', 'Rome') ，則為 True
value !in 陣列 如果沒有 array 的元素 == value ，則為 True
array_length(陣列) 如果不是陣列，則為空值
bag_keys(工具袋) 列舉動態內容工具袋物件中的所有根索引鍵。
bag_merge(bag1,...,bagN) 將動態內容工具袋合併成動態內容工具袋，並合併所有內容。
extractjson(路徑，物件) 使用路徑來導覽至物件。
parse_json(來源) 將 JSON 字串轉換成動態物件。
range(從、到、步驟) 值的陣列
mv-expand listColumn 針對指定資料格中清單的每一個值抄寫一列。
summarize buildschema(直欄) 從直欄內容推斷類型綱目
summarize make_bag(直欄) 將直欄中的內容工具袋 (字典) 值合併成一個內容工具袋，沒有索引鍵重複。
summarize make_bag_if(直欄，述詞) 將直欄中的內容工具袋 (字典) 值合併成一個內容工具袋，沒有索引鍵重複 (含述詞)。
summarize make_list(直欄) 壓縮列群組，並將直欄值放入陣列中。
summarize make_list_if(直欄，述詞) 壓縮列群組並將直欄值放入陣列中 (含述詞)。
summarize make_list_with_nulls(直欄) 壓縮列群組並將直欄值放入陣列中，包括空值。
summarize make_set(直欄) 將列群組平面化，並將直欄值放置在陣列中，沒有重複。

動態資料的索引

在資料吸收期間，每個欄位都會編製索引。 索引的範圍是單一資料 Shard。

為了檢索動態直欄，汲取程序會列舉動態值內的所有 "atomic" 元素 (內容名稱、值、陣列元素) ，並將它們轉遞至索引建置器。 否則，動態欄位與字串欄位具有相同的顛倒術語索引。