Conversion and casting functions

Latest Dynatrace
Reference

Conversion functions convert the expression or value from one data type to another type.

Converting data types

Functions prefixed with as(Type) ensure that a value is of a target type. If the data type is incompatible, they return null. These functions are applicable after parsing.

...
| parse content, "LD'DQL 'KVP{LD:key'='(LONG:valueLong| BOOLEAN:valueBoolean| [!;]*:valueStr)';'?}:q"
| fields timestamp, asLong(q[workTime])

Casting input data type to the target data type matrix

The as*T will try to cast the input to T but won't perform any conversions, it will cause an exception for strongly typed fields (marked as ) and null for incompatible data types (empty cell).

asT(arg) => if(typeOf(arg) == ’T’, arg)

as*T	asNumber	asRecord
`Integer`	`Integer`
`Long`	`Long`
`Double`	`Double`
`String`
`Boolean`
`Timestamp`
`Duration`
`Timeframe`
`Geopoint`
`IpAddress`
`Binary`
`Array`
`Record`
`V<Integer>`	`V<Integer>`
`V<Long>`	`V<Long>`
`V<Double>`	`V<Double>`
`V<String>`
`V<Boolean>`
`V<Timestamp>`
`V<Duration>`
`V<Timeframe>`
`V<Geopoint>`
`V<IpAddress>`
`V<SummaryStats>`
`V<Binary>`
`V<Array>`
`V<Record>`		`V<Record>`

asArray

Returns array value if the value is array, otherwise, returns null.

Syntax

asArray(value)

Parameters

Returns

The data type of the returned value is array.

Examples

Example 1

data record(a = array(2, 3, 7, 7, 1)),
     record(a = "DQL is awesome!"),
     record(a = 3.14)
| fieldsAdd type(a), asArray(a)

Query result:

a	type(a)	asArray(a)
`[2, 3, 7, 7, 1]`	`array`	`[2, 3, 7, 7, 1]`
`DQL is awesome!`	`string`	null
`3.14`	`double`	null

asBinary

Returns binary value (byte array) if the value is binary, otherwise, returns null.

Syntax

asBinary(value)

Parameters

Returns

The data type of the returned value is binary.

Examples

Example 1

data record(a = 3.14),
     record(a = "dynatrace"),
     record(a = true),
     record(a = decodeBase64ToBinary("ZHluYXRyYWNl"))
| fieldsAdd type(a), asBinary(a)

Query result:

a	type(a)	asBinary(a)
`3.14`	`double`	null
`dynatrace`	`string`	null
`true`	`boolean`	null
`ZHluYXRyYWNl`	`binary`	`ZHluYXRyYWNl`

asBoolean

Returns boolean value if the value is boolean, otherwise, returns null.

Syntax

asBoolean(value)

Parameters

Returns

The data type of the returned value is boolean.

Examples

Example 1

data record(a = true),
     record(a = "true"),
     record(a = 1)
| fieldsAdd type(a), asBoolean(a)

Query result:

asDouble

Returns double value if the value is double, otherwise, returns null.

Syntax

asDouble(value)

Parameters

Returns

The data type of the returned value is double.

Examples

Example 1

data record(a = 3),
     record(a = 3.14),
     record(a = "3.14")
| fieldsAdd type(a), asDouble(a)

Query result:

asDuration

Returns duration value if the value is duration, otherwise, returns null.

Syntax

asDuration(value)

Parameters

Returns

The data type of the returned value is duration.

Examples

Example 1

data record(a = 15s),
     record(a = 3.14),
     record(a = timeframe(from: "2019-08-01T09:30:00.000-0400", to: "2019-08-01T16:00:00.000-0400")),
     record(a = "42"),
     record(a = "42s")
| fieldsAdd type(a), asDuration(a)

Query result:

a	type(a)	asDuration(a)
`15 s`	`duration`	`15 s`
`3.14`	`double`	null
start: `2019-08-01T13:30:00.000Z` end: `2019-08-01T20:00:00.000Z`	`timeframe`	null
`42`	`string`	null
`42s`	`string`	null

asIp

You can use this function to cast to an IP address.

Syntax

asIp(expression)

Parameters

Returns

The data type of the returned value is ip.

Examples

Example 1

data record(a = ip("127.0.0.1")),
     record(a = "10.0.0.1")
| fieldsAdd type(a), asIp(a)

Query result:

asLong

Returns long value if the value is long, otherwise null.

Syntax

asLong(value)

Parameters

Returns

The data type of the returned value is long.

Examples

Example 1

data record(a = 3),
     record(a = 3.14),
     record(a = "3")
| fieldsAdd type(a), asLong(a)

Query result:

asNumber

Returns the same value if the value is integer, long, double, otherwise, returns null.

Syntax

asNumber(value)

Parameters

Returns

The data type of the returned value is double or long.

Examples

Example 1

data record(a = 3),
     record(a = 3.14),
     record(a = "3.14")
| fieldsAdd type(a), asNumber(a)

Query result:

asRecord

Returns record value if the value is record, otherwise, returns null.

Syntax

asRecord(value)

Parameters

Returns

The data type of the returned value is record.

Examples

Example 1

data record(a = record(b = 3)),
     record(a = 3.14),
     record(a = "3"),
     record(a = array(2, 3, 7, 7, 1))
| fieldsAdd type(a), asRecord(a)

Query result:

a	type(a)	asRecord(a)
b: `3`	`record`	b: `3`
`3.14`	`double`	null
`3`	`string`	null
`[2, 3, 7, 7, 1]`	`array`	null

asString

Returns string value if the value is string, otherwise, returns null.

Syntax

asString(value)

Parameters

Returns

The data type of the returned value is string.

Examples

Example 1

data record(a = array(1, 2, 3)),
     record(a = 3.14),
     record(a = "DQL is awesome!"),
     record(a = record(content = "A nested record"))
| fieldsAdd type(a), asString(a)

Query result:

a	type(a)	asString(a)
`[1, 2, 3]`	`array`	null
`3.14`	`double`	null
`DQL is awesome!`	`string`	`DQL is awesome!`
content: `A nested record`	`record`	null

asTimeframe

Returns timeframe value if the value is timeframe, otherwise returns null.

Syntax

asTimeframe(value)

Parameters

Returns

The data type of the returned value is timeframe.

Examples

Example 1

data record(timeframe = timeframe(from: "2019-08-01T09:30:00.000-0400", to: "2019-08-01T16:00:00.000-0400")),
     record(timeframe = timeframe(from: - 24h, to: - 2h)),
     record(timeframe = "2019-08-01T15:30:00.000-0400/2019-08-01T22:00:00.000-0400")
| fieldsAdd type(timeframe), asTimeframe(timeframe)

Query result:

asTimestamp

Returns timestamp value if the value is timestamp, otherwise, returns null.
Alternatively use the toTimestamp function to convert a long, double or string value to a value of type timestamp.

Syntax

asTimestamp(value)

Parameters

Returns

The data type of the returned value is timestamp.

Examples

Example 1

data record(timestamp = timestamp(2019, 8, 1, 13, 30, 0)),
     record(timestamp = 1564666200000000000),
     record(timestamp = "2019-08-01T09:30:00.000-0400")
| fieldsAdd type(timestamp), asTimestamp(timestamp)

Query result:

asUid

Returns a uid value if the value is uid, otherwise returns null.

Syntax

asUid(value)

Parameters

Returns

The data type of the returned value is uid.

Examples

Example 1

data record(a = uid64(123)), record(a = 123)
| fields asUid(a)

Query result:

decode

The decode function allows encoding binary data and strings into a string representation, and the opposite way. There are two types of decode functions, BASE64 and BASE16.

Syntax

decodeBase64ToBinary(expression)
decodeBase64ToString(expression)
decodeBase16ToBinary(expression)
decodeBase16ToString(expression)

Parameters

Returns

The data type of the returned value is binary or string.

Examples

Example 1

data record(content = "RFFMIGlzIGF3ZXNvbWUh"),
     record(content = "RHluYXRyYWNlIFF1ZXJ5IExhbmd1YWdl")
| fieldsAdd decodeBase64ToString(content)

Query result:

Example 2

data record(content = "44514c20697320617765736f6d6521"),
       record(content = "44796e617472616365205175657279204c616e6775616765")
| fieldsAdd decodeBase16ToString(content)

Query result:

encode

The encode function allows encoding binary data and strings into a string representation, and the opposite way. There are two types of encode functions, BASE64 and BASE16.

Syntax

encodeBase64(expression)
encodeBase16(expression)

Parameters

Returns

The data type of the returned value is string.

Examples

Example 1

data record(content = "DQL is awesome!"),
     record(content = "Dynatrace Query Language")
| fieldsAdd encodeBase16(content),
            encodeBase64(content)

Query result:

getHighBits

Extracts the most significant bits of an expression. It accepts uid or ip expression types. For all other types, it returns null.

Syntax

getHighBits(expression)

Parameters

Returns

The data type of the returned value is long.

Examples

Example 1

data record(a = uid64(123)),
     record(a = uid128(123, 456)),
     record(a = uuid(123, 456)),
	   record(a = ip("127.0.0.1")),
	   record(a = ip("192.168.0.1")),
     record(a = ip("2001:0db8:0000:0000:0000:8a2e:0370:7334")),
     record(a = ip("::1")),
	   record(a = 1),
	   record(a = true),
	   record(a = "foo")
| fields a, getHighBits(a)

Query result:

getLowBits

Extracts the least significant bits of an expression. It accepts uid or ip expression types. For all other types, it returns null.

Syntax

getLowBits(expression)

Parameters

Returns

The data type of the returned value is long.

Examples

Example 1

data record(a = uid64(123)),
     record(a = uid128(123, 456)),
     record(a = uuid(123, 456)),
	   record(a = ip("127.0.0.1")),
	   record(a = ip("192.168.0.1")),
     record(a = ip("2001:0db8:0000:0000:0000:8a2e:0370:7334")),
     record(a = ip("::1")),
	   record(a = 1),
	   record(a = true),
	   record(a = "foo")
| fields a, getLowBits(a)

Query result:

hexStringToNumber

Converts a hexadecimal string to a number.

Syntax

hexStringToNumber(expression)

Parameters

Returns

The data type of the returned value is double or long.

Examples

Example 1

data record(a = "0x7f"),
     record(a = "100"),
     record(a = "0X80000000")
| fieldsAdd hexStringToNumber(a)

Query result:

isUid128

Tests if a uid value is of subtype uid128.

Syntax

isUid128(expression)

Parameters

Returns

The data type of the returned value is boolean.

Examples

Example 1

data record(a = uid64(123)),
     record(a = toUid("000000000000007c")),
     record(a = uid128(123, 456)),
     record(a = toUid("000000000000007c00000000000001c8")),
     record(a = uuid(123, 456)),
     record(a = toUid("00000000-0000-007c-0000-0000000001c8"))
| fieldsAdd isUid128(a)

Query result:

isUid64

Tests if a uid value is of subtype uid64.

Syntax

isUid64(expression)

Parameters

Returns

The data type of the returned value is boolean.

Examples

Example 1

data record(a = uid64(123)),
     record(a = toUid("000000000000007c")),
     record(a = uid128(123, 456)),
     record(a = toUid("000000000000007c00000000000001c8")),
     record(a = uuid(123, 456)),
     record(a = toUid("00000000-0000-007c-0000-0000000001c8"))
| fieldsAdd isUid64(a)

Query result:

isUuid

Tests if a uid value is of subtype uuid.

Syntax

isUuid(expression)

Parameters

Returns

The data type of the returned value is boolean.

Examples

Example 1

data record(a = uid64(123)),
     record(a = toUid("000000000000007c")),
     record(a = uid128(123, 456)),
     record(a = toUid("000000000000007c00000000000001c8")),
     record(a = uuid(123, 456)),
     record(a = toUid("00000000-0000-007c-0000-0000000001c8"))
| fieldsAdd isUuid(a)

Query result:

numberToHexString

Converts a number to a hexadecimal string.

Syntax

numberToHexString(expression)

Parameters

Returns

The data type of the returned value is string.

Examples

Example 1

data record(a = 127),
     record(a = 256),
     record(a = 2147483648)
| fieldsAdd numberToHexString(a)

Query result:

toArray

Returns the value if it is an array. Otherwise, converts a value to the single element array holding that value.

Syntax

toArray(value)

Parameters

Returns

The data type of the returned value is array.

Examples

Example 1

data record(a = array(2, 3, 7, 7, 1)),
     record(a = "DQL is awesome!"),
     record(a = 3.14)
| fieldsAdd type(a), toArray(a)

Query result:

toBoolean

Converts a value to Boolean if the value is of a suitable type. If the argument is an array, the element at position 0 is converted.

Use asBoolean(value) function to return if the value is boolean or variant<boolean>, otherwise null.

Converts string values true or TRUE to a Boolean true.The comparison is case insensitive. Converts other values to Boolean false. Converts numeric value 0 to Boolean false. Converts other numeric values to Boolean true.

Syntax

toBoolean(value)

Parameters

Returns

The data type of the returned value is boolean.

Examples

Example 1

data record(a = true),
     record(a = "true"),
     record(a = "yes"),
     record(a = 0),
     record(a = 1),
     record(a = 2)
| fieldsAdd type(a), toBoolean(a)

Query result:

toDouble

Converts a value to double if the value is of a suitable type. If the argument is an array, the element at position 0 is converted.

Use asDouble(value) function to return if the value is double or variant<double>, otherwise null.

Syntax

toDouble(value)

Parameters

Returns

The data type of the returned value is double.

Examples

Example 1

data record(a = 3),
     record(a = 3.14),
     record(a = "3.14"),
     record(a = true),
     record(a = toTimestamp("2019-08-01T09:30:00.000-0400")),
     record(a = 15s),
     record(a = ip("10.0.0.1"))
| fieldsAdd type(a), toDouble(a)

Query result:

toDuration

Converts a value to duration if the value is of a suitable type. If the argument is an array, the element at position 0 is converted.

Syntax

toDuration(value)

Parameters

Returns

The data type of the returned value is duration.

Examples

Example 1

data record(a = 15s),
     record(a = 3.14),
     record(a = timeframe(from: "2019-08-01T09:30:00.000-0400", to: "2019-08-01T16:00:00.000-0400")),
     record(a = "42"),
     record(a = "42s")
| fieldsAdd type(a), toDuration(a)

Query result:

toIp

You can use this function to convert an expression to an IP address.

Syntax

toIp(expression)

Parameters

Returns

The data type of the returned value is ip.

Examples

Example 1

data record(a = ip("127.0.0.1")),
     record(a = "10.0.0.1"),
     record(a = "300.0.0.1"),
     record(a = 1234567890)
| fieldsAdd type(a), toIp(a)

Query result:

toLong

Converts a value to long if the value is of a suitable type. If the argument is an array, the element at position 0 is converted.

Syntax

toLong(value)

Parameters

Returns

The data type of the returned value is long.

Examples

Example 1

data record(a = 3),
     record(a = 3.14),
     record(a = "3"),
     record(a = true),
     record(a = false),
     record(a = ip("10.0.0.1")),
     record(a = 15s),
     record(a = toTimestamp("2019-08-01T09:30:00.000-0400"))
| fieldsAdd type(a), toLong(a)

Query result:

toString

Returns the string representation of a value.

Syntax

toString(value)

Parameters

Returns

The data type of the returned value is string.

Examples

Example 1

data record(a = array(1, 2, 3)),
     record(a = true),
     record(a = 3),
     record(a = 3.14),
     record(a = 5m),
     record(a = toIp("127.0.0.1")),
     record(a = "DQL is awesome!"),
     record(a = timeframe(from: now() - 5m, to: now())),
     record(a = toTimestamp("2019-08-01T09:30:00.000-0400")),
     record(a = record(content = "A nested record"))
| fieldsAdd type(a), toString(a)

Query result:

toTimeframe

Converts a value to timeframe if the value is of a suitable type. If the argument is an array, the element at position 0 is converted.

Syntax

toTimeframe(value)

Parameters

Returns

The data type of the returned value is timeframe.

Examples

Example 1

data record(timeframe = timeframe(from: "2019-08-01T09:30:00.000-0400", to: "2019-08-01T16:00:00.000-0400")),
     record(timeframe = timeframe(from: - 24h, to: - 2h)),
     record(timeframe = "2019-08-01T09:30:00.000-0400/2019-08-01T16:00:00.000-0400")
| fieldsAdd type(timeframe), toTimeframe(timeframe)

Query result:

toTimestamp

Converts a value to timestamp if the value is of a suitable type. If the argument is an ARRAY, the element at position 0 is converted.

Use asTimestamp(<value>) function to return if the value is timestamp or variant<timestamp>, otherwise null.

Syntax

toTimestamp(value)

Parameters

Returns

The data type of the returned value is timestamp.

Examples

Example 1

data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400")),
     record(timestamp = 1564666200000000000),
     record(timestamp = "2019-08-01T09:30:00.000-0400")
| fieldsAdd type(timestamp), toTimestamp(timestamp)

Query result:

toUid

Converts a value to uid if the value is of a suitable type.

Syntax

toUid(value)

Parameters

Returns

The data type of the returned value is uid.

Examples

Example 1

data record(a = "550e8400-e29b-41d4-a716-446655440000", b = 123, c = uid64(456), d=array(123))
| fields toUid(a), toUid(b), toUid(c), toUid(d)

Query result:

type

Returns the type of a value as a string.

Syntax

type(expression [, withSubtype])

Parameters

Returns

The data type of the returned value is string.

Examples

Example 1

data record(a = array(1, 2, 3)),
     record(a = true),
     record(a = 3),
     record(a = 3.14),
     record(a = 5m),
     record(a = toIp("127.0.0.1")),
     record(a = toIp("2001:0db8:0000:0000:0000:8a2e:0370:7334")),
     record(a = "DQL is awesome!"),
     record(a = timeframe(from: now() - 5m, to: now())),
     record(a = toTimestamp("2019-08-01T09:30:00.000-0400")),
     record(a = record(content = "A nested record")),
     record(a = uid64(123)),
     record(a = uid128(123, 456)),
     record(a = uuid(123, 456))
| fieldsAdd type(a), type(a, withSubtype:true)

Query result:

uid128

Creates a uid of subtype uid128 from two long expressions.

Syntax

uid128(mostSignificantBits, leastSignificantBits)

Parameters

Returns

The data type of the returned value is uid.

Examples

Example 1

data record(a = 123, b = 456)
| fields uid128(a, b)

Query result:

uid64

Creates a uid of subtype uid64 from a long expression.

Syntax

uid64(expression)

Parameters

Returns

The data type of the returned value is uid.

Examples

Example 1

data record(a = 123)
| fields uid64(a)

Query result:

uuid

Creates a uid of subtype uuid from two long expressions.

Syntax

uuid(mostSignificantBits, leastSignificantBits)

Parameters

Returns

The data type of the returned value is uid.

Examples

Example 1

data record(a = 123, b = 456)
| fields uuid(a, b)

Query result:

smartscapeId

Preview

Creates a smartscapeId from the given string and long expression.

Syntax

smartscapeId(type, numericId)

Parameters

Returns

The data type of the returned value is smartscapeId.

Examples

Example 1

data record(a = "HOST", b = 123)
| fields smartscapeId(a, b)

Query result:

asSmartscapeId

Preview

Returns smartscapeId value if the value is smartscapeId, otherwise returns null.

Syntax

asSmartscapeId(value)

Parameters

Returns

The data type of the returned value can be smartscapeId or null.

Examples

Example 1

data record(a = "SERVICE-00590715D82398FE"),
     record(a = toSmartscapeId("SERVICE-00590715D82398FE")),
     record(a = 1)
| fieldsAdd type(a), asSmartscapeId(a)

Query result:

toSmartscapeId

Preview

Converts a value to smartscapeId if the value is of a suitable type. If the argument is an array, only the element at position 0 is converted.

Syntax

toSmartscapeId(value)

Parameters

Returns

The data type of the returned value is smartscapeId.

Examples

Example 1

data record(a = "SERVICE-02E04D7E459555EC", b = array("DISK-000392498B505BD0"))
| fields toSmartscapeId(a), toSmartscapeId(b)

Query result: