Join KV

Text Processing String Manipulation Data Cleaning

Synopsis

Converts a map of key-value pairs to a formatted string.

Schema

- join_kv:
    field: <ident>
    target_field: <ident>
    separator: <string>
    kv_separator: <string>
    sort: <enum>
    index_name: <string>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Source field containing the map of key-value pairs
target_field	Y	-	Destination field to store the resulting string
separator	N	;	Character(s) used to separate key-value pairs
kv_separator	N	=	Character(s) used to separate keys from values
sort	N	asc	Sort order for keys: asc, desc, or index
index_name	N	field	Index name for sort: index mode
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if conversion fails
ignore_missing	N	false	Skip if source field doesn't exist
on_failure	N	-	Error handling processors
on_success	N	-	Success handling processors
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

Details

Converts a map (object) of key-value pairs into a single formatted string. The processor joins all key-value pairs from the source map using specified separators, creating a consistent string representation of the structured data.

note

Keys are sorted case-insensitively and ascending by default, so the output is deterministic regardless of the original map order — which matters when the string feeds a hash or signature. sort selects asc, desc or index; an unrecognised value falls back to a case-sensitive ascending sort.

Numbers are not written back as they appear in the event. A whole number loses its decimal point and a fractional one is padded to exactly six decimal places, so 75.2 becomes 75.200000. Format the value with a Convert step first if the exact original text matters.

target_field is required — an empty one fails with target_field is required — and the source must be a map; any other type fails with is not a map as expected.

warning

When converting complex nested objects, only the string representation of the value is included. Nested objects will be formatted using their default string representation, which may not be ideal in all cases. For complex nested structures, consider flattening the data first.

Examples

Basic

Converting map to string using default separators...	{ "user": { "attributes": { "name": "John", "role": "admin", "active": true } } } - join_kv: field: user.attributes target_field: user.attributes_string
creates a string with default separators:	{ "user": { "attributes": { "name": "John", "role": "admin", "active": true }, "attributes_string": "active=true;name=John;role=admin" } }

Custom

Using custom field and pair separators...	{ "request": { "headers": { "content-type": "application/json", "user-agent": "Mozilla/5.0", "accept": "text/html" } } } - join_kv: field: request.headers target_field: request.header_string separator: ", " kv_separator: ": "
formats headers in HTTP style:	{ "request": { "headers": { "content-type": "application/json", "user-agent": "Mozilla/5.0", "accept": "text/html" }, "header_string": "accept: text/html, content-type: application/json, user-agent: Mozilla/5.0" } }

URL Queries

Creating a URL query string format...	{ "query": { "params": { "q": "search term", "page": 1, "limit": 25 } } } - join_kv: field: query.params target_field: query.string separator: "&" kv_separator: "="
builds a properly formatted query string:	{ "query": { "params": { "q": "search term", "page": 1, "limit": 25 }, "string": "limit=25&page=1&q=search term" } }

Numeric Values

Joining a map of measurements...	{ "metrics": { "cpu": 75.2, "memory": 85.6, "disk": 45.3 } } - join_kv: field: metrics target_field: metrics_string separator: " "
a fractional number is rendered with six decimal places, and a whole one with none:	{ "metrics": { "cpu": 75.2, "memory": 85.6, "disk": 45.3 }, "metrics_string": "cpu=75.200000 disk=45.300000 memory=85.600000" }