ensure_field

You typically use ensure_field when working with schemaless or evolving data where fields might be absent, or when you want to write queries that handle missing fields gracefully without errors.

Usage#

Syntax#

ensure_field(field_name, field_type)

Parameters#

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 that matches the specified type.

Use case examples#

Log analysisOpenTelemetry traces

Handle missing fields gracefully when analyzing HTTP logs where some fields might not be present in all records.

Query

['sample-http-logs']
| extend user_agent = ensure_field('user_agent', typeof(string))
| extend referer = ensure_field('referer', typeof(string))
| where isnotnull(user_agent) or isnotnull(referer)
| project _time, ['uri'], user_agent, referer

Run in Playground

Output

_time	uri	user_agent	referer
Jun 24, 09:28:10	/api/users	Mozilla/5.0	https://example.com

This example safely accesses optional fields that may not exist in all log records, allowing the query to run successfully even when some fields are missing.

Access optional trace attributes that might not be present in all spans.

Query

['otel-demo-traces']
| extend http_method = ensure_field('http.method', typeof(string))
| extend http_path = ensure_field('http.path', typeof(string))
| where ['kind'] == 'server'
| project _time, ['trace_id'], ['service.name'], http_method, http_path

Run in Playground

Output

_time	trace_id	service.name	http_method	http_path
Jun 24, 09:28:10	abc123	frontend	GET	/api/users

This example safely accesses optional HTTP attributes in trace data, ensuring the query works even when these attributes are not present in all spans.

isnull: Checks if a value is null. Use isnull to test the result of ensure_field to determine if a field exists.
isnotnull: Checks if a value isn't null. Use isnotnull to verify that ensure_field successfully retrieved a field value.
coalesce: Returns the first non-null value from a list. Use coalesce with ensure_field to provide default values when fields are missing.

Other query languages#

Splunk SPL users

In Splunk, you can use if expressions with isnull or check field existence with isnull(field). In APL, ensure_field provides a more type-safe way to handle missing fields by returning a typed nil that matches the expected field type.

Splunk example

... | eval status = if(isnull(status_code), null(), status_code)

APL equivalent

... | extend status = ensure_field('status_code', typeof(string))

ANSI SQL users

In standard SQL, you use COALESCE or ISNULL functions to handle missing values, but these don't check for field existence. In APL, ensure_field checks if a field exists and returns a typed nil if it doesn't, allowing you to write queries that work with optional fields.

SQL example

SELECT COALESCE(optional_field, NULL) AS field_value FROM logs;