SheetMapper is about taking a google spreadsheet and converting a set of data rows into ruby objects.


Setup in Gemfile:

# Gemfile

gem 'sheet_mapper'

and then require 'sheet_mapper' and you are done!


First, you describe how to map a spreadsheet into data rows with a sheet object mapper:

class SomeMapper < SheetMapper::Base
  # Defines each column for a row and maps each column to an attribute
  columns :foo, :bar, :baz

  # Defines the condition for a row to be considered valid
  def valid_row?

  # Convert is_notable column to a boolean from raw string
  # Any methods named after a column will override the default value
  def is_notable

The mapper describes the column mappings and transformations to turn a spreadsheet row into a ruby object. Then you can apply a mapper to any worksheet (collection):

# Login and access a particular spreadsheet by key
sheet =>SomeMapper, :key=>'k', :login => 'u', :password => 'p')
# Find a particular worksheet (collection) by title
collection = sheet.find_collection_by_title('title')
# Iterate over the records within the worksheet
records = collection.each do |record|
  p record.attributes
  # => { :foo => "...", :bar => false, ... }

You can then work with objects within the collection and access their attributes. You can also modify objects and persist the changes back to the collection (worksheet):

# Fetch the second data row from the spreadsheet
record = collection.records[1]
record[:foo] = "other"
# Persist change of value to worksheet
# or more explicitly

If you want to reset changes made to your records, just use the reload method:

# Fetch the second data row from the spreadsheet
record = collection.records[1]
record[:foo] = "other"
# Reset unsaved changes

You may also come across situations where you need access to 'meta' information associated with the collection. Use the 'cell' method to access arbitrary data points:

# Accesses row 1, column 2 within the worksheet
collection.cell(1, 2) => "foo"


SheetMapper was created by Nathan Esquenazi at Miso in 2012.


SheetMapper is a new gem and I would love any feedback and/or pull requests.

Continuous Integration

Continuous Integration status

CI is hosted by


Check LICENSE but of course feel free to use this in any projects.