elastics-client 1.1.11 → 1.2.0

data/lib/elastics/api_templates/search_api.yml

@@ -0,0 +1,144 @@
+# These methods are available as Elastics.<method>(*vars)
+# you can get the updated full reference and usage example of these methods
+# by just doing in the console:
+# Elastics.doc
+
+
+
+#-----------------------------------------------------------------------------#
+### Search ###
+# The search api is covered by the templating system
+
+
+
+#-----------------------------------------------------------------------------#
+### Search Shards ###
+
+search_shards:
+  - GET
+  - /<<index>>/<<type>>/_search_shards
+  -
+  - REFERENCES:
+      group: search_api
+      api_name: Search Shards
+      api_url: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-shards.html
+      notice: "You can pass the parameters as the :params variable."
+
+
+
+#-----------------------------------------------------------------------------#
+### Multi Search ###
+# the Multi Search api is covered by the <YourClass>.multi_search method
+# added by the Elastics::Templates module
+
+
+
+#-----------------------------------------------------------------------------#
+### Count ###
+
+count:
+  - GET
+  - /<<index>>/<<type>>/_count
+  -
+  - REFERENCES:
+      group: search_api
+      api_name: Search Shards
+      api_url: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-count.html
+      notice: "You must pass the query to validate as the :data variable. You can pass the parameters as the :params variable."
+
+
+
+#-----------------------------------------------------------------------------#
+### Search Exists ###
+
+search_exists:
+  - GET
+  - /<<index>>/<<type>>/<<id= ~ >>/_search/exists
+  -
+  - REFERENCES:
+      group: search_api
+      api_name: Search Exists
+      api_url: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-exists.html
+      notice: "You must pass the query to validate as the :data variable. You can pass the parameters as the :params variable."
+
+
+
+#-----------------------------------------------------------------------------#
+### Validate ###
+
+validate:
+  - GET
+  - /<<index>>/<<type>>/<<id= ~ >>/_validate/query
+  -
+  - REFERENCES:
+      group: search_api
+      api_name: Validate
+      api_url: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-validate.html
+      notice: "You must pass the query to validate as the :data variable. You can pass the parameters as the :params variable."
+
+
+
+#-----------------------------------------------------------------------------#
+### Explain ###
+
+explain:
+  - GET
+  - /<<index>>/<<type>>/<<id= ~ >>/_explain
+  -
+  - REFERENCES:
+      group: search_api
+      api_name: Validate
+      api_url: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-explain.html
+      notice: "You must pass the query to explain as the :data variable. You can pass the parameters as the :params variable."
+
+
+
+#-----------------------------------------------------------------------------#
+### Percolator ###
+
+delete_percolator:
+  - DELETE
+  - /<<index>>/.percolator/<<id>>
+  -
+  - REFERENCES: &percolator
+      group: search_api
+      api_name: Percolator
+      api_url: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-percolate.html
+
+percolate:
+  - GET
+  - /<<index>>/<<type>>/_percolate
+  -
+  - &percolator_ref
+    REFERENCES:
+      <<: *percolator
+      notice: "You must pass the the document (and additional queries) as :data variable."
+
+percolate_count:
+  - GET
+  - /<<index>>/<<type>>/_percolate/count
+  -
+  - *percolator_ref
+
+put_percolator:
+  - PUT
+  - /<<index>>/.percolator/<<id>>
+  -
+  - *percolator_ref
+
+
+
+#-----------------------------------------------------------------------------#
+### More Like This ###
+
+more_like_this:
+  - GET
+  - /<<index>>/<<type>>/<<id>>/_mlt
+  -
+  - REFERENCES:
+      group: search_api
+      api_name: More Like This
+      api_url: http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-more-like-this.html
+      notice: "You can pass the search API as :data variable."
+      aliases:
+        - :mlt

data/lib/elastics/class_proxy/base.rb

@@ -5,8 +5,10 @@ module Elastics
       attr_accessor :variables
 
       def initialize(context, vars={})
-        @variables = Vars.new({:context => context,
-                               :index   => Conf.variables[:index]}.merge(vars))
+        v = {:context => context}
+        # support for elastics-rails index default
+        v[:index]  = Conf.variables[:index] if Conf.variables.has_key?(:index)
+        @variables = Vars.new(v, vars)
       end
 
       def init; end

data/lib/elastics/class_proxy/templates.rb

@@ -15,19 +15,24 @@ module Elastics
       # accepts a path to a file or YAML string
       def load_source_for(klass, source, source_vars)
         if source.nil? || source !~ /\n/m
-          paths = [ "#{Conf.elastics_dir}/#{source}.yml",
-                    "#{Conf.elastics_dir}/#{Utils.class_name_to_type(context.name)}.yml",
-                    source.to_s ]
-          source = paths.find {|p| File.exist?(p)}
+          base_names = [source, Utils.class_name_to_path(context.name), Utils.class_name_to_type(context.name)]
+          paths      = base_names.map{|bn| ["#{Conf.elastics_dir}/#{bn}.yml", "#{Conf.elastics_dir}/#{bn}.yml.erb"]}.flatten
+          paths     << source.to_s
+          source     = paths.find {|p| File.exist?(p)}
         end
-        raise ArgumentError, "expected a string, got #{source.inspect}" \
-            unless source.is_a?(String)
+        raise ArgumentError, "Unable to load the source: expected a string, got #{source.inspect}" \
+              unless source.is_a?(String)
         @sources << [klass, source, source_vars]
         do_load_source(klass, source, source_vars)
         # fixes the legacy empty stubs, which should call super instead
-        @templates.keys.each do |name|
-          meta_context.send(:define_method, name){|*vars| super *vars }
-        end
+        # @templates.keys.each do |name|
+        #   meta_context.send(:define_method, name){|*vars| super *vars }
+        # end
+      end
+
+      # loads a API Template source
+      def load_api_source(source=nil, source_vars=nil)
+        load_source_for(Elastics::Template::Api, source, source_vars)
       end
 
       # loads a Generic Template source

data/lib/elastics/class_proxy/templates/doc.rb

@@ -3,86 +3,155 @@ module Elastics
     module Templates
       module Doc
 
+        class Output
+
+
+          attr_reader :template, :method_call
+
+          def initialize(name, proxy)
+            @name, @template = proxy.templates.find do |n, t|
+                                 t.is_a?(Elastics::Template::Api) && t.aliases.include?(name)
+                               end || [ name, proxy.templates[name]]
+            @method_call = [proxy.context, @name].join('.')
+
+            sources = []
+            sources << { :class  => @template.class,
+                         :source => @template.to_source }
+            @template.partials.each do |name|
+              partial = proxy.partials[name]
+              sources << { :class  => partial.class,
+                           :source => partial.to_source }
+            end
+            @sources = sources
+          end
+
+
+          def render_usage(indent='')
+            variables = @template.instance_eval do
+                          interpolate
+                          @base_variables.deep_merge @host_elastics && @host_elastics.variables, @temp_variables
+                        end
+            all_tags  = @template.tags + @template.partials
+            return @method_call if all_tags.size == 0
+            lines = all_tags.map do |t|
+                      comments = 'partial' if t.to_s[0] == '_'
+                      line     = ['', t.inspect]
+                      line + if variables.has_key?(t)
+                               ["#{variables[t].inspect},", comments_to_s(comments)]
+                             else
+                               ["#{to_code(t)},", comments_to_s(comments, 'required')]
+                             end
+                    end
+            lines.sort! { |a,b| b[3] <=> a[3] }
+            lines.first[0] = @method_call
+            lines.last[2].chop!
+            max       = lines.transpose.map{ |c| c.map(&:length).max }
+            formatted = lines.map{ |line| "%-#{max[0]}s %-#{max[1]}s => %-#{max[2]}s  %s" % line }
+            indented  = formatted.shift
+            indented  = [indented] + formatted.map{ |line| indent + line }
+            indented.join("\n") + "\n "
+          end
+
+
+          def comments_to_s(*comments)
+            comments = comments.compact
+            return '' if comments == []
+            "# #{comments.join(' ')}"
+          end
+
+
+          def to_code(name)
+            keys = name.to_s.split('.').map{ |s| s =~ /^[0..9]+$/ ? s.to_i : s.to_sym }
+            code = keys.shift.to_s
+            return code if keys.empty?
+            keys.each { |k| code << "[#{k.inspect}]" }
+            code
+          end
+
+
+          def render_sources
+            @sources.map do |source|
+              <<-output.gsub(/^ {14}/m,'')
+              #{'-' * source[:class].name.length}
+              #{source[:class]}
+              #{source[:source]}
+              output
+            end.join("\n")
+          end
+
+
+          def render_api
+            notice = if @template.is_a?(Elastics::Template::Api) && @template.references['notice']
+                       "\nNotice: #{@template.references['notice']}\n "
+                     end
+            <<-output.gsub(/^ {12}/m,'')
+            ########## #{@method_call} ##########
+
+            API Name: #{@template.references['api_name']}
+            API URL: #{@template.references['api_url']}
+
+            #{render_sources}
+            Usage:
+            #{render_usage(' ' * 12)}#{ notice }
+            output
+          end
+
+
+          def render_custom
+            <<-output.gsub(/^ {12}/m,'')
+            ########## #{@method_call} ##########
+
+            #{render_sources}
+
+            Usage:
+            #{render_usage(' ' * 12)}
+            output
+          end
+
+
+          def render_stub
+            aliased  = if @template.is_a?(Elastics::Template::Api) && @template.references['aliases']
+                         "\n# also aliased by: #{@template.aliases.map(&:inspect).join(', ')}"
+                       end
+            <<-output.gsub(/^ {12}/m,'')
+            def self.#{@name}(*vars)
+              ## this is a stub, used for reference
+              super
+            end#{ aliased }
+            output
+          end
+
+
+          def render
+            output = (@template.is_a?(Elastics::Template::Api) ? render_api : render_custom)
+            output = output.split("\n").map{ |l| '#  ' + l }.join("\n")
+            output << "\n#{render_stub}\n\n"
+            output
+          end
+
+        end
+
+
         def doc(*names)
           names = templates.keys if names.empty?
-          doc = "\n"
+          doc   = "\n"
           names.each do |name|
-            next unless templates.include?(name)
-            block = ''
-            temp = templates[name]
-            meth_call = [context, name].join('.')
-            block << <<-meth_call
-########## #{meth_call} ##########
-#{'-' * temp.class.to_s.length}
-#{temp.class}
-#{temp.to_source}
-meth_call
-            temp.partials.each do |par_name|
-              par = partials[par_name]
-              block << <<-partial
-#{'-' * par.class.to_s.length}
-#{par.class}
-#{par.to_source}
-partial
-            end
-            block << "\nUsage:\n"
-            block << build_usage(meth_call, temp)
-            block << "\n "
-            doc << block.split("\n").map{|l| '#  ' + l}.join("\n")
-            doc << <<-meth.gsub(/^ {14}/m,'')
-
-def #{meth_call}(*vars)
-  ## this is a stub, used for reference
-  super
-end
-
-meth
+            next unless context.respond_to?(name)
+            doc << Output.new(name, self).render
           end
           Prompter.say_log doc
         end
 
-        def usage(name)
-          meth_call = [context, name].join('.')
-          Prompter.say_log build_usage(meth_call, templates[name])
-        end
 
-      private
-
-        def build_usage(meth_call, temp)
-          variables = temp.instance_eval do
-                        interpolate
-                        @base_variables.deep_merge @host_elastics && @host_elastics.variables, @temp_variables
-                      end
-          all_tags  = temp.tags + temp.partials
-          return meth_call if all_tags.size == 0
-          lines = all_tags.map do |t|
-                    comments = 'partial' if t.to_s[0] == '_'
-                    line = ['', t.inspect]
-                    line + if variables.has_key?(t)
-                             ["#{variables[t].inspect},", comments_to_s(comments)]
-                           else
-                             ["#{to_code(t)},", comments_to_s(comments, 'required')]
-                           end
-                  end
-          lines.sort! { |a,b| b[3] <=> a[3] }
-          lines.first[0] = meth_call
-          lines.last[2].chop!
-          max = lines.transpose.map { |c| c.map(&:length).max }
-          lines.map { |line| "%-#{max[0]}s %-#{max[1]}s => %-#{max[2]}s  %s" % line }.join("\n")
+        def usage(name)
+          Prompter.say_log "\n#{Output.new(name, self).render_usage}\n"
         end
 
-        def comments_to_s(*comments)
-          comments = comments.compact
-          return '' if comments == []
-          "# #{comments.join(' ')}"
-        end
 
-        def to_code(name)
-          keys = name.to_s.split('.').map{|s| s =~ /^[0..9]+$/ ? s.to_i : s.to_sym}
-          code = keys.shift.to_s
-          return code if keys.empty?
-          keys.each{|k| code << "[#{k.inspect}]"}
-          code
+        def find(pattern)
+          pattern = /#{pattern}/ unless pattern.is_a?(Regexp)
+          methods = templates.keys.select{ |key| key =~ pattern }
+          Prompter.say_log methods.to_yaml
         end
 
       end

data/lib/elastics/class_proxy/templates/search.rb

@@ -8,7 +8,7 @@ module Elastics
           send :define_template, Template::Search, name, args, source_vars
         end
 
-        # http://www.elasticsearch.org/guide/reference/api/multi-search.html
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html
         # requests can be an array of arrays: [[:template1, variable_hash1], [template2, variable_hash2]]
         # or a hash {:template1 => variable_hash1, template2 => variable_hash2}
         # The variables are an hash of variables that will be used to render the msearch template
@@ -34,24 +34,21 @@ module Elastics
           end
         end
 
-        # implements search_type=scan (http://www.elasticsearch.org/guide/reference/api/search/search-type.html)
+        # implements search_type=scan (https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-search-type.html#scan)
         def scan_search(template, *vars, &block)
           user_raw_result = vars.any?{|v| v[:raw_result]}
-          scroll      = '5m'
-          search_vars = Vars.new({:params     => { :search_type => 'scan',
-                                                   :scroll      => scroll,
-                                                   :size        => 50 },
-                                  :raw_result => true}, *vars)
-          search_temp = template.is_a?(Elastics::Template) ? template : templates[template]
+          scroll          = '5m'
+          search_vars     = Vars.new({:params     => { :search_type => 'scan',
+                                                       :scroll      => scroll,
+                                                       :size        => 50 },
+                                      :raw_result => true}, *vars)
+          search_temp     = template.is_a?(Elastics::Template) ? template : templates[template]
 
-          scroll_vars = Vars.new({:params     => { :scroll => scroll },
-                                  :raw_result => true}, variables, *vars)
-          scroll_temp = Elastics::Template.new( :get,
-                                            '/_search/scroll',
-                                            nil,
-                                            scroll_vars )
-          search_res  = search_temp.render search_vars
-          scroll_id   = search_res['_scroll_id']
+          scroll_vars     = Vars.new({:params     => { :scroll => scroll },
+                                      :raw_result => true}, variables, *vars)
+          scroll_temp     = Elastics::Template.new( :get, '/_search/scroll', nil, scroll_vars )
+          search_res      = search_temp.render search_vars
+          scroll_id       = search_res['_scroll_id']
           while (result = scroll_temp.render(:data => scroll_id)) do
             break if result['hits']['hits'].empty?
             scroll_id = result['_scroll_id']
@@ -60,7 +57,7 @@ module Elastics
           end
         end
 
-        # implements search_type=count (http://www.elasticsearch.org/guide/reference/api/search/search-type.html)
+        # implements search_type=count (https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-search-type.html#count)
         def count_search(template, *vars)
           template = template.is_a?(Elastics::Template) ? template : templates[template]
           template.render Vars.new({:params => {:search_type => 'count'}, :raw_result => true}, *vars)