Axiom
Overview

bag_keys

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_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.

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

Other query languages#

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)

APL equivalent

datatable(data: dynamic)
[
    dynamic({ "ip": "127.0.0.1", "status": "200", "method": "GET" })
]
| extend keys = bag_keys(data)
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;

APL equivalent

datatable(data: dynamic)
[
    dynamic({ "ip": "127.0.0.1", "status": "200", "method": "GET" })
]
| extend keys = bag_keys(data)

Updated

Was this page helpful?