Zip

Mutate

Synopsis

Combines parallel arrays element by element — either into an array of tuples, or into a single object built from a keys array and a values array.

Schema

- zip:
    fields: <string[]>
    mode: <enum>
    target_field: <ident>
    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
fields	Y	-	Array fields to combine. Between 2 and 16 in tuples mode, exactly 2 in bag mode
mode	N	"tuples"	tuples pairs the arrays by index; bag builds an object from a keys array and a values array. Matched case-insensitively
target_field	Y	-	Field to store the result. There is no default: an empty value fails with zip requires a target_field
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	See Handling Failures
ignore_missing	N	false	If true, quietly exit if field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
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

Tuples Mode

The result has as many tuples as the longest input array. Where a shorter array has run out, its slot in the tuple is null rather than the tuple being dropped — so no data is lost when the arrays are ragged, and the position of every element is preserved.

Every field must hold an array. A non-array is an error.

Bag Mode

Exactly two fields: the first supplies the keys, the second the values, paired by index.

Three rules decide what lands in the object:

• A non-string key is skipped, along with its value. Object keys have to be strings, and the pair is dropped rather than coerced.
• A key with no matching value — because the values array is shorter — is written with a value of null, so the key still appears.
• A duplicate key takes the value of its last occurrence, since each assignment overwrites the previous one.

If the keys field is not an array, the target is set to null rather than raising an error.

Examples

Pairing Two Arrays

Combining parallel arrays into positional tuples...	{ "ports": [80, 443, 8080], "states": ["open", "open", "filtered"] } - zip: fields: ["ports", "states"] target_field: port_states
one tuple per index:	{ "ports": [80, 443, 8080], "states": ["open", "open", "filtered"], "port_states": [ [80, "open"], [443, "open"], [8080, "filtered"] ] }

Ragged Arrays

A shorter array is padded rather than truncating the result...	{ "ports": [80, 443, 8080], "states": ["open", "open"] } - zip: fields: ["ports", "states"] target_field: port_states
so the third port is still represented:	{ "ports": [80, 443, 8080], "states": ["open", "open"], "port_states": [ [80, "open"], [443, "open"], [8080, null] ] }

Building an Object

In bag mode the first field supplies keys and the second values...	{ "header_names": ["content-type", "user-agent"], "header_values": ["application/json", "curl/8.4.0"] } - zip: fields: ["header_names", "header_values"] mode: bag target_field: http.headers
giving an object you can reference by name:	{ "header_names": ["content-type", "user-agent"], "header_values": ["application/json", "curl/8.4.0"], "http": { "headers": { "content-type": "application/json", "user-agent": "curl/8.4.0" } } }

Missing Values in Bag Mode

A key with no matching value is kept, set to null...	{ "keys": ["region", "zone", "rack"], "values": ["eu-west", "b"] } - zip: fields: ["keys", "values"] mode: bag target_field: placement
so the absent value is visible rather than silently dropped:	{ "keys": ["region", "zone", "rack"], "values": ["eu-west", "b"], "placement": { "region": "eu-west", "zone": "b", "rack": null } }