Conversion functions

Learn how to use and combine different conversion functions in APL

Conversion functions

Function Name	Description
ensure_field()	Ensures the existence of a field and returns its value or a typed nil if it doesn’t exist.
tobool()	Converts input to boolean (signed 8-bit) representation.
todatetime()	Converts input to datetime scalar.
todouble(), toreal()	Converts the input to a value of type real. todouble() and toreal() are synonyms.
tostring()	Converts input to a string representation.
totimespan()	Converts input to timespan scalar.
tohex()	Converts input to a hexadecimal string.
tolong()	Converts input to long (signed 64-bit) number representation.
dynamic_to_json()	Converts a scalar value of type dynamic to a canonical string representation.
isbool()	Returns a value of true or false if the expression value is passed.
toint()	Converts the input to an integer value (signed 64-bit) number representation.

ensure_field()

Ensures the existence of a field and returns its value or a typed nil if it doesn’t exist.

Arguments

name	type	description
field_name	string	The name of the field to ensure exists.
field_type	type	The type of the field. See scalar data types for supported types.

Returns

This function returns the value of the specified field if it exists, otherwise it returns a typed nil.

Examples

ensure_field(field_name, field_type)

Handle missing fields

In this example, the value of show_field is nil because the myfield field doesn’t exist.

['sample-http-logs']
| extend show_field = ensure_field("myfield", typeof(string))

Run in Playground

Access existing fields

In this example, the value of newstatus is the value of status because the status field exists.

['sample-http-logs']
| extend newstatus = ensure_field("status", typeof(string))

Run in Playground

Future-proof queries

In this example, the query is prepared for a field named upcoming_field that is expected to be added to the data soon. By using ensure_field(), logic can be written around this future field, and the query will work when the field becomes available.

['sample-http-logs']
| extend new_field = ensure_field("upcoming_field", typeof(int))
| where new_field > 100

tobool()

Converts input to boolean (signed 8-bit) representation.

Arguments

• Expr: Expression that will be converted to boolean.

Returns

• If conversion is successful, result will be a boolean. If conversion isn’t successful, result will be false

Examples

tobool(Expr)

toboolean(Expr) (alias)

tobool("true") == true

Run in Playground

• Result:

{
  "conversion_function": true
}

todatetime()

Converts input to datetime scalar.

Arguments

• Expr: Expression that will be converted to datetime.

Returns

If the conversion is successful, the result will be a datetime value. Else, the result will be false.

Examples

todatetime(Expr)

todatetime("2022-11-13")

Run in Playground

• Result

{
  "boo": "2022-11-13T00:00:00Z"
}

todouble(), toreal()

Converts the input to a value of type real. (todouble() is an alternative word to toreal())

Arguments

• Expr: An expression whose value will be converted to a value of type real.

Returns

If conversion is successful, the result is a value of type real. If conversion is not successful, the result returns false.

Examples

toreal(Expr)todouble(Expr)

toreal("1567") == 1567

Run in Playground

• Result:

{
  "conversion_function": true
}

tostring()

Converts input to a string representation.

Arguments

• Expr: Expression that will be converted to string.

Returns

If the Expression value is non-null, the result will be a string representation of the Expression. If the Expression value is null, the result will be an empty string.

Examples

tostring(Expr)

tostring(axiom) == "axiom"

Run in Playground

• Result:

{
  "conversion_function": "axiom"
}

totimespan

Converts input to timespan scalar.

Arguments

• Expr: Expression that will be converted to timespan.

Returns

If conversion is successful, result will be a timespan value. Else, result will be false.

Examples

totimespan(Expr)

Run in Playground

• Result

{
  "conversion_function": "1.998µs"
}

tohex()

Converts input to a hexadecimal string.

Arguments

• Expr: int or long value that will be converted to a hex string. Other types are not supported.

Returns

If conversion is successful, result will be a string value. If conversion is not successful, result will be false.

Examples

tohex(value)

tohex(-546) == 'fffffffffffffdde'

tohex(546) == '222'

Run in Playground

• Result:

{
  "conversion_function": "fffffffffffffdde"
}

tolong()

Converts input to long (signed 64-bit) number representation.

Arguments

• Expr: Expression that will be converted to long.

Returns

If conversion is successful, result will be a long number. If conversion is not successful, result will be false.

Examples

tolong(Expr)

tolong("241") == 241

Run in Playground

• Result:

{
  "conversion_function": 241
}

dynamic_to_json()

Converts a scalar value of type dynamic to a canonical string representation.

Arguments

• dynamic input (EXpr): The function accepts one argument.

Returns

Returns a canonical representation of the input as a value of type string, according to the following rules:

• If the input is a scalar value of type other than dynamic, the output is the app of tostring() to that value.

• If the input in an array of values, the output is composed of the characters [, ,, and ] interspersed with the canonical representation described here of each array element.

• If the input is a property bag, the output is composed of the characters {, ,, and } interspersed with the colon (:)-delimited name/value pairs of the properties. The pairs are sorted by the names, and the values are in the canonical representation described here of each array element.

Examples

dynamic_to_json(dynamic)

['sample-http-logs']
| project conversion_function = dynamic_to_json(dynamic([1,2,3]))

Run in Playground

• Result:

{
  "conversion_function": "[1,2,3]"
}

isbool()

Returns a value of true or false if the expression value is passed.

Arguments

• Expr: The function accepts one argument. The variable of expression to be evaluated.

Returns

Returns true if expression value is a bool, false otherwise.

Examples

isbool(expression)

isbool("pow") == false

Run in Playground

• Result:

{
  "conversion_function": false
}

---

toint()

Converts the input to an integer value (signed 64-bit) number representation.

Arguments

• Value: The value to convert to an integer.

Returns

If the conversion is successful, the result will be an integer. Otherwise, the result will be null.

Examples

toint(value)

| project toint("456") == 456

Run in Playground