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