v8.19.0

Client

Tested versions of Ruby for 8.19.0: Ruby (MRI) 3.1, 3.2, 3.3, 3.4. JRuby 9.3, JRuby 9.4 and JRuby 10.

API changes

• cluster.get_component_template - Adds flat_settings boolean parameter, return settings in flat format (default: false). Adds settings_filter String parameter, filter out results, for example to filter out sensitive information.
• cluster.put_component_template - Removes timeout parameter, adds cause String parameter, used defined reason for creation.
• create - Adds require_alias and require_data_stream boolean parameters, to specify required type to be created.
• eql.search - Adds ccs_minimize_roundtrips, ignore_unavailable, allow_no_indices boolean parameters and expand_wildcards String parameter.
• esql.async_query - Adds allow_partial_results boolean parameter.
• esql.async_query_get - Adds format String parameter (e.g. json, yaml).
• esql.query - Adds allow_partial_results boolean parameter.
• indices.recovery - Adds ignore_unavailable, allow_no_indices boolean parameters and expand_wildcards String parameter.
• msearch - Adds ignore_unavailable, ignore_throttled, allow_no_indices, include_named_queries_score boolean parameters, expand_wildcards String parameter and routing, a comma-separated list of specific routing values.
• open_point_in_time - Adds max_concurrent_shard_requests parameter, the number of concurrent shard requests per node executed concurrently when opening this point-in-time
• reindex - Adds require_alias boolean parameter.
• search_mvt - Adds grid_agg String parameter, aggregation used to create a grid for field.
• snapshot.repository_analyze - Adds register_operation_count parameter, the minimum number of linearizable register operations to perform in total.

Time parameters master_timeout and timeout have been added to the following APIs:

• index_lifecycle_management:

  • delete_lifecycle
  • get_lifecycle
  • put_lifecycle
  • start
  • stop
  • explain_lifecycle - Only master_timeout

• ingest:

  • delete_geoip_database
  • delete_ip_location_database
  • put_geoip_database
  • put_ip_location_database

New APIs

• indices.delete_data_stream_options - Deletes the data stream options of the selected data streams.
• indices.get_data_stream_options - Returns the data stream options of the selected data streams.
• indices.get_data_stream_settings - Gets a data stream's settings.
• indices.put_data_stream_options - Updates the data stream options of the selected data streams.
• indices.put_data_stream_settings - Updates a data stream's settings.
• inference.put_amazonsagemaker - Configure an Amazon SageMaker inference endpoint.
• inference.put_custom - Configure a custom inference endpoint.
• inference.put_deepseek - Configure a DeepSeek inference endpoint.

v9.0.3

• Adds ccr alias for cross_cluster_replication and slm alias for snapshot_lifecycle_management.
• Tested for JRuby 10.0.0.
• General updates in source code docs.

v9.0.2

Udpates setting 'Accept' and 'Content-Type' headers as to not duplicate or overwrite user set headers #2666.

v9.0.1

Fixes

• The request headers were updated for Elasticsearch v9: compatible-with=9 #2660.

v9.0.0

Ruby 3.2 and up are tested and supported for 9.0. Older versions of Ruby have reached their end of life. We follow Ruby’s own maintenance policy and officially support all currently maintained versions per Ruby Maintenance Branches. The required Ruby version is set to 2.6 to keep compatiblity wit JRuby 9.3. However, we only test the code against currently supported Ruby versions.

Gem

The size of both elasticsearch and elasticsearch-api gems is smaller than in previous versions. Some unnecessary files that were being included in the gem have now been removed. There has also been a lot of old code cleanup for the 9.x branch.

Elasticsearch Serverless

With the release of 9.0, the Elasticsearch Serverless client has been discontinued. You can use this client to build your Elasticsearch Serverless Ruby applications. The Elasticsearch Serverless API is fully supported. The CI build for Elasticsearch Ruby runs tests to ensure compatibility with Elasticsearch Serverless.

Elasticsearch API

• The source code is now generated from elasticsearch-specification, so the API documentation is much more detailed and extensive. The value Elasticsearch::ES_SPECIFICATION_COMMIT is updated with the commit hash of elasticsearch-specification in which the code is based every time it's generated.
• The API code has been updated for compatibility with Elasticsearch API v 9.0.
• indices.get_field_mapping - :fields is a required parameter.
• knn_search - This API has been removed. It was only ever experimental and was deprecated in v8.4. It isn't supported in 9.0, and only works when the header compatible-with=8 is set. The search API should be used for all knn queries.
• The functions in utils.rb that had names starting with double underscore have been renamed to remove these (e.g. __listify to listify).
• Namespaces clean up: The API namespaces are now generated dynamically based on the elasticsearch-specification. As such, some deprecated namespace files have been removed from the codebase:
  • The rollup namespace was removed. The rollup feature was never GA-ed, it has been deprecated since 8.11.0 in favor of downsampling.
  • The data_frame_deprecated, remote namespace files have been removed, no APIs were available.
  • The shutdown namespace was removed. It is designed for indirect use by ECE/ESS and ECK. Direct use is not supported.

Scroll APIs need to send scroll_id in request body

Sending the scroll_id as a parameter has been deprecated since version 7.0.0. It needs to be specified in the request body for clear_scroll and scroll.

Impact

Client code using clear_scroll or scroll APIs and the deprecated scroll_id as a parameter needs to be updated.

Action

If you are using the clear_scroll or scroll APIs, and sending the scroll_id as a parameter, you need to update your code to send the scroll_id as part of the request body:

# Before:
client.clear_scroll(scroll_id: scroll_id)
# Now:
client.clear_scroll(body: { scroll_id: scroll_id })

# Before:
client.scroll(scroll_id: scroll_id)
# Now:
client.scroll(body: { scroll_id: scroll_id })

Testing

The gem elasticsearch-api migrated away from the Elasticsearch REST API tests and test runner in CI. We now run the Elasticsearch Client tests with the Elasticsearch Tests Runner. This gives us more control on what we're testing and makes the Buildkite build way faster in Pull Requests and scheduled builds.

Fixes

• Some old rake tasks that were not being used have been removed. The rest were streamlined, the es namespace has been streamlined to make it easier to run Elasticsearch with Docker during development. The docker task namespace was merged into es.
• Elasticsearch's REST API Spec tests can still be ran with rake test:deprecated:rest_api and setting the corresponding value for the environment variable TEST_SUITE ('platinum' or 'free').

v8.18.0

API

New APIs:

• esql.async_query_stop - Stops a previously submitted async query request given its ID and collects the results.
• inference.chat_completion_unified - Perform chat completion inference
• inference.completion - Perform completion inference
• inference.put_alibabacloud - Configure an AlibabaCloud AI Search inference endpoint
• inference.put_amazonbedrock - Configure an Amazon Bedrock inference endpoint
• inference.put_anthropic - Configure an Anthropic inference endpoint
• inference.put_azureaistudio - Configure an Azure AI Studio inference endpoint
• inference.put_azureopenai - Configure an Azure OpenAI inference endpoint
• inference.put_cohere - Configure a Cohere inference endpoint
• inference.put_elasticsearch - Configure an Elasticsearch inference endpoint
• inference.put_elser - Configure an ELSER inference endpoint
• inference.put_googleaistudio - Configure a Google AI Studio inference endpoint
• inference.put_googlevertexai - Configure a Google Vertex AI inference endpoint
• inference.put_hugging_face - Configure a HuggingFace inference endpoint
• inference.put_jinaai - Configure a JinaAI inference endpoint
• inference.put_mistral - Configure a Mistral inference endpoint
• inference.put_openai - Configure an OpenAI inference endpoint
• inference.put_voyageai - Configure a VoyageAI inference endpoint
• inference.put_watsonx - Configure a Watsonx inference endpoint
• inference.rerank - Perform reranking inference
• inference.sparse_embedding - Perform sparse embedding inference
• inference.stream_inference renamed to inference.stream_completion - Perform streaming completion inference.
• inference.text_embedding - Perform text embedding inference

Updated APIs:

• bulk, create, index, update - Add Boolean parameter :include_source_on_error, if to include the document source in the error message in case of parsing errors (defaults to true).
• cat.segments
  • Adds Boolean parameter :local, return local information, do not retrieve the state from master node (default: false).
  • Adds Time parameter :master_timeout, explicit operation timeout for connection to master node.
• cat.tasks
  • Adds Time parameter :timeout, period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
  • Adds Boolean parameter :wait_for_completion, if true, the request blocks until the task has completed.
• eql.search
  • Adds Boolean parameter :allow_partial_search_results, control whether the query should keep running in case of shard failures, and return partial results.
  • Adds Boolean parameter :allow_partial_sequence_results, control whether a sequence query should return partial results or no results at all in case of shard failures. This option has effect only if [allow_partial_search_results] is true.
• index_lifecycle_management.delete_lifecycle, index_lifecycle_management.explain_lifecycle, index_lifecycle_management.get_lifecycle, index_lifecycle_management.put_lifecycle, index_lifecycle_management.start, index_lifecycle_management.stop, remove :master_timeout, :timeout parameters.
• indices.resolve_cluster - Adds :timeout parameter, :name no longer a required parameter.
• indices.rollover - Removes target_failure_store parameter.
• ingest.delete_geoip_database, ingest.delete_ip_location_database, put_geoip_database, put_ip_location_database remove :master_timeout, :timeout parameters.
• machine_learning.start_trained_model_deployment - Adds body request parameter, the settings for the trained model deployment.

v8.17.2

API

New APIs:

• esql.async_query_delete
• indices.get_data_lifecycle_stats
• inference.update
• security.delegate_pki

Updates APIs:

• async_search.submit - Adds keep_alive Time parameter.
• indices.put_template - Adds cause String parameter.
• xpack.info - Adds human parameter for human-readable information.
• Timeout parameters updated:
  • :master_timeout (Time), explicit operation timeout for connection to master node.
  • :timeout (Time), explicit operation timeout.
    • Added to:
      • index_lifecycle_management.delete_lifecycle - adds both.
      • index_lifecycle_management.delete_lifecycle - adds master_timeout.
      • index_lifecycle_management.get_lifecycle - adds both.
      • index_lifecycle_management.put_lifecycle - adds both.
      • index_lifecycle_management.start - adds both.
      • index_lifecycle_management.stop - adds both.
      • ingest.delete_geoip_database - adds both.
      • ingest.delete_geoip_location_database - adds both.
      • ingest.put_geoip_database - adds both.
      • ingest.put_ip_location_database - adds both.
      • license.post_start_trial - removes timeout.
      • shutdown.delete_node - adds both.
      • shutdown.put_node - adds both.
      • snapshot_lifecycle_management.delete_lifecycle - adds both.
      • snapshot_lifecycle_management.execute_lifecycle - adds both.
      • snapshot_lifecycle_management.execute_retention - adds both.
      • snapshot_lifecycle_management.get_lifecycle - adds both.
      • snapshot_lifecycle_management.get_stats - adds both.
      • snapshot_lifecycle_management.get_status - adds both.
      • snapshot_lifecycle_management.put_lifecycle - adds both.

APIs promoted from Experimental to Stable:

• inference.delete
• inference.get
• inference.inference
• inference.put
• inference.stream_inference

v8.17.1

• Fixes ScrollHelper issue #2556 - There was a bug where an additional search (with scroll) request was made to Elasticsearch for each resulting hit. It was rewritten so that the docs are retrieved as needed and the Helper instance doesn't store documents internally, with big savings in memory and requests to Elasticsearch.

v8.16.1

• Fixes ScrollHelper issue #2556 - There was a bug where an additional search (with scroll) request was made to Elasticsearch for each resulting hit. It was rewritten so that the docs are retrieved as needed and the Helper instance doesn't store documents internally, with big savings in memory and requests to Elasticsearch.

v8.17.0

Client

• Tested versions of Ruby for 8.17.0: Ruby (MRI) 3.1, 3.2 and 3.3. JRuby 9.3 and JRuby 9.4.

API

API changes

• async_search.submit - Removes keep_alive parameter. Adds:
  • ccs_minimize_roundtrips (Boolean): When doing a cross-cluster search, setting it to true may improve overall search latency, particularly when searching clusters with a large number of shards. However, when set to true, the progress of searches on the remote clusters will not be received until the search finishes on all clusters.
  • rest_total_hits_as_int (Boolean): Indicates whether hits.total should be rendered as an integer or an object in the rest search response.
• open_point_in_time - Adds allow_partial_search_results (Boolean) parameter: Specify whether to tolerate shards missing when creating the point-in-time, or otherwise throw an exception (default: false).