bag_keys

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

Use the bag_keys function in APL to extract the keys of a dynamic (bag) object as an array of strings. This is useful when you want to inspect or manipulate the structure of a dynamic field—such as JSON-like nested objects—without needing to know its exact schema in advance.

Use bag_keys when you’re working with semi-structured data and want to:

• Discover what properties are present in a dynamic object.
• Iterate over the keys programmatically using other array functions.
• Perform validation or debugging tasks to ensure all expected keys exist.

This function is especially helpful in log analytics, observability pipelines, and security auditing, where dynamic properties are often collected from various services or devices.

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 SPL, you typically interact with JSON-like fields using the spath command or use keys(_raw) to retrieve field names. In APL, bag_keys serves a similar purpose by returning an array of keys from a dynamic object.

Splunk example

| eval key_list=keys(data_field)

ANSI SQL users

ANSI SQL doesn’t have native support for dynamic objects or JSON key introspection in the same way. However, some SQL dialects (like PostgreSQL or BigQuery) provide JSON-specific functions for extracting keys. bag_keys is the APL equivalent for dynamically introspecting JSON objects.

SQL example

SELECT JSON_OBJECT_KEYS(data) FROM logs;

Usage

Syntax

bag_keys(bag)

Parameters

Name	Type	Description
bag	dynamic	The dynamic object whose keys you want to extract.

Returns

An array of type string[] containing the names of the keys in the dynamic object. If the input is not a dynamic object, the function returns null.

Use case examples

Log analysis

Use bag_keys to audit dynamic metadata fields in HTTP logs where each record contains a nested object representing additional request attributes.

Query

['sample-http-logs']
| extend metadata = dynamic({ 'os': 'Windows', 'browser': 'Firefox', 'device': 'Desktop' })
| extend key_list = bag_keys(metadata)
| project _time, uri, metadata, key_list

Run in Playground

Output

_time	uri	metadata	key_list
2025-05-26 12:01:23	/login	{os: Windows, browser: Firefox, device: Desktop}	[‘os’, ‘browser’, ‘device’]

This query inspects a simulated metadata object and returns the list of its keys, helping you debug inconsistencies or missing fields.

Use bag_keys to audit dynamic metadata fields in HTTP logs where each record contains a nested object representing additional request attributes.

Query

['sample-http-logs']
| extend metadata = dynamic({ 'os': 'Windows', 'browser': 'Firefox', 'device': 'Desktop' })
| extend key_list = bag_keys(metadata)
| project _time, uri, metadata, key_list

Run in Playground

Output

_time	uri	metadata	key_list
2025-05-26 12:01:23	/login	{os: Windows, browser: Firefox, device: Desktop}	[‘os’, ‘browser’, ‘device’]

This query inspects a simulated metadata object and returns the list of its keys, helping you debug inconsistencies or missing fields.

Use bag_keys to examine custom span attributes encoded as dynamic fields within OpenTelemetry trace events.

Query

['otel-demo-traces']
| extend attributes = dynamic({ 'user_id': 'abc123', 'feature_flag': 'enabled' })
| extend attribute_keys = bag_keys(attributes)
| project _time, ['service.name'], kind, attributes, attribute_keys

Run in Playground

Output

_time	[‘service.name’]	kind	attributes	attribute_keys
2025-05-26 13:14:01	frontend	client	{user_id: abc123, feature_flag: enabled}	[‘user_id’, ‘feature_flag’]

This query inspects the custom span-level attributes and extracts their keys to verify attribute coverage or completeness.

Use bag_keys to list all security-related fields captured dynamically during request monitoring for auditing or compliance.

Query

['sample-http-logs']
| extend security_context = dynamic({ 'auth_status': 'success', 'role': 'admin', 'ip': '192.168.1.5' })
| extend fields = bag_keys(security_context)
| project _time, status, ['geo.country'], security_context, fields

Run in Playground

Output

_time	status	[‘geo.country’]	security_context	fields
2025-05-26 15:32:10	200	US	{auth_status: success, role: admin, ip: 192.168.1.5}	[‘auth_status’, ‘role’, ‘ip’]

This helps you audit security metadata in requests and ensure key fields are present across records.

List of related functions

• bag_pack: Converts a list of key-value pairs to a dynamic property bag. Use when you need to build a bag.
• bag_has_key: Checks whether a dynamic property bag contains a specific key.