Skip to content
This repository has been archived by the owner. It is now read-only.
Ruby implementation of the AWS CloudSearch 2011 API -- No longer maintained
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


NOTICE: This gem is no longer maintained.
It is now provided as reference for those operating with a CloudSearch 2011 backed search system.
We recommend updating to the current (2013) API and the official aws/aws-sdk-ruby gems


This gem is an implementation of the Amazon Web Service CloudSearch 2011 API.

The AWS CloudSearch service is comprised of three API end-points:

  • search
  • document batching
  • configuration

This gem currently supports only the search and document batching APIs. To access the CloudSearch configuration API from Ruby, use the aws-sdk gem.


Spoke developed this library in a short period of time in order to migrate from IndexTank to AWS CloudSearch. As such, there are a few features that are missing that we would like to build over time.

  • Implementation of the configuration API
  • Query builder
  • Faceting helpers
  • Spec tests that stub the AWS CloudSearch service
  • Sample usage in this README


Add this line to your application's Gemfile:

gem 'aws_cloud_search'

And then execute:

$ bundle

Or install it yourself as:

$ gem install aws_cloud_search


Note: work in progress

###Initialize the library

# if your CloudSearch domain is in the us-east-1 region and availability zone
ds ='your-domain-name-53905x4594jxty')

# if your CloudSearch domain is in a different AWS region and/or availability zone
ds ='your-domain-53905x4594jxty', 'us-west-2')

Better yet, store those values in a YAML configuration file or in environment variables.

###Create some documents Since AWS charges per batch, it is best to batch as many documents as you can in each batch. Document#new takes an optional parameter auto_version which you set to true to automatically set the version, the default value is false.

doc1 = = '12345677890abcdef'
doc1.lang = 'en'
doc1.add_field('name', 'Jane Williams')
doc1.add_field('type', 'person')

doc2 = = '588687626634767634'
doc2.lang = 'en'
doc2.add_field :name, 'Bob Dobalina'
doc2.add_field :type, 'person'

###Add documents to a new document batch

batch =    
batch.add_document doc1
batch.add_document doc2

###Include document deletes to your document batch

doc3 = = 'fedcba0987654321'
batch.delete_document doc3

###Send the document batch


###Searching Text Fields with the Query Parameter See the related CloudSearch documentation

search_request =
search_request.q = "Bob"
search_results =
search_results.hits.each do |hit|
  puts hit['id']
  puts hit['name']

###Searching Literal Fields with a Boolean Query See the related CloudSearch documentation

search_request = = "type:'person'"
search_results =
search_results.hits.each do |hit|
  puts hit['id']
  puts hit['name']


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

Version History

0.0.2 Added support for faceting

See Also

  • cloud_search gem: another Ruby wrapper for the CloudSearch API
  • asari gem: and another Ruby wrapper for the CloudSearch API
  • aws-sdk gem: Amazon's official Ruby wrapper for AWS APIs
You can’t perform that action at this time.