From 02b31d22a437fb093550308bd32adeaaa2069c95 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Fri, 14 Nov 2025 14:28:47 -0500 Subject: [PATCH 1/5] Revise and expand --- docs/reference/index.md | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/reference/index.md b/docs/reference/index.md index afc7064a3..868c57391 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -3,6 +3,9 @@ navigation_title: "Python" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html - https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/overview.html +applies_to: + stack: ga + serverless: ga --- # {{es}} Python client [overview] @@ -11,7 +14,6 @@ This documentation covers the [official Python client for {{es}}](https://github API reference documentation is provided on [Read the Docs](https://elasticsearch-py.readthedocs.io). - The following example shows a simple Python client use case: ```python @@ -30,9 +32,6 @@ The following example shows a simple Python client use case: {'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'} ``` - - - ## Features [_features] The client's features include: @@ -51,11 +50,11 @@ The client also provides a convenient set of [helpers](client-helpers.md) for ta To get started, try this walkthrough: [Ingest data with Python](docs-content://manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md) :::: -### Elasticsearch Python DSL [_elasticsearch_python_dsl] +### {{es}} Python DSL [_elasticsearch_python_dsl] The [Python DSL module](../reference/elasticsearch-dsl.md) offers a convenient and idiomatic way to write and manipulate queries. -## {{es}} version compatibility [_compatibility] +## Version compatibility Language clients are **forward compatible**: each client version works with equivalent and later minor versions of the **same or next major** version of {{es}}. For full compatibility, the client and {{es}} minor versions should match. @@ -66,20 +65,34 @@ Language clients are **forward compatible**: each client version works with equi Compatibility does not imply feature parity. New {{es}} features are supported only in equivalent client versions. For example, an 8.12 client fully supports {{es}} 8.12 features and works with 8.13 without breaking, but it does not support new {{es}} 8.13 features. An 8.13 client fully supports {{es}} 8.13 features. -{{es}} language clients are also **backward compatible** across minor versions, with default distributions and without guarantees. +{{es}} language clients are also **backward compatible** across minor versions, with default distributions and without guarantees. -### Major version upgrades +## Upgrade to a new major version :::{important} To upgrade to a new major version, first [upgrade {{es}}](docs-content://deploy-manage/upgrade.md), then upgrade the Python client. ::: -As of version 8.0, {{es}} offers a [compatibility mode](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) for smoother upgrades. In compatibility mode, you can upgrade your {{es}} cluster to the next major version while continuing to use your existing client during the transition. +As of version 8.0, {{es}} offers a [REST API compatibility mode](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) for smoother upgrades. In compatibility mode, you can upgrade your {{es}} cluster to the next major version while continuing to use your existing client during the transition. + +### How compatibility mode works + +In the Python client, compatibility mode is **always enabled**. You don't need to configure it manually or set an environment variable. The client automatically sends compatibility headers with API requests so that it can communicate with the next major version of {{es}}. -For example, if you're upgrading {{es}} from 8.x to 9.x, you can continue to use the 8.x Python client during and after the {{es}} server upgrade, with the exception of [breaking changes](../release-notes/breaking-changes.md). +In compatibility mode, your Python client applications can continue running during an upgrade without restart or redeployment. For example, during a rolling upgrade of your {{es}} cluster from 8.x to 9.x, your 8.x Python client continues working throughout the process without any changes or intervention. -In the Python client, compatibility mode is always enabled. +**What to expect in compatibility mode:** + +If you're using the Python client in compatibility mode to work with the next major version of {{es}}: + +* API calls affected by [breaking changes](../release-notes/breaking-changes.md) might fail or behave differently. +* API calls unaffected by breaking changes continue to work as expected. +* New features from the next major version of {{es}} are not available until you upgrade the client itself. + +Although compatibility mode allows your Python client to keep working without intervention, you should upgrade the client when feasible. Even if you don't need the newest {{es}} features, upgrading the client ensures you receive the latest bug fixes and improvements. :::{tip} To support working with multiple client versions, the Python client is also released under the package names `elasticsearch8` and `elasticsearch9` (to prevent name collisions). -::: \ No newline at end of file +::: + +For guidance on upgrading your {{es}} deployment, refer to the [{{es}} upgrade documentation](docs-content://deploy-manage/upgrade.md) and [upgrade paths](docs-content://deploy-manage/upgrade.md#upgrade-paths). \ No newline at end of file From 233dd7373e68d0f10b2eb185cc4bd270bae4181c Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Fri, 14 Nov 2025 14:37:26 -0500 Subject: [PATCH 2/5] Accidentally deleted anchor --- docs/reference/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/index.md b/docs/reference/index.md index 868c57391..454f7ccbc 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -54,7 +54,7 @@ To get started, try this walkthrough: [Ingest data with Python](docs-content://m The [Python DSL module](../reference/elasticsearch-dsl.md) offers a convenient and idiomatic way to write and manipulate queries. -## Version compatibility +## Version compatibility [_compatibility] Language clients are **forward compatible**: each client version works with equivalent and later minor versions of the **same or next major** version of {{es}}. For full compatibility, the client and {{es}} minor versions should match. From fb7be1704d8d4196c5efec25bbfab86f804b49a3 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Thu, 20 Nov 2025 17:43:37 -0500 Subject: [PATCH 3/5] Address reviewer comment --- docs/reference/1120elasticsearch-py.code-workspace | 8 ++++++++ docs/reference/index.md | 4 ++-- 2 files changed, 10 insertions(+), 2 deletions(-) create mode 100644 docs/reference/1120elasticsearch-py.code-workspace diff --git a/docs/reference/1120elasticsearch-py.code-workspace b/docs/reference/1120elasticsearch-py.code-workspace new file mode 100644 index 000000000..407c76059 --- /dev/null +++ b/docs/reference/1120elasticsearch-py.code-workspace @@ -0,0 +1,8 @@ +{ + "folders": [ + { + "path": "../.." + } + ], + "settings": {} +} \ No newline at end of file diff --git a/docs/reference/index.md b/docs/reference/index.md index 454f7ccbc..b42193536 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -79,13 +79,13 @@ As of version 8.0, {{es}} offers a [REST API compatibility mode](elasticsearch:/ In the Python client, compatibility mode is **always enabled**. You don't need to configure it manually or set an environment variable. The client automatically sends compatibility headers with API requests so that it can communicate with the next major version of {{es}}. -In compatibility mode, your Python client applications can continue running during an upgrade without restart or redeployment. For example, during a rolling upgrade of your {{es}} cluster from 8.x to 9.x, your 8.x Python client continues working throughout the process without any changes or intervention. +For example, if you're upgrading {{es}} from 8.x to 9.x, you can continue to use the 8.x Python client during and after the {{es}} server upgrade, with the exception of [breaking changes](../release-notes/breaking-changes.md). **What to expect in compatibility mode:** If you're using the Python client in compatibility mode to work with the next major version of {{es}}: -* API calls affected by [breaking changes](../release-notes/breaking-changes.md) might fail or behave differently. +* API calls affected by [breaking changes](../release-notes/breaking-changes.md) might fail or behave differently. * API calls unaffected by breaking changes continue to work as expected. * New features from the next major version of {{es}} are not available until you upgrade the client itself. From d7a4449e5ab02dc9c6f0fc7a835dc5c358bfaed1 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Thu, 20 Nov 2025 17:44:07 -0500 Subject: [PATCH 4/5] Revert "Address reviewer comment" This reverts commit fb7be1704d8d4196c5efec25bbfab86f804b49a3. --- docs/reference/1120elasticsearch-py.code-workspace | 8 -------- docs/reference/index.md | 4 ++-- 2 files changed, 2 insertions(+), 10 deletions(-) delete mode 100644 docs/reference/1120elasticsearch-py.code-workspace diff --git a/docs/reference/1120elasticsearch-py.code-workspace b/docs/reference/1120elasticsearch-py.code-workspace deleted file mode 100644 index 407c76059..000000000 --- a/docs/reference/1120elasticsearch-py.code-workspace +++ /dev/null @@ -1,8 +0,0 @@ -{ - "folders": [ - { - "path": "../.." - } - ], - "settings": {} -} \ No newline at end of file diff --git a/docs/reference/index.md b/docs/reference/index.md index b42193536..454f7ccbc 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -79,13 +79,13 @@ As of version 8.0, {{es}} offers a [REST API compatibility mode](elasticsearch:/ In the Python client, compatibility mode is **always enabled**. You don't need to configure it manually or set an environment variable. The client automatically sends compatibility headers with API requests so that it can communicate with the next major version of {{es}}. -For example, if you're upgrading {{es}} from 8.x to 9.x, you can continue to use the 8.x Python client during and after the {{es}} server upgrade, with the exception of [breaking changes](../release-notes/breaking-changes.md). +In compatibility mode, your Python client applications can continue running during an upgrade without restart or redeployment. For example, during a rolling upgrade of your {{es}} cluster from 8.x to 9.x, your 8.x Python client continues working throughout the process without any changes or intervention. **What to expect in compatibility mode:** If you're using the Python client in compatibility mode to work with the next major version of {{es}}: -* API calls affected by [breaking changes](../release-notes/breaking-changes.md) might fail or behave differently. +* API calls affected by [breaking changes](../release-notes/breaking-changes.md) might fail or behave differently. * API calls unaffected by breaking changes continue to work as expected. * New features from the next major version of {{es}} are not available until you upgrade the client itself. From c7e8bf54e0f77ab3c8c310369cc59979868f7300 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Thu, 20 Nov 2025 17:46:51 -0500 Subject: [PATCH 5/5] Address reviewer comment --- docs/reference/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/index.md b/docs/reference/index.md index 454f7ccbc..b5ceb15e4 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -79,7 +79,7 @@ As of version 8.0, {{es}} offers a [REST API compatibility mode](elasticsearch:/ In the Python client, compatibility mode is **always enabled**. You don't need to configure it manually or set an environment variable. The client automatically sends compatibility headers with API requests so that it can communicate with the next major version of {{es}}. -In compatibility mode, your Python client applications can continue running during an upgrade without restart or redeployment. For example, during a rolling upgrade of your {{es}} cluster from 8.x to 9.x, your 8.x Python client continues working throughout the process without any changes or intervention. +For example, if you're upgrading {{es}} from 8.x to 9.x, you can continue to use the 8.x Python client during and after the {{es}} server upgrade, with the exception of [breaking changes](../release-notes/breaking-changes.md). **What to expect in compatibility mode:**