Skip to content

Update the compatiblity mode section of the docs #3098

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 13, 2025
Merged

Update the compatiblity mode section of the docs #3098

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e2ae249
Update the compatiblity mode section of the docs
miguelgrinberg Oct 9, 2025
6d2cf6d
merge with compatiblity section in index.md
miguelgrinberg Oct 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 0 additions & 7 deletions docs/reference/connecting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -277,13 +277,6 @@ client = Elasticsearch(
```


## Enabling the Compatibility Mode [compatibility-mode]

The {{es}} server version 8.0 is introducing a new compatibility mode that allows you a smoother upgrade experience from 7 to 8. In a nutshell, you can use the latest 7.x Python {{es}} {{es}} client with an 8.x {{es}} server, giving more room to coordinate the upgrade of your codebase to the next major version.

If you want to leverage this functionality, please make sure that you are using the latest 7.x Python {{es}} client and set the environment variable `ELASTIC_CLIENT_APIVERSIONING` to `true`. The client is handling the rest internally. For every 8.0 and beyond Python {{es}} client, you’re all set! The compatibility mode is enabled by default.


## Using the Client in a Function-as-a-Service Environment [connecting-faas]

This section illustrates the best practices for leveraging the {{es}} client in a Function-as-a-Service (FaaS) environment.
Expand Down
8 changes: 7 additions & 1 deletion docs/reference/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,14 @@ Compatibility does not imply full feature parity. New {{es}} features are suppor

{{es}} language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees.

### Major version upgrades

:::{tip}
To upgrade to a new major version, first upgrade {{es}}, then upgrade the Python {{es}} client.
:::

If you need to work with multiple client versions, note that older versions are also released as `elasticsearch7` and `elasticsearch8`.
Since version 8.0, the {{es}} server supports a compatibility mode that allows smoother upgrade experiences. In a nutshell, this makes it possible to upgrade the {{es}} server to the next major version, while continuing to use the same client. This gives more room to coordinate the upgrade of your codebase to the next major version.

For example, to upgrade a system that uses {{es}} 8.x you can upgrade the {{es}} server to 9.x first, and the 8.x Python {{es}} client will continue to work (aside from any breaking changes, which should be listed in the server release notes). You can continue using the 8.x client during the server migration, and only upgrade it once the server migration is complete. The process is described in detail in the [REST API compatibility workflow](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/compatibility#_rest_api_compatibility_workflow) section of the {{es}} documentation.

If you need to work with multiple client versions, note that older versions are also released with the `elasticsearch8` and `elasticsearch9` package names so that they can be installed together.
Loading