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).

v8.16.0

Client

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

API

API changes

• capabilities - Adds local_only boolean parameter: True if only the node being called should be considered.
• cluster.stats- Removes flat_settings parameter, adds include_remotes boolean parameter: Include remote cluster data into the response (default: false)
• indices.get_data_stream - Adds verbose boolean parameter: Whether the maximum timestamp for each data stream should be calculated and returned (default: false). Adds master_timeout (see below).
• query_rules.delete_ruleset - Accepts ignore: 404 common parameter.

Timeout parameters:

These parameters have been added to several APIs:

• master_timeout timeout for processing on master node.
• timeout timeout for acknowledgement of update from all nodes in cluster parameters.

Added in:

• indices.create_data_stream - both.
• indices.delete_data_stream - master_timeout.
• indices.get_data_lifecycle - master_timeout.
• indices.get_data_stream - master_timeout.
• indices.migrate_to_data_stream - both.
• indices.promote_data_stream - master_timeout.
• search_shards - master_timeout.

APIs Promoted from Experimental to Stable:

• indices.delete_data_lifecycle
• indices.explain_data_lifecycle
• indices.get_data_lifecycle
• indices.put_data_lifecycle
• security.create_cross_cluster_api_key
• security.update_cross_cluster_api_key

New APIs

• ingest.delete_ip_location_database - Deletes an ip location database configuration.
• ingest.get_ip_location_database - Returns the specified ip location database configuration.
• ingest.put_ip_location_database - Puts the configuration for a ip location database to be downloaded.

New Experimental APIs

• inference.stream_inference - Perform streaming inference.
• query_rules.test - Tests a query ruleset to identify the rules that would match input criteria.

v8.15.0

Client

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

API changes

• snapshot.delete - Adds wait_for_completion Boolean parameter, should this request wait until the operation has completed before returning.
• cluster.allocation_explain - body is no longer a required parameter.
• connector.put - (experimental API) body and connector_id no longer required parameters.
• machine_learning.update_trained_model_deployment has been promoted to stable from Beta. Adds Integer parameter number_of_allocations, updates the model deployment to this number of allocations.

master_timeout and timeout parameters

These parameters have been added to several APIs:

• master_timeout timeout for processing on master node.
• timeout timeout for acknowledgement of update from all nodes in cluster parameters.

The APIs:

• autoscaling.delete_autoscaling_policy - both.
• autoscaling.get_autoscaling_capacity- master_timeout.
• get_autoscaling_policy - master_timeout.
• put_autoscaling_policy - both.
• enrich.delete_policy - master_timeout.
• enrich.execute_policy - master_timeout.
• enrich.get_policy - master_timeout.
• enrich.put_policy - master_timeout.
• enrich.stats - master_timeout.
• features.reset_features - master_timeout.
• license.delete - both.
• license.post - both.
• license.post_start_basic - both.
• license.post_start_trial - both.
• security.get_settings - master_timeout.
• security.update_settings - both.
• shutdown.get_node - master_timeout.
• snapshot_lifecycle_management.start - both.
• snapshot_lifecycle_management.stop - both.
• watcher.get_settings - master_timeout.
• watcher.start - master_timeout.
• watcher.stop - master_timeout.
• watcher.update_settings - both.

Inference APIs have been renamed:

• inference.delete_model => inference.delete. Also adds two new parameters:
  • dry_run (Boolean), if true the endpoint will not be deleted and a list of ingest processors which reference this endpoint will be returned.
  • force (Boolean), if true the endpoint will be forcefully stopped (regardless of whether or not it is referenced by any ingest processors or semantic text fields).
• inference.get_model => inference.get
• inference.put_model => inference.put

Query Rules parameters consolidated

Changes in query_ruleset and query_rules APIs, these have been combined into the query_rules namespace:

• query_rules.delete_ruleset - Renamed from query_ruleset.delete, promoted from experimental to stable.
• query_rules.delete_rule - Deletes an individual query rule within a ruleset.
• query_rules.get_rule - Returns the details about an individual query rule within a ruleset.
• query_rules.get_ruleset - Renamed from query_ruleset.get, promoted from experimental to stable.
• query_rules.list_rulesets - Renamed from query_ruleset.list, promoted from experimental to stable.
• query_rules.put_rule - Creates or updates a query rule within a ruleset.
• query_rules.put_ruleset - Renamed from query_ruleset.put_ruleset, promoted from experimental to stable.

New APIs:

• ingest.delete_geoip_database - Deletes a geoip database configuration.
• ingest.get_geoip_database - Returns geoip database configuration.
• ingest.put_geoip_database - Puts the configuration for a geoip database to be downloaded.
• security.bulk_delete_role - Bulk delete roles in the native realm.
• security.bulk_put_role - Bulk adds and updates roles in the native realm.
• security.query_role - Retrieves information for Roles using a subset of query DSL.
• transform.get_node_stats - Retrieves transform usage information for transform nodes.

New Experimental APIs:

• connector.sync_job_claim - Claims a connector sync job.
• connector.update_features - Updates the connector features in the connector document.

Development

• Added a build using es-test-runner-ruby and Elasticsearch Clients Tests which will replace the Elasticsearch YAML test runner.

v8.14.0

Client

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

API

API changes:

• All Connector APIs have been migrated to one common namespace connector:

  • connector_secret.delete -> connector.secret_delete
  • connector_secret.get -> connector.secret_get
  • connector_secret.post -> connector.secret_post
  • connector_secret.put -> connector.secret_put
  • connector_sync_job.cancel -> connector.sync_job_cancel
  • connector_sync_job.check_in -> connector.sync_job_check_in
  • connector_sync_job.delete -> connector.sync_job_delete
  • connector_sync_job.error -> connector.sync_job_error
  • connector_sync_job.get -> connector.sync_job_get
  • connector_sync_job.post -> connector.sync_job_post
  • connector_sync_job.update_stats -> connector.sync_job_update_stats

• connector.delete - Adds Boolean parameter :delete_sync_jobs: Determines whether associated sync jobs are also deleted.

• cross_cluster_replication.delete_auto_follow_pattern, cross_cluster_replication.follow, cross_cluster_replication.follow_info, cross_cluster_replication.get_auto_follow_pattern, cross_cluster_replication.pause_auto_follow_pattern, cross_cluster_replication.pause_follow, cross_cluster_replication.put_auto_follow_pattern, cross_cluster_replication.resume_auto_follow_pattern, cross_cluster_replication.resume_follow, cross_cluster_replication.stats, cross_cluster_replication.unfollow - Add Time parameter :master_timeout: Explicit operation timeout for connection to master node.

• cross_cluster_replication.follow_stats, cross_cluster_replication.forget_follower, cross_cluster_replication.stats - Add Time parameter :timeout: Explicit operation timeout.

• indices/rollover - Adds Boolean parameter :target_failure If set to true, the rollover action will be applied on the failure store of the data stream.

• inference.get_model - Parameter inference_id no longer required.

• search_application.search - Adds Boolean parameter :typed_keys: Specify whether aggregation and suggester names should be prefixed by their respective types in the response.

• security.get_api_key, security.query_api_keys - Add Boolean parameter :with_profile_uid: flag to also retrieve the API Key's owner profile uid, if it exists.

New APIs:

• profiling.topn_functions - Extracts a list of topN functions from Universal Profiling.
• text_structure.find_field_structure - Finds the structure of a text field in an index.
• text_structure/find_message_structure- Finds the structure of a list of messages. The messages must contain data that is suitable to be ingested into Elasticsearch.

APIs Migrated from experimental to stable:

• esql.async_query
• esql.query

New Experimental APIs:

• connector.update_active_filtering - Activates the draft filtering rules if they are in a validated state.
• connector.update_filtering_validation - Updates the validation info of the draft filtering rules.