AWSCloudSearch

Description

This gem is an implementation of the Amazon Web Service CloudSearch 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.

Roadmap

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

Installation

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

Usage

Note: work in progress

###Initialize the library

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

# if your CloudSearch domain is in a different AWS region and/or availability zone
ds = AWSCloudSearch::CloudSearch.new('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 = AWSCloudSearch::Document.new(true)
doc1.id = '12345677890abcdef'
doc1.lang = 'en'
doc1.add_field('name', 'Jane Williams')
doc1.add_field('type', 'person')

doc2 = AWSCloudSearch::Document.new(true)
doc2.id = '588687626634767634'
doc2.lang = 'en'
doc2.add_field :name, 'Bob Dobalina'
doc2.add_field :type, 'person'

###Add documents to a new document batch

batch = AWSCloudSearch::DocumentBatch.new    
batch.add_document doc1
batch.add_document doc2

###Include document deletes to your document batch

doc3 = AWSCloudSearch::Document.new(true)
doc3.id = 'fedcba0987654321'
batch.delete_document doc3

###Send the document batch

ds.documents_batch(batch)

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

search_request = AWSCloudSearch::SearchRequest.new
search_request.q = "Bob"
search_results = ds.search(search_request)
search_results.hits.each do |hit|
  puts hit['id']
  puts hit['name']
end

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

search_request = AWSCloudSearch::SearchRequest.new
search_request.bq = "type:'person'"
search_results = ds.search(search_request)
search_results.hits.each do |hit|
  puts hit['id']
  puts hit['name']
end

Contributing

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
• aws-sdk gem: Amazon's official Ruby wrapper for AWS APIs