The dynamic data type

Note:

* 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 literals

A literal of type dynamic looks like this:

dynamic( Value )

Value can be:

• null, in which case the literal represents the null dynamic value: dynamic(null).
• Another scalar data type literal, in which case the literal represents the dynamic literal of the "inner" type. For example, dynamic(4) is a dynamic value holding the value 4 of the long scalar data type.
• An array of dynamic or other literals: [ ListOfValues ]. For example, dynamic([1, 2, "hello"]) is a dynamic array of three elements, two long values and one string value.
• A property bag: { Name = Value ... }. For example, dynamic({"a":1, "b":{"a":2}}) is a property bag with two slots, a, and b, with the second slot being another property bag.

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

For convenience, dynamic literals that appear in the query text itself may also include other Kusto literals with types: datetime, timespan, real, long, guid, bool, and dynamic. This extension over JSON isn't available when parsing strings (such as when using the parse_json function or when ingesting data), but it enables you to do the following:

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

To parse a string value that follows the JSON encoding rules into a dynamic value, use the parse_json function. For example:

• parse_json('[43, 21, 65]') - an array of numbers
• parse_json('{"name":"Alan", "age":21, "address":{"street":432,"postcode":"JLK32P"}}') - a dictionary
• parse_json('21') - a single value of dynamic type containing a number
• parse_json('"21"') - a single value of dynamic type containing a string
• parse_json('{"a":123, "b":"hello", "c":[1,2,3], "d":{}}') - gives the same value as o in the example above.

// 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!""}"]

Dynamic object accessors

To subscript a dictionary, use either the dot notation (dict.key) or the brackets notation (dict["key"]). When the subscript is a string constant, both options are equivalent.

To use an expression as the subscript, use the brackets notation. When using arithmetic expressions, the expression inside the brackets must be wrapped in parentheses.

In the examples below dict and arr are columns of dynamic type:

Performance tip:

Prefer to use constant subscripts when possible

Accessing a sub-object of a dynamic value yields another dynamic value, even if the sub-object has a different underlying type. Use the gettype function to discover the actual underlying type of the value, and any of the cast function listed below to cast it to the actual type.

Casting dynamic objects

After subscripting a dynamic object, you must cast the value to a simple type.

Cast functions are:

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

Building dynamic objects

Several functions enable you to create new dynamic objects:

• zip() pairs "parallel" values from two arrays into a single array.

Additionally, there are several aggregate functions which create dynamic arrays to hold aggregated values:

• make_list() returns an array holding all values, in sequence.
• make_list_if() returns an array holding all values, in sequence (with a predicate).
• make_list_with_nulls() returns an array holding all values, in sequence, including null values.
• make_set() returns an array holding all unique values.
• make_set_if() returns an array holding all unique values (with a predicate).

Operators and functions over dynamic types

For a complete list of scalar dynamic/array functions, see dynamic/array functions.

Indexing for dynamic data

Every field is indexed during data ingestion. The scope of the index is a single data shard.

To index dynamic columns, the ingestion process enumerates all “atomic” elements within the dynamic value (property names, values, array elements) and forwards them to the index builder. Otherwise, dynamic fields have the same inverted term index as string fields.