Data structure requirements for visualizations
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Data structure requirements for visualizations
In this topic we cover the data structure requirements of the different types of visualizations offered for our reports and dashboards. If you're trying to generate a visualization, and are wondering why certain visualizations are unavailable, this is the topic for you.
If you're getting the above error when you change the underlying search for an existing dashboard panel, or if you're creating a new panel and are finding that the visualization you want is unavailable, it's likely because the underlying search doesn't return data that will work for that visualization. In most cases, it's easy to tweak the search to get the visualization you want.
For example, most charting visualizations (column charts, line charts, area charts, bar charts, and so on) require search results that are structured as tables with at least two columns, where the first column provides x-axis values, and the subsequent columns provide y-axis values for each series represented in the chart (pie charts only provide information for single-series reports, while the other chart types can represent multiple series). To get these tables you need to set up the underlying search with reporting search commands like
For a high-level overview of Splunk's visualization options, see the "Visualization reference," in this manual.
- For more information about building searches with reporting commands, see "Use reporting commands."
- For more information about building reports with the Report Builder, see ""Define reports and generate charts" in this manual.
- For more information about using the Visualization Editor to design visualizations for dashboard panels, see "Define and edit dashboard panels."
Column, line, and area charts
It's important to understand that column, line, and area charts are two-dimensional charts supporting one or more series. They plot data on a Cartesian coordinate system, working off of tables that have at least two columns, where the first column contains x-axis values and the subsequent columns contain y-axis values (each column represents a series). This is why "Values over time" searches and searches that include splitbys are among those that are available as column, line, and area charts.
If you want to generate a column, line, or area chart from a search, that search must produce a table matching the description provided in the preceding paragraph. For example, any search using the
timechart reporting command will generate a table where
_time is the first column (and therefore the x-axis of any column, line, or area chart generated from those results). You'll get the same result with most basic searches involving reporting commands.
For example, a search like this, where the
over operator indicates that
source is the x-axis:
...| chart avg(bytes) over source
produces a two-column, single-series table like this:
In this table, the x-axis is
source, and the y-axis is
avg(bytes). With it you can produce a column chart that compares the average number of bytes passed through each source.
Say you change up the search a bit by adding
clientip as a splitby field:
...| chart avg(bytes) over source by clientip
This produces a table that features multiple series:
In this table, the x-axis is still
source, and the y-axis is still
avg(bytes), but it now breaks out the
clientip, creating a table with multiple series. You might generate a stacked column chart to represent this data.
You run into trouble when you design a complex search that returns a result table that lacks a valid x-axis or y-axis value. This can happen when you use the
fields commands to force a particular arrangement of columns in the finished table, for example.
Bar charts have the same data structure requirements as column, line, and area charts, except that the x- and y-axes are reversed. So they are working off of tables that have at least two columns, where the first column contains y-axis values and the subsequent columns contain x-axis values.
Pie charts are one dimensional and only support a single series. They work off of tables with just two columns, where the first column contains the labels for each slice of the pie, and the second column contains numerical values that correspond to each label, determining the relative size of each slice. If the table generated by the search contains additional columns, those extra columns have no meaning in the terms of the pie chart and are ignored.
Of the two "column, line, and area charts" search examples noted above, the first is the only one that could be used to make a pie chart. The
source column would provide the wedge labels, and the
avg(bytes) column would provide the relative sizes of the wedges (as percentages of the sum of
avg(bytes) returned by the search).
Scatter charts are cartesian charts that render data as scattered markers. They help you visualize situations where you may have multiple y-axis values for each x-axis value, even when you're not charting multiple series. Their data set can be in one of two forms:
- A single series setup, where the chart is structured on a 2-column data table, where the first column (column 0) contains the values to be plotted on the x-axis, and the second column (column 1) contains the values to be plotted on the y-axis.
- A multiple series setup, where the chart is structured on a data table that contains 3 columns. The first column (column 0) contains the series names, and the next two columns contain the values to be plotted on the x- and y-axes, respectively.
To generate a scatter chart you need to graph events directly with a search like:
* | fields - _* | fields clientip bytes
This search finds all of the packets received from various client IP addresses and then orders them according to the number of bytes in each packet.
- Note that the search removes all fields with a leading underscore, such as the
- The second
fieldscommand isolates the two fields that you want for the x- and y-axis of the chart, respectively. The y-axis value should be numerical for best results. (So in this case, the x-axis is
clientipwhile the y-axis is
Note: To create a scatter plot chart with a search like this, you need to enter the reporting commands directly into the Report Builder by clicking Define report data using search language in the Report Builder. You can run this report from the search bar, but when you open up Report Builder, it adds a timechart command that you should remove before formatting the report.
More complex scatter charts can be set up in dashboards using Splunk's view XML. For more information see the Custom charting configuration reference chapter in the Developer manual.
Gauges and single value visualizations
Gauges and single value visualizations are designed to represent searches that return a single numerical field value. Gauges show where this value exists within a defined range, while single value visualizations just display the number.
A simple example is a search that returns a count of the number of events matching a set of search criteria that come in within a specific time period, or a real-time window, if you are using a real-time search. If you base a gauge on a real-time search, the chart's range marker will appear to fluctuate as the value displayed within the real-time search window changes over time.
If you base a single value visualization on this same search, you'll see the value increase and decrease as the value returned by the real-time search changes over time. If you've used the
rangemap command in conjunction with the search, the single value visualization will change color depending on the value returned.