• Home
  • Observe and explore
  • Query data
  • Dynatrace Query Language
  • DQL Data types

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
Related topics
  • Dynatrace Query Language

    How to use Dynatrace Query Language.

  • How to use DQL queries

    Find out how DQL works and what are DQL key concepts.

  • DQL compared to SQL and more

    See how DQL compares to other query languages.

  • DQL language reference

    Dynatrace Query Language syntax reference.

  • DQL commands

    A list of DQL commands.

  • DQL functions

    A list of DQL Functions.

  • DQL operators

    A list of DQL Operators.

  • DQL Best practices

    Best practices for using Dynatrace Query Language.