Dot Expander

Transform Elastic Compatible

Synopsis

Expands fields containing dots in their names into nested objects.

Schema

- dot_expander:
    field: <ident>
    path: <string>
    description: <text>
    if: <script>
    ignore_failure: <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	-	Field containing dot-separated names to expand
path	N	Same as field	Where the value is written instead of the expanded field path. It is used verbatim, so a single-segment value produces no nesting at all
description	N	-	Explanatory note
if	N	-	Conditional expression
ignore_failure	N	false	Continue processing on errors
on_failure	N	-	Processors to run on failure
on_success	N	-	Processors to run on success
tag	N	-	Identifier for logging
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

The processor converts flat field names with dot notation into nested object structures. This is particularly useful for transforming flattened data into hierarchical formats, improving data readability and standardizing field structures for nested processing.

note

The field must contain at least one dot. Also, nested expansions create complex object structures.

Intermediate objects are created as needed, and the original flat key is removed once the value has been written.

path does not prefix the expansion — it replaces the destination outright. The expansion is always driven by the destination path, so path: target writes a plain target field while path: a.b.c nests three levels.

warning

Deeply nested fields can lead to performance issues.

Examples

Basic

Expanding a dotted field into nested objects...	{ "foo.bar.baz": 123 } - dot_expander: field: foo.bar.baz
creates a nested structure:	{ "foo": { "bar": { "baz": 123 } } }

Redirecting to Another Path

path REPLACES the destination — it does not nest the expansion under it...	{ "source.field.value": 123 } - dot_expander: field: source.field.value path: target
so the value lands at target and no nesting is created:	{ "target": 123 }
To nest it somewhere else, write the destination as a dotted path of its own...	- dot_expander: field: source.field.value path: target.field.value
which expands the way the path is written:	{ "target": { "field": { "value": 123 } } }

Conditionals

Expand only when a condition is met...	{ "foo.bar.baz": 123, "condition": true } - dot_expander: field: foo.bar.baz if: ctx.condition == true
result:	{ "condition": true, "foo": { "bar": { "baz": 123 } } }

Error Handling

When a field doesn't contain any dots...	{ "foo": 123 } - dot_expander: field: foo on_failure: - set: field: error value: "No dots in field name"
handle the error:	{ "foo": 123, "error": "No dots in field name" }