DQL data types

The Dynatrace Query Language operates with strongly typed data: the functions and operators accept only declared types of data. The type is assigned to data during parsing or by using casting functions. DQL also recognizes value types expressed in literal notation (for example, using constant values in functions).

Primitive types

Boolean

Boolean has only two possible values: true and false.

Literal notation
A Boolean value can be expressed using either uppercase or lowercase letters: true, TRUE, false, FALSE
Converting to Boolean
- Converts string values true, TRUE to a true Boolean value, and other values to false.
- Converts numeric value 0 to Boolean false. Converts other numeric values to Boolean true.
```
dql
...
| fields toBoolean("true"), toBoolean("TrUe"), toBoolean("1"), toBoolean(3), toBoolean("test"), toBoolean(0)
```

Expressions

plaintext
boolean_expr1 AND boolean_expr2
boolean_expr1 OR boolean_expr2
boolean_expr1 XOR boolean_expr2
NOT boolean_expr

Long

The signed long has a minimum value of -2^63 and a maximum value of 2^63-1.

Literal notation
LONG can be expressed in decimal or hexadecimal notation:
decimal: -9223372036854775808 to 9223372036854775807
hexadecimal: 0x0 to 0xFFFFFFFFFFFFFFFF

Converting to Long

dql
..
| fields toLong("83457264009472472"), toLong(30), toLong(25.34)

Double

Double-precision 64-bit IEEE 754 floating point.

Literal notation
Enclose data elements, separated by commas, in square brackets:
decimal: [2.0, -4.44]
scientific: 2.4e2
Converting to Long
Converts numeric values and expressions to a double value.
```
dql
...
| fields toDouble("1234.5"), toDouble(4+3/2)
```

Timestamp

A reference to a point in time with the precision of a nanosecond.

The primary usage for time expressions is the specification of a custom query timeframe in the DQL query string:

dql
fetch logs, from:-2h, to:-20m

Functions and comparison

dql
...
| fields time = toTimestamp("2022-08-01T12:00:00+01:00")
| fieldsAdd time == now(), time > now()-10d, newTime = time + 3d

Duration

A duration between two timestamps, consisting of an amount and a time unit.

dql
...
| fields duration = 1s

Time literals

The following time literals can be used to express durations:

ns: Nanoseconds
ms: Milliseconds
s: Seconds
m: Minutes
h: hours
d: Days

Creating a duration

In many cases, a parsed numeric value semantically represents a duration. The duration() function allows the creation of a field of type duration with the intended unit using the available time literals.

dql
...
| fields     dur = 62
| fieldsAdd  dur_ms = duration(dur, unit:"ms")
| fieldsAdd  dur_ms > 50ms

Converting to duration

Converting a nanoseconds value to a duration:

dql
...
...
| fields     dur = toDuration(62*1000000000*60*60*24)
| fieldsAdd  dur > 60d

Converting the period between timestamp1 and timestamp2 to a duration:

To illustrate, we calculate the age of the latest log message seen from a specific host.

dql
...
...
fetch       logs
| filter    dt.entity.host == "HOST-DD5679D1A0C6426C"
| sort      timestamp desc
| limit     1
| fields    timestamp, age_message = now()-timestamp

String

Sequence of characters with a specified character set.

Literal notation
Enclose the string in double quotes. Escape double quote in the string with a backslash \ if needed. A string can contain single quotes.
Optionally, you can enclose strings in triple quotes, such as """someString""".
- Inside triple quotes, no escaping is necessary.
- Triple quotes are not allowed as part of the string. In such a scenario, you can use the standard strings or the concat function.

Converting to String
All DQL datatypes can be converted to a string:

dql
...
| fields toString(toBoolean(1)), toString(array(1,2,3)), toString(1), toString(toTimestamp(now())), toString(toVariant(1)), toString(toIpAddress("192.168.0.1"))

IpAddress

Represents an IPv4 or IPv6 address.

Complex types

Array

A data structure that contains a sequence of values, each identified by index.

Accessing array elements

dql
...
| fieldsAdd int_array = array(1,2,2,3,4,5)
| fields first_element = int_array[0], fifth_element = int_array[4]

Comparing arrays
Only the equals operator == can be directly used on arrays.

dql
...
| ...
| fields a=array(1,2), b=array(1,2,3), c=array("a","b"), d=toArray("c,d")
| fields a == b, arraySize(b) > arraySize(c)

See the complete list of DQL array functions for further information.

Record

A set of key-value pair data whose value can be any DQL data type.

Accessing RECORD Elements
Data elements can be accessed by the key:

dql
...
| fields person = record({name="john", age=33, address=record({city="Atlanta", pcode="30308"})})
| fields person[name], person[address][pcode]

Converting to RECORD
The function record(expression,...) converts one or more expressions returning any data type to RECORD:

dql
...
| fields t = record(a=1+2,b=3,c=toString(timestamp))

Parsing

Parsing JSON or key-value pair strings results in RECORD data.

dql
STRUCTURE{matcher_expr, ...}:fieldname
JSON{matcher_expr, ...}:fieldname
KVP{matcher_expr, ...}:fieldname
$subpattern:fieldname

Parsing Key-value pair data

dql
...
| fields str = "name=\"john\"; age=33; city=\"Atlanta\""
| parse str, "KVP{LD:key'='(LONG:valueLong | STRING:valueStr)'; '?}:person"
| fields person[name], person[age], person[city]

Parsing JSON data

dql
...
| fields str = "{\"type\":\"update\",\"host\":\"CI_preprod_1\",\"version\":\"10.2.2367\"}"
| parse str,"JSON:event"
| fields event[type], event[host], event[version]

Variant<T>

Data type is evaluated dynamically at runtime. Variant can represent any of the primitive data types.

Sometimes the type of an extracted data element is not known before the parser is run. For instance, JSON structures also contain the type of data that could be used for extraction. In this case, the parser uses the VARIANT type to capture extracted data elements.

Parsing JSON object
Parsing the JSON object {"name":"John","age":33}, the resulting name and age fields will have the VARIANT type.

dql
| fields str = "{\"name\":\"John\",\"age\":33}"
| parse str, "JSON:person"
| fieldsAdd type(person[name]), type(person[age])

VARIANT processing

VARIANT fields have to be cast into the respective primitive types before further processing.

dql
| fields str = "{\"name\":\"John\",\"age\":33}"
| parse str, "JSON:person"
| fieldsAdd older_than_30 = toLong(person[age]) > 30