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.

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.