Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A wraper to Amazon CloudSearch's API

Merge pull request #9 from firecracker/master

Make cloud_search kaminari-compatible, clarifying incorrect README
latest commit c1bc229217
Paulo Ahagon pahagon authored

Build Status


This is a simple Ruby wrapper around the Amazon's CloudSearch API. It has support for searching (with both simple and boolean queries), pagination and documents indexing.


Add this line to your application's Gemfile:

gem "cloud_search"

And then execute:

$ bundle

Or install it yourself as:

$ gem install cloud_search


The example bellow uses the Amazon's example database called imdb-movies:

Use your AWS CloudSearch configuration

CloudSearch.configure do |config|
  config.domain_id   = "pl6u4t3elu7dhsbwaqbsy3y6be"
  config.domain_name = "imdb-movies"

Search for 'star wars' on 'imdb-movies'

searcher =
resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
         .with_query("star wars")

Or you can search using part of the name

searcher =
resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)

You can also search using boolean queries

searcher =
resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)

You can sort the result using a rank expression (previously created on your CloudSearch domain)

Rank expressions allow you to customize how results are ranked. You can use them to weight specific fields, or limit results only to those that meet a certain numeric threshold.

searcher =
resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)

If you want to rank using descending order, just prepend the expression name with a '-' sign:

resp = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)


resp.results.each do |result|
  movie = result["data"]

  # List of actors on the movie

  # Movie's name

  # A rank number used to sort the results
  # The `text_relevance` key is added by AMS CloudSearch


The results you get back are (currently) API-compatible with will_paginate and kaminari:

searcher =
resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
         .with_query("star wars")

resp.total_entries #=> 5000
resp.total_pages   #=> 167
resp.current_page  #=> 10
resp.offset        #=> 300
resp.page_size     #=> 30

Kaminari users can use the same at_page() and with_items_per_page() methods with the searcher. In the view, paginate will work as expected with the response: <%= paginate @response %>

Indexing documents

document = :type    => "add", # or "delete"
                                     :version => 123,
                                     :id      => 680,
                                     :lang    => :en,
                                     :fields  => {:title => "Lord of the Rings"}

indexer =
indexer << document # add as many documents as you want (CloudSearch currently sets a limit of 5MB per documents batch)


  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
Something went wrong with that request. Please try again.