elasticsearch-api 7.3.0 → 7.5.0

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

@@ -5,40 +5,35 @@
 module Elasticsearch
   module API
     module Actions
-
-      # Delete documents which match specified query.
-      #
-      # Provide the query either as a "query string" query in the `:q` argument, or using the Elasticsearch's
-      # [Query DSL](https://www.elastic.co/guide/reference/query-dsl/) in the `:body` argument.
-      #
-      # @example Deleting documents with a simple query
-      #
-      #     client.delete_by_query index: 'myindex', q: 'title:test'
-      #
-      # @example Deleting documents using the Query DSL
-      #
-      #     client.delete_by_query index: 'myindex', body: { query: { term: { published: false } } }
+      # Deletes documents matching the provided query.
       #
-      # @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 (*Required*)
+      # @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  (*Required*)
       # @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 (*Required*)
-      # @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] :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 [Number] :from Starting offset (default: 0)
       # @option arguments [Boolean] :ignore_unavailable Whether specified concrete indices should be ignored when unavailable (missing or closed)
       # @option arguments [Boolean] :allow_no_indices Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)
-      # @option arguments [String] :conflicts What to do when the delete by query hits version conflicts? (options: abort, proceed)
-      # @option arguments [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that are open, closed or both. (options: open, closed, none, all)
+      # @option arguments [String] :conflicts What to do when the delete by query hits version conflicts?
+      #   (options: abort,proceed)
+
+      # @option arguments [String] :expand_wildcards Whether to expand wildcard expression to concrete indices that are open, closed or both.
+      #   (options: open,closed,none,all)
+
       # @option arguments [Boolean] :lenient Specify whether format-based query failures (such as providing text to a numeric field) should be ignored
       # @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 [Time] :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, dfs_query_then_fetch)
+      # @option arguments [String] :search_type Search operation type
+      #   (options: query_then_fetch,dfs_query_then_fetch)
+
       # @option arguments [Time] :search_timeout Explicit timeout for each search request. Defaults to no timeout.
-      # @option arguments [Number] :size Number of hits to return (default: 10)
+      # @option arguments [Number] :size Deprecated, please use `max_docs` instead
+      # @option arguments [Number] :max_docs Maximum number of documents to process (default: all documents)
       # @option arguments [List] :sort A comma-separated list of <field>:<direction> pairs
       # @option arguments [List] :_source True or false to return the _source field or not, or a list of fields to return
       # @option arguments [List] :_source_excludes A list of fields to exclude from the returned _source field
@@ -54,58 +49,75 @@ module Elasticsearch
       # @option arguments [Boolean] :wait_for_completion Should the request should block until the delete by query is complete.
       # @option arguments [Number] :requests_per_second The throttle for this request in sub-requests per second. -1 means no throttle.
       # @option arguments [Number] :slices The number of slices this task should be divided into. Defaults to 1 meaning the task isn't sliced into subtasks.
+
+      # @option arguments [Hash] :body The search definition using the Query DSL (*Required*)
+      #
+      # *Deprecation notice*:
+      # Specifying types in urls has been deprecated
+      # Deprecated since version 7.0.0
       #
-      # @see https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-delete-by-query.html
       #
-      def delete_by_query(arguments={})
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/docs-delete-by-query.html
+      #
+      def delete_by_query(arguments = {})
+        raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
         raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
-        method = HTTP_POST
-        path   = Utils.__pathify Utils.__listify(arguments[:index]),
-                                 Utils.__listify(arguments[:type]),
-                                 '/_delete_by_query'
 
+        arguments = arguments.clone
+
+        _index = arguments.delete(:index)
+
+        _type = arguments.delete(:type)
+
+        method = Elasticsearch::API::HTTP_POST
+        path   = if _index && _type
+                   "#{Utils.__listify(_index)}/#{Utils.__listify(_type)}/_delete_by_query"
+                 else
+                   "#{Utils.__listify(_index)}/_delete_by_query"
+  end
         params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
-        body   = arguments[:body]
 
+        body = arguments[:body]
         perform_request(method, path, params, body).body
       end
 
       # Register this action with its valid params when the module is loaded.
       #
-      # @since 6.1.1
+      # @since 6.2.0
       ParamsRegistry.register(:delete_by_query, [
-          :analyzer,
-          :analyze_wildcard,
-          :default_operator,
-          :df,
-          :from,
-          :ignore_unavailable,
-          :allow_no_indices,
-          :conflicts,
-          :expand_wildcards,
-          :lenient,
-          :preference,
-          :q,
-          :routing,
-          :scroll,
-          :search_type,
-          :search_timeout,
-          :size,
-          :sort,
-          :_source,
-          :_source_excludes,
-          :_source_includes,
-          :terminate_after,
-          :stats,
-          :version,
-          :request_cache,
-          :refresh,
-          :timeout,
-          :wait_for_active_shards,
-          :scroll_size,
-          :wait_for_completion,
-          :requests_per_second,
-          :slices ].freeze)
+        :analyze_wildcard,
+        :default_operator,
+        :df,
+        :from,
+        :ignore_unavailable,
+        :allow_no_indices,
+        :conflicts,
+        :expand_wildcards,
+        :lenient,
+        :preference,
+        :q,
+        :routing,
+        :scroll,
+        :search_type,
+        :search_timeout,
+        :size,
+        :max_docs,
+        :sort,
+        :_source,
+        :_source_excludes,
+        :_source_includes,
+        :terminate_after,
+        :stats,
+        :version,
+        :request_cache,
+        :refresh,
+        :timeout,
+        :wait_for_active_shards,
+        :scroll_size,
+        :wait_for_completion,
+        :requests_per_second,
+        :slices
+      ].freeze)
+    end
     end
-  end
 end

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

@@ -0,0 +1,39 @@
+# Licensed to Elasticsearch B.V under one or more agreements.
+# Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+# See the LICENSE file in the project root for more information
+
+module Elasticsearch
+  module API
+    module Actions
+      # Changes the number of requests per second for a particular Delete By Query operation.
+      #
+      # @option arguments [String] :task_id The task id to rethrottle
+      # @option arguments [Number] :requests_per_second The throttle to set on this request in floating sub-requests per second. -1 means set no throttle.  (*Required*)
+
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/docs-delete-by-query.html
+      #
+      def delete_by_query_rethrottle(arguments = {})
+        raise ArgumentError, "Required argument 'task_id' missing" unless arguments[:task_id]
+
+        arguments = arguments.clone
+
+        _task_id = arguments.delete(:task_id)
+
+        method = Elasticsearch::API::HTTP_POST
+        path   = "_delete_by_query/#{Utils.__listify(_task_id)}/_rethrottle"
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+
+        body = nil
+        perform_request(method, path, params, body).body
+      end
+
+      # Register this action with its valid params when the module is loaded.
+      #
+      # @since 6.2.0
+      ParamsRegistry.register(:delete_by_query_rethrottle, [
+        :requests_per_second
+      ].freeze)
+    end
+    end
+end

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

@@ -5,7 +5,6 @@
 module Elasticsearch
   module API
     module Actions
-
       # The value of requests_per_second can be changed on a running delete by query using the _rethrottle API
       #
       # @option arguments [String] :task_id The task id to rethrottle (*Required*)
@@ -13,8 +12,9 @@ module Elasticsearch
       #
       # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html
       #
-      def delete_by_query_rethrottle(arguments={})
+      def delete_by_query_rethrottle(arguments = {})
         raise ArgumentError, "Required argument 'task_id' missing" unless arguments[:task_id]
+
         method = Elasticsearch::API::HTTP_POST
         path   = "_delete_by_query/#{arguments[:task_id]}/_rethrottle"
         params = Elasticsearch::API::Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
@@ -27,7 +27,8 @@ module Elasticsearch
       #
       # @since 6.2.0
       ParamsRegistry.register(:delete_by_query_rethrottle, [
-          :requests_per_second ].freeze)
+        :requests_per_second
+      ].freeze)
     end
   end
 end

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

@@ -5,31 +5,37 @@
 module Elasticsearch
   module API
     module Actions
-
-      # Remove an indexed script from Elasticsearch
+      # Deletes a script.
       #
-      # @option arguments [String] :id Script ID (*Required*)
+      # @option arguments [String] :id Script ID
       # @option arguments [Time] :timeout Explicit operation timeout
       # @option arguments [Time] :master_timeout Specify timeout for connection to master
+
       #
-      # @see https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/modules-scripting.html
       #
-      def delete_script(arguments={})
-        raise ArgumentError, "Required argument 'id' missing"   unless arguments[:id]
-        method = HTTP_DELETE
-        path   = "_scripts/#{arguments.has_key?(:lang) ? "#{arguments.delete(:lang)}/" : ''}#{arguments[:id]}"
+      def delete_script(arguments = {})
+        raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]
+
+        arguments = arguments.clone
+
+        _id = arguments.delete(:id)
+
+        method = Elasticsearch::API::HTTP_DELETE
+        path   = "_scripts/#{Utils.__listify(_id)}"
         params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
-        body   = nil
 
+        body = nil
         perform_request(method, path, params, body).body
       end
 
       # Register this action with its valid params when the module is loaded.
       #
-      # @since 6.1.1
+      # @since 6.2.0
       ParamsRegistry.register(:delete_script, [
-          :timeout,
-          :master_timeout ].freeze)
+        :timeout,
+        :master_timeout
+      ].freeze)
+    end
     end
-  end
 end

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

@@ -5,18 +5,12 @@
 module Elasticsearch
   module API
     module Actions
-
-      # Return true if the specified document exists, false otherwise.
-      #
-      # @example
+      # Returns information about whether a document exists in an index.
       #
-      #     client.exists? index: 'myindex', type: 'mytype', id: '1'
-      #
-      # @option arguments [String] :id The document ID (*Required*)
-      # @option arguments [String] :index The name of the index (*Required*)
-      # @option arguments [String] :type The type of the document (use `_all` to fetch the first document matching the ID across all types)
+      # @option arguments [String] :id The document ID
+      # @option arguments [String] :index The name of the index
+      # @option arguments [String] :type The type of the document (use `_all` to fetch the first document matching the ID across all types)   *Deprecated*
       # @option arguments [List] :stored_fields A comma-separated list of stored fields to return in the response
-      # @option arguments [String] :parent The ID of the parent document
       # @option arguments [String] :preference Specify the node or shard the operation should be performed on (default: random)
       # @option arguments [Boolean] :realtime Specify whether to perform the operation in realtime or search mode
       # @option arguments [Boolean] :refresh Refresh the shard containing the document before performing the operation
@@ -25,44 +19,60 @@ module Elasticsearch
       # @option arguments [List] :_source_excludes A list of fields to exclude from the returned _source field
       # @option arguments [List] :_source_includes A list of fields to extract and return from the _source field
       # @option arguments [Number] :version Explicit version number for concurrency control
-      # @option arguments [String] :version_type Specific version type (options: internal, external, external_gte, force)
+      # @option arguments [String] :version_type Specific version type
+      #   (options: internal,external,external_gte,force)
 
       #
-      # @see http://elasticsearch.org/guide/reference/api/get/
+      # *Deprecation notice*:
+      # Specifying types in urls has been deprecated
+      # Deprecated since version 7.0.0
+      #
       #
-      def exists(arguments={})
-        raise ArgumentError, "Required argument 'id' missing"    unless arguments[:id]
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/docs-get.html
+      #
+      def exists(arguments = {})
         raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
-        arguments[:type] ||= UNDERSCORE_ALL
-        method = HTTP_HEAD
-        path   = Utils.__pathify Utils.__escape(arguments[:index]),
-                                 Utils.__escape(arguments[:type]),
-                                 Utils.__escape(arguments[:id])
+        raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]
+
+        arguments = arguments.clone
+
+        _id = arguments.delete(:id)
+
+        _index = arguments.delete(:index)
 
+        _type = arguments.delete(:type)
+
+        method = Elasticsearch::API::HTTP_HEAD
+        path   = if _index && _type && _id
+                   "#{Utils.__listify(_index)}/#{Utils.__listify(_type)}/#{Utils.__listify(_id)}"
+                 else
+                   "#{Utils.__listify(_index)}/_doc/#{Utils.__listify(_id)}"
+  end
         params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
-        body   = nil
+
+        body = nil
 
         Utils.__rescue_from_not_found do
           perform_request(method, path, params, body).status == 200 ? true : false
         end
       end
-      alias_method :exists?, :exists
 
+      alias_method :exists?, :exists
       # Register this action with its valid params when the module is loaded.
       #
-      # @since 6.1.1
+      # @since 6.2.0
       ParamsRegistry.register(:exists, [
-          :stored_fields,
-          :parent,
-          :preference,
-          :realtime,
-          :refresh,
-          :routing,
-          :_source,
-          :_source_excludes,
-          :_source_includes,
-          :version,
-          :version_type ].freeze)
+        :stored_fields,
+        :preference,
+        :realtime,
+        :refresh,
+        :routing,
+        :_source,
+        :_source_excludes,
+        :_source_includes,
+        :version,
+        :version_type
+      ].freeze)
+    end
     end
-  end
 end

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

@@ -5,13 +5,11 @@
 module Elasticsearch
   module API
     module Actions
-
-      # The get API allows to get a typed JSON document from the index based on its id.
+      # Returns information about whether a document source exists in an index.
       #
-      # @option arguments [String] :id The document ID (*Required*)
-      # @option arguments [String] :index The name of the index (*Required*)
-      # @option arguments [String] :type The type of the document; use `_all` to fetch the first document matching the ID across all types (*Required*)
-      # @option arguments [String] :parent The ID of the parent document
+      # @option arguments [String] :id The document ID
+      # @option arguments [String] :index The name of the index
+      # @option arguments [String] :type The type of the document; deprecated and optional starting with 7.0   *Deprecated*
       # @option arguments [String] :preference Specify the node or shard the operation should be performed on (default: random)
       # @option arguments [Boolean] :realtime Specify whether to perform the operation in realtime or search mode
       # @option arguments [Boolean] :refresh Refresh the shard containing the document before performing the operation
@@ -20,36 +18,56 @@ module Elasticsearch
       # @option arguments [List] :_source_excludes A list of fields to exclude from the returned _source field
       # @option arguments [List] :_source_includes A list of fields to extract and return from the _source field
       # @option arguments [Number] :version Explicit version number for concurrency control
-      # @option arguments [String] :version_type Specific version type (options: internal, external, external_gte, force)
+      # @option arguments [String] :version_type Specific version type
+      #   (options: internal,external,external_gte,force)
+
       #
-      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html
+      # *Deprecation notice*:
+      # Specifying types in urls has been deprecated
+      # Deprecated since version 7.0.0
       #
-      def exists_source(arguments={})
-        raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/docs-get.html
+      #
+      def exists_source(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]
+
+        arguments = arguments.clone
+
+        _id = arguments.delete(:id)
+
+        _index = arguments.delete(:index)
+
+        _type = arguments.delete(:type)
+
         method = Elasticsearch::API::HTTP_HEAD
-        path   = "#{arguments[:index]}/#{arguments[:type]}/#{arguments[:id]}/_source"
-        params = Elasticsearch::API::Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
-        body   = nil
+        path   = if _index && _type && _id
+                   "#{Utils.__listify(_index)}/#{Utils.__listify(_type)}/#{Utils.__listify(_id)}/_source"
+                 else
+                   "#{Utils.__listify(_index)}/_source/#{Utils.__listify(_id)}"
+  end
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
 
+        body = nil
         perform_request(method, path, params, body).body
       end
 
+      alias_method :exists_source?, :exists_source
       # Register this action with its valid params when the module is loaded.
       #
       # @since 6.2.0
       ParamsRegistry.register(:exists_source, [
-          :parent,
-          :preference,
-          :realtime,
-          :refresh,
-          :routing,
-          :_source,
-          :_source_excludes,
-          :_source_includes,
-          :version,
-          :version_type ].freeze)
+        :preference,
+        :realtime,
+        :refresh,
+        :routing,
+        :_source,
+        :_source_excludes,
+        :_source_includes,
+        :version,
+        :version_type
+      ].freeze)
+    end
     end
-  end
 end

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

@@ -5,81 +5,76 @@
 module Elasticsearch
   module API
     module Actions
-
-      # Return information if and how well a document matches a query.
-      #
-      # The returned information contains a `_score` and its explanation, if the document matches the query.
-      #
-      # @example Passing the query in the Lucene query syntax as the `:q` URL parameter
-      #
-      #     client.explain index: 'myindex', type: 'mytype', id: '1', q: 'test'
-      #
-      # @example Passing the query in the Query DSL as the request `:body`
+      # Returns information about why a specific matches (or doesn't match) a query.
       #
-      #     client.explain index: 'myindex', type: 'mytype', id: '1',
-      #                    body: { query: { match: { title: 'test' } } }
-      #
-      # @option arguments [String] :id The document ID (*Required*)
-      # @option arguments [String] :index The name of the index (*Required*)
-      # @option arguments [String] :type The type of the document
-      # @option arguments [Hash] :body The query definition using the Query DSL
+      # @option arguments [String] :id The document ID
+      # @option arguments [String] :index The name of the index
+      # @option arguments [String] :type The type of the document   *Deprecated*
       # @option arguments [Boolean] :analyze_wildcard Specify whether wildcards and prefix queries in the query string query should be analyzed (default: false)
       # @option arguments [String] :analyzer The analyzer for the query string query
-      # @option arguments [String] :default_operator The default operator for query string query (AND or OR) (options: AND, OR)
+      # @option arguments [String] :default_operator The default operator for query string query (AND or OR)
+      #   (options: AND,OR)
+
       # @option arguments [String] :df The default field for query string query (default: _all)
       # @option arguments [List] :stored_fields A comma-separated list of stored fields to return in the response
       # @option arguments [Boolean] :lenient Specify whether format-based query failures (such as providing text to a numeric field) should be ignored
-      # @option arguments [String] :parent The ID of the parent document
       # @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 [String] :routing Specific routing value
       # @option arguments [List] :_source True or false to return the _source field or not, or a list of fields to return
       # @option arguments [List] :_source_excludes A list of fields to exclude from the returned _source field
       # @option arguments [List] :_source_includes A list of fields to extract and return from the _source field
+
+      # @option arguments [Hash] :body The query definition using the Query DSL
       #
-      # @see http://elasticsearch.org/guide/reference/api/explain/
+      # *Deprecation notice*:
+      # Specifying types in urls has been deprecated
+      # Deprecated since version 7.0.0
       #
-      def explain(arguments={})
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/search-explain.html
+      #
+      def explain(arguments = {})
         raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
-        raise ArgumentError, "Required argument 'id' missing"    unless arguments[:id]
-        method = HTTP_GET
+        raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]
 
-        if arguments[:type]
-          path   = Utils.__pathify Utils.__escape(arguments[:index]),
-                                   Utils.__escape(arguments[:type]),
-                                   Utils.__escape(arguments[:id]),
-                                   '_explain'
-        else
-          path   = Utils.__pathify Utils.__escape(arguments[:index]),
-                                   '_explain',
-                                   Utils.__escape(arguments[:id])
-        end
+        arguments = arguments.clone
 
-        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
-        body   = arguments[:body]
+        _id = arguments.delete(:id)
 
-        params[:fields] = Utils.__listify(params[:fields]) if params[:fields]
+        _index = arguments.delete(:index)
 
+        _type = arguments.delete(:type)
+
+        method = Elasticsearch::API::HTTP_GET
+        path   = if _index && _type && _id
+                   "#{Utils.__listify(_index)}/#{Utils.__listify(_type)}/#{Utils.__listify(_id)}/_explain"
+                 else
+                   "#{Utils.__listify(_index)}/_explain/#{Utils.__listify(_id)}"
+  end
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+
+        body = arguments[:body]
         perform_request(method, path, params, body).body
       end
 
       # Register this action with its valid params when the module is loaded.
       #
-      # @since 6.1.1
+      # @since 6.2.0
       ParamsRegistry.register(:explain, [
-          :analyze_wildcard,
-          :analyzer,
-          :default_operator,
-          :df,
-          :stored_fields,
-          :lenient,
-          :parent,
-          :preference,
-          :q,
-          :routing,
-          :_source,
-          :_source_excludes,
-          :_source_includes ].freeze)
+        :analyze_wildcard,
+        :analyzer,
+        :default_operator,
+        :df,
+        :stored_fields,
+        :lenient,
+        :preference,
+        :q,
+        :routing,
+        :_source,
+        :_source_excludes,
+        :_source_includes
+      ].freeze)
+    end
     end
-  end
 end