format_string ↗

Use the format_string() function to construct dynamic strings by inserting values into a predefined format.

Syntax

format_string ("<format_string>", <field_1>, <field_2>, ...<field_n>)

Parameters

Name Type Required Description
format_string string Yes A string literal that contains zero or more format specifiers initiated by the % symbol (for example, %s, %d).
field_n string, integer Yes A variable-length list of additional arguments whose values will be inserted into the format string. Each argument must match the type expected by its corresponding format specifier.

Returns

The format_string() function returns a single string containing the formatted text with argument values inserted.

Usage notes

  • Common format specifiers include %s for string values and %d for integer values.
  • You can use padding and width specifiers (for example, %10d, %05d, %-10s) to control output alignment and formatting.
  • The function requires strict type compatibility between arguments and specifiers. The function does not implicitly convert types (for example, a floating-point number passed to %d will fail).
  • Use explicit type conversion functions like to_string() or to_integer() to ensure non-matching values (like booleans or floats) are compatible with the specifiers.
  • Note that to_number() converts strings to floating-point numbers, which are incompatible with the %d (integer) specifier; use to_integer() instead.

Examples

Example 1: Basic string substitution (%s)

Goal: Combine literal text with string field values using the %s specifier.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter event_message = format_string("Description: %s. Domain: %s.", event_description, dst_domain)
| fields event_id, event_message
| limit 3

Explanation: The event_description and dst_domain fields, which are strings, are directly inserted into the format string at the %s placeholders.

Output:

EVENT_ID EVENT_MESSAGE
101 "Description: User login successful. Domain: ec2.amazonaws.com."
102 "Description: File access attempt. Domain: sts.amazonaws.com."
103 "Description: Network connection established. Domain: www.google.com."

Example 2: Integer substitution (%d)

Goal: Embed integer field values into a string using the %d specifier.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter formatted_id = format_string("Event #%d occurred.", event_id)
| fields event_id, formatted_id
| limit 3

Explanation: The event_id (an integer) is converted to its string representation and inserted into the output string where %d is specified.

Output:

EVENT_ID FORMATTED_ID
101 "Event #101 occurred."
102 "Event #102 occurred."
103 "Event #103 occurred."

Example 3: Combining different data types

Goal: Combine values of different original data types (boolean, float) into a single formatted string using explicit conversion.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter detailed_status = format_string("Successful: %s, Duration: %s seconds", to_string(is_successful), to_string(duration_seconds))
| fields event_id, is_successful, duration_seconds, detailed_status
| limit 3

Explanation: to_string(is_successful) converts the boolean to "true" or "false". to_string(duration_seconds) converts the float to a string like "1.5". format_string() then constructs the final string using these string representations for the %s specifiers.

Output:

EVENT_ID IS_SUCCESSFUL DURATION_SECONDS DETAILED_STATUS
101 true 1.5 "Successful: true, Duration: 1.5 seconds"
102 false 0.8 "Successful: false, Duration: 0.8 seconds"
103 true 10.2 "Successful: true, Duration: 10.2 seconds"

Example 4: Padding and zero-padding for integers

Goal: Utilize padding specifiers with %d and %s to control width and alignment.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter padded_event_id = format_string("ID: %05d | Full ID: %-10s | Raw: %s", event_id, to_string(event_id), to_string(event_id))
| fields event_id, padded_event_id
| limit 3

Explanation: %05d pads event_id with leading zeros to a width of 5. %-10s left-justifies the string version within 10 characters. %s performs basic substitution.

Output:

EVENT_ID PADDED_EVENT_ID
101 ID: 00101
102 ID: 00101
103 ID: 00101

Example 5: Formatting extracted JSON scalar values with integer conversion

Goal: Extract a numeric string from JSON, convert it to an integer, and format it with %d.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter status_code_string = coalesce(simple_json_data -> code, simple_json_data -> error_code)
| alter status_int = to_integer(status_code_string)
| alter formatted_status = format_string("API Status: %d", status_int)
| fields event_id, simple_json_data, formatted_status
| limit 3

Explanation: The query extracts the code as a string and explicitly converts it to an integer using to_integer(). This ensures compatibility with the %d specifier, which would fail if a float (from to_number) were passed.

Output:

EVENT_ID SIMPLE_JSON_DATA FORMATTED_STATUS
101 {"status": "ok", "code": 200} "API Status: 200"
102 {"status": "fail", "error": "access_denied"} NULL
103 {"connection_id": "CONN-001", "protocol": "TCP"} NULL