ensure_field

This page explains how to use the ensure_field function in APL.

Use the ensure_field function to safely access a field that may or may not exist in your data. The function returns the field’s value if it exists, or a typed nil if it doesn’t. This helps you write queries that work even when fields are missing, making your queries more robust and future-proof.

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.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

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)

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;

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 analysis

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.

OpenTelemetry traces

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.

List of related functions

• 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 is not 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.