README.md

CloudSearch

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.

Installation

Add this line to your application's Gemfile:

gem "cloud_search"

And then execute:

$ bundle

Or install it yourself as:

$ gem install cloud_search

Usage

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"
end

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

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

Or you can search using part of the name

searcher = CloudSearch::Searcher.new
resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
         .with_query("matri*")
         .search

You can also search using boolean queries

searcher = CloudSearch::Searcher.new
resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
         .as_boolean_query
         .with_query("year:2000")
         .search

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 = CloudSearch::Searcher.new
resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
           .with_query("matrix")
           .ranked_by("my_rank_expression")

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)
       .with_query("matrix")
       .ranked_by("-my_rank_expression")

Results

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

  # List of actors on the movie
  movie["actor"]

  # Movie's name
  movie["title"]

  # A rank number used to sort the results
  # The `text_relevance` key is added by AMS CloudSearch
  movie["text_relevance"]
end

Pagination

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

searcher = CloudSearch::Searcher.new
resp     = searcher.with_fields(:actor, :director, :title, :year, :text_relevance)
         .with_query("star wars")
         .with_items_per_page(30)
         .at_page(10)
         .search

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 = CloudSearch::Document.new :type    => "add", # or "delete"
                                     :version => 123,
                                     :id      => 680,
                                     :lang    => :en,
                                     :fields  => {:title => "Lord of the Rings"}

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

Contributing

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