KV

Parse Elastic Compatible

Synopsis

Parses strings to extract key-value pairs into structured fields.

Schema

kv:
  - field: <ident>
  - field_split: <regex>
  - value_split: <regex>
  - description: <text>
  - exclude_keys: <string[]>
  - if: <script>
  - ignore_casting: <boolean>
  - ignore_failure: <boolean>
  - ignore_missing: <boolean>
  - include_keys: <string[]>
  - lowercase_keys: <boolean>
  - on_failure: <processor[]>
  - on_success: <processor[]>
  - prefix: <string>
  - strip_brackets: <boolean>
  - tag: <string>
  - target_field: <ident>
  - trim_key: <char[]>
  - trim_value: <char[]>

Configuration

Field	Required	Default	Description
field	Y	-	Source field containing key-value pairs
field_split	Y	-	Delimiter between key-value pairs
value_split	Y	-	Delimiter between keys and values
description	N	-	Documentation note
exclude_keys	N	-	Keys to exclude from output
if	N	-	Conditional expression
ignore_casting	N	false	Disable automatic type conversion
ignore_failure	N	false	Skip processing errors
ignore_missing	N	false	Skip if input field missing
include_keys	N	-	Only include specified keys
lowercase_keys	N	false	Convert all keys to lowercase
on_failure	N	-	Error handling processors
on_success	N	-	Success handling processors
prefix	N	-	Prefix for extracted keys
strip_brackets	N	false	Remove brackets from values
tag	N	-	Identifier for logging
target_field	N	-	Output field for parsed data
trim_key	N	-	Characters to trim from keys
trim_value	N	-	Characters to trim from values

Details

The processor supports various delimiter patterns, key filtering, value formatting, and automatic type casting.

note

Whitespace around field and value delimiters is automatically trimmed.

warning

Malformed inputs may result in missing entries or incomplete parsing.

Examples

Basic

Parsing semicolon-separated pairs...	{ "message": "key1=value1;key2=value2;key3=value3" } kv: - field: message - field_split: ";" - value_split: "="
extracts the structured fields:	{ "message": "key1=value1;key2=value2;key3=value3", "key1": "value1", "key2": "value2", "key3": "value3" }

Target Field

Storing the parsed values in a separate object...	{ "data": "host=localhost:8080, status=200, method=GET" } kv: - field: data - field_split: "," - value_split: "=" - target_field: request_info
groups related fields:	{ "data": "host=localhost:8080, status=200, method=GET", "request_info": { "host": "localhost:8080", "status": "200", "method": "GET" } }

Keys

Including only specific keys...	{ "log": "user=admin role=sudo group=wheel status=active" } kv: - field: log - field_split: " " - value_split: "=" - include_keys: ["user", "role"]
extracts only those records:	{ "log": "user=admin role=sudo group=wheel status=active", "user": "admin", "role": "sudo" }

Formatting

Cleaning up and formatting values...	{ "data": "name=[John], age='25', city=<New York>" } kv: - field: data - field_split: "," - value_split: "=" - strip_brackets: true - trim_value: "'" - lowercase_keys: true
standardizes the output:	{ "data": "name=[John], age='25', city=<New York>", "name": "John", "age": "25", "city": "New York" }

Prefixing

Adding a prefix to the extracted keys...	{ "metrics": "cpu=80,mem=60,disk=45" } kv: - field: metrics - field_split: "," - value_split: "=" - prefix: "system_"
places the fields in a namespace:	{ "metrics": "cpu=80,mem=60,disk=45", "system_cpu": "80", "system_mem": "60", "system_disk": "45" }