This repository has been archived by the owner. It is now read-only.
Ruby implementation of the AWS CloudSearch 2011 API -- No longer maintained
Ruby
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.gitignore
.rspec
.rvmrc
Gemfile
LICENSE
README.md
Rakefile
aws_cloud_search.gemspec

README.md

AWSCloudSearch

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

Description

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.

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
  • asari gem: and another Ruby wrapper for the CloudSearch API
  • aws-sdk gem: Amazon's official Ruby wrapper for AWS APIs