elastic · pquentin · Apr 28, 2025 · Apr 28, 2025
diff --git a/docs/release-notes/breaking-changes.md b/docs/release-notes/breaking-changes.md
@@ -14,11 +14,40 @@ Breaking changes can impact your Elastic applications, potentially disrupting no
 % **Action**<br> Steps for mitigating deprecation impact.
 % ::::
 
-% ## 9.0.0 [elasticsearch-python-client-900-breaking-changes]
+## 9.0.0 [elasticsearch-python-client-900-breaking-changes]
 
-% ::::{dropdown} Title of breaking change 
-% Description of the breaking change.
-% For more information, check [PR #](PR link).
-% **Impact**<br> Impact of the breaking change.
-% **Action**<br> Steps for mitigating deprecation impact.
-% ::::
+::::{dropdown} Remove deprecated Elasticsearch() options
+The `timeout`, `randomize_hosts`, `host_info_callback`, `sniffer_timeout`, `sniff_on_connection_fail` and `maxsize` parameters were deprecated in elasticsearch-py 8.0 and are now removed from `Elasticsearch.__init__()`.
+For more information, check [PR #2840](https://github.com/elastic/elasticsearch-py/pull/2840).
+
+**Impact**<br> These parameters were removed in favor of more descriptive versions. Using any of these parameters will prevent instantiating the Elasticsearch client.
+
+**Action**<br> These parameters can be replaced as follows:
+ * `timeout` is now `request_timeout`
+ * `randomize_hosts` is now `randomize_nodes_in_pool`
+ * `host_info_callback` is now `sniffed_node_callback`
+ * `sniffer_timeout` is now `min_delay_between_sniffing`
+ * `sniff_on_connection_fail` is now `sniff_on_node_failure`
+ * `maxsize` is now `connection_per_node`
+::::
+
+::::{dropdown} Remove deprecated url_prefix and use_ssl host keys
+When instantiating a new client, `hosts` can be specified as a dictionary. The `url_prefix` and `use_ssl` keys are no longer allowed.
+For more information, check [PR #2797](https://github.com/elastic/elasticsearch-py/pull/2797).
+
+**Impact**<br>
+Using any of these parameters will prevent instantiating the Elasticsearch client.
+
+**Action**<br>
+The parameters can be replaced as follows:
+ * `use_ssl` isn't needed, as a scheme is required since elasticsearch-py 8.0 (`http` or `https`)
+ * `url_prefix` should be replaced with `path_prefix`, which is more descriptive. This functionality allows you to deploy Elasticsearch under a specific path, such as `http://host:port/path/to/elasticsearch`, instead of the default root path (`http://host:port/`)
+::::
+
+::::{dropdown} Remove APIs
+Elasticsearch 9 removed the kNN search and Unfreeze index APIs.
+
+**Action**<br>
+ * The kNN search API has been replaced by the `knn` option in the search API since Elasticsearch 8.4.
+ * The Unfreeze index API was deprecated in Elasticsearch 7.14 and has been removed in Elasticsearch 9.
+ ::::
diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md
@@ -21,54 +21,65 @@ To check for security updates, go to [Security announcements for the Elastic sta
 
 ## 9.0.0 (2025-04-15) [elasticsearch-python-client-900-release-notes]
 
+:::{tip}
+Upgrade to Elasticsearch 9 before using elasticsearch-py 9.0.0 or later. Using elasticsearch-py 9.0.0 on an Elasticsearch 8 server will fail.
+Since language clients are forward-compatible, you should first upgrade Elasticsearch, then the Elasticsearch client. See the [compatibility documentation](/reference/index.md#_compatibility) for more details.
+:::
+
+### Breaking changes
+
 * Remove deprecated `Elasticsearch()` options ([#2840](https://github.com/elastic/elasticsearch-py/pull/2840))
 * Remove deprecated `url_prefix` and `use_ssl` options ([#2797](https://github.com/elastic/elasticsearch-py/pull/2797))
-* Merge `Elasticsearch-DSL <https://github.com/elastic/elasticsearch-dsl-py/>`_ package ([#2736](https://github.com/elastic/elasticsearch-py/pull/2736))
+
+See the [breaking changes page](breaking-changes.md) for more details.
+
+### Enhancements
+
+* Merge [`elasticsearch-dsl-py`](https://github.com/elastic/elasticsearch-dsl-py/) _ package ([#2736](https://github.com/elastic/elasticsearch-py/pull/2736))
 * Add Python DSL documentation ([#2761](https://github.com/elastic/elasticsearch-py/pull/2761))
 * Autogenerate DSL field classes from schema ([#2780](https://github.com/elastic/elasticsearch-py/pull/2780))
 * Improve DSL documentation examples with class-based queries and type hints ([#2857](https://github.com/elastic/elasticsearch-py/pull/2857))
 * Document the use of `param()` in Python DSL methods ([#2861](https://github.com/elastic/elasticsearch-py/pull/2861))
 * Migrate documentation from AsciiDoc to Markdown format ([#2806](https://github.com/elastic/elasticsearch-py/pull/2806))
 * Document use of sub-clients ([#2798](https://github.com/elastic/elasticsearch-py/pull/2798))
-* Document how to making API calls ([#2843](https://github.com/elastic/elasticsearch-py/pull/2843))
+* Document how to make API calls ([#2843](https://github.com/elastic/elasticsearch-py/pull/2843))
 * Fix `simulate` sub-client documentation ([#2749](https://github.com/elastic/elasticsearch-py/pull/2749))
-* Update APIs
-  * Remove deprecated `/_knn_search` API
-  * Remove Unfreeze an index API
-  * Remove min_compatible_shard_node from Search and Async Search Submit APIs
-  * Remove local parameter from cat alias, Alias exists, and Get alias APIs
-  * Remove `verbose` from Index segments API
-  * Remove `include_model_definition` from Get trained model configuration info API
-  * Remove `wait_for_active_shards` from experimental Get field usage stats API
-  * Support soft-deletes in connectors:
-    * Add `hard` to Delete connector API
-    * Add `include_deleted` to Get and List Connector APIs
-  * Add `master_timeout` to Migrate to data tiers routing APIs
-  * Add `master_timeout` to the Alias exists and Get alias APIs.
-  * Add `expand_wildcards` to Create snapshot API
-  * Rename incorrect `access_token` to `token` in Logout of OpenID Connect API
-  * Add inference APIs: Alibaba Cloud AI Search, Amazon Bedrock, Anthropic, Azure AI Studio, Azure OpenAI, Cohere, Elastic Inference Service (EIS), Elasticsearch, ELSER, Google AI Studio, Google Vertex AI, Hugging Face, Jina AI, Mistral, OpenAI, and Voyage AI
-  * Add Elastic Inference Service (EIS) chat completion API
-  * Add Reindex legacy backing indices APIs
-  * Add Create an index from a source index API
-  * Add `include_source_on_error` to Create, Index, Update and Bulk APIs
-  * Add Stop async ES|QL query API
-  * Add `timeout` to Resolve Cluster API
-  * Add `adaptive_allocations` body field to Start and Update a trained model deployment API
-  * Rename `index_template_subtitutions` to `index_template_substitutions` in Simulate data ingestion API* Add `if_primary_term`, `if_seq_no`, `op_type`, `require_alias` and `require_data_stream` to Create API
-  * Add `max_concurrent_shard_requests` to Open point in time API
-  * Add `local` and `flat_settings` to Check index templates API
-  * Add `reopen` to Update index settings API
-  * Add `resource` to Reload search analyzer API
-  * Add `lazy` to Roll over to a new index API
-  * Add `cause` and `create` to Simulate index template APIs
-  * Add Elastic Inference Service (EIS) chat completion
-  * Add inference APIs: Alibaba Cloud AI Search, Amazon Bedrock, Anthropic, Azure AI Studio, Azure OpenAI, Cohere, Elastic Inference Service (EIS), Elasticsearch, ELSER, Google AI Studio, Google Vertex AI, Hugging Face, Jina AI, Mistral, OpenAI, and Voyage AI
-* Update DSL
-  * Add `ignore_malformed`, `script`,  `on_script_error` and `time_series_dimension` to Boolean field
-  * Add `index` to GeoShape field
-  * Add `search_inference_id` to SemanticText field
-
-### Features and enhancements [elasticsearch-python-client-900-features-enhancements]
-
-### Fixes [elasticsearch-python-client-900-fixes]
+
+### APIs
+
+* Remove deprecated `/_knn_search` API
+* Remove Unfreeze an index API
+* Remove `min_compatible_shard_node` from Search and Async Search Submit APIs
+* Remove local parameter from cat alias, Alias exists, and Get alias APIs
+* Remove `verbose` from Index segments API
+* Remove `include_model_definition` from Get trained model configuration info API
+* Remove `wait_for_active_shards` from experimental Get field usage stats API
+* Support soft-deletes in connectors:
+  * Add `hard` to Delete connector API
+  * Add `include_deleted` to Get and List Connector APIs
+* Add `master_timeout` to Migrate to data tiers routing APIs
+* Add `master_timeout` to the Alias exists and Get alias APIs.
+* Add `expand_wildcards` to Create snapshot API
+* Rename incorrect `access_token` to `token` in Logout of OpenID Connect API
+* Add inference APIs: Alibaba Cloud AI Search, Amazon Bedrock, Anthropic, Azure AI Studio, Azure OpenAI, Cohere, Elastic Inference Service (EIS), Elasticsearch, ELSER, Google AI Studio, Google Vertex AI, Hugging Face, Jina AI, Mistral, OpenAI, and Voyage AI
+* Add Elastic Inference Service (EIS) chat completion API
+* Add Reindex legacy backing indices APIs
+* Add Create an index from a source index API
+* Add `include_source_on_error` to Create, Index, Update and Bulk APIs
+* Add Stop async ES|QL query API
+* Add `timeout` to Resolve Cluster API
+* Add `adaptive_allocations` body field to Start and Update a trained model deployment API
+* Rename `index_template_subtitutions` to `index_template_substitutions` in Simulate data ingestion API
+* Add `if_primary_term`, `if_seq_no`, `op_type`, `require_alias` and `require_data_stream` to Create API
+* Add `max_concurrent_shard_requests` to Open point in time API
+* Add `local` and `flat_settings` to Check index templates API
+* Add `reopen` to Update index settings API
+* Add `resource` to Reload search analyzer API
+* Add `lazy` to Roll over to a new index API
+* Add `cause` and `create` to Simulate index template APIs
+* Add inference APIs: Alibaba Cloud AI Search, Amazon Bedrock, Anthropic, Azure AI Studio, Azure OpenAI, Cohere, Elasticsearch, ELSER, Google AI Studio, Google Vertex AI, Hugging Face, Jina AI, Mistral, OpenAI, and Voyage AI
+
+### DSL
+ * Add `ignore_malformed`, `script`,  `on_script_error` and `time_series_dimension` to Boolean field
+ * Add `index` to GeoShape field
+ * Add `search_inference_id` to SemanticText field