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 atrue
Boolean value, and other values tofalse
. - Converts numeric value
0
to Booleanfalse
. Converts other numeric values to Booleantrue
.
...| fields toBoolean("true"), toBoolean("TrUe"), toBoolean("1"), toBoolean(3), toBoolean("test"), toBoolean(0) - Converts string values
-
Expressions
boolean_expr1 AND boolean_expr2boolean_expr1 OR boolean_expr2boolean_expr1 XOR boolean_expr2NOT 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
to9223372036854775807
hexadecimal:0x0
to0xFFFFFFFFFFFFFFFF
-
Converting to Long
..| fields toLong("83457264009472472"), toLong(30), toLong(25.34)
Double
Double-precision 64-bit IEEE 754 floating point.
-
Literal notation
decimal:
2.34
scientific:2.4e2
-
Converting to Double
Converts numeric values and expressions to a double value....| 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:
fetch logs, from:-2h, to:-20m
Functions and comparison
...| fields time = toTimestamp("2022-08-01T12:00:00+01:00")| fieldsAdd time == now(), time > now()-10d, newTime = time + 3d
Timeframe
A specific time frame with a start time and an end time as timestamps with nanosecond precision. To execute the full query result including nanoseconds, change the visualization of the data in Notebooks to raw.
data record(tf = timeframe(from:now()-2h, to:now()))| fields tf, tf[start], tf[end]
Duration
A duration between two timestamps, consisting of an amount and a time unit.
...| 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.
...| fields dur = 62| fieldsAdd dur_ms = duration(dur, unit:"ms")| fieldsAdd dur_ms > 50ms
Converting to duration
Converting a nanoseconds value to a duration
:
......| 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.
......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:...| fields toString(toBoolean(1)), toString(array(1,2,3)), toString(1), toString(toTimestamp(now())), 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
...| 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....| ...| 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:...| fields person = record({name="john", age=33, address=record({city="Atlanta", pcode="30308"})})| fields person[name], person[address][pcode] -
Converting to RECORD
The functionrecord(expression,...)
converts one or more expressions returning any data type toRECORD
:...| fields t = record(a=1+2,b=3,c=toString(timestamp))ParsingParsing JSON or key-value pair strings results in
RECORD
data.STRUCTURE{matcher_expr, ...}:fieldnameJSON{matcher_expr, ...}:fieldnameKVP{matcher_expr, ...}:fieldname$subpattern:fieldname -
Parsing Key-value pair data
...| 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
...| fields str = "{\"type\":\"update\",\"host\":\"CI_preprod_1\",\"version\":\"10.2.2367\"}"| parse str,"JSON:event"| fields event[type], event[host], event[version]