Explode

Normally, if an attribute contains a list, or a key expression traversal that leads to multiple nodes, all items in the list appear in a single cell in the results. Sometimes, particularly when exporting data to other systems, it can be useful instead to 'explode' the items in the list into multiple output rows. The result is similar to the result of a join in a relational database. This query produces a table of network interfaces with one fully-qualified domain name per row:

SEARCH NetworkInterface SHOW ip_addr, EXPLODE fqdns

When exploding an entry, one row is created for each item in the exploded list; if the exploded list is empty, no rows are created.

A common requirement when exporting data for import into another system is to extract the node identifiers for all nodes related to a set of nodes, so the graph structure can be reconstructed. This can be achieved by exploding the related node identifiers. This query produces a table mapping Host node ids to all the Software Instances running on them:

SEARCH Host SHOW name, #id, EXPLODE #Host:HostedSoftware:RunningSoftware:SoftwareInstance.#id

Key expression traversals leading to multiple nodes can be limited in the system settings so that not all target nodes are used (although by default there is no limit). When exploded, key expressions have no traversal limit.

All key expressions with the same traversal specifications are handled as a group, meaning that multiple attributes can be selected, for example:

SEARCH Host 
SHOW name, 
    EXPLODE #Host:HostedSoftware:RunningSoftware:SoftwareInstance.name, 
            #Host:HostedSoftware:RunningSoftware:SoftwareInstance.instance

The result has one row per software instance. Even though the second key expression is not explicitly exploded, it is implicitly exploded since it shares the traversal with the exploded attribute.

This sort of implicit explode is only performed during normal result retrieval. Using PROCESSWITH to filter a search in post-processing accesses values without the context of retrieving complete rows, so implicit explodes do not take effect. This does not work:

SEARCH Host 
SHOW name, 
    EXPLODE #Host:HostedSoftware:RunningSoftware:SoftwareInstance.name, 
            #Host:HostedSoftware:RunningSoftware:SoftwareInstance.instance
    PROCESSWITH WHERE @1 = "example"   // Do not do this!

The PROCESSWITH accesses column 1 (the instance) without also accessing column 0, meaning that the explode does not take effect. Rather than explicitly exploding the column to be filtered, it is much more efficient to use a traversal expression to choose only the selected nodes in the first place:

SEARCH Host 
    WITH (TRAVERSE Host:HostedSoftware:RunningSoftware:SoftwareInstance as si where instance = "example")
    SHOW name, EXPLODE #si.name, #si.instance

Multiple Explodes

You should not use explode on more than one independent attribute or relationship traversal. If you do so, all possible combinations of the attribute values are exploded. This can produce very large datasets and can impact performance considerably.

For example, an attempt to see Hosts with all their directly running Software Instances and simultaneously all their IP addresses would be a mistake:

SEARCH Host 
SHOW name, 
    EXPLODE #Host:HostedSoftware:RunningSoftware:SoftwareInstance.name, 
    EXPLODE #DeviceWithAddress:DeviceAddress::IPAddress.ip_addr         // Do not do this!

If a Host had 10 Software Instances and 5 IP addresses, that one Host would produce 50 rows of output. Across all Hosts, that query could easily generate many millions of rows of output.