Guide to using datasets

  1. Glossary
  2. Picking a dataset
  3. Setup Screen
  4. Visualizations

The Datasets integration is our most powerful and flexible way to get data into Geckoboard yet.

It is particularly useful when you have specific sets of data that you want to display on our dashboards that can’t be accessed by the integrations we currently support. It’s also helpful if you want to get data from your own internal systems, or if you need to extend the functionality of one of our pre-built integrations.

This guide will give you an overview on how to visualize your data from datasets. We’ve covered how to get your data into Geckoboard as datasets on the Getting started section of our Developer Documentation.

Before we go any further, this will be a great time to define a few terms that will help better understand our Datasets integration datasets.


  • Dataset: A name, fields and corresponding data that make up one completed data API integration.
  • Schema: The defined structure of a dataset (a group of fields).
  • Field: A ‘column’ in spreadsheet terms. Structural, rather than referring to actual data. Has (at minimum) a name and a type.
  • Name: The developer-friendly designation that is used as a unique identifier for both either a data set or field. URL-friendly.
  • Type: Required when defining a field. Tells Geckoboard and the user what sort of data is expected in a field.
  • Record: A ‘row’ in spreadsheet terms. A single collection of data that fit into the data set’s structure.
  • Bucketing: To ‘roll-up’ a group of records from a given time period into one value. For example “bucket by week”,
  • Aggregate: The function used to calculate the ‘rolled-up’ value when bucketing. For example, sum, average, min, max.
  • Split: To break a series into multiple series by grouping together records based on a chosen matching field.
  • Count: An alternative aggregate, the number of records in a given time period.

Back to top

Picking a dataset

To get started, simply click on the +Add Widget button on the top right and search for Datasets.

Once you access the integration you’ll be taken to screen that lists all the datasets you’ve sent to your Geckoboard account. You’ll also see a default dataset ( that’s available to help you get a better idea of how the integration works before you send any of your own data.



We will be using this default dataset for all our examples here, so click on “” and we’re good to go.


Setup screen

The first thing you'll notice in the setup screen is that there’s an initial line chart based on the data provided. This is our default visualization and it will work if your data can be used to plot a line chart. You can change it by selecting a different one from our visualization selector. The dataset picker will allow you to change the dataset you’re currently using without having to leave this screen.



In the Widget Setup Area you will set up and define how to visualize the dataset. Any changes to this section will be displayed on the live preview screen to the right.

This area is broken into two sections: Build and Fine-tune.



This section is unique for each visualization. We’ll cover all options below:



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. 



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:

Aggregate: 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).

Split: 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.

  • Bucketing: A time value resulting from the roll-up of a group of records from a given time period. For example “bucket by week”.




This option allows you to add a goal to your visualizations. In the example below, the bars that have reached the goal are displayed in green.



Chart options settings:

With these settings you can modify the minimum and maximum of the Y-Axis.




The fine-tune section gives unprecedented control to your visualizations, in a nutshell:

    • Abbreviation: This controls the granularity of your data. If you leave Auto selected, Geckoboard will automatically abbreviate when necessary. To avoid abbreviating, select None, or you can manually specify how the numbers are displayed e.g. selecting K would display $2K instead of $2,000.
    • Decimal Places: Precision control for decimal places. You can choose Auto or Fixed. Fixed will allow you to specify up to 6 decimal places.
    • Unit: This gives you total control of the units displayed with your numbers. Auto means Geckoboard will decide how to handle the units for you. This will work in most cases, however there might be specific cases in which this needs to be manually updated. Prefix will add the unit symbol before the number and Suffix will add it after.


You can see the controls in action on the animated GIF below:


Back to top


Line chart

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 dates or datetime fields.

In the the animated .Gif below you will see us adding a line new widget from scratch and showing some of the visualization controls in action.



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.


Column chart

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.


Bar chart

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.



Number widget

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.




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.




Gauges are often used to show a data point that changes over time. The Geck-o-meter 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 Geck-o-meter will take the last value in the field and use it as its current value.


Back to top

Was this article helpful?

Thank you for your feedback!