search

spokesoftware / aws_cloud_search

Ruby implementation of the AWS CloudSearch 2011 API -- No longer maintained
Other
49 stars 24 forks source link

readme

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:

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.

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