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.
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.
... | extend status = ensure_field('status_code', typeof(string))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.
['sample-http-logs']
| extend field_value = ensure_field('optional_field', typeof(string))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
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, refererOutput
| _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_pathOutput
| _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
isnullto test the result ofensure_fieldto determine if a field exists. - isnotnull: Checks if a value is not null. Use
isnotnullto verify thatensure_fieldsuccessfully retrieved a field value. - coalesce: Returns the first non-null value from a list. Use
coalescewithensure_fieldto provide default values when fields are missing.