This guide will give you an overview on how to visualize your data from our Datasets API. To learn how to get your data into Geckoboard as as a dataset, see our Datasets API docs.
To use our Datasets API, you must be on a paid plan.
Selecting a dataset in Geckoboard
To get started, click on the Add widget button on the top right of your dashboard and search for Datasets.
After clicking on Datasets you’ll see a list of the datasets you’ve sent to your Geckoboard account. You’ll also see a default dataset
geckoboard.space.cargo that’s available to help you get a better idea of how Datasets works before you send your own data.
We'll use this default dataset for all our examples here, so click on
geckoboard.space.cargo and we’re good to go.
Configuring your visualization
The first thing you'll notice on the config screen is that there’s an initial line chart based on your imported data. You can change it by selecting a different one from our visualization selector. Any changes will be displayed on the widget preview to the right.
The visualization config panel is broken into two sections unique for each visualization type. All types include Metric, Time, Filters and Formatting.
Under the Metric heading you'll see a single Duration field. Click the select menu to switch the metric you want to display. For line and column charts you can display more metrics by clicking.
In this section of the Setup Area you will find the fields available for each visualization. These fields are populated by the data sent in your dataset. For the Line chart for example, these would be the lines plotted. The type of the fields (Money, Number, Percentage) and their names are defined when you’re setting up the schema. For line and column charts you can display more metrics by clicking.
A powerful option here is the record count. In our example Space Cargo dataset, this means you can now plot the number of orders by day and then split that by category or destination.
To understand why your data is populated in the way it is when you view the field option, it would be helpful at this stage to preview the structure of the original dataset. You can access this preview from the dataset options menu in the navigation bar.
The dataset preview displays the dataset as a spreadsheet and it shows 30 records from the dataset. The names of the fields with their types is visible and helps you understand how exactly your data will be populated on our widget. You can also see the last time the sheet was updated and the number of records included in it.
The preview looks like this:
We can further manipulate the data with two powerful functions:
- This is the function used to calculate a roll-up value from related records. The options are Sum (adds all records up and shows the total), Min (displays the minimum value), Max (displays the maximum value), Average (displays the average of all values for that record).
- Use this option to break a single line series into multiple series. Splitting consists of grouping together records based on a chosen matching field.
The X-axis will display the name of the field or a Time value. It accepts the types date and Datetime to display Time or a string to display the name of the field.
A time value resulting from the roll-up of a group of records from a given time period. For example “bucket by week”.
Select a Time value that you'd like to see data for. You can choose to track the Past 7, 14, 28, 30, or 90 days. You can also show the calendar day (Today) and This Week, Month, Quarter, or Year in progress. It's also possible to use a Custom timeframe.
Add any optional filters to refine your data a value that you'd like this filter to match. Filters allow you to select that it is or is not a specific value or that the filtered option contains or does not contain a specific value.
X-Axis (Line, Column and Bar charts only)
The X-axis can be changed to display either a field name or a Time value. Selecting Started At means you can group (bucket) from a selected time period (Minute, Hour, Day, Week, Month, or Year).
Goal (Number, Line, Column and Bar charts only)
This option allows you to add a goal to your number or line chart. In the example below, you can see the data points inside the goal shaded area.
Status indicators (Number and Gauge only)
Adding status indicators allows you to call attention to your number or gauge widget on your dashboard when it's performing above and below expectations. Status indicators will overwrite any goals you set on this widget.
Setting a Warning value means when the primary metric is above or below the warning value your widget will display red.
Setting a Success value means when the primary metric is above or below the success value your widget instead displays green.
Chart Options (Line chart only)
Change your line chart's Y-Axis minimum and maximum values.
The Formatting section allows you to change the number of decimal places used or add additional information about the values being displayed.
The Abbreviation options allow you to indicate that a number has been abbreviated by including the correct suffix for the units shown. There are preset values of K for thousand, M for million and B for billion. You can also remove any automatically applied value by choosing None.
The Decimal Places options allow you to add or remove decimal places for your numbers. The Auto option will show up to 3 decimal places. It is possible to show between 0 and 6 decimal places using the Fixed option.
The Unit options allow you to add up to 3 characters to the beginning or end of your number to indicate what it shows.
From the following visualization types, select you want to configure:
This visualization displays a metric that can be represented by a single number. The number can include a prefix or a suffix to add more context to the number.
There’s the option to add a comparison visualization to the number. In this way the widget will display a primary metric and its relationship with a goal.
Gauges are often used to show a data point that changes over time. The gauge would be ideal in cases where a data point needs to be compared with a minimum and maximum value.
It’s possible to add more context by adding a range in which the number is expected to fluctuate. If this is not added manually we will calculate them for you.
Showing progress towards a goal is also possible by enabling the Goal tab and adding a number that’s within the minimum and maximum.
One thing to note is that the gauge will take the last value in the field and use it as its current value.
Line charts are a great way to track changes over time. It’s also possible to plot multiple series of values and visualize the trend of these values over time.
On the setup screen you can choose the metric(s) you want to display. By default there’s only one field populated, however you can add as many fields as your dataset and the size of the widgets allow. Each field will represent a series of values.
It is important to note that in order for us to be able to plot a line chart the dataset must contain datetime fields.
For line charts it is also possible to set comparison styling on one of a line chart’s series. Great for showing period-over-period comparisons, as it keeps the emphasis on the present period while still giving a point of reference.
You’ll find the option in the new Series options menu by clicking the three dots next to any series.
The column chart is a straightforward visualization that’s ideal to showcase discrete data that’s categorical.
To select a Column chart simply click on the visualization selector and you’re good to go. The chart will respect any settings while you change visualization.
It is important to note that this visualization works best with 10-12 data points, more would make the graph look crammed.
Very similar to the Column chart, the bar chart is a great visualization to show comparison between several categories. One axis of the chart shows the categories compared, the other axis represents a discrete value.
Note that this visualization would work best if plotting a maximum of 10 -15 data points.
The leaderboard is the perfect visualization to use when displaying achievement or to show a ranking of people or things.
Our example below will show us the average Cost per destination and rank them based on these values.
The table visualization gives you the power to display columns directly from your dataset on your dashboard either "raw" which is exactly as it in the dataset or "summary" which aggregates data grouped by a (string or date) value in the dataset.
A table is perfect for communicating more detail such as names, values or any other information set up in your dataset.
With this power comes responsibility, however. After all, adding the whole dataset to your dashboard could introduce unnecessary distractions and cause a team to focus on the wrong things. That’s why we’ve made it easy to pick and choose which columns from your dataset are displayed in a table.