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.
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 isn’t a dynamic object, the function returns null.
Use case examples
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_listOutput
| _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_keysOutput
| _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, fieldsOutput
| _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.