elasticsearch-documents 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 09242c5b4dacbea5a8df8b92589cf7da49491d1c
+  data.tar.gz: b26f6777634d3e6e37207eafb0ed96e1def983d7
+SHA512:
+  metadata.gz: 5d7bb17681d33ef53bc909f4089be04971ca9f3b8f355a689f179cf5918ec7e36d1365de24c35aa05920f8ea50df01cef220e36364e17e433c4ac4e856339432
+  data.tar.gz: c778f6377d6243a1999c4edb25daf9a0c3a768f1d8ccd42756c520021d0f6bc0b59e8fdbf37bc9e8f68a2ab7dab2ec6e0d2740f98ea1df9718d7eb516f2b0826

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in elasticsearch-documents.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Ryan Houston and Project 10 LLC (culturalist.com)
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,217 @@
+# Elasticsearch::Extensions::Documents
+
+A service wrapper to manage Elasticsearch index documents
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'elasticsearch-documents'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install elasticsearch-documents
+
+## Configuration
+
+Before making any calls to Elasticsearch you need to configure the `Documents`
+extension.
+
+```ruby
+ES_MAPPINGS = {
+  user: {
+    _all: { analyzer: "snowball" },
+    properties: {
+      id:   { type: "integer", index: :not_analyzed },
+      name: { type: "string", analyzer: "snowball" },
+      bio:  { type: "string", analyzer: "snowball" },
+      updated_at:   { type: "date", include_in_all: false }
+    }
+  }
+}
+
+ES_SETTINGS = {
+  index: {
+    number_of_shards: 3,
+    number_of_replicas: 2,
+  }
+}
+
+Elasticsearch::Extensions::Documents.configure do |config|
+  config.url        = 'http://example.com:9200' # your elasticsearch endpoint
+  config.index_name = 'test_index'              # the name of your index
+  config.mappings   = ES_MAPPINGS               # a hash containing your index mappings
+  config.settings   = ES_SETTINGS               # a hash containing your index settings
+  config.logger     = Logger.new(STDOUT)        # the logger to use. (defaults to Logger.new(STDOUT)
+  config.log        = true                      # if the elasticsearch-ruby should provide logging
+end
+```
+
+If you are using this extension with a Rails application this configuration
+could live in an initializer like `config/initializers/elasticsearch.rb`.
+
+## Usage
+
+The `Documents` extension builds on the
+`elasticsearch-ruby` Gem adding conventions and helper classes to aide in the
+serialization and flow of data between your application code and the
+elasticsearch-ruby interface. To accomplish this the application data models
+will be serialized into `Document`s that can be indexed and searched with the
+`elasticsearch-ruby` Gem.
+
+### Saving a Document
+If your application has a model called `User` that you wanted to index you would
+create a `Document` that defined how the `User` is stored in the index.
+
+```ruby
+class UserDocument < Elasticsearch::Extensions::Documents::Document
+  indexes_as_type :user
+
+  def as_hash
+    {
+      name:   object.name,
+      title:  object.title,
+      bio:    object.bio,
+    }
+  end
+
+end
+
+user = User.new  # could be a PORO or an ActiveRecord model
+user_doc = UserDocument.new(user)
+
+index = Elasticsearch::Extensions::Documents::Index.new
+index.index(user_doc)
+```
+
+### Deleting a Document
+Deleting a document is just as easy
+
+```ruby
+user_doc = UserDocument.new(user)
+index.delete(user_doc)
+```
+
+### Searching for Documents
+Create classes which include `Elasticsearch::Extensions::Documents::Queryable`.
+Then implement a `#as_hash` method to define the JSON structure of an
+Elasticsearch Query using the [Query DSL][es-query-dsl]. This hash should be
+formatted appropriately to be passed on to the
+[Elasticsearch::Transport::Client#search][es-ruby-search-src] method.
+
+```ruby
+class GeneralSiteSearchQuery
+  include Elasticsearch::Extensions::Documents::Queryable
+
+  def as_hash
+    {
+      index: 'test_index',
+      body: {
+        query: {
+          query_string: {
+            analyzer: "snowball",
+            query:    "something to search for",
+          }
+        }
+      }
+    }
+  end
+end
+```
+
+You could elaborate on this class with a constructor that takes the search
+term and other options specific to your use case as arguments.
+
+You can then call the `#execute` method to run the query. The Elasticsearch JSON
+response will be returned in whole wrapped in a
+[`Hashie::Mash`](https://github.com/intridea/hashie) instance to allow
+the results to be interacted with in object notation instead of hash notation.
+
+```ruby
+query = GeneralSiteSearchQuery.new
+results = query.execute
+results.hits.total
+results.hits.max_score
+results.hits.hits.each { |hit| puts hit._source }
+```
+
+You can also easily define a custom result format by overriding the
+`#parse_results` method in your Queryable class.
+
+```ruby
+class GeneralSiteSearchQuery
+  include Elasticsearch::Extensions::Documents::Queryable
+
+  def as_hash
+    # your query structure here
+  end
+
+  def parse_results(raw_results)
+    CustomQueryResults.new(raw_results)
+  end
+end
+```
+
+Here the `CustomQueryResults` gets passed the `Hashie::Mash` results object and
+can parse and coerce that data into whatever structure is most useful for your
+application.
+
+
+### Index Management
+
+The Indexer uses the `Elasticsearch::Extensions::Documents.configuration`
+to create the index with the configured `#index_name`, `#mappings`, and
+`#settings`.
+
+```ruby
+indexer = Elasticsearch::Extensions::Documents::Indexer.new
+indexer.create_index
+indexer.drop_index
+```
+
+The `Indexer` can `#bulk_index` documents sending multiple documents to
+Elasticsearch in a single request. This may be more efficient when
+programmatically re-indexing entire sets of documents.
+
+```ruby
+user_documents = users.collect { |user| UserDocument.new(user) }
+indexer.bulk_index(user_documents)
+```
+
+The `Indexer` accepts a block to the `#reindex` method to encapsulate the
+processes of dropping the old index, creating a new index with the latest
+configured mappings and settings, and bulk indexing a set of documents into the
+newly created index. The content of the block should be the code that creates
+your documents in batches and passes them to the `#bulk_index` method of the
+`Indexer`.
+
+```ruby
+indexer.reindex do |indexer|
+
+  # For ActiveRecord you may want to find_in_batches
+  User.find_in_batches(batch_size: 500) do |batch|
+    documents = batch.map { |user| UserDocument.new(user) }
+    indexer.bulk_index(documents)
+  end
+
+  # Otherwise you can add whatever logic you need to bulk index your documents
+  documents = users.map { |model| UserDocument.new(model) }
+  indexer.bulk_index(documents)
+end
+```
+## 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
+
+
+[es-query-dsl]: http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html
+[es-ruby-search-src]: https://github.com/elasticsearch/elasticsearch-ruby/blob/master/elasticsearch-api/lib/elasticsearch/api/actions/search.rb
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec
+

data/elasticsearch-documents.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'elasticsearch/extensions/documents/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "elasticsearch-documents"
+  spec.version       = Elasticsearch::Extensions::Documents::VERSION
+  spec.required_ruby_version = ">= 1.9.3"
+
+  spec.authors       = ["Ryan Houston"]
+  spec.email         = ["ryanhouston83@gmail.com"]
+  spec.summary       = %q{A service wrapper to manage elasticsearch index documents}
+  spec.description   = %q{Define mappings to turn model instances into indexable search documents}
+  spec.homepage      = "http://github.com/RyanHouston/elasticsearch-documents"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+
+  spec.add_runtime_dependency "elasticsearch"
+  spec.add_runtime_dependency "hashie"
+end
+

data/lib/elasticsearch/extensions/documents/document.rb

@@ -0,0 +1,32 @@
+module Elasticsearch
+  module Extensions
+    module Documents
+      class Document
+        attr_reader :object
+
+        def initialize(object)
+          @object = object
+        end
+
+        class << self
+          def indexes_as_type(type)
+            @index_type = type.to_s
+          end
+
+          attr_reader :index_type
+          alias :type :index_type
+        end
+
+        def id
+          object.id
+        end
+
+        def as_hash
+          raise NotImplementedError, 'A subclass should define this method'
+        end
+
+      end
+    end
+  end
+end
+

data/lib/elasticsearch/extensions/documents/index.rb

@@ -0,0 +1,47 @@
+require 'hashie/mash'
+
+module Elasticsearch
+  module Extensions
+    module Documents
+      class Index
+        attr_reader :client
+
+        def initialize(client = nil)
+          @client = client || Documents.client
+        end
+
+        def index(document)
+          payload = {
+            index:  Documents.index_name,
+            type:   document.class.type,
+            id:     document.id,
+            body:   document.as_hash,
+          }
+          client.index payload
+        end
+
+        def delete(document)
+          payload = {
+            index:  Documents.index_name,
+            type:   document.class.type,
+            id:     document.id,
+          }
+          client.delete payload
+        rescue Elasticsearch::Transport::Transport::Errors::NotFound => not_found
+          Documents.logger.info "[Documents] Attempted to delete missing document: #{not_found}"
+        end
+
+        def search(query)
+          response = client.search(query.as_hash)
+          Hashie::Mash.new(response)
+        end
+
+        def refresh
+          client.indices.refresh index: Documents.index_name
+        end
+
+      end
+    end
+  end
+end
+

data/lib/elasticsearch/extensions/documents/indexer.rb

@@ -0,0 +1,60 @@
+module Elasticsearch
+  module Extensions
+    module Documents
+      class Indexer
+        attr_reader :client, :config
+
+        def initialize(options = {})
+          @client = options.fetch(:client) { Documents.client }
+          @config = options.fetch(:config) { Documents.configuration }
+        end
+
+        def drop_index
+          client.indices.delete(index: config.index_name) if index_exists?
+        end
+
+        def index_exists?
+          client.indices.exists(index: config.index_name)
+        end
+
+        def create_index
+          client.indices.create(index: config.index_name, body: create_index_body) unless index_exists?
+        end
+
+        def create_index_body
+          {}.tap do |body|
+            body[:settings] = config.settings if config.settings
+            body[:mappings] = config.mappings if config.mappings
+          end
+        end
+
+        def reindex(&block)
+          drop_index
+          create_index
+          block.call(self) if block_given?
+        end
+
+        def bulk_index(documents)
+          client.bulk body: bulk_index_operations(documents)
+        end
+
+        def bulk_index_operations(documents)
+          documents.collect { |document| bulk_index_operation_hash(document) }
+        end
+
+        def bulk_index_operation_hash(document)
+          {
+            index: {
+              _index: config.index_name,
+              _type:  document.class.type,
+              _id:    document.id,
+              data:   document.as_hash,
+            }
+          }
+        end
+
+      end
+    end
+  end
+end
+

data/lib/elasticsearch/extensions/documents/queryable.rb

@@ -0,0 +1,31 @@
+module Elasticsearch
+  module Extensions
+    module Documents
+      module Queryable
+
+        def as_hash
+          raise NotImplementedError, "#{self.class.name} should implement #as_hash method"
+        end
+
+        def execute
+          raw_results = index.search(self)
+          parse_results(raw_results)
+        end
+
+        def parse_results(raw_results)
+          raw_results
+        end
+
+        def index_name
+          Elasticsearch::Extensions::Documents.index_name
+        end
+
+        def index
+          @index ||= Elasticsearch::Extensions::Documents::Index.new
+        end
+
+      end
+    end
+  end
+end
+

data/lib/elasticsearch/extensions/documents/utils.rb

@@ -0,0 +1,31 @@
+module Elasticsearch
+  module Extensions
+    module Documents
+      module Utils
+
+        def self.sanitize_for_query_string_query(query_string)
+          # http://stackoverflow.com/questions/16205341/symbols-in-query-string-for-elasticse
+          # Escape special characters
+          # http://lucene.apache.org/core/old_versioned_docs/versions/2_9_1/queryparsersyntax
+          escaped_characters = Regexp.escape('/\\+-&|!(){}[]^~*?:')
+          query_string = query_string.gsub(/([#{escaped_characters}])/, '\\\\\1')
+
+          # AND, OR and NOT are used by lucene as logical operators. We need
+          # to escape them
+          ['AND', 'OR', 'NOT'].each do |word|
+            escaped_word = word.split('').map {|char| "\\#{char}" }.join('')
+            query_string = query_string.gsub(/\s*\b(#{word.upcase})\b\s*/, " #{escaped_word} ")
+          end
+
+          # Escape odd quotes
+          quote_count = query_string.count '"'
+          query_string = query_string.gsub(/(.*)"(.*)/, '\1\"\2') if quote_count % 2 == 1
+
+          query_string
+        end
+
+      end
+    end
+  end
+end
+

data/lib/elasticsearch/extensions/documents/version.rb

@@ -0,0 +1,8 @@
+module Elasticsearch
+  module Extensions
+    module Documents
+      VERSION = "0.0.1"
+    end
+  end
+end
+

data/lib/elasticsearch/extensions/documents.rb

@@ -0,0 +1,50 @@
+require "elasticsearch"
+require "logger"
+require "elasticsearch/extensions/documents/version"
+require "elasticsearch/extensions/documents/document"
+require "elasticsearch/extensions/documents/index"
+require "elasticsearch/extensions/documents/indexer"
+require "elasticsearch/extensions/documents/queryable"
+require "elasticsearch/extensions/documents/utils"
+
+module Elasticsearch
+  module Extensions
+    module Documents
+
+      class << self
+        attr_accessor :client, :configuration
+
+        def client
+          @client ||= Elasticsearch::Client.new({
+            host: self.configuration.url,
+            log:  self.configuration.log,
+          })
+        end
+
+        def configure
+          self.configuration ||= Configuration.new
+          yield configuration
+        end
+
+        def index_name
+          self.configuration.index_name
+        end
+
+        def logger
+          self.configuration.logger
+        end
+      end
+
+      class Configuration
+        attr_accessor :url, :index_name, :mappings, :settings, :log, :logger
+
+        def initialize
+          @logger = Logger.new(STDOUT)
+          @log    = true
+        end
+      end
+
+    end
+  end
+end
+

data/lib/elasticsearch-documents.rb

@@ -0,0 +1,2 @@
+require "elasticsearch/extensions/documents"
+

data/spec/elasticsearch/extensions/documentor_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+require 'logger'
+
+module Elasticsearch::Extensions
+  describe Documents do
+
+    let(:logger) { Logger.new(STDOUT) }
+    before do
+      Documents.configure do |config|
+        config.logger     = logger
+        config.log        = true
+      end
+    end
+
+    describe '.configuration' do
+      subject(:config) { Documents.configuration }
+
+      specify { expect(config.url).to eql 'http://example.com:9200' }
+      specify { expect(config.index_name).to eql 'test_index' }
+      specify { expect(config.mappings).to eql( :fake_mappings ) }
+      specify { expect(config.settings).to eql( :fake_settings ) }
+      specify { expect(config.logger).to equal logger }
+      specify { expect(config.logger).to be_true }
+    end
+
+    describe '.client' do
+      subject(:client) { Documents.client }
+
+      it 'creates an instance of Elasticsearch::Transport::Client' do
+        expect(client).to be_instance_of Elasticsearch::Transport::Client
+      end
+
+      it 'caches the client instance' do
+        c1 = Documents.client
+        c2 = Documents.client
+        expect(c1).to equal c2
+      end
+    end
+
+    describe '.index_name' do
+      specify { expect(Documents.index_name).to eq 'test_index' }
+    end
+
+    describe '.logger' do
+      specify { expect(Documents.logger).to equal logger }
+    end
+
+  end
+end
+

data/spec/elasticsearch/extensions/documents/document_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+module Elasticsearch
+  module Extensions
+    module Documents
+      Documents.configure {|config| config.index_name = 'test_index' }
+
+      describe Document do
+        let(:document_class) { Class.new(Elasticsearch::Extensions::Documents::Document) }
+        let(:model) { double(:model) }
+        subject(:document) { document_class.new(model) }
+
+        describe '.indexes_as_type' do
+          it 'sets the index type name' do
+            document_class.indexes_as_type('test_type')
+            expect(document_class.index_type).to eq 'test_type'
+            expect(document_class.type).to eq 'test_type'
+          end
+        end
+
+        describe '#id' do
+          it 'delegates to the model' do
+            expect(model).to receive(:id)
+            document.id
+          end
+        end
+
+        describe '#as_hash' do
+          it 'raises an error if not redefined by a subclass' do
+            expect{ document.as_hash }.to raise_error NotImplementedError
+          end
+        end
+
+      end
+    end
+  end
+end
+

data/spec/elasticsearch/extensions/documents/index_spec.rb

@@ -0,0 +1,98 @@
+require 'spec_helper'
+
+module Elasticsearch
+  module Extensions
+    module Documents
+      class TestDocument < Document
+        indexes_as_type :test_doc
+        def as_hash
+          { valueA: :a, valueB: :b }
+        end
+      end
+
+      describe Index do
+        let(:client) { double(:client) }
+        let(:model) { double(:model, id: 1) }
+        let(:document) { TestDocument.new(model) }
+        subject(:index) { Index.new(client) }
+
+        describe '#index' do
+          it 'adds or replaces a document in the search index' do
+            payload = {
+              index: 'test_index',
+              type: 'test_doc',
+              id: 1,
+              body: {valueA: :a, valueB: :b}
+            }
+            expect(client).to receive(:index).with(payload)
+            index.index document
+          end
+        end
+
+        describe '#delete' do
+          it 'removes a document from the search index' do
+            payload = {
+              index: 'test_index',
+              type: 'test_doc',
+              id: 1,
+            }
+            expect(client).to receive(:delete).with(payload)
+            index.delete document
+          end
+        end
+
+        describe '#search' do
+          let(:query_params) do
+            {
+              index: 'test_index',
+              query: {
+                query_string: "search term",
+                analyzer:     "snowball",
+              }
+            }
+          end
+
+          let(:response) do
+            {
+              "hits" => {
+                "total" => 4000,
+                "max_score" => 4.222,
+                "hits" => [
+                  {"_index" => "test_index",
+                    "_type"  => "user",
+                    "_id"    => 42,
+                    "_score" => 4.222,
+                    "_source" => { "name" => "Joe" }
+                  }
+                ],
+              }
+            }
+          end
+
+          let(:query) { double(:query, as_hash: query_params) }
+
+          it 'passes on the query request body to the client' do
+            expect(client).to receive(:search).with(query_params)
+            index.search query
+          end
+
+          it 'returns a Hashie::Mash instance' do
+            expect(client).to receive(:search).with(query_params).and_return(response)
+            response = index.search(query)
+            response.should be_kind_of Hashie::Mash
+          end
+        end
+
+        describe '#refresh' do
+          it 'delegates to the client#indices' do
+            indices = double(:indices, refresh: true)
+            client.stub(:indices).and_return(indices)
+            expect(indices).to receive(:refresh).with(index: 'test_index')
+            index.refresh
+          end
+        end
+
+      end
+    end
+  end
+end

data/spec/elasticsearch/extensions/documents/indexer_spec.rb

@@ -0,0 +1,112 @@
+require 'spec_helper'
+
+module Elasticsearch
+  module Extensions
+    module Documents
+      describe Indexer do
+
+        let(:indices) { double(:indices) }
+        let(:client) { double(:client, indices: indices) }
+        subject(:indexer) { Indexer.new(client: client) }
+
+        describe '#create_index' do
+          it 'creates the index if it does not exist' do
+            expected_client_params = {
+              index: 'test_index',
+              body:  {
+                settings: :fake_settings,
+                mappings: :fake_mappings,
+              }
+            }
+            indices.stub(:exists).and_return(false)
+            expect(indices).to receive(:create).with(expected_client_params)
+            indexer.create_index
+          end
+
+          it 'does not create the index if it exists' do
+            indices.stub(:exists).and_return(true)
+            expect(indices).not_to receive(:create)
+            indexer.create_index
+          end
+        end
+
+        describe '#drop_index' do
+          it 'drops the index if it exists' do
+            indices.stub(:exists).and_return(true)
+            expect(indices).to receive(:delete)
+            indexer.drop_index
+          end
+
+          it 'does not drop the index if it does not exist' do
+            indices.stub(:exists).and_return(false)
+            expect(indices).not_to receive(:delete)
+            indexer.drop_index
+          end
+        end
+
+        describe '#index_exists?' do
+          it 'delegates to the client indices' do
+            expect(indices).to receive(:exists).with(index: 'test_index')
+            indexer.index_exists?
+          end
+        end
+
+        describe '#bulk_index' do
+          let(:models) { [double(:model, id: 1, a: 1, b: 2), double(:model, id: 2, a: 3, b: 4)] }
+          let(:documents) { models.map { |m| TestDocumentsDocument.new(m) } }
+
+          it 'passes operations to the client bulk action' do
+            expected_body = {
+              body: [
+                {
+                  index: {
+                    _index: 'test_index',
+                    _type:  'documents_test',
+                    _id:    1,
+                    data:   { a: 1, b: 2 },
+                  }
+                },
+                {
+                  index: {
+                    _index: 'test_index',
+                    _type:  'documents_test',
+                    _id:    2,
+                    data:   { a: 3, b: 4 },
+                  },
+                }
+              ]
+            }
+            expect(client).to receive(:bulk).with(expected_body)
+            indexer.bulk_index(documents)
+          end
+        end
+
+        describe '#reindex' do
+
+          it 'drops the index if exists' do
+            indices.stub(:exists).and_return(true)
+            expect(indexer).to receive(:drop_index)
+            indexer.reindex
+          end
+
+          it 'creates a new index' do
+            indices.stub(:exists).and_return(false)
+            expect(indexer).to receive(:create_index)
+            indexer.reindex
+          end
+
+          it 'calls a given block to batch index the documents' do
+            indexer.stub(:drop_index)
+            indexer.stub(:create_index)
+            documents = double(:documents)
+            expect(indexer).to receive(:bulk_index).with(documents)
+            indexer.reindex { |indexer| indexer.bulk_index(documents) }
+          end
+
+        end
+
+      end
+    end
+  end
+end
+

data/spec/elasticsearch/extensions/documents/queryable_spec.rb

@@ -0,0 +1,55 @@
+require 'spec_helper'
+require 'elasticsearch/extensions/documents/queryable'
+
+module Elasticsearch
+  module Extensions
+    module Documents
+      describe Queryable do
+
+        context 'when a subclass is not correctly implemented' do
+          class InvalidQuery
+            include Queryable
+          end
+
+          subject(:query) { InvalidQuery.new }
+
+          it 'raises an error when a query is run' do
+            expect { query.execute }.to raise_error NotImplementedError
+          end
+        end
+
+        context 'when the query class defines a custom result format' do
+          class CustomResultsQuery
+            include Queryable
+
+            def as_hash
+              { query: 'foo' }
+            end
+
+            def parse_results(raw_results)
+              { custom_format: raw_results }
+            end
+          end
+
+          subject(:query) { CustomResultsQuery.new }
+
+          describe '#execute' do
+            it 'provides the search results in a custom format' do
+              query.index.stub(:search).and_return({ foo: :bar})
+              expect(query.execute).to eql({ custom_format: { foo: :bar } })
+            end
+          end
+
+          describe '#index_name' do
+            it 'provides the index_name from the config' do
+              expect(query.index_name).to eql 'test_index'
+            end
+          end
+
+        end
+
+      end
+    end
+  end
+end
+

data/spec/elasticsearch/extensions/documents/utils_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+require 'elasticsearch/extensions/documents/utils'
+
+module Elasticsearch
+  module Extensions
+    module Documents
+      describe Utils do
+
+        describe '.sanitize_for_query_string_query' do
+          subject { Utils.public_method(:sanitize_for_query_string_query) }
+
+          it 'escapes special syntax characters' do
+            %w(/ \\ + - & | ! ( ) { } [ ] ^ ~ * ? :).each do |char|
+              term = 'a' + char + 'b'
+              sanitized_term = 'a\\' + char + 'b'
+              expect(subject.call(term)).to eq sanitized_term
+            end
+          end
+
+          it 'escapes boolean terms' do
+            term = 'this AND that'
+            expect(subject.call(term)).to eq 'this \A\N\D that'
+            term = 'this OR that'
+            expect(subject.call(term)).to eq 'this \O\R that'
+            term = 'this NOT that'
+            expect(subject.call(term)).to eq 'this \N\O\T that'
+          end
+
+          it 'escapes odd quotes' do
+            term = 'A "quoted" te"m'
+            expect(subject.call(term)).to eq 'A "quoted" te\"m'
+          end
+        end
+
+      end
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,28 @@
+require 'elasticsearch-documents'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  config.order = 'random'
+end
+
+Elasticsearch::Extensions::Documents.configure do |config|
+  config.url        = 'http://example.com:9200'
+  config.index_name = 'test_index'
+  config.settings   = :fake_settings
+  config.mappings   = :fake_mappings
+end
+
+class TestDocumentsDocument < Elasticsearch::Extensions::Documents::Document
+  indexes_as_type :documents_test
+
+  def as_hash
+    {
+      a: object.a,
+      b: object.b,
+    }
+  end
+end
+

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: elasticsearch-documents
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ryan Houston
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: elasticsearch
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Define mappings to turn model instances into indexable search documents
+email:
+- ryanhouston83@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- elasticsearch-documents.gemspec
+- lib/elasticsearch-documents.rb
+- lib/elasticsearch/extensions/documents.rb
+- lib/elasticsearch/extensions/documents/document.rb
+- lib/elasticsearch/extensions/documents/index.rb
+- lib/elasticsearch/extensions/documents/indexer.rb
+- lib/elasticsearch/extensions/documents/queryable.rb
+- lib/elasticsearch/extensions/documents/utils.rb
+- lib/elasticsearch/extensions/documents/version.rb
+- spec/elasticsearch/extensions/documentor_spec.rb
+- spec/elasticsearch/extensions/documents/document_spec.rb
+- spec/elasticsearch/extensions/documents/index_spec.rb
+- spec/elasticsearch/extensions/documents/indexer_spec.rb
+- spec/elasticsearch/extensions/documents/queryable_spec.rb
+- spec/elasticsearch/extensions/documents/utils_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/RyanHouston/elasticsearch-documents
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: A service wrapper to manage elasticsearch index documents
+test_files:
+- spec/elasticsearch/extensions/documentor_spec.rb
+- spec/elasticsearch/extensions/documents/document_spec.rb
+- spec/elasticsearch/extensions/documents/index_spec.rb
+- spec/elasticsearch/extensions/documents/indexer_spec.rb
+- spec/elasticsearch/extensions/documents/queryable_spec.rb
+- spec/elasticsearch/extensions/documents/utils_spec.rb
+- spec/spec_helper.rb