Mode Ruby SDK

Build Status Code Climate Gem Version

This SDK provides a wrapper for the Mode Analytics API.


Add this line to your application's Gemfile:

gem 'mode-sdk'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mode-sdk

Command line importing

The mode_import command line interface allows you to import CSV files from your computer directly into Mode's public data warehouse.

$ mode_import --help
Usage: mode_import [options]
    -h, --help                       Display this help
    -r, --replace                    Replace table if it already exists
    -u, --upload-token=value         Upload token
    -t, --table-name=name            Table name
    -f, --file=value                 CSV file
    -c, --clean                      Clean table data


$ mode_import --file=~/locations.csv --table-name=film_locations --replace

You will be prompted for authentication credentials if MODE_TOKEN and MODE_SECRET environment variables are not set.



Mode::Sdk.configure do |config|
  config.token  = 'token'
  config.secret = 'secret'

You can manage your Mode API tokens here:

1. Upload CSV to Mode

Before importing a table, you will need to upload the raw CSV (with no header) using the Upload class. The first argument can be either a string or an IO-like object.

csv ='sf_film_locations.csv', 'r') { |f| }

upload =
upload.token # => '5b68f4b6a3c6' save this token for step 2

Full Upload API documentation:,header:uploads-upload

2. Import the table

Next, initialize a Table instance with a name:

table ='sf_film_locations')
table.exists? # => true, false

Assign a column schema (required) and description (optional):

table.columns = [
  { name: 'movie_title',  type: 'string' },
  { name: 'release_year', type: 'integer' },
  { name: 'location',     type: 'string' }

table.description = 'Famous film locations in San Francisco'

Then use the upload token from Step 1 to create or replace the table:

table.upload_token = '5b68f4b6a3c6'


3. Check the status of your import

The response from Table#create or Table#replace will indicate the status of your import, including:

  • enqueued
  • running
  • succeeded
  • failed

You can poll this response until your import has completed.



A collection of examples can be found in the mode/mode-ruby-examples repository.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request