Trellis layout

CAUTION: Trellis is only available for single value visualizations and area, line, bar, and column charts.

Organize your search results with the trellis layout for a holistic view of your data. Trellis layout visualizes your search results by separating each field value or aggregation.

The search in the following example returns customer purchases by product name. Applying a trellis layout creates a view of each product name as its own single value visualization.

index="sample-data" | stats count by productName

The "sample-data" in this example is a data set from the Search Tutorial in the Search Tutorial manual.

A visualization split into 5 columns and 4 rows. Each cell of the visualization is labeled by a game name with the number of customer purchases below the label.

Create a trellis layout

Using the visual editor, create a visualization that supports trellis by selecting the Add chart dropdown menu in the editing toolbar.
Set up a new data source by doing one of the following:
1. Select + Create search and add a search to the SPL query window.
2. Select an existing data source under the Search, Saved search, or Chain search dropdown lists.
Activate the trellis layout by toggling on Trellis layout in the Data display section of the Configuration panel.
From the Split by dropdown list, select the field name of the column with categories used or Aggregations to split the data into individual visualizations for trellis display, if applicable. If using an SPL timechart command, this may default to the SPL by clause field. If using an SPL chart command, this may default to the first string field.
In the Min column width field, specify the minimum width, in pixels, of each visualization in the trellis container. If you resize the window or panel, you can view the remaining visualizations by scrolling.
In the Row height field, specify each visualization's height, in pixels, in the trellis container. If you resize the window or panel, you can view the remaining visualizations by scrolling.
In the Max number of components per page field, specify the maximum number of visualizations to display on a single page in the trellis container. The remaining visualizations paginate accordingly.

You can also configure your visualization for the trellis layout by adding the splitByLayout:trellis option in the options stanza of your dashboard definition. The trellis layout might need some manual adjustment to fit your dashboard.

Split data by a non-default field

If you don't want to rely on the default data-splitting logic, you can split your data by a specific field name using the Split by option. Using Split by overrides the default logic.

The following example sets Split by to attack_type with the SPL search index="sample-data" | chart count by severity_level, attack_type.

For area, line, bar, and column charts, by default, the visualizations share the same Y-axis scale. If desired, you can disable Shared y-axis scale. The following example shows the same data as the previous example, but with Shared y-axis scale disabled. You can see that the 3 visualizations have different scales, ranging from a maximum of 20 for the DDoS visualization to a maximum of 60 for the Malware visualization.

A visualization split into 3 columns. Each visualization is a bar chart that shows the number of high, low, and medium severity cybersecurity threats for each attack type. This example is the same as the previous example, except that each visualization has a different y-axis scale applied.

A table split into 7 columns and 5 rows. The second column shows the severity level of different cybersecurity threats, and the third column shows the attack type. Other columns show other information related to the threat.

Source code

The following source code example shows a dashboard definition that uses the trellis layout, splits data by the non-default attack_type field, and does not use a shared scale.

{
    "title": "Worldwide Cybersecurity Threat Monitor",
    "description": "",
    "inputs": {},
    "defaults": {
        "dataSources": {
            "ds.search": {
                "options": {
                    "queryParameters": {
                        "earliest": "$global_time.earliest$",
                        "latest": "$global_time.latest$"
                    }
                }
            }
        },
        "visualizations": {
            "global": {
                "showProgressBar": true
            }
        }
    },
    "visualizations": {
        "viz_5pIU8XpW": {
            "containerOptions": {},
            "dataSources": {
                "primary": "ds_GMXKMxp8"
            },
            "options": {
                "splitByLayout": "trellis",
                "trellisSharedScale": false,
                "trellisSplitBy": "attack_type",
                "xAxisTitleVisibility": "hide"
            },
            "showLastUpdated": false,
            "showProgressBar": true,
            "type": "splunk.bar"
        }
    },
    "dataSources": {
        "ds_GMXKMxp8": {
            "name": "Search_1",
            "options": {
                "query": "index=\"sample-data\" | chart count by severity_level, attack_type"
            },
            "type": "ds.search"
        }
    },
    "layout": {
        "globalInputs": [],
        "layoutDefinitions": {
            "layout_eWkkmclc": {
                "structure": [
                    {
                        "item": "viz_5pIU8XpW",
                        "position": {
                            "h": 180,
                            "w": 770,
                            "x": 0,
                            "y": 0
                        },
                        "type": "block"
                    }
                ],
                "type": "absolute"
            }
        },
        "options": {},
        "tabs": {
            "items": [
                {
                    "label": "Overview",
                    "layoutId": "layout_eWkkmclc"
                }
            ]
        }
    },
    "applicationProperties": {
        "hideViewModeActionMenu": true
    }
}

Split data by aggregations

Aggregations are categories specified by field name prefixes. For example, avg(price) is an aggregation of the average price, and max(price) is an aggregation of the maximum price. You can split your data by aggregations.

The following example splits data by aggregations with the SPL search index="sample-data" | timechart avg(price), max(price). A visualization split into two cells. The first cell shows the value of the average price of each product and the second cell shows the maximum product price. A table split into three columns and nine rows. The first column shows different dates by year, month and day. The second column shows the average price with its associated date. The third column shows the maximum price with each associated date.

Source code

The following source code example shows a dashboard definition that uses the trellis layout and splits data by aggregations.

{
    "visualizations": {
        "viz_ngtz80fU": {
            "type": "splunk.singlevalue",
            "options": {
                "splitByLayout": "trellis"
            },
            "dataSources": {
                "primary": "ds_dKKG8nXI"
            }
        }
    },
    "dataSources": {
        "ds_dKKG8nXI": {
            "type": "ds.search",
            "options": {
                "query": "index=\"sample-data\" | timechart avg(price), max(price)"
            },
            "name": "Search_4"
        }
    },
    "defaults": {
        "dataSources": {
            "ds.search": {
                "options": {
                    "queryParameters": {
                        "latest": "$global_time.latest$",
                        "earliest": "$global_time.earliest$"
                    }
                }
            }
        }
    },
    "inputs": {
        "input_global_trp": {
            "type": "input.timerange",
            "options": {
                "token": "global_time",
                "defaultValue": "-24h@h,now"
            },
            "title": "Global Time Range"
        }
    },
    "layout": {
        "tabs": {
            "items": [
                {
                    "layoutId": "layout_1",
                    "label": "New tab"
                }
            ]
        },
        "layoutDefinitions": {
            "layout_1": {
                "type": "absolute",
                "options": {
                    "width": 1440,
                    "height": 960,
                    "display": "auto"
                },
                "structure": [
                    {
                        "item": "viz_ngtz80fU",
                        "type": "block",
                        "position": {
                            "x": 130,
                            "y": 90,
                            "w": 1010,
                            "h": 330
                        }
                    }
                ]
            }
        },
        "globalInputs": [
            "input_global_trp"
        ]
    },
    "description": "",
    "title": "Single value for trellis with aggregations"
}

Customize trellis columns with trellisMinColumnWidth and trellisColumns

You can customize the width of each visualization in the trellis layout with the trellisMinColumnWidth option. By default, trellisMinColumnWidth adjusts based on the configuration of the config.ts file and the parent panel width.

The following example shows how the trellis layout changes when the default trellisMinColumnWidth is updated to trellisMinColumnWidth: 150.

You can customize the number of visualizations to display in a single row of the trellis panel with trellisColumns. Visualizations with an undefined trellisColumns fill and wrap within the set width of the trellis panel.

The following example shows how visualizations might extend beyond the trellis panel with a trellisMinColumnWidth: 150 and trellisColumns: 6.

Tokens

You can use predefined tokens to access values in a trellis layout. Trellis layout supports the following predefined tokens:

value
name
trellis.value
trellis.name

A visualization split into five columns and four rows. A game name labels each cell of the visualization with the number of customer purchases.

For example, if selecting the Benign Space Debris trellis in the example, the values for the tokens are as follows:

value: 1,309
name: count
trellis.value: Benign Space Debris
trellis.name: productName

Predefined tokens for trellis split fields

If your trellis layout splits on a search result field, you can use the trellis.name and trellis.value predefined tokens to access the split field name and value from a clicked visualization segment.

You can pass these values to a drilldown target, such as a form or external URL. This example drilldown links to an external retail website, using the trellis.value token to pass in the product field value from the clicked segment.

"eventHandlers": [
        {
            "type": "drilldown.customUrl",
            "options": {
                "fields": [
                    "ID"
                ],
                "url": "http://buttercupgames.com?product=$trellis.value$",
                "newTab": true
            }
        }
]

Note: Aggregations are not available in predefined tokens.

Default data splitting logic

The following only provides an overview of default data splitting behavior for reference. You can configure a trellis to split data using any field.

By default, the trellis layout splits data visualizations based on the SPL commands and associated metadata or configurations provided. The data splitting logic defaults to SPL commands and associated metadata first, then option configurations. If you apply configuration options, any of those options could impact how the logic behaves with SPL commands or data field types. The following examples show different examples of default data splitting logic.

Split data with the timechart command

When using the SPL timechart command, the trellis layout defaults to an associated by clause. The following example shows how the trellis layout categorizes each single value visualization by product name as a result of the SPL search index="sample-data" | timechart count by productName. The "sample-data" in this example is a data set from the Search Tutorial in the Search Tutorial manual.

A visualization split into five columns and three rows. A game name labels each cell of the visualization with the number of customer purchases and an arrow indicating if the number has trended down or up and by how much. A table split into seven columns and eight rows. The first column shows dates in ascending order. The remaining columns show different games and the number of customer purchases of each game for each date.

Source code

The following source code example shows a dashboard definition that uses the trellis layout with the timechart command to split data by productName.

{
    "visualizations": {
        "viz_DgbNcpY7": {
            "type": "splunk.singlevalue",
            "options": {
                "splitByLayout": "trellis"
            },
            "dataSources": {
                "primary": "ds_RWdnS6Rc"
            }
        }
    },
    "dataSources": {
        "ds_RWdnS6Rc": {
            "type": "ds.search",
            "options": {
                "query": " index=\"sample-data\" | timechart count by productName"
            },
            "name": "Search_1"
        }
    },
    "defaults": {
        "dataSources": {
            "ds.search": {
                "options": {
                    "queryParameters": {
                        "latest": "$global_time.latest$",
                        "earliest": "$global_time.earliest$"
                    }
                }
            }
        }
    },
    "inputs": {
        "input_global_trp": {
            "type": "input.timerange",
            "options": {
                "token": "global_time",
                "defaultValue": "-24h@h,now"
            },
            "title": "Global Time Range"
        }
    },
    "layout": {
        "tabs": {
            "items": [
                {
                    "layoutId": "layout_1",
                    "label": "New tab"
                }
            ]
        },
        "layoutDefinitions": {
            "layout_1": {
                "type": "absolute",
                "options": {
                    "width": 1440,
                    "height": 960,
                    "display": "auto"
                },
                "structure": [
                    {
                        "item": "viz_DgbNcpY7",
                        "type": "block",
                        "position": {
                            "x": 300,
                            "y": 100,
                            "w": 700,
                            "h": 260
                        }
                    }
                ]
            }
        },
        "globalInputs": [
            "input_global_trp"
        ]
    },
    "description": "",
    "title": "Single value for trellis with timechart command"
}

Split data with the chart or stats commands

The trellis layout defaults to the first string field when using the SPL chart or stats command with one by clause. The following example shows how the trellis layout categorizes each single value visualization by the productName column as a result of the SPL search index="sample-data" | chart count by productName. The "sample-data" in this example is a data set from the Search Tutorial in the Search Tutorial manual.

A visualization split into five columns and four rows. A game name labels each cell of the visualization with the number of customer purchases. A table split into two columns and eleven rows. The first column shows the product name of different games, and the second column shows the number of total customer purchases for each game.

Source code

The following source code example shows a dashboard definition that uses the trellis layout with the chart command to split data by productName.

{
    "visualizations": {
        "viz_3V5QUYuU": {
            "type": "splunk.singlevalue",
            "options": {
                "splitByLayout": "trellis"
            },
            "dataSources": {
                "primary": "ds_fyNUplwK"
            }
        }
    },
    "dataSources": {
        "ds_fyNUplwK": {
            "type": "ds.search",
            "options": {
                "query": "index=\"sample-data\" | chart count by productName"
            },
            "name": "Search_2"
        }
    },
    "defaults": {
        "dataSources": {
            "ds.search": {
                "options": {
                    "queryParameters": {
                        "latest": "$global_time.latest$",
                        "earliest": "$global_time.earliest$"
                    }
                }
            }
        }
    },
    "inputs": {
        "input_global_trp": {
            "type": "input.timerange",
            "options": {
                "token": "global_time",
                "defaultValue": "-24h@h,now"
            },
            "title": "Global Time Range"
        }
    },
    "layout": {
        "tabs": {
            "items": [
                {
                    "layoutId": "layout_1",
                    "label": "New tab"
                }
            ]
        },
        "layoutDefinitions": {
            "layout_1": {
                "type": "absolute",
                "options": {
                    "width": 1440,
                    "height": 960,
                    "display": "auto"
                },
                "structure": [
                    {
                        "item": "viz_3V5QUYuU",
                        "type": "block",
                        "position": {
                            "x": 280,
                            "y": 150,
                            "w": 840,
                            "h": 420
                        }
                    }
                ]
            }
        },
        "globalInputs": [
            "input_global_trp"
        ]
    },
    "description": "",
    "title": "Single value for trellis with chart command"
}

Source options for trellis layout

Add the following trellis configurations to the options stanza of your dashboard definition for further customization.

The following options are available for editing trellises in the source editor:


Option	Type	Default	Description
splitByLayout	string	off	Specify the layout method to display the visualization, which splits the data into individual visualizations based on a specific category. The available values are off and trellis.
trellisBackgroundColor	string	> themes.defaultBackgroundColor	Specify the background color of the whole panel in the trellis layout display. For example, #ff0000. You can use a hexadecimal code to apply the color. The default for Enterprise light is #ffffff. The default for Enterprise dark is #000000. The default for Prisma dark is #0b0c0e.
trellisColumns	number	n/a	Specify the number of columns in a trellis layout container. For example, six columns allow six visualizations per row. Rows populate to accommodate the total number of visualizations. If no column number is specified, the number of columns is automatically set based on the value specified for `trellisMinColumnWidth`.
trellisMinColumnWidth	number	100	Specify the minimum width, in pixels, of each visualization in the trellis container. If you resize the window or panel, you can view the remaining visualizations by scrolling.
trellisPageCount	number	20	Specify the maximum number of visualizations to display on a single page in the trellis container. The remaining visualizations paginate accordingly.
trellisRowHeight	number	70	Specify each visualization's height, in pixels, in the trellis container. If you resize the window or panel, you can view the remaining visualizations by scrolling.
trellisSharedScale	boolean	true	Specify whether all visualizations share the same y-axis scale in the trellis container.
trellisSplitBy	string	n/a	If applicable, specify the column's field name with categories used or aggregations to split the data into individual visualizations for trellis display. If you use an SPL `timechart` command, this might default to the SPL `by` clause field. If you use an SPL `chart` command, this might default to the first string field.