Create a new dataset using Ruby

Follow this guide to add your first Dataset to Geckoboard using Ruby.

Before you start

Ruby is just one of the programming languages you can use to add a Dataset to Geckoboard. We have also have walkthroughs for cURL, Node.js, and Python.

We also have a dedicated guide to sending SQL data to datasets using either a MacOS, Linux or Windows machine or server.

Installation

To begin, add this line to your application’s Gemfile:

gem 'geckoboard-ruby'

And then execute:

$ bundle

Alternatively, install it yourself as:

$ gem install geckoboard-ruby

Require the gem and create an instance of the client:

require 'geckoboard'
client = Geckoboard.client(api_key)

Authenticate your account

Authenticate your account when using the API by including your personal API key in the request.

client.ping

Example authentication

Geckoboard.client('good-api-key').ping # => true
Geckoboard.client('bad-api-key').ping # => raises Geckoboard::UnauthorizedError

Note

You can find your API key by following these steps.

Important note

Your Geckoboard API key is just as powerful as your login credentials, so keep it safe. Do not share it in publicly accessible areas such GitHub, client-side code, and so forth.

Get help

If you’re having problems with authentication then you can get in contact with our Customer Success team who can assist you.

Make a dataset

Find and verify an existing dataset or create a new dataset with the find_or_create method.

You’ll need to give your dataset an id so that you can find it easily in Geckoboard.

client.datasets.find_or_create(id, fields: fields)

Example

dataset = client.datasets.find_or_create('sales.by_day', fields: [
  Geckoboard::MoneyField.new(:amount, name: 'Amount', currency_code: 'USD', optional: false),
  Geckoboard::DateTimeField.new(:timestamp, name: 'Time'),
], unique_by: [:timestamp])

unique_by is an optional array of one or more field names whose values will be unique across all your records.

fields is an object with keys for each column in your dataset. The value describes the type for that column.

Available field types:

  • DateField
  • DateTimeField
  • NumberField
  • PercentageField
  • StringField
  • MoneyField

Important note

You must use lower case letters for field names.

Add data to the dataset for the first time

To add data to the dataset for the first time, you must use the PUT method. Adding data will, effectively, replace will delete all the existing data within the dataset and then write the new data. Your dataset will contain only the new records that you just pushed.

dataset.put(items)

Example

dataset.put([
  {
    timestamp: DateTime.new(2018, 1, 2, 12, 0, 0),
    amount: 40900
  },
  {
    timestamp: DateTime.new(2018, 1, 3, 12, 0, 0),
    amount: 16400
  }
])

Append data to the dataset

You can append records to your dataset by using the POST method. These new records will be added to the existing contents of your datasets.

dataset.post(items, delete_by: optional_name_of_a_date_or_datetime_field)

Example:

dataset.post([
  {
    timestamp: DateTime.new(2018, 1, 2, 12, 0, 0),
    amount: 40900
  },
  {
    timestamp: DateTime.new(2018, 1, 3, 12, 0, 0),
    amount: 16400
  }
], delete_by: :timestamp)

Should the number of records in your dataset exceed the limit following a POST the oldest records (by insertion time) will be removed. This behaviour can be overridden by using the delete_by option when appending new records.

Next steps

Assuming you’ve encountered no errors, then that’s it! You've created a new dataset using Ruby.

You can find more detailed information about configuring your dataset in our API Reference.

You can also find instructions on how to delete this dataset.

Was this article helpful?

Awesome! 👍  Thanks so much for your feedback!