elasticsearch-api 0.0.2

data/lib/elasticsearch/api/actions/search.rb

@@ -0,0 +1,145 @@
+module Elasticsearch
+  module API
+    module Actions
+
+      # Return documents matching a query, as well as aggregations (facets), highlighted snippets, suggestions, etc.
+      #
+      # The search API is used to query one or more indices either using simple
+      # [query string queries](http://www.elasticsearch.org/guide/reference/api/search/uri-request/)
+      # as the `:q` argument , or by passing the
+      # [full request definition](http://www.elasticsearch.org/guide/reference/api/search/request-body/)
+      # in the [Query DSL](http://www.elasticsearch.org/guide/reference/query-dsl/) as the `:body` argument.
+      #
+      # @example Search with a simple query string query
+      #
+      #     client.search index: 'myindex', q: 'title:test'
+      #
+      # @example Passing a full request definition in the Elasticsearch's Query DSL as a `Hash`
+      #
+      #     client.search index: 'myindex',
+      #                   body: {
+      #                     query: { match: { title: 'test' } },
+      #                     facets: { tags: { terms: { field: 'tags' } } }
+      #                   }
+      #
+      # @example Passing the search definition as a `String`, built with a JSON builder
+      #
+      #     require 'jbuilder'
+      #
+      #     json = Jbuilder.encode do |json|
+      #       json.query do
+      #         json.match do
+      #           json.title do
+      #             json.query    'test 1'
+      #             json.operator 'and'
+      #           end
+      #         end
+      #       end
+      #     end
+      #
+      #     client.search index: 'myindex', body: json
+      #
+      # @example Wrapping the result in [`Hashie::Mash`](https://github.com/intridea/hashie) for easier access
+      #
+      #     response = client.search index: 'myindex',
+      #                              body: {
+      #                                query:  { match: { title: 'test' } },
+      #                                facets: { tags:  { terms: { field: 'tags' } } }
+      #                              }
+      #
+      #     response = Hashie::Mash.new response
+      #
+      #     response.hits.hits.first._source.title
+      #
+      #     response.facets.tags.terms.to_a.map { |f| "#{f.term} [#{f.count}]" }.join(', ')
+      #
+      # @option arguments [List] :index A comma-separated list of index names to search; use `_all`
+      #                                 or empty string to perform the operation on all indices
+      # @option arguments [List] :type A comma-separated list of document types to search;
+      #                                leave empty to perform the operation on all types
+      # @option arguments [Hash] :body The search definition using the Query DSL
+      # @option arguments [String] :analyzer The analyzer to use for the query string
+      # @option arguments [Boolean] :analyze_wildcard Specify whether wildcard and prefix queries should be analyzed
+      #                                               (default: false)
+      # @option arguments [String] :default_operator The default operator for query string query (AND or OR)
+      #                                              (options: AND, OR)
+      # @option arguments [String] :df The field to use as default where no field prefix is given in the query string
+      # @option arguments [Boolean] :explain Specify whether to return detailed information about score computation
+      #                                      as part of a hit
+      # @option arguments [List] :fields A comma-separated list of fields to return as part of a hit
+      # @option arguments [Number] :from Starting offset (default: 0)
+      # @option arguments [String] :ignore_indices When performed on multiple indices, allows to ignore `missing` ones
+      #                                            (options: none, missing)
+      # @option arguments [List] :indices_boost Comma-separated list of index boosts
+      # @option arguments [Boolean] :lenient Specify whether format-based query failures
+      #                                      (such as providing text to a numeric field) should be ignored
+      # @option arguments [Boolean] :lowercase_expanded_terms Specify whether query terms should be lowercased
+      # @option arguments [String] :preference Specify the node or shard the operation should be performed on
+      #                                        (default: random)
+      # @option arguments [String] :q Query in the Lucene query string syntax
+      # @option arguments [List] :routing A comma-separated list of specific routing values
+      # @option arguments [Duration] :scroll Specify how long a consistent view of the index should be maintained
+      #                                      for scrolled search
+      # @option arguments [String] :search_type Search operation type (options: query_then_fetch, query_and_fetch,
+      #                                         dfs_query_then_fetch, dfs_query_and_fetch, count, scan)
+      # @option arguments [Number] :size Number of hits to return (default: 10)
+      # @option arguments [List] :sort A comma-separated list of <field>:<direction> pairs
+      # @option arguments [String] :source The URL-encoded request definition using the Query DSL
+      #                                    (instead of using request body)
+      # @option arguments [List] :stats Specific 'tag' of the request for logging and statistical purposes
+      # @option arguments [String] :suggest_field Specify which field to use for suggestions
+      # @option arguments [String] :suggest_mode Specify suggest mode (options: missing, popular, always)
+      # @option arguments [Number] :suggest_size How many suggestions to return in response
+      # @option arguments [Text] :suggest_text The source text for which the suggestions should be returned
+      # @option arguments [Time] :timeout Explicit operation timeout
+      # @option arguments [Boolean] :version Specify whether to return document version as part of a hit
+      #
+      # @return [Hash]
+      #
+      # @see http://www.elasticsearch.org/guide/reference/api/search/
+      # @see http://www.elasticsearch.org/guide/reference/api/search/request-body/
+      #
+      def search(arguments={})
+        arguments[:index] = '_all' if ! arguments[:index] && arguments[:type]
+
+        method = 'GET'
+        path   = Utils.__pathify( Utils.__listify(arguments[:index]), Utils.__listify(arguments[:type]), '_search' )
+        params = arguments.select do |k,v|
+          [ :analyzer,
+            :analyze_wildcard,
+            :default_operator,
+            :df,
+            :explain,
+            :fields,
+            :from,
+            :ignore_indices,
+            :indices_boost,
+            :lenient,
+            :lowercase_expanded_terms,
+            :preference,
+            :q,
+            :routing,
+            :scroll,
+            :search_type,
+            :size,
+            :sort,
+            :source,
+            :stats,
+            :suggest_field,
+            :suggest_mode,
+            :suggest_size,
+            :suggest_text,
+            :timeout,
+            :version ].include?(k)
+        end
+        # Normalize Ruby 1.8 and Ruby 1.9 Hash#select behaviour
+        params = Hash[params] unless params.is_a?(Hash)
+        body   = arguments[:body]
+
+        params[:fields] = Utils.__listify(params[:fields]) if params[:fields]
+
+        perform_request(method, path, params, body).body
+      end
+    end
+  end
+end

data/lib/elasticsearch/api/actions/suggest.rb

@@ -0,0 +1,46 @@
+module Elasticsearch
+  module API
+    module Actions
+
+      # Return query terms suggestions based on provided text and configuration.
+      #
+      # Pass the request definition in the `:body` argument.
+      #
+      # @example Return query terms suggestions ("auto-correction")
+      #
+      #     client.suggest index: 'myindex',
+      #                    body: { my_suggest: { text: 'tset', term: { field: 'title' } } }
+      #     # => { ... "my_suggest"=>[ {"text"=>"tset", ... "options"=>[{"text"=>"test", "score"=>0.75, "freq"=>5}] }]}
+      #
+      # @option arguments [List] :index A comma-separated list of index names to restrict the operation;
+      #                                 use `_all` or empty string to perform the operation on all indices
+      # @option arguments [Hash] :body The request definition
+      # @option arguments [String] :ignore_indices When performed on multiple indices, allows to ignore `missing` ones
+      #                                            (options: none, missing)
+      # @option arguments [String] :preference Specify the node or shard the operation should be performed on
+      #                                        (default: random)
+      # @option arguments [String] :routing Specific routing value
+      # @option arguments [String] :source The URL-encoded request definition (instead of using request body)
+      #
+      # @since 0.90
+      #
+      # @see http://elasticsearch.org/guide/reference/api/search/suggest/
+      #
+      def suggest(arguments={})
+        method = 'POST'
+        path   = Utils.__pathify( Utils.__listify(arguments[:index]), '_suggest' )
+        params = arguments.select do |k,v|
+          [ :ignore_indices,
+            :preference,
+            :routing,
+            :source ].include?(k)
+        end
+        # Normalize Ruby 1.8 and Ruby 1.9 Hash#select behaviour
+        params = Hash[params] unless params.is_a?(Hash)
+        body   = arguments[:body]
+
+        perform_request(method, path, params, body).body
+      end
+    end
+  end
+end

data/lib/elasticsearch/api/actions/update.rb

@@ -0,0 +1,103 @@
+module Elasticsearch
+  module API
+    module Actions
+
+      # Update a document without sending the whole document in the request ("partial update").
+      #
+      # Send either a partial document (`doc` ) which will be deeply merged into an existing document,
+      # or a `script`, which will update the document content, in the `:body` argument.
+      #
+      # The partial update operation allows you to limit the amount of data you send over the wire and
+      # reduces the chance of failed updates due to conflict.
+      #
+      # Specify the `:version` and `:retry_on_conflict` arguments to balance convenience and consistency.
+      #
+      # @example Update document _title_ using partial `doc`-ument
+      #
+      #     client.update index: 'myindex', type: 'mytype', id: '1',
+      #                   body: { doc: { title: 'Updated' } }
+      #
+      # @example Add a tag to document `tags` property using a `script`
+      #
+      #     client.update index: 'myindex', type: 'mytype', id: '1',
+      #                   body: { script: 'ctx._source.tags += tag', params: { tag: 'x' } }
+      #
+      # @example Increment a document counter by 1 _or_ initialize it, when the document does not exist
+      #
+      #     client.update index: 'myindex', type: 'mytype', id: '666',
+      #                   body: { script: 'ctx._source.counter += 1', upsert: { counter: 1 } }
+      #
+      # @example Delete a document if it's tagged "to-delete"
+      #
+      #     client.update index: 'myindex', type: 'mytype', id: '1',
+      #                   body: { script: 'ctx._source.tags.contains(tag) ? ctx.op = "delete" : ctx.op = "none"',
+      #                           params: { tag: 'to-delete' } }
+      #
+      # @option arguments [String] :id Document ID (*Required*)
+      # @option arguments [Number,List] :ignore The list of HTTP errors to ignore; only `404` supported at the moment
+      # @option arguments [String] :index The name of the index (*Required*)
+      # @option arguments [String] :type The type of the document (*Required*)
+      # @option arguments [Hash] :body The request definition using either `script` or partial `doc` (*Required*)
+      # @option arguments [String] :consistency Explicit write consistency setting for the operation
+      #                                         (options: one, quorum, all)
+      # @option arguments [List] :fields A comma-separated list of fields to return in the response
+      # @option arguments [String] :lang The script language (default: mvel)
+      # @option arguments [String] :parent ID of the parent document
+      # @option arguments [String] :percolate Perform percolation during the operation;
+      #                                       use specific registered query name, attribute, or wildcard
+      # @option arguments [Boolean] :refresh Refresh the index after performing the operation
+      # @option arguments [String] :replication Specific replication type (options: sync, async)
+      # @option arguments [Number] :retry_on_conflict Specify how many times should the operation be retried
+      #                                               when a conflict occurs (default: 0)
+      # @option arguments [String] :routing Specific routing value
+      # @option arguments [String] :script The URL-encoded script definition (instead of using request body)
+      # @option arguments [Time] :timeout Explicit operation timeout
+      # @option arguments [Time] :timestamp Explicit timestamp for the document
+      # @option arguments [Duration] :ttl Expiration time for the document
+      # @option arguments [Number] :version Explicit version number for concurrency control
+      # @option arguments [Number] :version_type Explicit version number for concurrency control
+      #
+      # @since 0.20
+      #
+      # @see http://elasticsearch.org/guide/reference/api/update/
+      #
+      def update(arguments={})
+        raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
+        raise ArgumentError, "Required argument 'type' missing"  unless arguments[:type]
+        raise ArgumentError, "Required argument 'id' missing"    unless arguments[:id]
+        method = 'POST'
+        path   = Utils.__pathify( arguments[:index], arguments[:type], arguments[:id], '_update' )
+        params = arguments.select do |k,v|
+          [ :consistency,
+            :fields,
+            :lang,
+            :parent,
+            :percolate,
+            :refresh,
+            :replication,
+            :retry_on_conflict,
+            :routing,
+            :script,
+            :timeout,
+            :timestamp,
+            :ttl,
+            :version,
+            :version_type ].include?(k)
+        end
+        # Normalize Ruby 1.8 and Ruby 1.9 Hash#select behaviour
+        params = Hash[params] unless params.is_a?(Hash)
+        body   = arguments[:body]
+
+        params[:fields] = Utils.__listify(params[:fields]) if params[:fields]
+
+        perform_request(method, path, params, body).body
+
+      rescue Exception => e
+        # NOTE: Use exception name, not full class in Elasticsearch::Client to allow client plugability
+        if arguments[:ignore] == 404 && e.class.to_s =~ /NotFound/; false
+        else raise(e)
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/api/namespace/cluster.rb

@@ -0,0 +1,20 @@
+module Elasticsearch
+  module API
+    module Cluster
+      module Actions; end
+
+      # Client for the "cluster" namespace (includes the {Cluster::Actions} methods)
+      #
+      class ClusterClient
+        include Common::Client, Common::Client::Base, Cluster::Actions
+      end
+
+      # Proxy method for {ClusterClient}, available in the receiving object
+      #
+      def cluster
+        @cluster ||= ClusterClient.new(self)
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/api/namespace/common.rb

@@ -0,0 +1,27 @@
+module Elasticsearch
+  module API
+    module Common
+      module Actions; end
+
+      module Client
+
+        # Base client wrapper
+        #
+        module Base
+          attr_reader :client
+
+          def initialize(client)
+            @client = client
+          end
+        end
+
+        # Delegates the `perform_request` method to the wrapped client
+        #
+        def perform_request(method, path, params={}, body=nil)
+          client.perform_request method, path, params, body
+        end
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/api/namespace/indices.rb

@@ -0,0 +1,20 @@
+module Elasticsearch
+  module API
+    module Indices
+      module Actions; end
+
+      # Client for the "indices" namespace (includes the {Indices::Actions} methods)
+      #
+      class IndicesClient
+        include Common::Client, Common::Client::Base, Indices::Actions
+      end
+
+      # Proxy method for {IndicesClient}, available in the receiving object
+      #
+      def indices
+        @indices ||= IndicesClient.new(self)
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/api/utils.rb

@@ -0,0 +1,97 @@
+module Elasticsearch
+  module API
+
+    # Generic utility methods
+    #
+    module Utils
+
+      # URL-escape a string
+      #
+      # @example
+      #     __escape('bar^bam') # => 'bar%5Ebam'
+      #
+      # @api private
+      def __escape(string)
+        URI.encode(string.to_s)
+      end
+
+      # Create a "list" of values from arguments, ignoring nil values
+      #
+      # @example Create a list from array
+      #     __listify(['A','B']) # => 'A,B'
+      #
+      # @example Create a list from arguments
+      #     __listify('A','B') # => 'A,B'
+      #
+      # @api private
+      def __listify(*list)
+        Array(list).flatten.compact.join(',')
+      end
+
+      # Create a path (URL part) from arguments, ignoring nil values and empty strings,
+      # and encoding special characters
+      #
+      # @example Create a path from array
+      #     __pathify(['foo', '', nil, 'bar']) # => 'foo/bar'
+      #
+      # @example Create a path from arguments
+      #     __pathify('foo', '', nil, 'bar') # => 'foo/bar'
+      #
+      # # @example Encode special characters
+      #     __pathify(['foo', 'bar^bam']) # => 'foo/bar%5Ebam'
+      #
+      # @api private
+      def __pathify(*segments)
+        Array(segments).flatten.
+          compact.
+          reject { |s| s.to_s =~ /^\s*$/ }.
+          map    { |s| __escape(s) }.
+          join('/').
+          squeeze('/')
+      end
+
+      # Convert an array of payloads into Elasticsearch `header\ndata` format
+      #
+      #     Elasticsearch::API::Utils.__bulkify [
+      #       { :index =>  { :_index => 'myindexA', :_type => 'mytype', :_id => '1', :data => { :title => 'Test' } } },
+      #       { :update => { :_index => 'myindexB', :_type => 'mytype', :_id => '2', :data => { :doc => { :title => 'Update' } } } }
+      #     ]
+      #
+      #     # => {"index":{"_index":"myindexA","_type":"mytype","_id":"1"}}
+      #     # => {"title":"Test"}
+      #     # => {"update":{"_index":"myindexB","_type":"mytype","_id":"2"}}
+      #     # => {"doc":{"title":"Update"}}
+      #
+      def __bulkify(payload)
+        case
+        # Hashes with `:data`
+        when payload.any? { |d| d.is_a?(Hash) && d.values.first.is_a?(Hash) && (d.values.first[:data] || d.values.first['data']) }
+          payload = payload.
+          inject([]) do |sum, item|
+            operation, meta = item.to_a.first
+            data            = meta.delete(:data) || meta.delete('data')
+
+            sum << { operation => meta }
+            sum << data if data
+            sum
+          end.
+          map { |item| MultiJson.dump(item) }
+          payload << "" unless payload.empty?
+
+        # Array of strings
+        when payload.all? { |d| d.is_a? String }
+          payload << ''
+
+        # Header/Data pairs
+        else
+          payload = payload.map { |item| MultiJson.dump(item) }
+          payload << ''
+        end
+
+        payload = payload.join("\n")
+      end
+
+      extend self
+    end
+  end
+end