explode - Convert N array elements into N documents

The explode command explodes an array of N elements into N documents, each containing one element of the array in the specified keypath.

Syntax

explode <expression> into <keypath> [original discard|preserve]

Note

The default behaviour is discard (see next section for how this works)

Preserve or discard

As part of the explode operation, users can declare what they would like to do with the original document's fields. For example, consider the following document:

{
    "my_arr": ["a", "b", "c"],
    "id": 10
}

If we run the following command:

explode my_arr into arr_element original discard

Then the new documents will look like this. Note that the original id field and my_arr is now gone:

{
    "arr_element": "a"
},
{
    "arr_element": "b"
},
{
    "arr_element": "c"
}

However, if we were to run the following command:

explode my_arr into arr_element original preserve

Then the resultant documents would look like this, with the original my_arr and id values intact:

{
    "arr_element": "a",
    "id": 10,
    "my_arr": ["a", "b", "c"]
},
{
    "arr_element": "b",
    "id": 10,
    "my_arr": ["a", "b", "c"]
},
{
    "arr_element": "c",
    "id": 10,
    "my_arr": ["a", "b", "c"]
}

Note

If an exploded value matches a keypath of an existing value in the original document, the exploded value takes priority, meaning it overwrites the value in the original document.

Note

When preserving original fields, if the destination keypath already exists, it will be overwritten with an exploded value.

Example - Showing all user permissions

Consider the following documents:

{ 
    "userid": "1", 
    "scopes": ["read", "write"] 
},
{ 
    "userid": "2", 
    "scopes": ["read", null] 
}

I want to render these so that each document represents an individual permission, rather than constantly performing array operations. We can do this using explode:

source logs | explode scopes into scope original preserve

This will result in the following documents:

{ "userid": "1", "scope": "read", "scopes": ["read", "write"]}
{ "userid": "1", "scope": "write", "scopes": ["read", "write"]}
{ "userid": "2", "scope": "read", "scopes": ["read", null]}
{ "userid": "2", "scope": null, "scopes": ["read", null]}

Previous enrich

Next extract