diff --git a/.buildkite/run-repository.sh b/.buildkite/run-repository.sh
index ce9344e8d..04d4440f0 100755
--- a/.buildkite/run-repository.sh
+++ b/.buildkite/run-repository.sh
@@ -21,6 +21,7 @@ echo -e "\033[34;1mINFO:\033[0m TEST_SUITE ${TEST_SUITE}\033[0m"
echo -e "\033[34;1mINFO:\033[0m NOX_SESSION ${NOX_SESSION}\033[0m"
echo -e "\033[34;1mINFO:\033[0m PYTHON_VERSION ${PYTHON_VERSION}\033[0m"
echo -e "\033[34;1mINFO:\033[0m PYTHON_CONNECTION_CLASS ${PYTHON_CONNECTION_CLASS}\033[0m"
+echo -e "\033[34;1mINFO:\033[0m ES_YAML_TESTS_BRANCH ${ES_YAML_TESTS_BRANCH}\033[0m"
echo -e "\033[1m>>>>> Build [elastic/elasticsearch-py container] >>>>>>>>>>>>>>>>>>>>>>>>>>>>>\033[0m"
@@ -42,6 +43,7 @@ docker run \
--env "ELASTICSEARCH_URL=${elasticsearch_url}" \
--env "TEST_SUITE=${TEST_SUITE}" \
--env "PYTHON_CONNECTION_CLASS=${PYTHON_CONNECTION_CLASS}" \
+ --env "ES_YAML_TESTS_BRANCH=${ES_YAML_TESTS_BRANCH}" \
--env "TEST_TYPE=server" \
--env "FORCE_COLOR=1" \
--name elasticsearch-py \
diff --git a/.buildkite/run-tests b/.buildkite/run-tests
index 5d6b38039..c1b8f4733 100755
--- a/.buildkite/run-tests
+++ b/.buildkite/run-tests
@@ -9,6 +9,10 @@ export STACK_VERSION="${STACK_VERSION:=8.0.0-SNAPSHOT}"
export TEST_SUITE="${TEST_SUITE:=platinum}"
export PYTHON_VERSION="${PYTHON_VERSION:=3.13}"
export PYTHON_CONNECTION_CLASS="${PYTHON_CONNECTION_CLASS:=urllib3}"
+export ES_YAML_TESTS_BRANCH="${BUILDKITE_PULL_REQUEST_BASE_BRANCH}"
+if [[ ! -n "$ES_YAML_TESTS_BRANCH" ]]; then
+ export ES_YAML_TESTS_BRANCH="${BUILDKITE_BRANCH}"
+fi
script_path=$(dirname $(realpath -s $0))
source $script_path/functions/imports.sh
diff --git a/.github/make.sh b/.github/make.sh
index 79d785957..4a363e524 100755
--- a/.github/make.sh
+++ b/.github/make.sh
@@ -11,12 +11,13 @@
#
# Targets:
# ---------------------------
-# assemble : build client artefacts with version
-# bump : bump client internals to version
-# codegen : generate endpoints
-# docsgen : generate documentation
-# examplegen : generate the doc examples
-# clean : clean workspace
+# assemble : build client artefacts with version
+# bump : bump client internals to version
+# bumpmatrix : bump stack version in test matrix to version
+# codegen : generate endpoints
+# docsgen : generate documentation
+# examplegen : generate the doc examples
+# clean : clean workspace
#
# ------------------------------------------------------- #
@@ -24,7 +25,7 @@
# Bootstrap
# ------------------------------------------------------- #
-script_path=$(dirname "$(realpath -s "$0")")
+script_path=$(dirname "$(realpath "$0")")
repo=$(realpath "$script_path/../")
# shellcheck disable=SC1090
@@ -100,6 +101,15 @@ case $CMD in
# VERSION is BRANCH here for now
TASK_ARGS=("$VERSION")
;;
+ bumpmatrix)
+ if [ -v $VERSION ]; then
+ echo -e "\033[31;1mTARGET: bumpmatrix -> missing version parameter\033[0m"
+ exit 1
+ fi
+ echo -e "\033[36;1mTARGET: bump stack in test matrix to version $VERSION\033[0m"
+ TASK=bumpmatrix
+ TASK_ARGS=("$VERSION")
+ ;;
*)
echo -e "\nUsage:\n\t $CMD is not supported right now\n"
exit 1
@@ -160,6 +170,13 @@ if [[ "$CMD" == "bump" ]]; then
exit 0
fi
+if [[ "$CMD" == "bumpmatrix" ]]; then
+ TEST_CONFIG_FILE=.buildkite/pipeline.yml
+ sed -E -i.bak 's/[0-9]+\.[0-9]+\.[0-9]+-SNAPSHOT/'$VERSION'/g' $TEST_CONFIG_FILE
+ rm ${TEST_CONFIG_FILE}.bak
+ exit 0
+fi
+
if [[ "$CMD" == "codegen" ]]; then
docker run \
--rm -v $repo:/code/elasticsearch-py \
diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml
deleted file mode 100644
index 40d7b7208..000000000
--- a/.github/workflows/docs-preview.yml
+++ /dev/null
@@ -1,20 +0,0 @@
----
-name: docs-preview
-
-on:
- pull_request_target:
- types: [opened]
-
-permissions:
- pull-requests: write
-
-jobs:
- doc-preview-pr:
- runs-on: ubuntu-latest
- steps:
- - uses: elastic/docs/.github/actions/docs-preview@master
- with:
- github-token: ${{ secrets.GITHUB_TOKEN }}
- repo: ${{ github.event.repository.name }}
- preview-path: 'guide/en/elasticsearch/client/python-api/index.html'
- pr: ${{ github.event.pull_request.number }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fb156ae2a..df468b466 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1 +1 @@
-See: https://www.elastic.co/guide/en/elasticsearch/client/python-api/master/release-notes.html
+See: https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/release-notes.html
diff --git a/README.md b/README.md
index eb242a90c..11d1b8259 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-
+
# Elasticsearch Python Client
@@ -63,24 +63,23 @@ of the getting started documentation.
## Compatibility
-Language clients are forward compatible; meaning that the clients support
-communicating with greater or equal minor versions of Elasticsearch without
-breaking. It does not mean that the clients automatically support new features
-of newer Elasticsearch versions; it is only possible after a release of a new
-client version. For example, a 8.12 client version won't automatically support
-the new features of the 8.13 version of Elasticsearch, the 8.13 client version
-is required for that. Elasticsearch language clients are only backwards
-compatible with default distributions and without guarantees made.
+Language clients are _forward compatible:_ each client version works with equivalent and later minor versions of Elasticsearch without breaking.
-| Elasticsearch Version | Elasticsearch-Python Branch | Supported |
-| --------------------- | ------------------------ | --------- |
-| main | main | |
-| 8.x | 8.x | 8.x |
-| 7.x | 7.x | 7.17 |
+Compatibility does not imply full feature parity. New Elasticsearch features are supported only in equivalent client versions. For example, an 8.12 client fully supports Elasticsearch 8.12 features and works with 8.13 without breaking; however, it does not support new Elasticsearch 8.13 features. An 8.13 client fully supports Elasticsearch 8.13 features.
+| Elasticsearch version | elasticsearch-py branch |
+| --- | --- |
+| main | main |
+| 9.x | 9.x |
+| 9.x | 8.x |
+| 8.x | 8.x |
-If you have a need to have multiple versions installed at the same time older
-versions are also released as ``elasticsearch7`` and ``elasticsearch8``.
+Elasticsearch language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees.
+
+> [!TIP]
+> To upgrade to a new major version, first upgrade Elasticsearch, then upgrade the Python Elasticsearch client.
+
+If you need to work with multiple client versions, note that older versions are also released as `elasticsearch7` and `elasticsearch8`.
## Documentation
diff --git a/docs/docset.yml b/docs/docset.yml
index 882aea405..b4185d296 100644
--- a/docs/docset.yml
+++ b/docs/docset.yml
@@ -7,482 +7,4 @@ toc:
- toc: reference
- toc: release-notes
subs:
- ref: "https://www.elastic.co/guide/en/elasticsearch/reference/current"
- ref-bare: "https://www.elastic.co/guide/en/elasticsearch/reference"
- ref-8x: "https://www.elastic.co/guide/en/elasticsearch/reference/8.1"
- ref-80: "https://www.elastic.co/guide/en/elasticsearch/reference/8.0"
- ref-7x: "https://www.elastic.co/guide/en/elasticsearch/reference/7.17"
- ref-70: "https://www.elastic.co/guide/en/elasticsearch/reference/7.0"
- ref-60: "https://www.elastic.co/guide/en/elasticsearch/reference/6.0"
- ref-64: "https://www.elastic.co/guide/en/elasticsearch/reference/6.4"
- xpack-ref: "https://www.elastic.co/guide/en/x-pack/6.2"
- logstash-ref: "https://www.elastic.co/guide/en/logstash/current"
- kibana-ref: "https://www.elastic.co/guide/en/kibana/current"
- kibana-ref-all: "https://www.elastic.co/guide/en/kibana"
- beats-ref-root: "https://www.elastic.co/guide/en/beats"
- beats-ref: "https://www.elastic.co/guide/en/beats/libbeat/current"
- beats-ref-60: "https://www.elastic.co/guide/en/beats/libbeat/6.0"
- beats-ref-63: "https://www.elastic.co/guide/en/beats/libbeat/6.3"
- beats-devguide: "https://www.elastic.co/guide/en/beats/devguide/current"
- auditbeat-ref: "https://www.elastic.co/guide/en/beats/auditbeat/current"
- packetbeat-ref: "https://www.elastic.co/guide/en/beats/packetbeat/current"
- metricbeat-ref: "https://www.elastic.co/guide/en/beats/metricbeat/current"
- filebeat-ref: "https://www.elastic.co/guide/en/beats/filebeat/current"
- functionbeat-ref: "https://www.elastic.co/guide/en/beats/functionbeat/current"
- winlogbeat-ref: "https://www.elastic.co/guide/en/beats/winlogbeat/current"
- heartbeat-ref: "https://www.elastic.co/guide/en/beats/heartbeat/current"
- journalbeat-ref: "https://www.elastic.co/guide/en/beats/journalbeat/current"
- ingest-guide: "https://www.elastic.co/guide/en/ingest/current"
- fleet-guide: "https://www.elastic.co/guide/en/fleet/current"
- apm-guide-ref: "https://www.elastic.co/guide/en/apm/guide/current"
- apm-guide-7x: "https://www.elastic.co/guide/en/apm/guide/7.17"
- apm-app-ref: "https://www.elastic.co/guide/en/kibana/current"
- apm-agents-ref: "https://www.elastic.co/guide/en/apm/agent"
- apm-android-ref: "https://www.elastic.co/guide/en/apm/agent/android/current"
- apm-py-ref: "https://www.elastic.co/guide/en/apm/agent/python/current"
- apm-py-ref-3x: "https://www.elastic.co/guide/en/apm/agent/python/3.x"
- apm-node-ref-index: "https://www.elastic.co/guide/en/apm/agent/nodejs"
- apm-node-ref: "https://www.elastic.co/guide/en/apm/agent/nodejs/current"
- apm-node-ref-1x: "https://www.elastic.co/guide/en/apm/agent/nodejs/1.x"
- apm-rum-ref: "https://www.elastic.co/guide/en/apm/agent/rum-js/current"
- apm-ruby-ref: "https://www.elastic.co/guide/en/apm/agent/ruby/current"
- apm-java-ref: "https://www.elastic.co/guide/en/apm/agent/java/current"
- apm-go-ref: "https://www.elastic.co/guide/en/apm/agent/go/current"
- apm-dotnet-ref: "https://www.elastic.co/guide/en/apm/agent/dotnet/current"
- apm-php-ref: "https://www.elastic.co/guide/en/apm/agent/php/current"
- apm-ios-ref: "https://www.elastic.co/guide/en/apm/agent/swift/current"
- apm-lambda-ref: "https://www.elastic.co/guide/en/apm/lambda/current"
- apm-attacher-ref: "https://www.elastic.co/guide/en/apm/attacher/current"
- docker-logging-ref: "https://www.elastic.co/guide/en/beats/loggingplugin/current"
- esf-ref: "https://www.elastic.co/guide/en/esf/current"
- kinesis-firehose-ref: "https://www.elastic.co/guide/en/kinesis/%7B%7Bkinesis_version%7D%7D"
- estc-welcome-current: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current"
- estc-welcome: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions/current"
- estc-welcome-all: "https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its-solutions"
- hadoop-ref: "https://www.elastic.co/guide/en/elasticsearch/hadoop/current"
- stack-ref: "https://www.elastic.co/guide/en/elastic-stack/current"
- stack-ref-67: "https://www.elastic.co/guide/en/elastic-stack/6.7"
- stack-ref-68: "https://www.elastic.co/guide/en/elastic-stack/6.8"
- stack-ref-70: "https://www.elastic.co/guide/en/elastic-stack/7.0"
- stack-ref-80: "https://www.elastic.co/guide/en/elastic-stack/8.0"
- stack-ov: "https://www.elastic.co/guide/en/elastic-stack-overview/current"
- stack-gs: "https://www.elastic.co/guide/en/elastic-stack-get-started/current"
- stack-gs-current: "https://www.elastic.co/guide/en/elastic-stack-get-started/current"
- javaclient: "https://www.elastic.co/guide/en/elasticsearch/client/java-api/current"
- java-api-client: "https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current"
- java-rest: "https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current"
- jsclient: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current"
- jsclient-current: "https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current"
- es-ruby-client: "https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current"
- es-dotnet-client: "https://www.elastic.co/guide/en/elasticsearch/client/net-api/current"
- es-php-client: "https://www.elastic.co/guide/en/elasticsearch/client/php-api/current"
- es-python-client: "https://www.elastic.co/guide/en/elasticsearch/client/python-api/current"
- defguide: "https://www.elastic.co/guide/en/elasticsearch/guide/2.x"
- painless: "https://www.elastic.co/guide/en/elasticsearch/painless/current"
- plugins: "https://www.elastic.co/guide/en/elasticsearch/plugins/current"
- plugins-8x: "https://www.elastic.co/guide/en/elasticsearch/plugins/8.1"
- plugins-7x: "https://www.elastic.co/guide/en/elasticsearch/plugins/7.17"
- plugins-6x: "https://www.elastic.co/guide/en/elasticsearch/plugins/6.8"
- glossary: "https://www.elastic.co/guide/en/elastic-stack-glossary/current"
- upgrade_guide: "https://www.elastic.co/products/upgrade_guide"
- blog-ref: "https://www.elastic.co/blog/"
- curator-ref: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current"
- curator-ref-current: "https://www.elastic.co/guide/en/elasticsearch/client/curator/current"
- metrics-ref: "https://www.elastic.co/guide/en/metrics/current"
- metrics-guide: "https://www.elastic.co/guide/en/metrics/guide/current"
- logs-ref: "https://www.elastic.co/guide/en/logs/current"
- logs-guide: "https://www.elastic.co/guide/en/logs/guide/current"
- uptime-guide: "https://www.elastic.co/guide/en/uptime/current"
- observability-guide: "https://www.elastic.co/guide/en/observability/current"
- observability-guide-all: "https://www.elastic.co/guide/en/observability"
- siem-guide: "https://www.elastic.co/guide/en/siem/guide/current"
- security-guide: "https://www.elastic.co/guide/en/security/current"
- security-guide-all: "https://www.elastic.co/guide/en/security"
- endpoint-guide: "https://www.elastic.co/guide/en/endpoint/current"
- sql-odbc: "https://www.elastic.co/guide/en/elasticsearch/sql-odbc/current"
- ecs-ref: "https://www.elastic.co/guide/en/ecs/current"
- ecs-logging-ref: "https://www.elastic.co/guide/en/ecs-logging/overview/current"
- ecs-logging-go-logrus-ref: "https://www.elastic.co/guide/en/ecs-logging/go-logrus/current"
- ecs-logging-go-zap-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/current"
- ecs-logging-go-zerolog-ref: "https://www.elastic.co/guide/en/ecs-logging/go-zap/current"
- ecs-logging-java-ref: "https://www.elastic.co/guide/en/ecs-logging/java/current"
- ecs-logging-dotnet-ref: "https://www.elastic.co/guide/en/ecs-logging/dotnet/current"
- ecs-logging-nodejs-ref: "https://www.elastic.co/guide/en/ecs-logging/nodejs/current"
- ecs-logging-php-ref: "https://www.elastic.co/guide/en/ecs-logging/php/current"
- ecs-logging-python-ref: "https://www.elastic.co/guide/en/ecs-logging/python/current"
- ecs-logging-ruby-ref: "https://www.elastic.co/guide/en/ecs-logging/ruby/current"
- ml-docs: "https://www.elastic.co/guide/en/machine-learning/current"
- eland-docs: "https://www.elastic.co/guide/en/elasticsearch/client/eland/current"
- eql-ref: "https://eql.readthedocs.io/en/latest/query-guide"
- extendtrial: "https://www.elastic.co/trialextension"
- wikipedia: "https://en.wikipedia.org/wiki"
- forum: "https://discuss.elastic.co/"
- xpack-forum: "https://discuss.elastic.co/c/50-x-pack"
- security-forum: "https://discuss.elastic.co/c/x-pack/shield"
- watcher-forum: "https://discuss.elastic.co/c/x-pack/watcher"
- monitoring-forum: "https://discuss.elastic.co/c/x-pack/marvel"
- graph-forum: "https://discuss.elastic.co/c/x-pack/graph"
- apm-forum: "https://discuss.elastic.co/c/apm"
- enterprise-search-ref: "https://www.elastic.co/guide/en/enterprise-search/current"
- app-search-ref: "https://www.elastic.co/guide/en/app-search/current"
- workplace-search-ref: "https://www.elastic.co/guide/en/workplace-search/current"
- enterprise-search-node-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/enterprise-search-node/current"
- enterprise-search-php-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/php/current"
- enterprise-search-python-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/python/current"
- enterprise-search-ruby-ref: "https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current"
- elastic-maps-service: "https://maps.elastic.co/"
- integrations-docs: "https://docs.elastic.co/en/integrations"
- integrations-devguide: "https://www.elastic.co/guide/en/integrations-developer/current"
- time-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#time-units"
- byte-units: "https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html#byte-units"
- apm-py-ref-v: "https://www.elastic.co/guide/en/apm/agent/python/current"
- apm-node-ref-v: "https://www.elastic.co/guide/en/apm/agent/nodejs/current"
- apm-rum-ref-v: "https://www.elastic.co/guide/en/apm/agent/rum-js/current"
- apm-ruby-ref-v: "https://www.elastic.co/guide/en/apm/agent/ruby/current"
- apm-java-ref-v: "https://www.elastic.co/guide/en/apm/agent/java/current"
- apm-go-ref-v: "https://www.elastic.co/guide/en/apm/agent/go/current"
- apm-ios-ref-v: "https://www.elastic.co/guide/en/apm/agent/swift/current"
- apm-dotnet-ref-v: "https://www.elastic.co/guide/en/apm/agent/dotnet/current"
- apm-php-ref-v: "https://www.elastic.co/guide/en/apm/agent/php/current"
- ecloud: "Elastic Cloud"
- esf: "Elastic Serverless Forwarder"
- ess: "Elasticsearch Service"
- ece: "Elastic Cloud Enterprise"
- eck: "Elastic Cloud on Kubernetes"
- serverless-full: "Elastic Cloud Serverless"
- serverless-short: "Serverless"
- es-serverless: "Elasticsearch Serverless"
- es3: "Elasticsearch Serverless"
- obs-serverless: "Elastic Observability Serverless"
- sec-serverless: "Elastic Security Serverless"
- serverless-docs: "https://docs.elastic.co/serverless"
- cloud: "https://www.elastic.co/guide/en/cloud/current"
- ess-utm-params: "?page=docs&placement=docs-body"
- ess-baymax: "?page=docs&placement=docs-body"
- ess-trial: "https://cloud.elastic.co/registration?page=docs&placement=docs-body"
- ess-product: "https://www.elastic.co/cloud/elasticsearch-service?page=docs&placement=docs-body"
- ess-console: "https://cloud.elastic.co/?page=docs&placement=docs-body"
- ess-console-name: "Elasticsearch Service Console"
- ess-deployments: "https://cloud.elastic.co/deployments?page=docs&placement=docs-body"
- ece-ref: "https://www.elastic.co/guide/en/cloud-enterprise/current"
- eck-ref: "https://www.elastic.co/guide/en/cloud-on-k8s/current"
- ess-leadin: "You can run Elasticsearch on your own hardware or use our hosted Elasticsearch Service that is available on AWS, GCP, and Azure. https://cloud.elastic.co/registration{ess-utm-params}[Try the Elasticsearch Service for free]."
- ess-leadin-short: "Our hosted Elasticsearch Service is available on AWS, GCP, and Azure, and you can https://cloud.elastic.co/registration{ess-utm-params}[try it for free]."
- ess-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"https://cloud.elastic.co/registration%7Bess-utm-params%7D/", title=\"Supported on Elasticsearch Service\"]"
- ece-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud_ece.svg[link=\"https://cloud.elastic.co/registration%7Bess-utm-params%7D/", title=\"Supported on Elastic Cloud Enterprise\"]"
- cloud-only: "This feature is designed for indirect use by https://cloud.elastic.co/registration{ess-utm-params}[Elasticsearch Service], https://www.elastic.co/guide/en/cloud-enterprise/{ece-version-link}[Elastic Cloud Enterprise], and https://www.elastic.co/guide/en/cloud-on-k8s/current[Elastic Cloud on Kubernetes]. Direct use is not supported."
- ess-setting-change: "image:https://doc-icons.s3.us-east-2.amazonaws.com/logo_cloud.svg[link=\"{ess-trial}\", title=\"Supported on {ess}\"] indicates a change to a supported https://www.elastic.co/guide/en/cloud/current/ec-add-user-settings.html[user setting] for Elasticsearch Service."
- ess-skip-section: "If you use Elasticsearch Service, skip this section. Elasticsearch Service handles these changes for you."
- api-cloud: "https://www.elastic.co/docs/api/doc/cloud"
- api-ece: "https://www.elastic.co/docs/api/doc/cloud-enterprise"
- api-kibana-serverless: "https://www.elastic.co/docs/api/doc/serverless"
- es-feature-flag: "This feature is in development and not yet available for use. This documentation is provided for informational purposes only."
- es-ref-dir: "'{{elasticsearch-root}}/docs/reference'"
- apm-app: "APM app"
- uptime-app: "Uptime app"
- synthetics-app: "Synthetics app"
- logs-app: "Logs app"
- metrics-app: "Metrics app"
- infrastructure-app: "Infrastructure app"
- siem-app: "SIEM app"
- security-app: "Elastic Security app"
- ml-app: "Machine Learning"
- dev-tools-app: "Dev Tools"
- ingest-manager-app: "Ingest Manager"
- stack-manage-app: "Stack Management"
- stack-monitor-app: "Stack Monitoring"
- alerts-ui: "Alerts and Actions"
- rules-ui: "Rules"
- rac-ui: "Rules and Connectors"
- connectors-ui: "Connectors"
- connectors-feature: "Actions and Connectors"
- stack-rules-feature: "Stack Rules"
- user-experience: "User Experience"
- ems: "Elastic Maps Service"
- ems-init: "EMS"
- hosted-ems: "Elastic Maps Server"
- ipm-app: "Index Pattern Management"
- ingest-pipelines: "ingest pipelines"
- ingest-pipelines-app: "Ingest Pipelines"
- ingest-pipelines-cap: "Ingest pipelines"
- ls-pipelines: "Logstash pipelines"
- ls-pipelines-app: "Logstash Pipelines"
- maint-windows: "maintenance windows"
- maint-windows-app: "Maintenance Windows"
- maint-windows-cap: "Maintenance windows"
- custom-roles-app: "Custom Roles"
- data-source: "data view"
- data-sources: "data views"
- data-source-caps: "Data View"
- data-sources-caps: "Data Views"
- data-source-cap: "Data view"
- data-sources-cap: "Data views"
- project-settings: "Project settings"
- manage-app: "Management"
- index-manage-app: "Index Management"
- data-views-app: "Data Views"
- rules-app: "Rules"
- saved-objects-app: "Saved Objects"
- tags-app: "Tags"
- api-keys-app: "API keys"
- transforms-app: "Transforms"
- connectors-app: "Connectors"
- files-app: "Files"
- reports-app: "Reports"
- maps-app: "Maps"
- alerts-app: "Alerts"
- crawler: "Enterprise Search web crawler"
- ents: "Enterprise Search"
- app-search-crawler: "App Search web crawler"
- agent: "Elastic Agent"
- agents: "Elastic Agents"
- fleet: "Fleet"
- fleet-server: "Fleet Server"
- integrations-server: "Integrations Server"
- ingest-manager: "Ingest Manager"
- ingest-management: "ingest management"
- package-manager: "Elastic Package Manager"
- integrations: "Integrations"
- package-registry: "Elastic Package Registry"
- artifact-registry: "Elastic Artifact Registry"
- aws: "AWS"
- stack: "Elastic Stack"
- xpack: "X-Pack"
es: "Elasticsearch"
- kib: "Kibana"
- esms: "Elastic Stack Monitoring Service"
- esms-init: "ESMS"
- ls: "Logstash"
- beats: "Beats"
- auditbeat: "Auditbeat"
- filebeat: "Filebeat"
- heartbeat: "Heartbeat"
- metricbeat: "Metricbeat"
- packetbeat: "Packetbeat"
- winlogbeat: "Winlogbeat"
- functionbeat: "Functionbeat"
- journalbeat: "Journalbeat"
- es-sql: "Elasticsearch SQL"
- esql: "ES|QL"
- elastic-agent: "Elastic Agent"
- k8s: "Kubernetes"
- log-driver-long: "Elastic Logging Plugin for Docker"
- security: "X-Pack security"
- security-features: "security features"
- operator-feature: "operator privileges feature"
- es-security-features: "Elasticsearch security features"
- stack-security-features: "Elastic Stack security features"
- endpoint-sec: "Endpoint Security"
- endpoint-cloud-sec: "Endpoint and Cloud Security"
- elastic-defend: "Elastic Defend"
- elastic-sec: "Elastic Security"
- elastic-endpoint: "Elastic Endpoint"
- swimlane: "Swimlane"
- sn: "ServiceNow"
- sn-itsm: "ServiceNow ITSM"
- sn-itom: "ServiceNow ITOM"
- sn-sir: "ServiceNow SecOps"
- jira: "Jira"
- ibm-r: "IBM Resilient"
- webhook: "Webhook"
- webhook-cm: "Webhook - Case Management"
- opsgenie: "Opsgenie"
- bedrock: "Amazon Bedrock"
- gemini: "Google Gemini"
- hive: "TheHive"
- monitoring: "X-Pack monitoring"
- monitor-features: "monitoring features"
- stack-monitor-features: "Elastic Stack monitoring features"
- watcher: "Watcher"
- alert-features: "alerting features"
- reporting: "X-Pack reporting"
- report-features: "reporting features"
- graph: "X-Pack graph"
- graph-features: "graph analytics features"
- searchprofiler: "Search Profiler"
- xpackml: "X-Pack machine learning"
- ml: "machine learning"
- ml-cap: "Machine learning"
- ml-init: "ML"
- ml-features: "machine learning features"
- stack-ml-features: "Elastic Stack machine learning features"
- ccr: "cross-cluster replication"
- ccr-cap: "Cross-cluster replication"
- ccr-init: "CCR"
- ccs: "cross-cluster search"
- ccs-cap: "Cross-cluster search"
- ccs-init: "CCS"
- ilm: "index lifecycle management"
- ilm-cap: "Index lifecycle management"
- ilm-init: "ILM"
- dlm: "data lifecycle management"
- dlm-cap: "Data lifecycle management"
- dlm-init: "DLM"
- search-snap: "searchable snapshot"
- search-snaps: "searchable snapshots"
- search-snaps-cap: "Searchable snapshots"
- slm: "snapshot lifecycle management"
- slm-cap: "Snapshot lifecycle management"
- slm-init: "SLM"
- rollup-features: "data rollup features"
- ipm: "index pattern management"
- ipm-cap: "Index pattern"
- rollup: "rollup"
- rollup-cap: "Rollup"
- rollups: "rollups"
- rollups-cap: "Rollups"
- rollup-job: "rollup job"
- rollup-jobs: "rollup jobs"
- rollup-jobs-cap: "Rollup jobs"
- dfeed: "datafeed"
- dfeeds: "datafeeds"
- dfeed-cap: "Datafeed"
- dfeeds-cap: "Datafeeds"
- ml-jobs: "machine learning jobs"
- ml-jobs-cap: "Machine learning jobs"
- anomaly-detect: "anomaly detection"
- anomaly-detect-cap: "Anomaly detection"
- anomaly-job: "anomaly detection job"
- anomaly-jobs: "anomaly detection jobs"
- anomaly-jobs-cap: "Anomaly detection jobs"
- dataframe: "data frame"
- dataframes: "data frames"
- dataframe-cap: "Data frame"
- dataframes-cap: "Data frames"
- watcher-transform: "payload transform"
- watcher-transforms: "payload transforms"
- watcher-transform-cap: "Payload transform"
- watcher-transforms-cap: "Payload transforms"
- transform: "transform"
- transforms: "transforms"
- transform-cap: "Transform"
- transforms-cap: "Transforms"
- dataframe-transform: "transform"
- dataframe-transform-cap: "Transform"
- dataframe-transforms: "transforms"
- dataframe-transforms-cap: "Transforms"
- dfanalytics-cap: "Data frame analytics"
- dfanalytics: "data frame analytics"
- dataframe-analytics-config: "'{dataframe} analytics config'"
- dfanalytics-job: "'{dataframe} analytics job'"
- dfanalytics-jobs: "'{dataframe} analytics jobs'"
- dfanalytics-jobs-cap: "'{dataframe-cap} analytics jobs'"
- cdataframe: "continuous data frame"
- cdataframes: "continuous data frames"
- cdataframe-cap: "Continuous data frame"
- cdataframes-cap: "Continuous data frames"
- cdataframe-transform: "continuous transform"
- cdataframe-transforms: "continuous transforms"
- cdataframe-transforms-cap: "Continuous transforms"
- ctransform: "continuous transform"
- ctransform-cap: "Continuous transform"
- ctransforms: "continuous transforms"
- ctransforms-cap: "Continuous transforms"
- oldetection: "outlier detection"
- oldetection-cap: "Outlier detection"
- olscore: "outlier score"
- olscores: "outlier scores"
- fiscore: "feature influence score"
- evaluatedf-api: "evaluate {dataframe} analytics API"
- evaluatedf-api-cap: "Evaluate {dataframe} analytics API"
- binarysc: "binary soft classification"
- binarysc-cap: "Binary soft classification"
- regression: "regression"
- regression-cap: "Regression"
- reganalysis: "regression analysis"
- reganalysis-cap: "Regression analysis"
- depvar: "dependent variable"
- feature-var: "feature variable"
- feature-vars: "feature variables"
- feature-vars-cap: "Feature variables"
- classification: "classification"
- classification-cap: "Classification"
- classanalysis: "classification analysis"
- classanalysis-cap: "Classification analysis"
- infer-cap: "Inference"
- infer: "inference"
- lang-ident-cap: "Language identification"
- lang-ident: "language identification"
- data-viz: "Data Visualizer"
- file-data-viz: "File Data Visualizer"
- feat-imp: "feature importance"
- feat-imp-cap: "Feature importance"
- nlp: "natural language processing"
- nlp-cap: "Natural language processing"
- apm-agent: "APM agent"
- apm-go-agent: "Elastic APM Go agent"
- apm-go-agents: "Elastic APM Go agents"
- apm-ios-agent: "Elastic APM iOS agent"
- apm-ios-agents: "Elastic APM iOS agents"
- apm-java-agent: "Elastic APM Java agent"
- apm-java-agents: "Elastic APM Java agents"
- apm-dotnet-agent: "Elastic APM .NET agent"
- apm-dotnet-agents: "Elastic APM .NET agents"
- apm-node-agent: "Elastic APM Node.js agent"
- apm-node-agents: "Elastic APM Node.js agents"
- apm-php-agent: "Elastic APM PHP agent"
- apm-php-agents: "Elastic APM PHP agents"
- apm-py-agent: "Elastic APM Python agent"
- apm-py-agents: "Elastic APM Python agents"
- apm-ruby-agent: "Elastic APM Ruby agent"
- apm-ruby-agents: "Elastic APM Ruby agents"
- apm-rum-agent: "Elastic APM Real User Monitoring (RUM) JavaScript agent"
- apm-rum-agents: "Elastic APM RUM JavaScript agents"
- apm-lambda-ext: "Elastic APM AWS Lambda extension"
- project-monitors: "project monitors"
- project-monitors-cap: "Project monitors"
- private-location: "Private Location"
- private-locations: "Private Locations"
- pwd: "YOUR_PASSWORD"
- esh: "ES-Hadoop"
- default-dist: "default distribution"
- oss-dist: "OSS-only distribution"
- observability: "Observability"
- api-request-title: "Request"
- api-prereq-title: "Prerequisites"
- api-description-title: "Description"
- api-path-parms-title: "Path parameters"
- api-query-parms-title: "Query parameters"
- api-request-body-title: "Request body"
- api-response-codes-title: "Response codes"
- api-response-body-title: "Response body"
- api-example-title: "Example"
- api-examples-title: "Examples"
- api-definitions-title: "Properties"
- multi-arg: "†footnoteref:[multi-arg,This parameter accepts multiple arguments.]"
- multi-arg-ref: "†footnoteref:[multi-arg]"
- yes-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-yes.png[Yes,20,15]"
- no-icon: "image:https://doc-icons.s3.us-east-2.amazonaws.com/icon-no.png[No,20,15]"
- es-repo: "https://github.com/elastic/elasticsearch/"
- es-issue: "https://github.com/elastic/elasticsearch/issues/"
- es-pull: "https://github.com/elastic/elasticsearch/pull/"
- es-commit: "https://github.com/elastic/elasticsearch/commit/"
- kib-repo: "https://github.com/elastic/kibana/"
- kib-issue: "https://github.com/elastic/kibana/issues/"
- kibana-issue: "'{kib-repo}issues/'"
- kib-pull: "https://github.com/elastic/kibana/pull/"
- kibana-pull: "'{kib-repo}pull/'"
- kib-commit: "https://github.com/elastic/kibana/commit/"
- ml-repo: "https://github.com/elastic/ml-cpp/"
- ml-issue: "https://github.com/elastic/ml-cpp/issues/"
- ml-pull: "https://github.com/elastic/ml-cpp/pull/"
- ml-commit: "https://github.com/elastic/ml-cpp/commit/"
- apm-repo: "https://github.com/elastic/apm-server/"
- apm-issue: "https://github.com/elastic/apm-server/issues/"
- apm-pull: "https://github.com/elastic/apm-server/pull/"
- kibana-blob: "https://github.com/elastic/kibana/blob/current/"
- apm-get-started-ref: "https://www.elastic.co/guide/en/apm/get-started/current"
- apm-server-ref: "https://www.elastic.co/guide/en/apm/server/current"
- apm-server-ref-v: "https://www.elastic.co/guide/en/apm/server/current"
- apm-server-ref-m: "https://www.elastic.co/guide/en/apm/server/master"
- apm-server-ref-62: "https://www.elastic.co/guide/en/apm/server/6.2"
- apm-server-ref-64: "https://www.elastic.co/guide/en/apm/server/6.4"
- apm-server-ref-70: "https://www.elastic.co/guide/en/apm/server/7.0"
- apm-overview-ref-v: "https://www.elastic.co/guide/en/apm/get-started/current"
- apm-overview-ref-70: "https://www.elastic.co/guide/en/apm/get-started/7.0"
- apm-overview-ref-m: "https://www.elastic.co/guide/en/apm/get-started/master"
- infra-guide: "https://www.elastic.co/guide/en/infrastructure/guide/current"
- a-data-source: "a data view"
- icon-bug: "pass:[]"
- icon-checkInCircleFilled: "pass:[]"
- icon-warningFilled: "pass:[]"
diff --git a/docs/images/logo-elastic-glyph-color.svg b/docs/images/logo-elastic-glyph-color.svg
new file mode 100644
index 000000000..bfc5bfb6a
--- /dev/null
+++ b/docs/images/logo-elastic-glyph-color.svg
@@ -0,0 +1,16 @@
+
diff --git a/docs/reference/async.md b/docs/reference/async.md
index f205d3807..70e8949d5 100644
--- a/docs/reference/async.md
+++ b/docs/reference/async.md
@@ -34,8 +34,7 @@ async def main():
)
print(resp)
-loop = asyncio.get_event_loop()
-loop.run_until_complete(main())
+asyncio.run(main())
```
All APIs that are available under the sync client are also available under the async client.
diff --git a/docs/reference/client-helpers.md b/docs/reference/client-helpers.md
index 02ab4e026..08f480e23 100644
--- a/docs/reference/client-helpers.md
+++ b/docs/reference/client-helpers.md
@@ -5,14 +5,14 @@ mapped_pages:
# Client helpers [client-helpers]
-You can find here a collection of simple helper functions that abstract some specifics of the raw API. For detailed examples, refer to [this page](https://elasticsearch-py.readthedocs.io/en/stable/helpers.md).
+You can find here a collection of simple helper functions that abstract some specifics of the raw API.
## Bulk helpers [bulk-helpers]
There are several helpers for the bulk API since its requirement for specific formatting and other considerations can make it cumbersome if used directly.
-All bulk helpers accept an instance of `{{es}}` class and an iterable `action` (any iterable, can also be a generator, which is ideal in most cases since it allows you to index large datasets without the need of loading them into memory).
+All bulk helpers accept an instance of `Elasticsearch` class and an iterable `action` (any iterable, can also be a generator, which is ideal in most cases since it allows you to index large datasets without the need of loading them into memory).
The items in the iterable `action` should be the documents we wish to index in several formats. The most common one is the same as returned by `search()`, for example:
diff --git a/docs/reference/connecting.md b/docs/reference/connecting.md
index aefc50b1f..27f7fecbc 100644
--- a/docs/reference/connecting.md
+++ b/docs/reference/connecting.md
@@ -352,6 +352,6 @@ def main(request: func.HttpRequest) -> func.HttpResponse:
Resources used to assess these recommendations:
* [GCP Cloud Functions: Tips & Tricks](https://cloud.google.com/functions/docs/bestpractices/tips#use_global_variables_to_reuse_objects_in_future_invocations)
-* [Best practices for working with AWS Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.md)
+* [Best practices for working with AWS Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html)
* [Azure Functions Python developer guide](https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference-python?tabs=azurecli-linux%2Capplication-level#global-variables)
-* [AWS Lambda: Comparing the effect of global scope](https://docs.aws.amazon.com/lambda/latest/operatorguide/global-scope.md)
+* [AWS Lambda: Comparing the effect of global scope](https://docs.aws.amazon.com/lambda/latest/operatorguide/global-scope.html)
diff --git a/docs/reference/_configuration.md b/docs/reference/dsl_configuration.md
similarity index 100%
rename from docs/reference/_configuration.md
rename to docs/reference/dsl_configuration.md
diff --git a/docs/reference/_examples.md b/docs/reference/dsl_examples.md
similarity index 100%
rename from docs/reference/_examples.md
rename to docs/reference/dsl_examples.md
diff --git a/docs/reference/_how_to_guides.md b/docs/reference/dsl_how_to_guides.md
similarity index 78%
rename from docs/reference/_how_to_guides.md
rename to docs/reference/dsl_how_to_guides.md
index 08e16b28c..5f0884c3c 100644
--- a/docs/reference/_how_to_guides.md
+++ b/docs/reference/dsl_how_to_guides.md
@@ -23,7 +23,7 @@ The `Search` object represents the entire search request:
* additional parameters
* associated client
-The API is designed to be chainable. With the exception of the aggregations functionality this means that the `Search` object is immutable -all changes to the object will result in a shallow copy being created which contains the changes. This means you can safely pass the `Search` object to foreign code without fear of it modifying your objects as long as it sticks to the `Search` object APIs.
+The API is designed to be chainable. With the exception of the aggregations functionality this means that the `Search` object is immutable -all changes to the object will result in a shallow copy being created which contains the changes. You can safely pass the `Search` object to foreign code without fear of it modifying your objects as long as it sticks to the `Search` object APIs.
You can pass an instance of the [elasticsearch client](https://elasticsearch-py.readthedocs.io/) when instantiating the `Search` object:
@@ -51,7 +51,7 @@ All methods return a *copy* of the object, making it safe to pass to outside cod
The API is chainable, allowing you to combine multiple method calls in one statement:
```python
-s = Search().using(client).query("match", title="python")
+s = Search().using(client).query(Match("title", "python"))
```
To send the request to Elasticsearch:
@@ -67,9 +67,9 @@ for hit in s:
print(hit.title)
```
-Search results will be cached. Subsequent calls to `execute` or trying to iterate over an already executed `Search` object will not trigger additional requests being sent to Elasticsearch. To force a request specify `ignore_cache=True` when calling `execute`.
+Search results will be cached. Subsequent calls to `execute` or trying to iterate over an already executed `Search` object will not trigger additional requests being sent to Elasticsearch. To force a new request to be issued specify `ignore_cache=True` when calling `execute`.
-For debugging purposes you can serialize the `Search` object to a `dict` explicitly:
+For debugging purposes you can serialize the `Search` object to a `dict` with the raw Elasticsearch request:
```python
print(s.to_dict())
@@ -79,33 +79,38 @@ print(s.to_dict())
You can delete the documents matching a search by calling `delete` on the `Search` object instead of `execute` like this:
+```python
+s = Search(index='i').query(Match("title", "python"))
+response = s.delete()
+```
+
+To pass [deletion parameters](https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.delete_by_query)
+in your query, you can add them by calling ``params`` on the ``Search`` object before ``delete`` like this:
+
```python
s = Search(index='i').query("match", title="python")
+s = s.params(ignore_unavailable=False, wait_for_completion=True)
response = s.delete()
```
#### Queries [_queries]
-The library provides classes for all Elasticsearch query types. Pass all the parameters as keyword arguments. The classes accept any keyword arguments, the dsl then takes all arguments passed to the constructor and serializes them as top-level keys in the resulting dictionary (and thus the resulting json being sent to elasticsearch). This means that there is a clear one-to-one mapping between the raw query and its equivalent in the DSL:
+The `elasticsearch.dsl.query` module provides classes for all Elasticsearch query types. These classes accept keyword arguments in their constructors, which are serialized to the appropriate format to be sent to Elasticsearch. There is a clear one-to-one mapping between the raw query and its equivalent class-based version:
```python
-from elasticsearch.dsl.query import MultiMatch, Match
+>>> from elasticsearch.dsl.query import MultiMatch, Match
-# {"multi_match": {"query": "python django", "fields": ["title", "body"]}}
-MultiMatch(query='python django', fields=['title', 'body'])
+>>> q = MultiMatch(query='python django', fields=['title', 'body'])
+>>> q.to_dict()
+{'multi_match': {'query': 'python django', 'fields': ['title', 'body']}}
-# {"match": {"title": {"query": "web framework", "type": "phrase"}}}
-Match(title={"query": "web framework", "type": "phrase"})
+>>> q = Match("title", {"query": "web framework", "type": "phrase"})
+>>> q.to_dict()
+{'match': {'title': {'query': 'web framework', 'type': 'phrase'}}}
```
-::::{note}
-In some cases this approach is not possible due to python’s restriction on identifiers - for example if your field is called `@timestamp`. In that case you have to fall back to unpacking a dictionary: `Range(*+ {'@timestamp': {'lt': 'now'}})`
-
-::::
-
-
-You can use the `Q` shortcut to construct the instance using a name with parameters or the raw `dict`:
+An alternative to the class-based queries is to use the `Q` shortcut, passing a query name followed by its parameters, or the raw query as a `dict`:
```python
from elasticsearch.dsl import Q
@@ -114,20 +119,20 @@ Q("multi_match", query='python django', fields=['title', 'body'])
Q({"multi_match": {"query": "python django", "fields": ["title", "body"]}})
```
-To add the query to the `Search` object, use the `.query()` method:
+To add a query to the `Search` object, use the `.query()` method. This works with class-based or `Q` queries:
```python
q = Q("multi_match", query='python django', fields=['title', 'body'])
s = s.query(q)
```
-The method also accepts all the parameters as the `Q` shortcut:
+As a shortcut the `query()` method also accepts all the parameters of the `Q` shortcut directly:
```python
s = s.query("multi_match", query='python django', fields=['title', 'body'])
```
-If you already have a query object, or a `dict` representing one, you can just override the query used in the `Search` object:
+If you already have a query object, or a `dict` representing one, you can assign it to the `query` attribute of a `Search` object to add it to it, replacing any previously configured queries:
```python
s.query = Q('bool', must=[Q('match', title='python'), Q('match', body='best')])
@@ -136,7 +141,7 @@ s.query = Q('bool', must=[Q('match', title='python'), Q('match', body='best')])
#### Dotted fields [_dotted_fields]
-Sometimes you want to refer to a field within another field, either as a multi-field (`title.keyword`) or in a structured `json` document like `address.city`. To make it easier, the `Q` shortcut (as well as the `query`, `filter`, and `exclude` methods on `Search` class) allows you to use `_+` (double underscore) in place of a dot in a keyword argument:
+Sometimes you want to refer to a field within another field, either as a multi-field (`title.keyword`) or in a structured `json` document like `address.city`. This is not a problem when using class-based queries, but when working without classes it is often required to pass field names as keyword arguments. To make this easier, you can use `__` (double underscore) in place of a dot in a keyword argument:
```python
s = Search()
@@ -144,7 +149,7 @@ s = s.filter('term', category__keyword='Python')
s = s.query('match', address__city='prague')
```
-Alternatively you can always fall back to python’s kwarg unpacking if you prefer:
+Alternatively you can use Python’s keyword argument unpacking:
```python
s = Search()
@@ -155,20 +160,23 @@ s = s.query('match', **{'address.city': 'prague'})
#### Query combination [_query_combination]
-Query objects can be combined using logical operators:
+Query objects can be combined using logical operators `|`, `&` and `~`:
```python
-Q("match", title='python') | Q("match", title='django')
-# {"bool": {"should": [...]}}
+>>> q = Match("title", "python") | Match("title", "django")
+>>> q.to_dict()
+{'bool': {'should': [{'match': {'title': 'python'}}, {'match': {'title': 'django'}}]}}
-Q("match", title='python') & Q("match", title='django')
-# {"bool": {"must": [...]}}
+>>> q = Match("title", "python") & Match("title", "django")
+>>> q.to_dict()
+{'bool': {'must': [{'match': {'title': 'python'}}, {'match': {'title': 'django'}}]}}
-~Q("match", title="python")
-# {"bool": {"must_not": [...]}}
+>>> q = ~Match("title", "python")
+>>> q.to_dict()
+{'bool': {'must_not': [{'match': {'title': 'python'}}]}}
```
-When you call the `.query()` method multiple times, the `&` operator will be used internally:
+When you call the `.query()` method multiple times, the `&` operator will be used internally to combine all the queries:
```python
s = s.query().query()
@@ -193,48 +201,64 @@ s = Search().query(q)
If you want to add a query in a [filter context](docs-content://explore-analyze/query-filter/languages/querydsl.md) you can use the `filter()` method to make things easier:
```python
+from elasticsearch.dsl.query import Terms
+
s = Search()
-s = s.filter('terms', tags=['search', 'python'])
+s = s.filter(Terms("tags", ['search', 'python']))
```
Behind the scenes this will produce a `Bool` query and place the specified `terms` query into its `filter` branch, making it equivalent to:
```python
+from elasticsearch.dsl.query import Terms, Bool
+
s = Search()
-s = s.query('bool', filter=[Q('terms', tags=['search', 'python'])])
+s = s.query(Bool(filter=[Terms("tags", ["search", "python"])]))
```
-If you want to use the post_filter element for faceted navigation, use the `.post_filter()` method.
+If you want to use the `post_filter` element for faceted navigation, use the `.post_filter()` method.
-You can also `exclude()` items from your query like this:
+The `exclude()` method works like `filter()`, but it applies the query as negated:
```python
s = Search()
-s = s.exclude('terms', tags=['search', 'python'])
+s = s.exclude(Terms("tags", ['search', 'python']))
```
-which is shorthand for: `s = s.query('bool', filter=[~Q('terms', tags=['search', 'python'])])`
+which is shorthand for:
+
+```python
+s = s.query(Bool(filter=[~Terms("tags", ["search", "python"])]))
+```
#### Aggregations [_aggregations]
-To define an aggregation, you can use the `A` shortcut:
+As with queries, there are classes that represent each aggregation type, all accessible through the `elasticsearch.dsl.aggs` module:
+
+```python
+from elasticsearch.dsl import aggs
+
+a = aggs.Terms(field="tags")
+# {"terms": {"field": "tags"}}
+```
+
+It is also possible to define an aggregation using the `A` shortcut:
```python
from elasticsearch.dsl import A
A('terms', field='tags')
-# {"terms": {"field": "tags"}}
```
To nest aggregations, you can use the `.bucket()`, `.metric()` and `.pipeline()` methods:
```python
-a = A('terms', field='category')
+a = aggs.Terms(field="category")
# {'terms': {'field': 'category'}}
-a.metric('clicks_per_category', 'sum', field='clicks')\
- .bucket('tags_per_category', 'terms', field='tags')
+a.metric("clicks_per_category", aggs.Sum(field="clicks")) \
+ .bucket("tags_per_category", aggs.Terms(field="tags"))
# {
# 'terms': {'field': 'category'},
# 'aggs': {
@@ -248,8 +272,8 @@ To add aggregations to the `Search` object, use the `.aggs` property, which acts
```python
s = Search()
-a = A('terms', field='category')
-s.aggs.bucket('category_terms', a)
+a = aggs.Terms(field="category")
+s.aggs.bucket("category_terms", a)
# {
# 'aggs': {
# 'category_terms': {
@@ -265,10 +289,10 @@ or
```python
s = Search()
-s.aggs.bucket('articles_per_day', 'date_histogram', field='publish_date', interval='day')\
- .metric('clicks_per_day', 'sum', field='clicks')\
- .pipeline('moving_click_average', 'moving_avg', buckets_path='clicks_per_day')\
- .bucket('tags_per_day', 'terms', field='tags')
+s.aggs.bucket("articles_per_day", aggs.DateHistogram(field="publish_date", interval="day")) \
+ .metric("clicks_per_day", aggs.Sum(field="clicks")) \
+ .pipeline("moving_click_average", aggs.MovingAvg(buckets_path="clicks_per_day")) \
+ .bucket("tags_per_day", aggs.Terms(field="tags"))
s.to_dict()
# {
@@ -290,9 +314,9 @@ You can access an existing bucket by its name:
```python
s = Search()
-s.aggs.bucket('per_category', 'terms', field='category')
-s.aggs['per_category'].metric('clicks_per_category', 'sum', field='clicks')
-s.aggs['per_category'].bucket('tags_per_category', 'terms', field='tags')
+s.aggs.bucket("per_category", aggs.Terms(field="category"))
+s.aggs["per_category"].metric("clicks_per_category", aggs.Sum(field="clicks"))
+s.aggs["per_category"].bucket("tags_per_category", aggs.Terms(field="tags"))
```
::::{note}
@@ -301,7 +325,7 @@ When chaining multiple aggregations, there is a difference between what `.bucket
::::
-As opposed to other methods on the `Search` objects, defining aggregations is done in-place (does not return a copy).
+As opposed to other methods on the `Search` objects, aggregations are defined in-place, without returning a new copy.
#### K-Nearest Neighbor Searches [_k_nearest_neighbor_searches]
@@ -348,7 +372,7 @@ s = s.sort()
#### Pagination [_pagination]
-To specify the from/size parameters, use the Python slicing API:
+To specify the from/size parameters, apply the standard Python slicing operator on the `Search` instance:
```python
s = s[10:20]
@@ -417,7 +441,7 @@ The first argument is the name of the suggestions (name under which it will be r
To collapse search results use the `collapse` method on your `Search` object:
```python
-s = Search().query("match", message="GET /search")
+s = Search().query(Match("message", "GET /search"))
# collapse results by user_id
s = s.collapse("user_id")
```
@@ -526,11 +550,11 @@ If you want to inspect the contents of the `response` objects, just use its `to_
#### Hits [_hits]
-To access to the hits returned by the search, access the `hits` property or just iterate over the `Response` object:
+To access the hits returned by the search, use the `hits` property or just iterate over the `Response` object:
```python
response = s.execute()
-print('Total %d hits found.' % response.hits.total)
+print(f"Total {response.hits.total} hits found.")
for h in response:
print(h.title, h.body)
```
@@ -549,8 +573,7 @@ The individual hits is wrapped in a convenience class that allows attribute acce
```python
response = s.execute()
h = response.hits[0]
-print('/%s/%s/%s returned with score %f' % (
- h.meta.index, h.meta.doc_type, h.meta.id, h.meta.score))
+print(f"/{h.meta.index}/{h.meta.doc_type}/{h.meta.id} returned with score {h.meta.score}")
```
::::{note}
@@ -577,11 +600,12 @@ If you need to execute multiple searches at the same time you can use the `Multi
```python
from elasticsearch.dsl import MultiSearch, Search
+from elasticsearch.dsl.query import Term
ms = MultiSearch(index='blogs')
-ms = ms.add(Search().filter('term', tags='python'))
-ms = ms.add(Search().filter('term', tags='elasticsearch'))
+ms = ms.add(Search().filter(Term("tags", "python")))
+ms = ms.add(Search().filter(Term("tags", 'elasticsearch')))
responses = ms.execute()
@@ -653,9 +677,9 @@ class Post(Document):
#### Data types [_data_types]
-The `Document` instances use native python types like `str` and `datetime`. In case of `Object` or `Nested` fields an instance of the `InnerDoc` subclass is used, as in the `add_comment` method in the above example where we are creating an instance of the `Comment` class.
+The `Document` instances use native python types such as `str` and `datetime` for its attributes. In case of `Object` or `Nested` fields an instance of the `InnerDoc` subclass is used, as in the `add_comment` method in the above example, where we are creating an instance of the `Comment` class.
-There are some specific types that were created as part of this library to make working with some field types easier, for example the `Range` object used in any of the [range fields](elasticsearch://reference/elasticsearch/mapping-reference/range.md):
+There are some specific types that were created to make working with some field types easier, for example the `Range` object used in any of the [range fields](elasticsearch://reference/elasticsearch/mapping-reference/range.md):
```python
from elasticsearch.dsl import Document, DateRange, Keyword, Range
@@ -664,7 +688,6 @@ class RoomBooking(Document):
room = Keyword()
dates = DateRange()
-
rb = RoomBooking(
room='Conference Room II',
dates=Range(
@@ -700,7 +723,7 @@ class Post(Document):
It is important to note that when using `Field` subclasses such as `Text`, `Date` and `Boolean`, they must be given in the right-side of an assignment, as shown in examples above. Using these classes as type hints will result in errors.
-Python types are mapped to their corresponding field type according to the following table:
+Python types are mapped to their corresponding field types according to the following table:
| Python type | DSL field |
| --- | --- |
@@ -740,18 +763,18 @@ class Post(Document):
comments: List[Comment] # same as comments = Nested(Comment, required=True)
```
-Unfortunately it is impossible to have Python type hints that uniquely identify every possible Elasticsearch field type. To choose a field type that is different than the ones in the table above, the field instance can be added explicitly as a right-side assignment in the field declaration. The next example creates a field that is typed as `Optional[str]`, but is mapped to `Keyword` instead of `Text`:
+Unfortunately it is impossible to have Python type hints that uniquely identify every possible Elasticsearch field type. To choose a field type that is different than the one that is assigned according to the table above, the desired field instance can be added explicitly as a right-side assignment in the field declaration. The next example creates a field that is typed as `Optional[str]`, but is mapped to `Keyword` instead of `Text`:
```python
class MyDocument(Document):
category: Optional[str] = Keyword()
```
-This form can also be used when additional options need to be given to initialize the field, such as when using custom analyzer settings or changing the `required` default:
+This form can also be used when additional options need to be given to initialize the field, such as when using custom analyzer settings:
```python
class Comment(InnerDoc):
- content: str = Text(analyzer='snowball', required=True)
+ content: str = Text(analyzer='snowball')
```
When using type hints as above, subclasses of `Document` and `InnerDoc` inherit some of the behaviors associated with Python dataclasses, as defined by [PEP 681](https://peps.python.org/pep-0681/) and the [dataclass_transform decorator](https://typing.readthedocs.io/en/latest/spec/dataclasses.html#dataclass-transform). To add per-field dataclass options such as `default` or `default_factory`, the `mapped_field()` wrapper can be used on the right side of a typed field declaration:
@@ -761,12 +784,12 @@ class MyDocument(Document):
title: str = mapped_field(default="no title")
created_at: datetime = mapped_field(default_factory=datetime.now)
published: bool = mapped_field(default=False)
- category: str = mapped_field(Keyword(required=True), default="general")
+ category: str = mapped_field(Keyword(), default="general")
```
When using the `mapped_field()` wrapper function, an explicit field type instance can be passed as a first positional argument, as the `category` field does in the example above.
-Static type checkers such as [mypy](https://mypy-lang.org/) and [pyright](https://github.com/microsoft/pyright) can use the type hints and the dataclass-specific options added to the `mapped_field()` function to improve type inference and provide better real-time suggestions in IDEs.
+Static type checkers such as [mypy](https://mypy-lang.org/) and [pyright](https://github.com/microsoft/pyright) can use the type hints and the dataclass-specific options added to the `mapped_field()` function to improve type inference and provide better real-time code completion and suggestions in IDEs.
One situation in which type checkers can’t infer the correct type is when using fields as class attributes. Consider the following example:
@@ -804,7 +827,7 @@ The `InstrumentedField` objects returned when fields are accessed as class attri
s = MyDocument.search().sort(-MyDocument.created_at, MyDocument.title)
```
-When specifying sorting order, the `{{plus}}` and `-` unary operators can be used on the class field attributes to indicate ascending and descending order.
+When specifying sorting order, the `+` and `-` unary operators can be used on the class field attributes to indicate ascending and descending order.
Finally, the `ClassVar` annotation can be used to define a regular class attribute that should not be mapped to the Elasticsearch index:
@@ -812,9 +835,8 @@ Finally, the `ClassVar` annotation can be used to define a regular class attribu
from typing import ClassVar
class MyDoc(Document):
- title: M[str] created_at: M[datetime] =
- mapped_field(default_factory=datetime.now) my_var:
- ClassVar[str] # regular class variable, ignored by Elasticsearch
+ title: M[str] created_at: M[datetime] = mapped_field(default_factory=datetime.now)
+ my_var: ClassVar[str] # regular class variable, ignored by Elasticsearch
```
@@ -1050,13 +1072,13 @@ You can use standard Python inheritance to extend models, this can be useful in
```python
class User(InnerDoc):
- username = Text(fields={'keyword': Keyword()})
- email = Text()
+ username: str = mapped_field(Text(fields={'keyword': Keyword()}))
+ email: str
class BaseDocument(Document):
- created_by = Object(User)
- created_date = Date()
- last_updated = Date()
+ created_by: User
+ created_date: datetime
+ last_updated: datetime
def save(**kwargs):
if not self.created_date:
@@ -1101,7 +1123,7 @@ blogs.document(Post)
# can also be used as class decorator when defining the Document
@blogs.document
class Post(Document):
- title = Text()
+ title: str
# You can attach custom analyzers to the index
@@ -1138,9 +1160,15 @@ dev_blogs.setting(number_of_shards=1)
#### IndexTemplate [index-template]
-The DSL module also exposes an option to manage [index templates](docs-content://manage-data/data-store/templates.md) in elasticsearch using the `IndexTemplate` class which has very similar API to `Index`.
+The DSL module also exposes an option to manage [index templates](docs-content://manage-data/data-store/templates.md) in elasticsearch using the `ComposableIndexTemplate` and `IndexTemplate` classes, which have very similar API to `Index`.
-Once an index template is saved in elasticsearch it’s contents will be automatically applied to new indices (existing indices are completely unaffected by templates) that match the template pattern (any index starting with `blogs-` in our example), even if the index is created automatically upon indexing a document into that index.
+::::{note}
+Composable index templates should be always be preferred over the legacy index templates, since the latter are deprecated.
+
+::::
+
+
+Once an index template is saved in Elasticsearch its contents will be automatically applied to new indices (existing indices are completely unaffected by templates) that match the template pattern (any index starting with `blogs-` in our example), even if the index is created automatically upon indexing a document into that index.
Potential workflow for a set of time based indices governed by a single template:
@@ -1151,14 +1179,11 @@ from elasticsearch.dsl import Document, Date, Text
class Log(Document):
- content = Text()
- timestamp = Date()
+ content: str
+ timestamp: datetime
class Index:
name = "logs-*"
- settings = {
- "number_of_shards": 2
- }
def save(self, **kwargs):
# assign now if no timestamp given
@@ -1170,7 +1195,7 @@ class Log(Document):
return super().save(**kwargs)
# once, as part of application setup, during deploy/migrations:
-logs = Log._index.as_template('logs', order=0)
+logs = Log._index.as_composable_template('logs', priority=100)
logs.save()
# to perform search across all logs:
@@ -1184,12 +1209,6 @@ search = Log.search()
The library comes with a simple abstraction aimed at helping you develop faceted navigation for your data.
-::::{note}
-This API is experimental and will be subject to change. Any feedback is welcome.
-
-::::
-
-
### Configuration [_configuration_2]
You can provide several configuration options (as class attributes) when declaring a `FacetedSearch` subclass:
@@ -1316,7 +1335,7 @@ All methods return a *copy* of the object, making it safe to pass to outside cod
The API is chainable, allowing you to combine multiple method calls in one statement:
```python
-ubq = UpdateByQuery().using(client).query("match", title="python")
+ubq = UpdateByQuery().using(client).query(Match("title", python"))
```
To send the request to Elasticsearch:
@@ -1406,6 +1425,127 @@ print(response.took)
If you want to inspect the contents of the `response` objects, just use its `to_dict` method to get access to the raw data for pretty printing.
+## ES|QL Queries
+
+When working with `Document` classes, you can use the ES|QL query language to retrieve documents. For this you can use the `esql_from()` and `esql_execute()` methods available to all sub-classes of `Document`.
+
+Consider the following `Employee` document definition:
+
+```python
+from elasticsearch.dsl import Document, InnerDoc, M
+
+class Address(InnerDoc):
+ address: M[str]
+ city: M[str]
+ zip_code: M[str]
+
+class Employee(Document):
+ emp_no: M[int]
+ first_name: M[str]
+ last_name: M[str]
+ height: M[float]
+ still_hired: M[bool]
+ address: M[Address]
+
+ class Index:
+ name = 'employees'
+```
+
+The `esql_from()` method creates a base ES|QL query for the index associated with the document class. The following example creates a base query for the `Employee` class:
+
+```python
+query = Employee.esql_from()
+```
+
+This query includes a `FROM` command with the index name, and a `KEEP` command that retrieves all the document attributes.
+
+To execute this query and receive the results, you can pass the query to the `esql_execute()` method:
+
+```python
+for emp in Employee.esql_execute(query):
+ print(f"{emp.name} from {emp.address.city} is {emp.height:.2f}m tall")
+```
+
+In this example, the `esql_execute()` class method runs the query and returns all the documents in the index, up to the maximum of 1000 results allowed by ES|QL. Here is a possible output from this example:
+
+```
+Kevin Macias from North Robert is 1.60m tall
+Drew Harris from Boltonshire is 1.68m tall
+Julie Williams from Maddoxshire is 1.99m tall
+Christopher Jones from Stevenbury is 1.98m tall
+Anthony Lopez from Port Sarahtown is 2.42m tall
+Tricia Stone from North Sueshire is 2.39m tall
+Katherine Ramirez from Kimberlyton is 1.83m tall
+...
+```
+
+To search for specific documents you can extend the base query with additional ES|QL commands that narrow the search criteria. The next example searches for documents that include only employees that are taller than 2 meters, sorted by their last name. It also limits the results to 4 people:
+
+```python
+query = (
+ Employee.esql_from()
+ .where(Employee.height > 2)
+ .sort(Employee.last_name)
+ .limit(4)
+)
+```
+
+When running this query with the same for-loop shown above, possible results would be:
+
+```
+Michael Adkins from North Stacey is 2.48m tall
+Kimberly Allen from Toddside is 2.24m tall
+Crystal Austin from East Michaelchester is 2.30m tall
+Rebecca Berger from Lake Adrianside is 2.40m tall
+```
+
+### Additional fields
+
+ES|QL provides a few ways to add new fields to a query, for example through the `EVAL` command. The following example shows a query that adds an evaluated field:
+
+```python
+from elasticsearch.esql import E, functions
+
+query = (
+ Employee.esql_from()
+ .eval(height_cm=functions.round(Employee.height * 100))
+ .where(E("height_cm") >= 200)
+ .sort(Employee.last_name)
+ .limit(10)
+)
+```
+
+In this example we are adding the height in centimeters to the query, calculated from the `height` document field, which is in meters. The `height_cm` calculated field is available to use in other query clauses, and in particular is referenced in `where()` in this example. Note how the new field is given as `E("height_cm")` in this clause. The `E()` wrapper tells the query builder that the argument is an ES|QL field name and not a string literal. This is done automatically for document fields that are given as class attributes, such as `Employee.height` in the `eval()`. The `E()` wrapper is only needed for fields that are not in the document.
+
+By default, the `esql_execute()` method returns only document instances. To receive any additional fields that are not part of the document in the query results, the `return_additional=True` argument can be passed to it, and then the results are returned as tuples with the document as first element, and a dictionary with the additional fields as second element:
+
+```python
+for emp, additional in Employee.esql_execute(query, return_additional=True):
+ print(emp.name, additional)
+```
+
+Example output from the query given above:
+
+```
+Michael Adkins {'height_cm': 248.0}
+Kimberly Allen {'height_cm': 224.0}
+Crystal Austin {'height_cm': 230.0}
+Rebecca Berger {'height_cm': 240.0}
+Katherine Blake {'height_cm': 214.0}
+Edward Butler {'height_cm': 246.0}
+Steven Carlson {'height_cm': 242.0}
+Mark Carter {'height_cm': 240.0}
+Joseph Castillo {'height_cm': 229.0}
+Alexander Cohen {'height_cm': 245.0}
+```
+
+### Missing fields
+
+The base query returned by the `esql_from()` method includes a `KEEP` command with the complete list of fields that are part of the document. If any subsequent clauses added to the query remove fields that are part of the document, then the `esql_execute()` method will raise an exception, because it will not be able construct complete document instances to return as results.
+
+To prevent errors, it is recommended that the `keep()` and `drop()` clauses are not used when working with `Document` instances.
+
+If a query has missing fields, it can be forced to execute without errors by passing the `ignore_missing_fields=True` argument to `esql_execute()`. When this option is used, returned documents will have any missing fields set to `None`.
## Using asyncio with Elasticsearch Python DSL [asyncio]
@@ -1444,8 +1584,9 @@ Use the `AsyncSearch` class to perform asynchronous searches.
```python
from elasticsearch.dsl import AsyncSearch
+from elasticsearch.dsl.query import Match
-s = AsyncSearch().query("match", title="python")
+s = AsyncSearch().query(Match("title", "python"))
async for hit in s:
print(hit.title)
```
@@ -1453,7 +1594,7 @@ async for hit in s:
Instead of using the `AsyncSearch` object as an asynchronous iterator, you can explicitly call the `execute()` method to get a `Response` object.
```python
-s = AsyncSearch().query("match", title="python")
+s = AsyncSearch().query(Match("title", "python"))
response = await s.execute()
for hit in response:
print(hit.title)
@@ -1463,11 +1604,12 @@ An `AsyncMultiSearch` is available as well.
```python
from elasticsearch.dsl import AsyncMultiSearch
+from elasticsearch.dsl.query import Term
ms = AsyncMultiSearch(index='blogs')
-ms = ms.add(AsyncSearch().filter('term', tags='python'))
-ms = ms.add(AsyncSearch().filter('term', tags='elasticsearch'))
+ms = ms.add(AsyncSearch().filter(Term("tags", "python")))
+ms = ms.add(AsyncSearch().filter(Term("tags", "elasticsearch")))
responses = await ms.execute()
diff --git a/docs/reference/dsl_migrating.md b/docs/reference/dsl_migrating.md
new file mode 100644
index 000000000..ef4bd9f23
--- /dev/null
+++ b/docs/reference/dsl_migrating.md
@@ -0,0 +1,35 @@
+# Migrating from the `elasticsearch-dsl` package [_migrating_from_elasticsearch_dsl_package]
+
+In the past the Elasticsearch Python DSL module was distributed as a standalone package called `elasticsearch-dsl`. This package is now deprecated, since all its functionality has been integrated into the main Python client. We recommend all developers to migrate their applications and eliminate their dependency on the `elasticsearch-dsl` package.
+
+To migrate your application, all references to `elasticsearch_dsl` as a top-level package must be changed to `elasticsearch.dsl`. In other words, the underscore from the package name should be replaced by a period.
+
+Here are a few examples:
+
+```python
+# from:
+from elasticsearch_dsl import Date, Document, InnerDoc, Text, connections
+# to:
+from elasticsearch.dsl import Date, Document, InnerDoc, Text, connections
+
+# from:
+from elasticsearch_dsl.query import MultiMatch
+# to:
+from elasticsearch.dsl.query import MultiMatch
+
+# from:
+import elasticsearch_dsl as dsl
+# to:
+from elasticsearch import dsl
+
+# from:
+import elasticsearch_dsl
+# to:
+from elasticsearch import dsl as elasticsearch_dsl
+
+# from:
+import elasticsearch_dsl
+# to:
+from elasticsearch import dsl
+# and replace all references to "elasticsearch_dsl" in the code with "dsl"
+```
diff --git a/docs/reference/_tutorials.md b/docs/reference/dsl_tutorials.md
similarity index 79%
rename from docs/reference/_tutorials.md
rename to docs/reference/dsl_tutorials.md
index 7b72bc04e..16224a13f 100644
--- a/docs/reference/_tutorials.md
+++ b/docs/reference/dsl_tutorials.md
@@ -47,17 +47,17 @@ Let’s rewrite the example using the DSL module:
```python
from elasticsearch import Elasticsearch
-from elasticsearch.dsl import Search
+from elasticsearch.dsl import Search, query, aggs
client = Elasticsearch("https://localhost:9200/")
s = Search(using=client, index="my-index") \
- .filter("term", category="search") \
- .query("match", title="python") \
- .exclude("match", description="beta")
+ .query(query.Match("title", "python")) \
+ .filter(query.Term("category", "search")) \
+ .exclude(query.Match("description", "beta"))
-s.aggs.bucket('per_tag', 'terms', field='tags') \
- .metric('max_lines', 'max', field='lines')
+s.aggs.bucket('per_tag', aggs.Terms(field="tags")) \
+ .metric('max_lines', aggs.Max(field='lines'))
response = s.execute()
@@ -68,9 +68,9 @@ for tag in response.aggregations.per_tag.buckets:
print(tag.key, tag.max_lines.value)
```
-As you see, the library took care of:
+As you see, the DSL module took care of:
-* creating appropriate `Query` objects by name (eq. "match")
+* creating appropriate `Query` objects from classes
* composing queries into a compound `bool` query
* putting the `term` query in a filter context of the `bool` query
* providing a convenient access to response data
@@ -83,17 +83,17 @@ Let’s have a simple Python class representing an article in a blogging system:
```python
from datetime import datetime
-from elasticsearch.dsl import Document, Date, Integer, Keyword, Text, connections
+from elasticsearch.dsl import Document, Date, Integer, Keyword, Text, connections, mapped_field
# Define a default Elasticsearch client
connections.create_connection(hosts="https://localhost:9200/")
class Article(Document):
- title = Text(analyzer='snowball', fields={'raw': Keyword()})
- body = Text(analyzer='snowball')
- tags = Keyword()
- published_from = Date()
- lines = Integer()
+ title: str = mapped_field(Text(analyzer='snowball', fields={'raw': Keyword()}))
+ body: str = mapped_field(Text(analyzer='snowball'))
+ tags: list[str] = mapped_field(Keyword())
+ published_from: datetime
+ lines: int
class Index:
name = 'blog'
@@ -101,7 +101,7 @@ class Article(Document):
"number_of_shards": 2,
}
- def save(self, ** kwargs):
+ def save(self, **kwargs):
self.lines = len(self.body.split())
return super(Article, self).save(** kwargs)
@@ -127,7 +127,7 @@ print(connections.get_connection().cluster.health())
In this example you can see:
* providing a default connection
-* defining fields with mapping configuration
+* defining fields with Python type hints and additional mapping configuration when necessary
* setting index name
* defining custom methods
* overriding the built-in `.save()` method to hook into the persistence life cycle
@@ -141,12 +141,6 @@ You can see more in the `persistence` chapter.
If you have your `Document`s defined you can very easily create a faceted search class to simplify searching and filtering.
-::::{note}
-This feature is experimental and may be subject to change.
-
-::::
-
-
```python
from elasticsearch.dsl import FacetedSearch, TermsFacet, DateHistogramFacet
@@ -208,11 +202,12 @@ Using the DSL, we can now express this query as such:
```python
from elasticsearch import Elasticsearch
from elasticsearch.dsl import Search, UpdateByQuery
+from elasticsearch.dsl.query import Match
client = Elasticsearch()
ubq = UpdateByQuery(using=client, index="my-index") \
- .query("match", title="python") \
- .exclude("match", description="beta") \
+ .query(Match("title", "python")) \
+ .exclude(Match("description", "beta")) \
.script(source="ctx._source.likes++", lang="painless")
response = ubq.execute()
@@ -221,6 +216,20 @@ response = ubq.execute()
As you can see, the `Update By Query` object provides many of the savings offered by the `Search` object, and additionally allows one to update the results of the search based on a script assigned in the same manner.
+## ES|QL Queries
+
+The DSL module features an integration with the ES|QL query builder, consisting of two methods available in all `Document` sub-classes: `esql_from()` and `esql_execute()`. Using the `Article` document from above, we can search for up to ten articles that include `"world"` in their titles with the following ES|QL query:
+
+```python
+from elasticsearch.esql import functions
+
+query = Article.esql_from().where(functions.match(Article.title, 'world')).limit(10)
+for a in Article.esql_execute(query):
+ print(a.title)
+```
+
+Review the [ES|QL Query Builder section](esql-query-builder.md) to learn more about building ES|QL queries in Python.
+
## Migration from the standard client [_migration_from_the_standard_client]
You don’t have to port your entire application to get the benefits of the DSL module, you can start gradually by creating a `Search` object from your existing `dict`, modifying it using the API and serializing it back to a `dict`:
@@ -232,7 +241,7 @@ body = {...} # insert complicated query here
s = Search.from_dict(body)
# Add some filters, aggregations, queries, ...
-s.filter("term", tags="python")
+s.filter(query.Term("tags", "python"))
# Convert back to dict to plug back into existing code
body = s.to_dict()
diff --git a/docs/reference/elasticsearch-dsl.md b/docs/reference/elasticsearch-dsl.md
index 4030e232d..ad72cb1fe 100644
--- a/docs/reference/elasticsearch-dsl.md
+++ b/docs/reference/elasticsearch-dsl.md
@@ -9,11 +9,12 @@ Elasticsearch DSL is a module of the official Python client that aims to help wi
```python
from elasticsearch.dsl import Search
+from elasticsearch.dsl.query import Match, Term
s = Search(index="my-index") \
- .filter("term", category="search") \
- .query("match", title="python") \
- .exclude("match", description="beta")
+ .query(Match("title", "python")) \
+ .filter(Term("category", "search")) \
+ .exclude(Match("description", "beta"))
for hit in s:
print(hit.title)
```
@@ -22,12 +23,13 @@ Or with asynchronous Python:
```python
from elasticsearch.dsl import AsyncSearch
+from elasticsearch.dsl.query import Match, Term
async def run_query():
s = AsyncSearch(index="my-index") \
- .filter("term", category="search") \
- .query("match", title="python") \
- .exclude("match", description="beta")
+ .query(Match("title", "python")) \
+ .filter(Term("category", "search")) \
+ .exclude(Match("description", "beta"))
async for hit in s:
print(hit.title)
```
diff --git a/docs/reference/esql-pandas.md b/docs/reference/esql-pandas.md
index 506ea6579..5e7e0c886 100644
--- a/docs/reference/esql-pandas.md
+++ b/docs/reference/esql-pandas.md
@@ -355,7 +355,7 @@ You can now analyze the data with Pandas or you can also continue transforming t
## Analyze the data with Pandas [analyze-data]
-In the next example, the [STATS … BY](elasticsearch://reference/query-languages/esql/esql-commands.md#esql-stats-by) command is utilized to count how many employees are speaking a given language. The results are sorted with the `languages` column using [SORT](elasticsearch://reference/query-languages/esql/esql-commands.md#esql-sort):
+In the next example, the [STATS … BY](elasticsearch://reference/query-languages/esql/commands/processing-commands.md#esql-stats-by) command is utilized to count how many employees are speaking a given language. The results are sorted with the `languages` column using [SORT](elasticsearch://reference/query-languages/esql/commands/processing-commands.md#esql-sort):
```python
response = client.esql.query(
diff --git a/docs/reference/esql-query-builder.md b/docs/reference/esql-query-builder.md
new file mode 100644
index 000000000..7ef9a0960
--- /dev/null
+++ b/docs/reference/esql-query-builder.md
@@ -0,0 +1,260 @@
+# ES|QL Query Builder
+
+::::{warning}
+This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
+::::
+
+The ES|QL Query Builder allows you to construct ES|QL queries using Python syntax. Consider the following example:
+
+```python
+>>> from elasticsearch.esql import ESQL
+>>> query = (
+ ESQL.from_("employees")
+ .sort("emp_no")
+ .keep("first_name", "last_name", "height")
+ .eval(height_feet="height * 3.281", height_cm="height * 100")
+ .limit(3)
+)
+```
+
+You can then see the assembled ES|QL query by printing the resulting query object:
+
+```python
+>>> print(query)
+FROM employees
+| SORT emp_no
+| KEEP first_name, last_name, height
+| EVAL height_feet = height * 3.281, height_cm = height * 100
+| LIMIT 3
+```
+
+To execute this query, you can pass it to the `client.esql.query()` endpoint:
+
+```python
+>>> from elasticsearch import Elasticsearch
+>>> client = Elasticsearch(hosts=[os.environ['ELASTICSEARCH_URL']])
+>>> response = client.esql.query(query=query)
+```
+
+The response body contains a `columns` attribute with the list of columns included in the results, and a `values` attribute with the list of results for the query, each given as a list of column values. Here is a possible response body returned by the example query given above:
+
+```python
+>>> from pprint import pprint
+>>> pprint(response.body)
+{'columns': [{'name': 'first_name', 'type': 'text'},
+ {'name': 'last_name', 'type': 'text'},
+ {'name': 'height', 'type': 'double'},
+ {'name': 'height_feet', 'type': 'double'},
+ {'name': 'height_cm', 'type': 'double'}],
+ 'is_partial': False,
+ 'took': 11,
+ 'values': [['Adrian', 'Wells', 2.424, 7.953144, 242.4],
+ ['Aaron', 'Gonzalez', 1.584, 5.1971, 158.4],
+ ['Miranda', 'Kramer', 1.55, 5.08555, 155]]}
+```
+
+## Creating an ES|QL query
+
+To construct an ES|QL query you start from one of the ES|QL source commands:
+
+### `ESQL.from_`
+
+The `FROM` command selects the indices, data streams or aliases to be queried.
+
+Examples:
+
+```python
+from elasticsearch.esql import ESQL
+
+# FROM employees
+query1 = ESQL.from_("employees")
+
+# FROM
+query2 = ESQL.from_("")
+
+# FROM employees-00001, other-employees-*
+query3 = ESQL.from_("employees-00001", "other-employees-*")
+
+# FROM cluster_one:employees-00001, cluster_two:other-employees-*
+query4 = ESQL.from_("cluster_one:employees-00001", "cluster_two:other-employees-*")
+
+# FROM employees METADATA _id
+query5 = ESQL.from_("employees").metadata("_id")
+```
+
+Note how in the last example the optional `METADATA` clause of the `FROM` command is added as a chained method.
+
+### `ESQL.row`
+
+The `ROW` command produces a row with one or more columns, with the values that you specify.
+
+Examples:
+
+```python
+from elasticsearch.esql import ESQL, functions
+
+# ROW a = 1, b = "two", c = null
+query1 = ESQL.row(a=1, b="two", c=None)
+
+# ROW a = [1, 2]
+query2 = ESQL.row(a=[1, 2])
+
+# ROW a = ROUND(1.23, 0)
+query3 = ESQL.row(a=functions.round(1.23, 0))
+```
+
+### `ESQL.show`
+
+The `SHOW` command returns information about the deployment and its capabilities.
+
+Example:
+
+```python
+from elasticsearch.esql import ESQL
+
+# SHOW INFO
+query = ESQL.show("INFO")
+```
+
+## Adding processing commands
+
+Once you have a query object, you can add one or more processing commands to it. The following
+example shows how to create a query that uses the `WHERE` and `LIMIT` commands to filter the
+results:
+
+```python
+from elasticsearch.esql import ESQL
+
+# FROM employees
+# | WHERE still_hired == true
+# | LIMIT 10
+query = ESQL.from_("employees").where("still_hired == true").limit(10)
+```
+
+For a complete list of available commands, review the methods of the [`ESQLBase` class](https://elasticsearch-py.readthedocs.io/en/stable/esql.html) in the Elasticsearch Python API documentation.
+
+## Creating ES|QL Expressions and Conditions
+
+The ES|QL query builder for Python provides two ways to create expressions and conditions in ES|QL queries.
+
+The simplest option is to provide all ES|QL expressions and conditionals as strings. The following example uses this approach to add two calculated columns to the results using the `EVAL` command:
+
+```python
+from elasticsearch.esql import ESQL
+
+# FROM employees
+# | SORT emp_no
+# | KEEP first_name, last_name, height
+# | EVAL height_feet = height * 3.281, height_cm = height * 100
+query = (
+ ESQL.from_("employees")
+ .sort("emp_no")
+ .keep("first_name", "last_name", "height")
+ .eval(height_feet="height * 3.281", height_cm="height * 100")
+)
+```
+
+A more advanced alternative is to replace the strings with Python expressions, which are automatically translated to ES|QL when the query object is rendered to a string. The following example is functionally equivalent to the one above:
+
+```python
+from elasticsearch.esql import ESQL, E
+
+# FROM employees
+# | SORT emp_no
+# | KEEP first_name, last_name, height
+# | EVAL height_feet = height * 3.281, height_cm = height * 100
+query = (
+ ESQL.from_("employees")
+ .sort("emp_no")
+ .keep("first_name", "last_name", "height")
+ .eval(height_feet=E("height") * 3.281, height_cm=E("height") * 100)
+)
+```
+
+Here the `E()` helper function is used as a wrapper to the column name that initiates an ES|QL expression. The `E()` function transforms the given column into an ES|QL expression that can be modified with Python operators.
+
+Here is a second example, which uses a conditional expression in the `WHERE` command:
+
+```python
+from elasticsearch.esql import ESQL
+
+# FROM employees
+# | KEEP first_name, last_name, height
+# | WHERE first_name == "Larry"
+query = (
+ ESQL.from_("employees")
+ .keep("first_name", "last_name", "height")
+ .where('first_name == "Larry"')
+)
+```
+
+Using Python syntax, the condition can be rewritten as follows:
+
+```python
+from elasticsearch.esql import ESQL, E
+
+# FROM employees
+# | KEEP first_name, last_name, height
+# | WHERE first_name == "Larry"
+query = (
+ ESQL.from_("employees")
+ .keep("first_name", "last_name", "height")
+ .where(E("first_name") == "Larry")
+)
+```
+
+### Preventing injection attacks
+
+ES|QL, like most query languages, is vulnerable to [code injection attacks](https://en.wikipedia.org/wiki/Code_injection) if untrusted data provided by users is added to a query. To eliminate this risk, ES|QL allows untrusted data to be given separately from the query as parameters.
+
+Continuing with the example above, let's assume that the application needs a `find_employee_by_name()` function that searches for the name given as an argument. If this argument is received by the application from users, then it is considered untrusted and should not be added to the query directly. Here is how to code the function in a secure manner:
+
+```python
+def find_employee_by_name(name):
+ query = (
+ ESQL.from_("employees")
+ .keep("first_name", "last_name", "height")
+ .where(E("first_name") == E("?"))
+ )
+ return client.esql.query(query=query, params=[name])
+```
+
+Here the part of the query in which the untrusted data needs to be inserted is replaced with a parameter, which in ES|QL is defined by the question mark. When using Python expressions, the parameter must be given as `E("?")` so that it is treated as an expression and not as a literal string.
+
+The list of values given in the `params` argument to the query endpoint are assigned in order to the parameters defined in the query.
+
+## Using ES|QL functions
+
+The ES|QL language includes a rich set of functions that can be used in expressions and conditionals. These can be included in expressions given as strings, as shown in the example below:
+
+```python
+from elasticsearch.esql import ESQL
+
+# FROM employees
+# | KEEP first_name, last_name, height
+# | WHERE LENGTH(first_name) < 4"
+query = (
+ ESQL.from_("employees")
+ .keep("first_name", "last_name", "height")
+ .where("LENGTH(first_name) < 4")
+)
+```
+
+All available ES|QL functions have Python wrappers in the `elasticsearch.esql.functions` module, which can be used when building expressions using Python syntax. Below is the example above coded using Python syntax:
+
+```python
+from elasticsearch.esql import ESQL, functions
+
+# FROM employees
+# | KEEP first_name, last_name, height
+# | WHERE LENGTH(first_name) < 4"
+query = (
+ ESQL.from_("employees")
+ .keep("first_name", "last_name", "height")
+ .where(functions.length(E("first_name")) < 4)
+)
+```
+
+Note that arguments passed to functions are assumed to be literals. When passing field names, parameters or other ES|QL expressions, it is necessary to wrap them with the `E()` helper function so that they are interpreted correctly.
+
+You can find the complete list of available functions in the Python client's [ES|QL API reference documentation](https://elasticsearch-py.readthedocs.io/en/stable/esql.html#module-elasticsearch.esql.functions).
diff --git a/docs/reference/getting-started.md b/docs/reference/getting-started.md
index df413e836..54fce4ec3 100644
--- a/docs/reference/getting-started.md
+++ b/docs/reference/getting-started.md
@@ -41,15 +41,11 @@ client = Elasticsearch(
Your Elasticsearch endpoint can be found on the **My deployment** page of your deployment:
-:::{image} ../images/es-endpoint.jpg
-:alt: Finding Elasticsearch endpoint
-:::
+
You can generate an API key on the **Management** page under Security.
-:::{image} ../images/create-api-key.png
-:alt: Create API key
-:::
+
For other connection options, refer to the [*Connecting*](/reference/connecting.md) section.
diff --git a/docs/images/create-api-key.png b/docs/reference/images/create-api-key.png
similarity index 100%
rename from docs/images/create-api-key.png
rename to docs/reference/images/create-api-key.png
diff --git a/docs/images/es-endpoint.jpg b/docs/reference/images/es-endpoint.jpg
similarity index 100%
rename from docs/images/es-endpoint.jpg
rename to docs/reference/images/es-endpoint.jpg
diff --git a/docs/images/otel-waterfall-retry.png b/docs/reference/images/otel-waterfall-retry.png
similarity index 100%
rename from docs/images/otel-waterfall-retry.png
rename to docs/reference/images/otel-waterfall-retry.png
diff --git a/docs/images/otel-waterfall-with-http.png b/docs/reference/images/otel-waterfall-with-http.png
similarity index 100%
rename from docs/images/otel-waterfall-with-http.png
rename to docs/reference/images/otel-waterfall-with-http.png
diff --git a/docs/images/otel-waterfall-without-http.png b/docs/reference/images/otel-waterfall-without-http.png
similarity index 100%
rename from docs/images/otel-waterfall-without-http.png
rename to docs/reference/images/otel-waterfall-without-http.png
diff --git a/docs/reference/images/python-example.png b/docs/reference/images/python-example.png
new file mode 100644
index 000000000..3eaee6d02
Binary files /dev/null and b/docs/reference/images/python-example.png differ
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 99282dec2..6046d7801 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -6,7 +6,7 @@ mapped_pages:
# Python [overview]
-This is the official low-level Python client for {{es}}. Its goal is to provide common ground for all {{es}}-related code in Python. For this reason, the client is designed to be unopinionated and extendable. An API reference is available on [Read the Docs](https://elasticsearch-py.readthedocs.io).
+This is the official Python client for {{es}}. Its goal is to provide common ground for all {{es}}-related code in Python. For this reason, the client is designed to be unopinionated and extendable. API reference documentation for this client is available on [Read the Docs](https://elasticsearch-py.readthedocs.io).
## Example use [_example_use]
@@ -46,7 +46,7 @@ The client’s features include:
* Thread safety
* Pluggable architecture
-The client also contains a convenient set of [helpers](https://elasticsearch-py.readthedocs.org/en/master/helpers.md) for some of the more engaging tasks like bulk indexing and reindexing.
+The client also contains a convenient set of [helpers](client-helpers.md) for some of the more engaging tasks like bulk indexing and reindexing.
## Elasticsearch Python DSL [_elasticsearch_python_dsl]
@@ -56,12 +56,21 @@ For a higher level access with more limited scope, have a look at the DSL module
## Compatibility [_compatibility]
-Language clients are forward compatible; meaning that the clients support communicating with greater or equal minor versions of {{es}} without breaking. It does not mean that the clients automatically support new features of newer {{es}} versions; it is only possible after a release of a new client version. For example, a 8.12 client version won’t automatically support the new features of the 8.13 version of {{es}}, the 8.13 client version is required for that. {{es}} language clients are only backwards compatible with default distributions and without guarantees made.
+Language clients are _forward compatible:_ each client version works with equivalent and later minor versions of {{es}} without breaking.
-| Elasticsearch version | elasticsearch-py branch | Supported |
-| --- | --- | --- |
-| main | main | |
-| 8.x | 8.x | 8.x |
-| 7.x | 7.x | 7.17 |
+Compatibility does not imply full 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; however, it does not support new {{es}} 8.13 features. An 8.13 client fully supports {{es}} 8.13 features.
-If you have a need to have multiple versions installed at the same time older versions are also released as `elasticsearch7` and `elasticsearch8`.
+| Elasticsearch version | elasticsearch-py branch |
+| --- | --- |
+| main | main |
+| 9.x | 9.x |
+| 9.x | 8.x |
+| 8.x | 8.x |
+
+{{es}} language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees.
+
+:::{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`.
diff --git a/docs/reference/opentelemetry.md b/docs/reference/opentelemetry.md
index fb117d505..d2dbb5482 100644
--- a/docs/reference/opentelemetry.md
+++ b/docs/reference/opentelemetry.md
@@ -9,24 +9,18 @@ You can use [OpenTelemetry](https://opentelemetry.io/) to monitor the performanc
The native instrumentation in the Python client follows the [OpenTelemetry Semantic Conventions for {{es}}](https://opentelemetry.io/docs/specs/semconv/database/elasticsearch/). In particular, the instrumentation in the client covers the logical layer of {{es}} requests. A single span per request is created that is processed by the service through the Python client. The following image shows a trace that records the handling of two different {{es}} requests: an `info` request and a `search` request.
-:::{image} ../images/otel-waterfall-without-http.png
-:alt: Distributed trace with Elasticsearch spans
-:class: screenshot
-:::
+% TO DO: Use `:class: screenshot`
+
Usually, OpenTelemetry auto-instrumentation modules come with instrumentation support for HTTP-level communication. In this case, in addition to the logical {{es}} client requests, spans will be captured for the physical HTTP requests emitted by the client. The following image shows a trace with both, {{es}} spans (in blue) and the corresponding HTTP-level spans (in red) after having installed the ``opentelemetry-instrumentation-urllib3`` package:
-:::{image} ../images/otel-waterfall-with-http.png
-:alt: Distributed trace with Elasticsearch spans
-:class: screenshot
-:::
+% TO DO: Use `:class: screenshot`
+
Advanced Python client behavior such as nodes round-robin and request retries are revealed through the combination of logical {{es}} spans and the physical HTTP spans. The following example shows a `search` request in a scenario with two nodes:
-:::{image} ../images/otel-waterfall-retry.png
-:alt: Distributed trace with Elasticsearch spans
-:class: screenshot
-:::
+% TO DO: Use `:class: screenshot`
+
The first node is unavailable and results in an HTTP error, while the retry to the second node succeeds. Both HTTP requests are subsumed by the logical {{es}} request span (in blue).
@@ -41,7 +35,7 @@ When using the [manual Python OpenTelemetry instrumentation](https://opentelemet
## Comparison with community instrumentation [_comparison_with_community_instrumentation]
-The [commmunity OpenTelemetry Elasticsearch instrumentation](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/elasticsearch/elasticsearch.md) also instruments the client and sends OpenTelemetry traces, but was developed before the OpenTelemetry Semantic Conventions for {{es}}, so the traces attributes are inconsistent with other OpenTelemetry Elasticsearch client instrumentations. To avoid tracing the same requests twice, make sure to use only one instrumentation, either by uninstalling the opentelemetry-instrumentation-elasticsearch Python package or by [disabling the native instrumentation](#opentelemetry-config-enable).
+The [commmunity OpenTelemetry Elasticsearch instrumentation](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/elasticsearch/elasticsearch.html) also instruments the client and sends OpenTelemetry traces, but was developed before the OpenTelemetry Semantic Conventions for {{es}}, so the traces attributes are inconsistent with other OpenTelemetry Elasticsearch client instrumentations. To avoid tracing the same requests twice, make sure to use only one instrumentation, either by uninstalling the opentelemetry-instrumentation-elasticsearch Python package or by [disabling the native instrumentation](#opentelemetry-config-enable).
### Configuring the OpenTelemetry instrumentation [_configuring_the_opentelemetry_instrumentation]
diff --git a/docs/reference/querying.md b/docs/reference/querying.md
new file mode 100644
index 000000000..a4946d340
--- /dev/null
+++ b/docs/reference/querying.md
@@ -0,0 +1,104 @@
+# Querying
+
+The Python Elasticsearch client provides several ways to send queries to Elasticsearch. This document explains the details of how to construct and execute queries using the client. This document does not cover the DSL module.
+
+## From API URLs to function calls
+
+Elasticsearch APIs are grouped by namespaces.
+
+ * There's the global namespace, with APIs like the Search API (`GET _search`) or the Index API (`PUT //_doc/<_id>` and related endpoints).
+ * Then there are all the other namespaces, such as:
+ * Indices with APIs like the Create index API (`PUT /my-index`),
+ * ES|QL with the Run an ES|QL query API (`POST /_async`),
+ * and so on.
+
+As a result, when you know which namespace and function you need, you can call the function. Assuming that `client` is an Elasticsearch instance, here is how you would call the examples from above:
+
+* Global namespace: `client.search(...)` and `client.index(...)`
+* Other namespaces:
+ * Indices: `client.indices.create(...)`
+ * ES|QL: `client.esql.query(...)`
+
+How can you figure out the namespace?
+
+* The [Elasticsearch API docs](https://www.elastic.co/docs/api/doc/elasticsearch/) can help, even though the tags it uses do not fully map to namespaces.
+* You can also use the client documentation, by:
+ * browsing the [Elasticsearch API Reference](https://elasticsearch-py.readthedocs.io/en/stable/api.html) page, or
+ * searching for your endpoint using [Read the Docs](https://elasticsearch-py.readthedocs.io/) search, which is powered by Elasticsearch!
+* Finally, for Elasticsearch 8.x, most examples in the [Elasticsearch guide](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html) are also available in Python. (This is still a work in progress for Elasticsearch 9.x.) In the example below, `client.ingest.put_pipeline(...)` is the function that calls the "Create or update a pipeline" API.
+
+
+
+
+## Parameters
+
+Now that you know which functions to call, the next step is parameters. To avoid ambiguity, the Python Elasticsearch client mandates keyword arguments. To give an example, let's look at the ["Create an index" API](https://elasticsearch-py.readthedocs.io/en/stable/api/indices.html#elasticsearch.client.IndicesClient.create). There's only one required parameter, `index`, so the minimal form looks like this:
+
+```python
+from elasticsearch import Elasticsearch
+
+client = Elasticsearch("http://localhost:9200/", api_key="...")
+
+client.indices.create(index="my-index")
+```
+
+You can also use other parameters, including the first level of body parameters, such as:
+
+```python
+resp = client.indices.create(
+ index="logs",
+ aliases={"logs-alias": {}},
+ mappings={"name": {"type": "text"}},
+)
+print(resp)
+```
+
+In this case, the client will send to Elasticsearch the following JSON body:
+
+```console
+PUT /logs
+{
+ "aliases": {"logs-alias": {}},
+ "mappings": {"name": {"type": "text"}}
+}
+```
+
+## Unknown parameters or APIs
+
+Like other clients, the Python Elasticsearch client is generated from the [Elasticsearch specification](https://github.com/elastic/elasticsearch-specification). While we strive to keep it up to date, it is not (yet!) perfect, and sometimes body parameters are missing. In this case, you can specify the body directly, as follows:
+
+```python
+resp = client.indices.create(
+ index="logs",
+ body={
+ "aliases": {"logs-alias": {}},
+ "mappings": {"name": {"type": "text"}},
+ "missing_parameter": "foo",
+ }
+)
+print(resp)
+```
+
+In the event where an API is missing, you need to use the low-level `perform_request` function:
+
+```python
+resp = client.perform_request(
+ "PUT",
+ "/logs"
+ index="logs",
+ headers={"content-type": "application/json", "accept": "application/json"},
+ body={
+ "aliases": {"logs-alias": {}},
+ "mappings": {"name": {"type": "text"}},
+ "missing_parameter": "foo",
+ }
+)
+print(resp)
+```
+
+One benefit of this function is that it lets you use arbitrary headers, such as the `es-security-runas-user` header used to [impersonate users](https://www.elastic.co/guide/en/elasticsearch/reference/current/run-as-privilege.html).
+
+
+## Options
+
+You can specify options such as request timeouts or retries using the `.options()` API, see the [Configuration](./configuration.md) page for details.
\ No newline at end of file
diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml
index 8de284050..7e26b7274 100644
--- a/docs/reference/toc.yml
+++ b/docs/reference/toc.yml
@@ -4,6 +4,8 @@ toc:
- file: installation.md
- file: connecting.md
- file: configuration.md
+ - file: querying.md
+ - file: esql-query-builder.md
- file: async.md
- file: integrations.md
children:
@@ -12,8 +14,9 @@ toc:
- file: examples.md
- file: elasticsearch-dsl.md
children:
- - file: _configuration.md
- - file: _tutorials.md
- - file: _how_to_guides.md
- - file: _examples.md
- - file: client-helpers.md
\ No newline at end of file
+ - file: dsl_configuration.md
+ - file: dsl_tutorials.md
+ - file: dsl_how_to_guides.md
+ - file: dsl_examples.md
+ - file: dsl_migrating.md
+ - file: client-helpers.md
diff --git a/docs/release-notes/breaking-changes.md b/docs/release-notes/breaking-changes.md
index b79d3cb96..0a354b9ce 100644
--- a/docs/release-notes/breaking-changes.md
+++ b/docs/release-notes/breaking-changes.md
@@ -1,14 +1,11 @@
---
-navigation_title: "Elasticsearch Python Client"
+navigation_title: "Breaking changes"
---
# Elasticsearch Python Client breaking changes [elasticsearch-python-client-breaking-changes]
-Before you upgrade, carefully review the Elasticsearch Python Client breaking changes and take the necessary steps to mitigate any issues.
-
-To learn how to upgrade, check out .
+Breaking changes can impact your Elastic applications, potentially disrupting normal operations. Before you upgrade, carefully review the Elasticsearch Python Client breaking changes and take the necessary steps to mitigate any issues. To learn how to upgrade, check [Upgrade](docs-content://deploy-manage/upgrade.md).
% ## Next version [elasticsearch-python-client-nextversion-breaking-changes]
-% **Release date:** Month day, year
% ::::{dropdown} Title of breaking change
% Description of the breaking change.
@@ -17,12 +14,40 @@ To learn how to upgrade, check out .
% **Action** Steps for mitigating deprecation impact.
% ::::
-% ## 9.0.0 [elasticsearch-python-client-900-breaking-changes]
-% **Release date:** March 25, 2025
+## 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** Impact of the breaking change.
-% **Action** Steps for mitigating deprecation impact.
-% ::::
\ No newline at end of file
+::::{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** These parameters were removed in favor of more descriptive versions. Using any of these parameters will prevent instantiating the Elasticsearch client.
+
+**Action** 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 `connections_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**
+Using any of these parameters will prevent instantiating the Elasticsearch client.
+
+**Action**
+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**
+ * 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/deprecations.md b/docs/release-notes/deprecations.md
index 1b9bfbb74..3f3fa82a6 100644
--- a/docs/release-notes/deprecations.md
+++ b/docs/release-notes/deprecations.md
@@ -1,14 +1,13 @@
---
-navigation_title: "Elasticsearch Python Client"
+navigation_title: "Deprecations"
---
# Elasticsearch Python Client deprecations [elasticsearch-python-client-deprecations]
-Review the deprecated functionality for your Elasticsearch Python Client version. While deprecations have no immediate impact, we strongly encourage you update your implementation after you upgrade.
+Over time, certain Elastic functionality becomes outdated and is replaced or removed. To help with the transition, Elastic deprecates functionality for a period before removal, giving you time to update your applications.
-To learn how to upgrade, check out .
+Review the deprecated functionality for Elasticsearch Python Client. While deprecations have no immediate impact, we strongly encourage you update your implementation after you upgrade. To learn how to upgrade, check out [Upgrade](docs-content://deploy-manage/upgrade.md).
% ## Next version [elasticsearch-python-client-versionnext-deprecations]
-% **Release date:** Month day, year
% ::::{dropdown} Deprecation title
% Description of the deprecation.
@@ -18,7 +17,6 @@ To learn how to upgrade, check out .
% ::::
% ## 9.0.0 [elasticsearch-python-client-900-deprecations]
-% **Release date:** March 25, 2025
% ::::{dropdown} Deprecation title
% Description of the deprecation.
diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md
index 156625560..5c25e8633 100644
--- a/docs/release-notes/index.md
+++ b/docs/release-notes/index.md
@@ -1,27 +1,150 @@
---
navigation_title: "Elasticsearch Python Client"
+mapped_pages:
+ - https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/release-notes.html
---
# Elasticsearch Python Client release notes [elasticsearch-python-client-release-notes]
-Review the changes, fixes, and more in each version of Elasticsearch Python Client.
+Review the changes, fixes, and more in each version of Elasticsearch Python Client.
To check for security updates, go to [Security announcements for the Elastic stack](https://discuss.elastic.co/c/announcements/security-announcements/31).
-% Release notes include only features, enhancements, and fixes. Add breaking changes, deprecations, and known issues to the applicable release notes sections.
+% Release notes include only features, enhancements, and fixes. Add breaking changes, deprecations, and known issues to the applicable release notes sections.
-% ## version.next [felasticsearch-python-client-next-release-notes]
-% **Release date:** Month day, year
+% ## version.next [elasticsearch-python-client-next-release-notes]
% ### Features and enhancements [elasticsearch-python-client-next-features-enhancements]
-% *
+% *
% ### Fixes [elasticsearch-python-client-next-fixes]
-% *
+## 9.0.4 (2025-09-11)
-## 9.0.0 [elasticsearch-python-client-900-release-notes]
-**Release date:** March 25, 2025
+* ES|QL query builder integration with the DSL module ([#3058](https://github.com/elastic/elasticsearch-py/pull/3058))
+* ES|QL query builder robustness fixes ([#3017](https://github.com/elastic/elasticsearch-py/pull/3017))
+* Fix ES|QL `multi_match()` signature ([#3052](https://github.com/elastic/elasticsearch-py/pull/3052))
-### Features and enhancements [elasticsearch-python-client-900-features-enhancements]
+API
+* Add support for ES|QL query builder objects to ES|QL Query and Async Query APIs
+* Add Transform Set Upgrade Mode API
+* Fix type of `fields` parameter of Term Vectors API to array of strings
+* Fix type of `params` parameter of SQL Query API to array
-### Fixes [elasticsearch-python-client-900-fixes]
\ No newline at end of file
+DSL
+* Preserve the `skip_empty` setting in `to_dict()` recursive serializations ([#3041](https://github.com/elastic/elasticsearch-py/pull/3041))
+* Add `primary` attribute to `ShardFailure` type
+* Fix type of `key` attribute of `ArrayPercentilesItem` to float
+
+
+## 9.0.3 (2025-07-30)
+
+Enhancements
+
+* ES|QL query builder (technical preview) ([#2997](https://github.com/elastic/elasticsearch-py/pull/2997))
+* Add option to disable accurate reporting of file and line location in warnings (Fixes #3003) ([#3006](https://github.com/elastic/elasticsearch-py/pull/3006))
+
+APIs
+
+* Remove `if_primary_term`, `if_seq_no` and `op_type` from Create API
+* Remove `stored_fields` from Get Source API
+* Remove `master_timeout` from Ingest Get Ip Location Database API
+* Remove `application`, `priviledge` and `username` from the Security Get User API
+* Rename `type_query_string` to `type` in License Post Start Trial API
+* Add `require_data_stream` to Index API
+* Add `settings_filter` to Cluster Get Component Template API
+* Add `cause` to Cluster Put Component Template API
+* Add `ccs_minimize_roundtrips` to EQL Search API
+* Add `keep_alive` and `keep_on_completion` to ES|QL Async Query API
+* Add `format` to ES|QL Async Query Get API
+* Add `allow_no_indices`, `expand_wildcards` and `ignore_available` to Indices Recovery API
+* Add `timeout` to all Inference Put APIs
+* Add `refresh` to Security Get User Profile API
+* Add `wait_for_completion` to the Snapshot Delete API
+
+DSL
+
+* Handle lists in `copy_to` field option correctly (Fixes #2992) ([#2993](https://github.com/elastic/elasticsearch-py/pull/2993))
+* Add `key` to FiltersBucket type
+
+
+
+## 9.0.2 (2025-06-05) [elasticsearch-python-client-902-release-notes]
+
+### DSL
+
+* Add `rescore_vector` to `DenseVectorIndexOptions`
+
+
+## 9.0.1 (2025-04-28) [elasticsearch-python-client-901-release-notes]
+
+### Features and enhancements [elasticsearch-python-client-901-features-enhancements]
+
+* Surface caused_by in ApiError ([#2932](https://github.com/elastic/elasticsearch-py/pull/2932))
+* Clarify Elasticsearch 9.x compatibility ([#2928](https://github.com/elastic/elasticsearch-py/pull/2928))
+* Reorganize Sphinx docs to only include reference pages ([#2776](https://github.com/elastic/elasticsearch-py/pull/2776))
+
+
+## 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))
+
+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 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))
+
+### 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
diff --git a/docs/release-notes/known-issues.md b/docs/release-notes/known-issues.md
index da93abb27..465030552 100644
--- a/docs/release-notes/known-issues.md
+++ b/docs/release-notes/known-issues.md
@@ -1,5 +1,5 @@
---
-navigation_title: "Elasticsearch Python Client"
+navigation_title: "Known issues"
---
diff --git a/docs/sphinx/api_helpers.rst b/docs/sphinx/api_helpers.rst
new file mode 100644
index 000000000..31d5b241d
--- /dev/null
+++ b/docs/sphinx/api_helpers.rst
@@ -0,0 +1,26 @@
+.. _helpers:
+
+Helpers
+=======
+
+.. py:module:: elasticsearch.helpers
+
+Streaming Bulk
+--------------
+.. autofunction:: streaming_bulk
+
+Parallel Bulk
+-------------
+.. autofunction:: parallel_bulk
+
+Bulk
+----
+.. autofunction:: bulk
+
+Scan
+----
+.. autofunction:: scan
+
+Reindex
+-------
+.. autofunction:: reindex
diff --git a/docs/sphinx/async.rst b/docs/sphinx/async.rst
deleted file mode 100644
index 22a49b312..000000000
--- a/docs/sphinx/async.rst
+++ /dev/null
@@ -1,237 +0,0 @@
-Using asyncio with Elasticsearch
-================================
-
- .. py:module:: elasticsearch
- :no-index:
-
-The ``elasticsearch`` package supports async/await with
-`asyncio `_ and `aiohttp `_.
-You can either install ``aiohttp`` directly or use the ``[async]`` extra:
-
- .. code-block:: bash
-
- $ python -m pip install elasticsearch aiohttp
-
- # - OR -
-
- $ python -m pip install elasticsearch[async]
-
-Getting Started with Async
---------------------------
-
-After installation all async API endpoints are available via :class:`~elasticsearch.AsyncElasticsearch`
-and are used in the same way as other APIs, just with an extra ``await``:
-
- .. code-block:: python
-
- import asyncio
- from elasticsearch import AsyncElasticsearch
-
- client = AsyncElasticsearch()
-
- async def main():
- resp = await client.search(
- index="documents",
- body={"query": {"match_all": {}}},
- size=20,
- )
- print(resp)
-
- loop = asyncio.get_event_loop()
- loop.run_until_complete(main())
-
-All APIs that are available under the sync client are also available under the async client.
-
-ASGI Applications and Elastic APM
----------------------------------
-
-`ASGI `_ (Asynchronous Server Gateway Interface) is a new way to
-serve Python web applications making use of async I/O to achieve better performance.
-Some examples of ASGI frameworks include FastAPI, Django 3.0+, and Starlette.
-If you're using one of these frameworks along with Elasticsearch then you
-should be using :py:class:`~elasticsearch.AsyncElasticsearch` to avoid blocking
-the event loop with synchronous network calls for optimal performance.
-
-`Elastic APM `_
-also supports tracing of async Elasticsearch queries just the same as
-synchronous queries. For an example on how to configure ``AsyncElasticsearch`` with
-a popular ASGI framework `FastAPI `_ and APM tracing
-there is a `pre-built example `_
-in the ``examples/fastapi-apm`` directory.
-
-Frequently Asked Questions
---------------------------
-
-ValueError when initializing ``AsyncElasticsearch``?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If when trying to use ``AsyncElasticsearch`` you receive ``ValueError: You must
-have 'aiohttp' installed to use AiohttpHttpNode`` you should ensure that you
-have ``aiohttp`` installed in your environment (check with ``$ python -m pip
-freeze | grep aiohttp``). Otherwise, async support won't be available.
-
-What about the ``elasticsearch-async`` package?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Previously asyncio was supported separately via the `elasticsearch-async `_
-package. The ``elasticsearch-async`` package has been deprecated in favor of
-``AsyncElasticsearch`` provided by the ``elasticsearch`` package
-in v7.8 and onwards.
-
-Receiving 'Unclosed client session / connector' warning?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This warning is created by ``aiohttp`` when an open HTTP connection is
-garbage collected. You'll typically run into this when closing your application.
-To resolve the issue ensure that :meth:`~elasticsearch.AsyncElasticsearch.close`
-is called before the :py:class:`~elasticsearch.AsyncElasticsearch` instance is garbage collected.
-
-For example if using FastAPI that might look like this:
-
- .. code-block:: python
-
- import os
- from contextlib import asynccontextmanager
-
- from fastapi import FastAPI
- from elasticsearch import AsyncElasticsearch
-
- ELASTICSEARCH_URL = os.environ["ELASTICSEARCH_URL"]
- client = None
-
- @asynccontextmanager
- async def lifespan(app: FastAPI):
- global client
- client = AsyncElasticsearch(ELASTICSEARCH_URL)
- yield
- await client.close()
-
- app = FastAPI(lifespan=lifespan)
-
- @app.get("/")
- async def main():
- return await client.info()
-
-You can run this example by saving it to ``main.py`` and executing
-``ELASTICSEARCH_URL=http://localhost:9200 uvicorn main:app``.
-
-
-Async Helpers
--------------
-
-Async variants of all helpers are available in ``elasticsearch.helpers``
-and are all prefixed with ``async_*``. You'll notice that these APIs
-are identical to the ones in the sync :ref:`helpers` documentation.
-
-All async helpers that accept an iterator or generator also accept async iterators
-and async generators.
-
- .. py:module:: elasticsearch.helpers
- :no-index:
-
-Bulk and Streaming Bulk
-~~~~~~~~~~~~~~~~~~~~~~~
-
- .. autofunction:: async_bulk
-
- .. code-block:: python
-
- import asyncio
- from elasticsearch import AsyncElasticsearch
- from elasticsearch.helpers import async_bulk
-
- client = AsyncElasticsearch()
-
- async def gendata():
- mywords = ['foo', 'bar', 'baz']
- for word in mywords:
- yield {
- "_index": "mywords",
- "doc": {"word": word},
- }
-
- async def main():
- await async_bulk(client, gendata())
-
- loop = asyncio.get_event_loop()
- loop.run_until_complete(main())
-
- .. autofunction:: async_streaming_bulk
-
- .. code-block:: python
-
- import asyncio
- from elasticsearch import AsyncElasticsearch
- from elasticsearch.helpers import async_streaming_bulk
-
- client = AsyncElasticsearch()
-
- async def gendata():
- mywords = ['foo', 'bar', 'baz']
- for word in mywords:
- yield {
- "_index": "mywords",
- "word": word,
- }
-
- async def main():
- async for ok, result in async_streaming_bulk(client, gendata()):
- action, result = result.popitem()
- if not ok:
- print("failed to %s document %s" % ())
-
- loop = asyncio.get_event_loop()
- loop.run_until_complete(main())
-
-Scan
-~~~~
-
- .. autofunction:: async_scan
-
- .. code-block:: python
-
- import asyncio
- from elasticsearch import AsyncElasticsearch
- from elasticsearch.helpers import async_scan
-
- client = AsyncElasticsearch()
-
- async def main():
- async for doc in async_scan(
- client=client,
- query={"query": {"match": {"title": "python"}}},
- index="orders-*"
- ):
- print(doc)
-
- loop = asyncio.get_event_loop()
- loop.run_until_complete(main())
-
-Reindex
-~~~~~~~
-
- .. autofunction:: async_reindex
-
-
-API Reference
--------------
-
- .. py:module:: elasticsearch
- :no-index:
-
-The API of :class:`~elasticsearch.AsyncElasticsearch` is nearly identical
-to the API of :class:`~elasticsearch.Elasticsearch` with the exception that
-every API call like :py:func:`~elasticsearch.AsyncElasticsearch.search` is
-an ``async`` function and requires an ``await`` to properly return the response
-body.
-
-AsyncElasticsearch
-~~~~~~~~~~~~~~~~~~
-
- .. note::
-
- To reference Elasticsearch APIs that are namespaced like ``.indices.create()``
- refer to the sync API reference. These APIs are identical between sync and async.
-
- .. autoclass:: AsyncElasticsearch
- :members:
diff --git a/docs/sphinx/async_api_helpers.rst b/docs/sphinx/async_api_helpers.rst
new file mode 100644
index 000000000..61dbb5c24
--- /dev/null
+++ b/docs/sphinx/async_api_helpers.rst
@@ -0,0 +1,29 @@
+Async Helpers
+=============
+
+Async variants of all helpers are available in ``elasticsearch.helpers``
+and are all prefixed with ``async_*``. You'll notice that these APIs
+are identical to the ones in the sync :ref:`helpers` documentation.
+
+All async helpers that accept an iterator or generator also accept async iterators
+and async generators.
+
+ .. py:module:: elasticsearch.helpers
+ :no-index:
+
+Streaming Bulk
+--------------
+ .. autofunction:: async_streaming_bulk
+
+Bulk
+----
+ .. autofunction:: async_bulk
+
+Scan
+----
+ .. autofunction:: async_scan
+
+Reindex
+-------
+ .. autofunction:: async_reindex
+
diff --git a/docs/sphinx/async_dsl.rst b/docs/sphinx/async_dsl.rst
new file mode 100644
index 000000000..89ac8565d
--- /dev/null
+++ b/docs/sphinx/async_dsl.rst
@@ -0,0 +1,49 @@
+.. _async_dsl:
+
+Async DSL
+=========
+
+.. py:module:: elasticsearch.dsl
+ :no-index:
+
+Search
+------
+.. autoclass:: AsyncSearch
+ :inherited-members:
+ :members:
+
+Multi-Search
+------------
+.. autoclass:: AsyncMultiSearch
+ :inherited-members:
+ :members:
+
+Document
+--------
+.. autoclass:: AsyncDocument
+ :inherited-members:
+ :members:
+
+Index
+-----
+.. autoclass:: AsyncIndex
+ :inherited-members:
+ :members:
+
+Mapping
+-------
+.. autoclass:: AsyncMapping
+ :inherited-members:
+ :members:
+
+Faceted Search
+--------------
+.. autoclass:: AsyncFacetedSearch
+ :inherited-members:
+ :members:
+
+Update by Query
+---------------
+.. autoclass:: AsyncUpdateByQuery
+ :inherited-members:
+ :members:
diff --git a/docs/sphinx/async_es_api.rst b/docs/sphinx/async_es_api.rst
new file mode 100644
index 000000000..d4acf2ff0
--- /dev/null
+++ b/docs/sphinx/async_es_api.rst
@@ -0,0 +1,15 @@
+Async Elasticsearch API
+=======================
+
+ .. py:module:: elasticsearch
+ :no-index:
+
+ .. note::
+
+ To reference Elasticsearch APIs that are namespaced like ``.indices.create()``
+ refer to the sync API reference. These APIs are identical between sync and async.
+
+Elasticsearch
+-------------
+ .. autoclass:: AsyncElasticsearch
+ :members:
diff --git a/docs/sphinx/dsl.rst b/docs/sphinx/dsl.rst
new file mode 100644
index 000000000..08ab3c935
--- /dev/null
+++ b/docs/sphinx/dsl.rst
@@ -0,0 +1,49 @@
+.. _dsl:
+
+DSL
+===
+
+.. py:module:: elasticsearch.dsl
+
+Search
+------
+.. autoclass:: Search
+ :inherited-members:
+ :members:
+
+Multi-Search
+------------
+.. autoclass:: MultiSearch
+ :inherited-members:
+ :members:
+
+Document
+--------
+.. autoclass:: Document
+ :inherited-members:
+ :members:
+
+Index
+-----
+.. autoclass:: Index
+ :inherited-members:
+ :members:
+
+Mapping
+-------
+.. autoclass:: Mapping
+ :inherited-members:
+ :members:
+
+Faceted Search
+--------------
+.. autoclass:: FacetedSearch
+ :inherited-members:
+ :members:
+
+Update by Query
+---------------
+.. autoclass:: UpdateByQuery
+ :inherited-members:
+ :members:
+
diff --git a/docs/sphinx/api.rst b/docs/sphinx/es_api.rst
similarity index 95%
rename from docs/sphinx/api.rst
rename to docs/sphinx/es_api.rst
index 61d3214e6..d246ec6f5 100644
--- a/docs/sphinx/api.rst
+++ b/docs/sphinx/es_api.rst
@@ -1,7 +1,7 @@
.. _api:
-Elasticsearch API Reference
-===========================
+Elasticsearch API
+=================
All the API calls map the raw REST API as closely as possible, including the
distinction between required and optional arguments to the calls. Keyword
diff --git a/docs/sphinx/esql.rst b/docs/sphinx/esql.rst
new file mode 100644
index 000000000..1104b5b97
--- /dev/null
+++ b/docs/sphinx/esql.rst
@@ -0,0 +1,100 @@
+ES|QL Query Builder
+===================
+
+Commands
+--------
+
+.. autoclass:: elasticsearch.esql.ESQL
+ :inherited-members:
+ :members:
+
+.. autoclass:: elasticsearch.esql.esql.ESQLBase
+ :inherited-members:
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.From
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Row
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Show
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.ChangePoint
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Completion
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Dissect
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Drop
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Enrich
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Eval
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Fork
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Grok
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Keep
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Limit
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.LookupJoin
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.MvExpand
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Rename
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Sample
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Sort
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Stats
+ :members:
+ :exclude-members: __init__
+
+.. autoclass:: elasticsearch.esql.esql.Where
+ :members:
+ :exclude-members: __init__
+
+Functions
+---------
+
+.. automodule:: elasticsearch.esql.functions
+ :members:
diff --git a/docs/sphinx/helpers.rst b/docs/sphinx/helpers.rst
deleted file mode 100644
index 3390958a8..000000000
--- a/docs/sphinx/helpers.rst
+++ /dev/null
@@ -1,146 +0,0 @@
-.. _helpers:
-
-Helpers
-=======
-
-Collection of simple helper functions that abstract some specifics of the raw API.
-
-Connecting
-----------
-
-.. code-block:: python
-
- from elasticsearch import Elasticsearch
-
- client = Elasticsearch("https://.../", api_key="YOUR_API_KEY")
-
-
-Bulk helpers
-------------
-
-There are several helpers for the ``bulk`` API since its requirement for
-specific formatting and other considerations can make it cumbersome if used directly.
-
-All bulk helpers accept an instance of ``Elasticsearch`` class and an iterable
-``actions`` (any iterable, can also be a generator, which is ideal in most
-cases since it will allow you to index large datasets without the need of
-loading them into memory).
-
-The items in the ``action`` iterable should be the documents we wish to index
-in several formats. The most common one is the same as returned by
-:meth:`~elasticsearch.Elasticsearch.search`, for example:
-
-.. code:: python
-
- {
- '_index': 'index-name',
- '_id': 42,
- '_routing': 5,
- 'pipeline': 'my-ingest-pipeline',
- '_source': {
- "title": "Hello World!",
- "body": "..."
- }
- }
-
-Alternatively, if `_source` is not present, it will pop all metadata fields
-from the doc and use the rest as the document data:
-
-.. code:: python
-
- {
- "_id": 42,
- "_routing": 5,
- "title": "Hello World!",
- "body": "..."
- }
-
-The :meth:`~elasticsearch.Elasticsearch.bulk` api accepts ``index``, ``create``,
-``delete``, and ``update`` actions. Use the ``_op_type`` field to specify an
-action (``_op_type`` defaults to ``index``):
-
-.. code:: python
-
- {
- '_op_type': 'delete',
- '_index': 'index-name',
- '_id': 42,
- }
- {
- '_op_type': 'update',
- '_index': 'index-name',
- '_id': 42,
- 'doc': {'question': 'The life, universe and everything.'}
- }
-
-
-Example:
-~~~~~~~~
-
-Lets say we have an iterable of data. Lets say a list of words called ``mywords``
-and we want to index those words into individual documents where the structure of the
-document is like ``{"word": ""}``.
-
-.. code:: python
-
- from elasticsearch.helpers import bulk
-
- def gendata():
- mywords = ['foo', 'bar', 'baz']
- for word in mywords:
- yield {
- "_index": "mywords",
- "word": word,
- }
-
- bulk(client, gendata())
-
-
-For a more complete and complex example please take a look at
-https://github.com/elastic/elasticsearch-py/blob/main/examples/bulk-ingest
-
-The :meth:`~elasticsearch.Elasticsearch.parallel_bulk` api is a wrapper around the :meth:`~elasticsearch.Elasticsearch.bulk` api to provide threading. :meth:`~elasticsearch.Elasticsearch.parallel_bulk` returns a generator which must be consumed to produce results.
-
-To see the results use:
-
-.. code:: python
-
- for success, info in parallel_bulk(...):
- if not success:
- print('A document failed:', info)
-
-If you don't care about the results, you can use deque from collections:
-
-.. code:: python
-
- from collections import deque
- deque(parallel_bulk(...), maxlen=0)
-
-.. note::
-
- When reading raw json strings from a file, you can also pass them in
- directly (without decoding to dicts first). In that case, however, you lose
- the ability to specify anything (index, op_type and even id) on a per-record
- basis, all documents will just be sent to elasticsearch to be indexed
- as-is.
-
-
-.. py:module:: elasticsearch.helpers
-
-.. autofunction:: streaming_bulk
-
-.. autofunction:: parallel_bulk
-
-.. autofunction:: bulk
-
-
-Scan
-----
-
-.. autofunction:: scan
-
-
-Reindex
--------
-
-.. autofunction:: reindex
diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst
index 70ab257d3..afbdf0aef 100644
--- a/docs/sphinx/index.rst
+++ b/docs/sphinx/index.rst
@@ -1,140 +1,29 @@
Python Elasticsearch Client
===========================
-Official low-level client for Elasticsearch. Its goal is to provide common
-ground for all Elasticsearch-related code in Python; because of this it tries
-to be opinion-free and very extendable.
+Welcome to the API documentation of the official Python client for Elasticsearch!
+The goal of this client is to provide common ground for all Elasticsearch-related
+code in Python; because of this it tries to be opinion-free and very extendable.
-`Download the latest version of Elasticsearch `_
-or
-`sign-up `_
-for a free trial of Elastic Cloud.
-
-
-Installation
-------------
-
-Install the ``elasticsearch`` package with `pip
-`_:
-
-.. code-block:: console
-
- $ python -m pip install elasticsearch
-
-If your application uses async/await in Python you can install with
-the ``async`` extra:
-
-.. code-block:: console
-
- $ python -m pip install elasticsearch[async]
-
-Read more about `how to use asyncio with this project `_.
-
-
-Compatibility
--------------
-
-Language clients are forward compatible; meaning that the clients support
-communicating with greater or equal minor versions of Elasticsearch without
-breaking. It does not mean that the clients automatically support new features
-of newer Elasticsearch versions; it is only possible after a release of a new
-client version. For example, a 8.12 client version won't automatically support
-the new features of the 8.13 version of Elasticsearch, the 8.13 client version
-is required for that. Elasticsearch language clients are only backwards
-compatible with default distributions and without guarantees made.
-
-+-----------------------+-------------------------+-----------+
-| Elasticsearch version | elasticsearch-py branch | Supported |
-+=======================+=========================+===========+
-| main | main | |
-+-----------------------+-------------------------+-----------+
-| 8.x | 8.x | 8.x |
-+-----------------------+-------------------------+-----------+
-| 7.x | 7.x | 7.17 |
-+-----------------------+-------------------------+-----------+
-
-If you need multiple versions installed at the same time, versions are
-also released, such as ``elasticsearch7`` and ``elasticsearch8``.
-
-
-Example Usage
--------------
-
-.. code-block:: python
-
- from datetime import datetime
- from elasticsearch import Elasticsearch
-
- client = Elasticsearch("http://localhost:9200/", api_key="YOUR_API_KEY")
-
- doc = {
- "author": "kimchy",
- "text": "Elasticsearch: cool. bonsai cool.",
- "timestamp": datetime.now(),
- }
- resp = client.index(index="test-index", id=1, document=doc)
- print(resp["result"])
-
- resp = client.get(index="test-index", id=1)
- print(resp["_source"])
-
- client.indices.refresh(index="test-index")
-
- resp = client.search(index="test-index", query={"match_all": {}})
- print("Got {} hits:".format(resp["hits"]["total"]["value"]))
- for hit in resp["hits"]["hits"]:
- print("{timestamp} {author} {text}".format(**hit["_source"]))
-
-See more examples in the :ref:`quickstart` page.
-
-
-
-Features
---------
-
-This client was designed as very thin wrapper around Elasticsearch's REST API to
-allow for maximum flexibility. This means that there are no opinions in this
-client; it also means that some of the APIs are a little cumbersome to use from
-Python. We have created some :ref:`helpers` to help with this issue as well as
-a more high level library (`elasticsearch-dsl`_) on top of this one to provide
-a more convenient way of working with Elasticsearch.
-
-
-
-Elasticsearch-DSL
------------------
-
-For a more high level client library with more limited scope, have a look at
-`elasticsearch-dsl`_ - a more pythonic library sitting on top of
-``elasticsearch-py``.
-
-`elasticsearch-dsl`_ provides a more convenient and idiomatic way to write and manipulate
-`queries`_ by mirroring the terminology and structure of Elasticsearch JSON DSL
-while exposing the whole range of the DSL from Python
-either directly using defined classes or a queryset-like expressions.
-
-It also provides an optional `persistence layer`_ for working with documents as
-Python objects in an ORM-like fashion: defining mappings, retrieving and saving
-documents, wrapping the document data in user-defined classes.
-
-.. _elasticsearch-dsl: https://elasticsearch-dsl.readthedocs.io/
-.. _queries: https://elasticsearch-dsl.readthedocs.io/en/latest/search_dsl.html
-.. _persistence layer: https://elasticsearch-dsl.readthedocs.io/en/latest/persistence.html#doctype
+High-level documentation for this client is `also available `_.
+.. toctree::
+ :maxdepth: 2
-Contents
---------
+ es_api
+ esql
+ dsl
+ api_helpers
+ exceptions
.. toctree::
- :maxdepth: 3
+ :caption: Async
+ :maxdepth: 2
+
+ async_es_api
+ async_dsl
+ async_api_helpers
- quickstart
- interactive
- api
- exceptions
- async
- helpers
- Release Notes
License
-------
diff --git a/docs/sphinx/interactive.rst b/docs/sphinx/interactive.rst
deleted file mode 100644
index 257d2aad1..000000000
--- a/docs/sphinx/interactive.rst
+++ /dev/null
@@ -1,107 +0,0 @@
-.. _interactive:
-
-Interactive examples
-====================
-
-The `elasticsearch-labs `_ repo contains interactive and executable `Python notebooks `_, sample apps, and resources for testing out Elasticsearch, using the Python client.
-These examples are mainly focused on vector search, hybrid search and generative AI use cases, but you'll also find examples of basic operations like creating index mappings and performing lexical search.
-
-Search notebooks
-----------------
-
-The `Search `_ folder is a good place to start if you're new to Elasticsearch.
-This folder contains a number of notebooks that demonstrate the fundamentals of Elasticsearch, like indexing vectors, running lexical, semantic and *hybrid* searches, and more.
-
-The following notebooks are available:
-
-0. `Quick start `_
-1. `Keyword, querying, filtering `_
-2. `Hybrid search `_
-3. `Semantic search with ELSER `_
-4. `Multilingual semantic search `_
-5. `Query rules `_
-6. `Synonyms API quick start `_
-
-Here's a brief overview of what you'll learn in each notebook.
-
-Quick start
-^^^^^^^^^^^
-
-In the `00-quick-start.ipynb `_ notebook you'll learn how to:
-
-- Use the Elasticsearch Python client for various operations.
-- Create and define an index for a sample dataset with ``dense_vector`` fields.
-- Transform book titles into embeddings using `Sentence Transformers `_ and index them into Elasticsearch.
-- Perform k-nearest neighbors (knn) semantic searches.
-- Integrate traditional text-based search with semantic search, for a hybrid search system.
-- Use reciprocal rank fusion (RRF) to intelligently combine search results from different retrieval systems.
-
-Keyword, querying, filtering
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In the `01-keyword-querying-filtering.ipynb `_ notebook, you'll learn how to:
-
-- Use `query and filter contexts `_ to search and filter documents in Elasticsearch.
-- Execute full-text searches with ``match`` and ``multi-match`` queries.
-- Query and filter documents based on ``text``, ``number``, ``date``, or ``boolean`` values.
-- Run multi-field searches using the ``multi-match`` query.
-- Prioritize specific fields in the ``multi-match`` query for tailored results.
-
-Hybrid search
-^^^^^^^^^^^^^
-
-In the `02-hybrid-search.ipynb `_ notebook, you'll learn how to:
-
-- Combine results of traditional text-based search with semantic search, for a hybrid search system.
-- Transform fields in the sample dataset into embeddings using the Sentence Transformer model and index them into Elasticsearch.
-- Use the `RRF API `_ to combine the results of a ``match`` query and a ``kNN`` semantic search.
-- Walk through a super simple toy example that demonstrates, step by step, how RRF ranking works.
-
-Semantic search with ELSER
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In the `03-ELSER.ipynb `_ notebook, you'll learn how to:
-
-- Use the Elastic Learned Sparse Encoder (ELSER) for text expansion-powered semantic search, out of the box — without training, fine-tuning, or embeddings generation.
-- Download and deploy the ELSER model in your Elastic environment.
-- Create an Elasticsearch index named `search-movies` with specific mappings and index a dataset of movie descriptions.
-- Create an ingest pipeline containing an inference processor for ELSER model execution.
-- Reindex the data from `search-movies` into another index, `elser-movies`, using the ELSER pipeline for text expansion.
-- Observe the results of running the documents through the model by inspecting the additional terms it adds to documents, which enhance searchability.
-- Perform simple keyword searches on the `elser-movies` index to assess the impact of ELSER's text expansion.
-- Execute ELSER-powered semantic searches using the ``text_expansion`` query.
-
-Multilingual semantic search
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In the `04-multilingual.ipynb `_ notebook, you'll learn how to:
-
-- Use a multilingual embedding model for semantic search across languages.
-- Transform fields in the sample dataset into embeddings using the Sentence Transformer model and index them into Elasticsearch.
-- Use filtering with a ``kNN`` semantic search.
-- Walk through a super simple toy example that demonstrates, step by step, how multilingual search works across languages, and within non-English languages.
-
-Query rules
-^^^^^^^^^^^
-
-In the `05-query-rules.ipynb `_ notebook, you'll learn how to:
-
-- Use the query rules management APIs to create and edit promotional rules based on contextual queries.
-- Apply these query rules by using the ``rule_query`` in Query DSL.
-
-Synonyms API quick start
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-In the `06-synonyms-api.ipynb `_ notebook, you'll learn how to:
-
-- Use the synonyms management API to create a synonyms set to enhance your search recall.
-- Configure an index to use search-time synonyms.
-- Update synonyms in real time.
-- Run queries that are enhanced by synonyms.
-
-Other notebooks
----------------
-
-- `Generative AI `_. Notebooks that demonstrate various use cases for Elasticsearch as the retrieval engine and vector store for LLM-powered applications.
-- `Integrations `_. Notebooks that demonstrate how to integrate popular services and projects with Elasticsearch, including OpenAI, Hugging Face, and LlamaIndex
-- `Langchain `_. Notebooks that demonstrate how to integrate Elastic with LangChain, a framework for developing applications powered by language models.
diff --git a/docs/sphinx/quickstart.rst b/docs/sphinx/quickstart.rst
deleted file mode 100644
index f7e527858..000000000
--- a/docs/sphinx/quickstart.rst
+++ /dev/null
@@ -1,167 +0,0 @@
-.. _quickstart:
-
-Quickstart
-==========
-
-This guide shows you how to install the Elasticsearch Python client and perform basic
-operations like indexing or searching documents.
-
-Requirements
-------------
-
-- `Python `_ 3.8 or newer
-- `pip `_
-
-
-Installation
-------------
-
-To install the client, run the following command:
-
-.. code-block:: console
-
- $ python -m pip install elasticsearch
-
-
-Connecting
-----------
-
-You can connect to Elastic Cloud using an API key and the Cloud ID.
-
-.. code-block:: python
-
- from elasticsearch import Elasticsearch
-
- client = Elasticsearch(cloud_id="YOUR_CLOUD_ID", api_key="YOUR_API_KEY")
-
-Your Cloud ID can be found on the **My deployment** page of your deployment
-under **Cloud ID**.
-
-You can generate an API key on the **Management** page under Security.
-
-.. image:: _static/images/create-api-key.png
-
-Confirm that the connection was successful.
-
-.. code-block:: python
-
- print(client.info())
-
-Using the client
-----------------
-
-Time to use Elasticsearch! This section walks you through the most important
-operations of Elasticsearch. The following examples assume that the Python
-client was instantiated as above.
-
-Create an index with mappings
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is how you create the `my_index` index.
-Optionally, you can first define the expected types of your features with a custom mapping.
-
-.. code-block:: python
-
- mappings = {
- "properties": {
- "foo": {"type": "text"},
- "bar": {
- "type": "text",
- "fields": {
- "keyword": {
- "type": "keyword",
- "ignore_above": 256,
- }
- },
- },
- }
- }
-
- client.indices.create(index="my_index", mappings=mappings)
-
-Indexing documents
-^^^^^^^^^^^^^^^^^^
-
-This indexes a document with the index API:
-
-.. code-block:: python
-
- client.index(
- index="my_index",
- id="my_document_id",
- document={
- "foo": "foo",
- "bar": "bar",
- },
- )
-
-You can also index multiple documents at once with the bulk helper function:
-
-.. code-block:: python
-
- from elasticsearch import helpers
-
- def generate_docs():
- for i in range(10):
- yield {
- "_index": "my_index",
- "foo": f"foo {i}",
- "bar": "bar",
- }
-
- helpers.bulk(client, generate_docs())
-
-These helpers are the recommended way to perform bulk ingestion. While it is also possible to perform bulk ingestion using ``client.bulk`` directly, the helpers handle retries, ingesting chunk by chunk and more. See the :ref:`helpers` page for more details.
-
-Getting documents
-^^^^^^^^^^^^^^^^^
-
-You can get documents by using the following code:
-
-.. code-block:: python
-
- client.get(index="my_index", id="my_document_id")
-
-
-Searching documents
-^^^^^^^^^^^^^^^^^^^
-
-This is how you can create a single match query with the Python client:
-
-
-.. code-block:: python
-
- client.search(index="my_index", query={"match": {"foo": {"query": "foo"}}})
-
-
-Updating documents
-^^^^^^^^^^^^^^^^^^
-
-This is how you can update a document, for example to add a new field:
-
-.. code-block:: python
-
- client.update(
- index="my_index",
- id="my_document_id",
- doc={
- "foo": "bar",
- "new_field": "new value",
- },
- )
-
-
-Deleting documents
-^^^^^^^^^^^^^^^^^^
-
-.. code-block:: python
-
- client.delete(index="my_index", id="my_document_id")
-
-
-Deleting an index
-^^^^^^^^^^^^^^^^^
-
-.. code-block:: python
-
- client.indices.delete(index="my_index")
diff --git a/elasticsearch/_async/client/__init__.py b/elasticsearch/_async/client/__init__.py
index 98d006405..69b2ad886 100644
--- a/elasticsearch/_async/client/__init__.py
+++ b/elasticsearch/_async/client/__init__.py
@@ -18,7 +18,6 @@
import logging
import typing as t
-import warnings
from elastic_transport import (
AsyncTransport,
@@ -181,37 +180,13 @@ def __init__(
t.Callable[[t.Dict[str, t.Any], NodeConfig], t.Optional[NodeConfig]]
] = None,
meta_header: t.Union[DefaultType, bool] = DEFAULT,
- timeout: t.Union[DefaultType, None, float] = DEFAULT,
- randomize_hosts: t.Union[DefaultType, bool] = DEFAULT,
- host_info_callback: t.Optional[
- t.Callable[
- [t.Dict[str, t.Any], t.Dict[str, t.Union[str, int]]],
- t.Optional[t.Dict[str, t.Union[str, int]]],
- ]
- ] = None,
- sniffer_timeout: t.Union[DefaultType, None, float] = DEFAULT,
- sniff_on_connection_fail: t.Union[DefaultType, bool] = DEFAULT,
http_auth: t.Union[DefaultType, t.Any] = DEFAULT,
- maxsize: t.Union[DefaultType, int] = DEFAULT,
# Internal use only
_transport: t.Optional[AsyncTransport] = None,
) -> None:
if hosts is None and cloud_id is None and _transport is None:
raise ValueError("Either 'hosts' or 'cloud_id' must be specified")
- if timeout is not DEFAULT:
- if request_timeout is not DEFAULT:
- raise ValueError(
- "Can't specify both 'timeout' and 'request_timeout', "
- "instead only specify 'request_timeout'"
- )
- warnings.warn(
- "The 'timeout' parameter is deprecated in favor of 'request_timeout'",
- category=DeprecationWarning,
- stacklevel=2,
- )
- request_timeout = timeout
-
if serializer is not None:
if serializers is not DEFAULT:
raise ValueError(
@@ -220,58 +195,6 @@ def __init__(
)
serializers = {default_mimetype: serializer}
- if randomize_hosts is not DEFAULT:
- if randomize_nodes_in_pool is not DEFAULT:
- raise ValueError(
- "Can't specify both 'randomize_hosts' and 'randomize_nodes_in_pool', "
- "instead only specify 'randomize_nodes_in_pool'"
- )
- warnings.warn(
- "The 'randomize_hosts' parameter is deprecated in favor of 'randomize_nodes_in_pool'",
- category=DeprecationWarning,
- stacklevel=2,
- )
- randomize_nodes_in_pool = randomize_hosts
-
- if sniffer_timeout is not DEFAULT:
- if min_delay_between_sniffing is not DEFAULT:
- raise ValueError(
- "Can't specify both 'sniffer_timeout' and 'min_delay_between_sniffing', "
- "instead only specify 'min_delay_between_sniffing'"
- )
- warnings.warn(
- "The 'sniffer_timeout' parameter is deprecated in favor of 'min_delay_between_sniffing'",
- category=DeprecationWarning,
- stacklevel=2,
- )
- min_delay_between_sniffing = sniffer_timeout
-
- if sniff_on_connection_fail is not DEFAULT:
- if sniff_on_node_failure is not DEFAULT:
- raise ValueError(
- "Can't specify both 'sniff_on_connection_fail' and 'sniff_on_node_failure', "
- "instead only specify 'sniff_on_node_failure'"
- )
- warnings.warn(
- "The 'sniff_on_connection_fail' parameter is deprecated in favor of 'sniff_on_node_failure'",
- category=DeprecationWarning,
- stacklevel=2,
- )
- sniff_on_node_failure = sniff_on_connection_fail
-
- if maxsize is not DEFAULT:
- if connections_per_node is not DEFAULT:
- raise ValueError(
- "Can't specify both 'maxsize' and 'connections_per_node', "
- "instead only specify 'connections_per_node'"
- )
- warnings.warn(
- "The 'maxsize' parameter is deprecated in favor of 'connections_per_node'",
- category=DeprecationWarning,
- stacklevel=2,
- )
- connections_per_node = maxsize
-
# Setting min_delay_between_sniffing=True implies sniff_before_requests=True
if min_delay_between_sniffing is not DEFAULT:
sniff_before_requests = True
@@ -293,22 +216,7 @@ def __init__(
)
sniff_callback = None
- if host_info_callback is not None:
- if sniffed_node_callback is not None:
- raise ValueError(
- "Can't specify both 'host_info_callback' and 'sniffed_node_callback', "
- "instead only specify 'sniffed_node_callback'"
- )
- warnings.warn(
- "The 'host_info_callback' parameter is deprecated in favor of 'sniffed_node_callback'",
- category=DeprecationWarning,
- stacklevel=2,
- )
-
- sniff_callback = create_sniff_callback(
- host_info_callback=host_info_callback
- )
- elif sniffed_node_callback is not None:
+ if sniffed_node_callback is not None:
sniff_callback = create_sniff_callback(
sniffed_node_callback=sniffed_node_callback
)
@@ -700,6 +608,7 @@ async def bulk(
JavaScript: Check out client.helpers.*
.NET: Check out BulkAllObservable
PHP: Check out bulk indexing.
+
Ruby: Check out Elasticsearch::Helpers::BulkHelper
Submitting bulk requests with cURL
If you're providing text file input to curl, you must use the --data-binary flag instead of plain -d.
@@ -729,9 +638,11 @@ async def bulk(
Imagine a _bulk?refresh=wait_for request with three documents in it that happen to be routed to different shards in an index with five shards.
The request will only wait for those three shards to refresh.
The other two shards that make up the index do not participate in the _bulk request at all.
+
You might want to disable the refresh interval temporarily to improve indexing throughput for large bulk requests.
+ Refer to the linked documentation for step-by-step instructions using the index settings API.
- ``_
+ ``_
:param operations:
:param index: The name of the data stream, index, or index alias to perform bulk
@@ -856,7 +767,7 @@ async def clear_scroll(
Clear the search context and results for a scrolling search.
- ``_
+ ``_
:param scroll_id: The scroll IDs to clear. To clear all scroll IDs, use `_all`.
"""
@@ -913,7 +824,7 @@ async def close_point_in_time(
However, keeping points in time has a cost; close them as soon as they are no longer required for search requests.
- ``_
+ ``_
:param id: The ID of the point-in-time.
"""
@@ -997,7 +908,7 @@ async def count(
This means that replicas increase the scalability of the count.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases to
search. It supports wildcards (`*`). To search all data streams and indices,
@@ -1127,6 +1038,8 @@ async def create(
refresh: t.Optional[
t.Union[bool, str, t.Literal["false", "true", "wait_for"]]
] = None,
+ require_alias: t.Optional[bool] = None,
+ require_data_stream: t.Optional[bool] = None,
routing: t.Optional[str] = None,
timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
version: t.Optional[int] = None,
@@ -1194,7 +1107,7 @@ async def create(
The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.
- ``_
+ ``_
:param index: The name of the data stream or index to target. If the target doesn't
exist and matches the name or wildcard (`*`) pattern of an index template
@@ -1214,6 +1127,9 @@ async def create(
:param refresh: If `true`, Elasticsearch refreshes the affected shards to make
this operation visible to search. If `wait_for`, it waits for a refresh to
make this operation visible to search. If `false`, it does nothing with refreshes.
+ :param require_alias: If `true`, the destination must be an index alias.
+ :param require_data_stream: If `true`, the request's actions must target a data
+ stream (existing or to be created).
:param routing: A custom value that is used to route operations to a specific
shard.
:param timeout: The period the request waits for the following operations: automatic
@@ -1262,6 +1178,10 @@ async def create(
__query["pretty"] = pretty
if refresh is not None:
__query["refresh"] = refresh
+ if require_alias is not None:
+ __query["require_alias"] = require_alias
+ if require_data_stream is not None:
+ __query["require_data_stream"] = require_data_stream
if routing is not None:
__query["routing"] = routing
if timeout is not None:
@@ -1338,7 +1258,7 @@ async def delete(
It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.
- ``_
+ ``_
:param index: The name of the target index.
:param id: A unique identifier for the document.
@@ -1407,7 +1327,7 @@ async def delete(
)
@_rewrite_parameters(
- body_fields=("max_docs", "query", "slice"),
+ body_fields=("max_docs", "query", "slice", "sort"),
parameter_aliases={"from": "from_"},
)
async def delete_by_query(
@@ -1451,7 +1371,12 @@ async def delete_by_query(
] = None,
slice: t.Optional[t.Mapping[str, t.Any]] = None,
slices: t.Optional[t.Union[int, t.Union[str, t.Literal["auto"]]]] = None,
- sort: t.Optional[t.Sequence[str]] = None,
+ sort: t.Optional[
+ t.Union[
+ t.Sequence[t.Union[str, t.Mapping[str, t.Any]]],
+ t.Union[str, t.Mapping[str, t.Any]],
+ ]
+ ] = None,
stats: t.Optional[t.Sequence[str]] = None,
terminate_after: t.Optional[int] = None,
timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
@@ -1527,7 +1452,7 @@ async def delete_by_query(
The get task status API will continue to list the delete by query task until this task checks that it has been cancelled and terminates itself.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases to
search. It supports wildcards (`*`). To search all data streams or indices,
@@ -1553,7 +1478,7 @@ async def delete_by_query(
If the request can target data streams, this argument determines whether
wildcard expressions match hidden data streams. It supports comma-separated
values, such as `open,hidden`.
- :param from_: Starting offset (default: 0)
+ :param from_: Skips the specified number of documents.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
:param lenient: If `true`, format-based query failures (such as providing text
@@ -1583,7 +1508,7 @@ async def delete_by_query(
:param slice: Slice the request manually using the provided slice ID and total
number of slices.
:param slices: The number of slices this task should be divided into.
- :param sort: A comma-separated list of `:` pairs.
+ :param sort: A sort object that specifies the order of deleted documents.
:param stats: The specific `tag` of the request for logging and statistical purposes.
:param terminate_after: The maximum number of documents to collect for each shard.
If a query reaches this limit, Elasticsearch terminates the query early.
@@ -1673,8 +1598,6 @@ async def delete_by_query(
__query["search_type"] = search_type
if slices is not None:
__query["slices"] = slices
- if sort is not None:
- __query["sort"] = sort
if stats is not None:
__query["stats"] = stats
if terminate_after is not None:
@@ -1694,6 +1617,8 @@ async def delete_by_query(
__body["query"] = query
if slice is not None:
__body["slice"] = slice
+ if sort is not None:
+ __body["sort"] = sort
__headers = {"accept": "application/json", "content-type": "application/json"}
return await self.perform_request( # type: ignore[return-value]
"POST",
@@ -1724,7 +1649,7 @@ async def delete_by_query_rethrottle(
Rethrottling that speeds up the query takes effect immediately but rethrotting that slows down the query takes effect after completing the current batch to prevent scroll timeouts.
- ``_
+ ``_
:param task_id: The ID for the task.
:param requests_per_second: The throttle for this request in sub-requests per
@@ -1774,7 +1699,7 @@ async def delete_script(
Deletes a stored script or search template.
- ``_
+ ``_
:param id: The identifier for the stored script or search template.
:param master_timeout: The period to wait for a connection to the master node.
@@ -1858,7 +1783,7 @@ async def exists(
Elasticsearch cleans up deleted documents in the background as you continue to index more data.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases. It
supports wildcards (`*`).
@@ -1981,7 +1906,7 @@ async def exists_source(
A document's source is not available if it is disabled in the mapping.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases. It
supports wildcards (`*`).
@@ -2087,7 +2012,7 @@ async def explain(
It computes a score explanation for a query and a specific document.
- ``_
+ ``_
:param index: Index names that are used to limit the request. Only a single index
name can be provided to this parameter.
@@ -2222,7 +2147,7 @@ async def field_caps(
For example, a runtime field with a type of keyword is returned the same as any other field that belongs to the keyword family.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases used
to limit the request. Supports wildcards (*). To target all data streams
@@ -2383,12 +2308,12 @@ async def get(
Elasticsearch cleans up deleted documents in the background as you continue to index more data.
- ``_
+ ``_
:param index: The name of the index that contains the document.
:param id: A unique document identifier.
:param force_synthetic_source: Indicates whether the request forces synthetic
- `_source`. Use this paramater to test if the mapping supports synthetic `_source`
+ `_source`. Use this parameter to test if the mapping supports synthetic `_source`
and to get a sense of the worst case performance. Fetches with this parameter
enabled will be slower than enabling synthetic source natively in the index.
:param preference: The node or shard the operation should be performed on. By
@@ -2419,8 +2344,8 @@ async def get(
:param stored_fields: A comma-separated list of stored fields to return as part
of a hit. If no fields are specified, no stored fields are included in the
response. If this field is specified, the `_source` parameter defaults to
- `false`. Only leaf fields can be retrieved with the `stored_field` option.
- Object fields can't be returned;if specified, the request fails.
+ `false`. Only leaf fields can be retrieved with the `stored_fields` option.
+ Object fields can't be returned; if specified, the request fails.
:param version: The version number for concurrency control. It must match the
current version of the document for the request to succeed.
:param version_type: The version type.
@@ -2490,7 +2415,7 @@ async def get_script(
Retrieves a stored script or search template.
- ``_
+ ``_
:param id: The identifier for the stored script or search template.
:param master_timeout: The period to wait for the master node. If the master
@@ -2539,7 +2464,7 @@ async def get_script_context(
Get a list of supported script contexts and their methods.
Get a list of available script types, languages, and contexts.
- ``_
+ ``_
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_script_language"
@@ -2624,7 +2549,6 @@ async def get_source(
source: t.Optional[t.Union[bool, t.Union[str, t.Sequence[str]]]] = None,
source_excludes: t.Optional[t.Union[str, t.Sequence[str]]] = None,
source_includes: t.Optional[t.Union[str, t.Sequence[str]]] = None,
- stored_fields: t.Optional[t.Union[str, t.Sequence[str]]] = None,
version: t.Optional[int] = None,
version_type: t.Optional[
t.Union[str, t.Literal["external", "external_gte", "force", "internal"]]
@@ -2643,7 +2567,7 @@ async def get_source(
- ``_
+ ``_
:param index: The name of the index that contains the document.
:param id: A unique document identifier.
@@ -2661,8 +2585,6 @@ async def get_source(
the response.
:param source_includes: A comma-separated list of source fields to include in
the response.
- :param stored_fields: A comma-separated list of stored fields to return as part
- of a hit.
:param version: The version number for concurrency control. It must match the
current version of the document for the request to succeed.
:param version_type: The version type.
@@ -2696,8 +2618,6 @@ async def get_source(
__query["_source_excludes"] = source_excludes
if source_includes is not None:
__query["_source_includes"] = source_includes
- if stored_fields is not None:
- __query["stored_fields"] = stored_fields
if version is not None:
__query["version"] = version
if version_type is not None:
@@ -2743,7 +2663,7 @@ async def health_report(
When setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.
- ``_
+ ``_
:param feature: A feature of the cluster, as returned by the top-level health
report API.
@@ -2806,6 +2726,7 @@ async def index(
t.Union[bool, str, t.Literal["false", "true", "wait_for"]]
] = None,
require_alias: t.Optional[bool] = None,
+ require_data_stream: t.Optional[bool] = None,
routing: t.Optional[str] = None,
timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
version: t.Optional[int] = None,
@@ -2908,7 +2829,7 @@ async def index(
- ``_
+ ``_
:param index: The name of the data stream or index to target. If the target doesn't
exist and matches the name or wildcard (`*`) pattern of an index template
@@ -2941,6 +2862,8 @@ async def index(
this operation visible to search. If `wait_for`, it waits for a refresh to
make this operation visible to search. If `false`, it does nothing with refreshes.
:param require_alias: If `true`, the destination must be an index alias.
+ :param require_data_stream: If `true`, the request's actions must target a data
+ stream (existing or to be created).
:param routing: A custom value that is used to route operations to a specific
shard.
:param timeout: The period the request waits for the following operations: automatic
@@ -3002,6 +2925,8 @@ async def index(
__query["refresh"] = refresh
if require_alias is not None:
__query["require_alias"] = require_alias
+ if require_data_stream is not None:
+ __query["require_data_stream"] = require_data_stream
if routing is not None:
__query["routing"] = routing
if timeout is not None:
@@ -3037,10 +2962,11 @@ async def info(
.. raw:: html
Get cluster info.
- Get basic build, version, and cluster information.
NOTE: The kNN search API has been replaced by the knn option in the search API.
-
Perform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.
- Given a query vector, the API finds the k closest vectors and returns those documents as search hits.
-
Elasticsearch uses the HNSW algorithm to support efficient kNN search.
- Like most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.
- This means the results returned are not always the true k closest neighbors.
-
The kNN search API supports restricting the search using a filter.
- The search will return the top k documents that also match the filter query.
-
A kNN search response has the exact same structure as a search API response.
- However, certain sections have a meaning specific to kNN search:
-
-
The document _score is determined by the similarity between the query and document vector.
-
The hits.total object contains the total number of nearest neighbor candidates considered, which is num_candidates * num_shards. The hits.total.relation will always be eq, indicating an exact value.
-
-
-
- ``_
-
- :param index: A comma-separated list of index names to search; use `_all` or
- to perform the operation on all indices.
- :param knn: The kNN query to run.
- :param docvalue_fields: The request returns doc values for field names matching
- these patterns in the `hits.fields` property of the response. It accepts
- wildcard (`*`) patterns.
- :param fields: The request returns values for field names matching these patterns
- in the `hits.fields` property of the response. It accepts wildcard (`*`)
- patterns.
- :param filter: A query to filter the documents that can match. The kNN search
- will return the top `k` documents that also match this filter. The value
- can be a single query or a list of queries. If `filter` isn't provided, all
- documents are allowed to match.
- :param routing: A comma-separated list of specific routing values.
- :param source: Indicates which source fields are returned for matching documents.
- These fields are returned in the `hits._source` property of the search response.
- :param stored_fields: A list of stored fields to return as part of a hit. If
- no fields are specified, no stored fields are included in the response. If
- this field is specified, the `_source` parameter defaults to `false`. You
- can pass `_source: true` to return both source fields and stored fields in
- the search response.
- """
- if index in SKIP_IN_PATH:
- raise ValueError("Empty value passed for parameter 'index'")
- if knn is None and body is None:
- raise ValueError("Empty value passed for parameter 'knn'")
- __path_parts: t.Dict[str, str] = {"index": _quote(index)}
- __path = f'/{__path_parts["index"]}/_knn_search'
- __query: t.Dict[str, t.Any] = {}
- __body: t.Dict[str, t.Any] = body if body is not None else {}
- if error_trace is not None:
- __query["error_trace"] = error_trace
- if filter_path is not None:
- __query["filter_path"] = filter_path
- if human is not None:
- __query["human"] = human
- if pretty is not None:
- __query["pretty"] = pretty
- if routing is not None:
- __query["routing"] = routing
- if not __body:
- if knn is not None:
- __body["knn"] = knn
- if docvalue_fields is not None:
- __body["docvalue_fields"] = docvalue_fields
- if fields is not None:
- __body["fields"] = fields
- if filter is not None:
- __body["filter"] = filter
- if source is not None:
- __body["_source"] = source
- if stored_fields is not None:
- __body["stored_fields"] = stored_fields
- if not __body:
- __body = None # type: ignore[assignment]
- __headers = {"accept": "application/json"}
- if __body is not None:
- __headers["content-type"] = "application/json"
- return await self.perform_request( # type: ignore[return-value]
- "POST",
- __path,
- params=__query,
- headers=__headers,
- body=__body,
- endpoint_id="knn_search",
- path_parts=__path_parts,
- )
-
@_rewrite_parameters(
body_fields=("docs", "ids"),
parameter_aliases={
@@ -3230,7 +3035,7 @@ async def mget(
You can include the stored_fields query parameter in the request URI to specify the defaults to use when there are no per-document instructions.
- ``_
+ ``_
:param index: Name of the index to retrieve documents from when `ids` are specified,
or when a document in the `docs` array does not specify an index.
@@ -3365,7 +3170,7 @@ async def msearch(
When sending requests to this endpoint the Content-Type header should be set to application/x-ndjson.
- ``_
+ ``_
:param searches:
:param index: Comma-separated list of data streams, indices, and index aliases
@@ -3392,7 +3197,8 @@ async def msearch(
computationally expensive named queries on a large number of hits may add
significant overhead.
:param max_concurrent_searches: Maximum number of concurrent searches the multi
- search API can execute.
+ search API can execute. Defaults to `max(1, (# of data nodes * min(search
+ thread pool size, 10)))`.
:param max_concurrent_shard_requests: Maximum number of concurrent shard requests
that each sub-search request executes per node.
:param pre_filter_shard_size: Defines a threshold that enforces a pre-filter
@@ -3511,7 +3317,7 @@ async def msearch_template(
- ``_
+ ``_
:param search_templates:
:param index: A comma-separated list of data streams, indices, and aliases to
@@ -3616,7 +3422,7 @@ async def mtermvectors(
The mapping used is determined by the specified _index.
- ``_
+ ``_
:param index: The name of the index that contains the documents.
:param docs: An array of existing or artificial documents.
@@ -3720,6 +3526,7 @@ async def open_point_in_time(
human: t.Optional[bool] = None,
ignore_unavailable: t.Optional[bool] = None,
index_filter: t.Optional[t.Mapping[str, t.Any]] = None,
+ max_concurrent_shard_requests: t.Optional[int] = None,
preference: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
routing: t.Optional[str] = None,
@@ -3756,7 +3563,7 @@ async def open_point_in_time(
You can check how many point-in-times (that is, search contexts) are open with the nodes stats API.
- ``_
+ ``_
:param index: A comma-separated list of index names to open point in time; use
`_all` or empty string to perform the operation on all indices
@@ -3769,12 +3576,13 @@ async def open_point_in_time(
:param expand_wildcards: The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether
wildcard expressions match hidden data streams. It supports comma-separated
- values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`,
- `hidden`, `none`.
+ values, such as `open,hidden`.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
:param index_filter: Filter indices if the provided query rewrites to `match_none`
on every shard.
+ :param max_concurrent_shard_requests: Maximum number of concurrent shard requests
+ that each sub-search request executes per node.
:param preference: The node or shard the operation should be performed on. By
default, it is random.
:param routing: A custom value that is used to route operations to a specific
@@ -3802,6 +3610,8 @@ async def open_point_in_time(
__query["human"] = human
if ignore_unavailable is not None:
__query["ignore_unavailable"] = ignore_unavailable
+ if max_concurrent_shard_requests is not None:
+ __query["max_concurrent_shard_requests"] = max_concurrent_shard_requests
if preference is not None:
__query["preference"] = preference
if pretty is not None:
@@ -3850,7 +3660,7 @@ async def put_script(
Creates or updates a stored script or search template.
- ``_
+ ``_
:param id: The identifier for the stored script or search template. It must be
unique within the cluster.
@@ -3940,7 +3750,7 @@ async def rank_eval(
Evaluate the quality of ranked search results over a set of typical search queries.
- ``_
+ ``_
:param requests: A set of typical search requests, together with their provided
ratings.
@@ -4066,113 +3876,17 @@ async def reindex(
In this case, the response includes a count of the version conflicts that were encountered.
Note that the handling of other error types is unaffected by the conflicts property.
Additionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than max_docs until it has successfully indexed max_docs documents into the target or it has gone through every document in the source query.
-
NOTE: The reindex API makes no effort to handle ID collisions.
- The last document written will "win" but the order isn't usually predictable so it is not a good idea to rely on this behavior.
- Instead, make sure that IDs are unique by using a script.
-
Running reindex asynchronously
-
If the request contains wait_for_completion=false, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task.
- Elasticsearch creates a record of this task as a document at _tasks/<task_id>.
-
Reindex from multiple sources
-
If you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources.
- That way you can resume the process if there are any errors by removing the partially completed source and starting over.
- It also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel.
-
For example, you can use a bash script like this:
-
for index in i1 i2 i3 i4 i5; do
- curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{
- "source": {
- "index": "'$index'"
- },
- "dest": {
- "index": "'$index'-reindexed"
- }
- }'
- done
-
-
Throttling
-
Set requests_per_second to any positive decimal number (1.4, 6, 1000, for example) to throttle the rate at which reindex issues batches of index operations.
- Requests are throttled by padding each batch with a wait time.
- To turn off throttling, set requests_per_second to -1.
-
The throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding.
- The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing.
- By default the batch size is 1000, so if requests_per_second is set to 500:
Since the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set.
- This is "bursty" instead of "smooth".
-
Slicing
-
Reindex supports sliced scroll to parallelize the reindexing process.
- This parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.
-
NOTE: Reindexing from remote clusters does not support manual or automatic slicing.
-
You can slice a reindex request manually by providing a slice ID and total number of slices to each request.
- You can also let reindex automatically parallelize by using sliced scroll to slice on _id.
- The slices parameter specifies the number of slices to use.
-
Adding slices to the reindex request just automates the manual process, creating sub-requests which means it has some quirks:
+
It's recommended to reindex on indices with a green status. Reindexing can fail when a node shuts down or crashes.
-
You can see these requests in the tasks API. These sub-requests are "child" tasks of the task for the request with slices.
-
Fetching the status of the task for the request with slices only contains the status of completed slices.
-
These sub-requests are individually addressable for things like cancellation and rethrottling.
-
Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
-
Canceling the request with slices will cancel each sub-request.
-
Due to the nature of slices, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
-
Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being reindexed.
-
Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time.
+
When requested with wait_for_completion=true (default), the request fails if the node shuts down.
+
When requested with wait_for_completion=false, a task id is returned, for use with the task management APIs. The task may disappear or fail if the node shuts down.
+ When retrying a failed reindex operation, it might be necessary to set conflicts=proceed or to first delete the partial destination index.
+ Additionally, dry runs, checking disk space, and fetching index recovery information can help address the root cause.
-
If slicing automatically, setting slices to auto will choose a reasonable number for most indices.
- If slicing manually or otherwise tuning automatic slicing, use the following guidelines.
-
Query performance is most efficient when the number of slices is equal to the number of shards in the index.
- If that number is large (for example, 500), choose a lower number as too many slices will hurt performance.
- Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
-
Indexing performance scales linearly across available resources with the number of slices.
-
Whether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources.
-
Modify documents during reindexing
-
Like _update_by_query, reindex operations support a script that modifies the document.
- Unlike _update_by_query, the script is allowed to modify the document's metadata.
-
Just as in _update_by_query, you can set ctx.op to change the operation that is run on the destination.
- For example, set ctx.op to noop if your script decides that the document doesn’t have to be indexed in the destination. This "no operation" will be reported in the noop counter in the response body.
- Set ctx.op to delete if your script decides that the document must be deleted from the destination.
- The deletion will be reported in the deleted counter in the response body.
- Setting ctx.op to anything else will return an error, as will setting any other field in ctx.
-
Think of the possibilities! Just be careful; you are able to change:
-
-
_id
-
_index
-
_version
-
_routing
-
-
Setting _version to null or clearing it from the ctx map is just like not sending the version in an indexing request.
- It will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API.
-
Reindex from remote
-
Reindex supports reindexing from a remote Elasticsearch cluster.
- The host parameter must contain a scheme, host, port, and optional path.
- The username and password parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication.
- Be sure to use HTTPS when using basic authentication or the password will be sent in plain text.
- There are a range of settings available to configure the behavior of the HTTPS connection.
-
When using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key.
- Remote hosts must be explicitly allowed with the reindex.remote.whitelist setting.
- It can be set to a comma delimited list of allowed remote host and port combinations.
- Scheme is ignored; only the host and port are used.
- For example:
The list of allowed hosts must be configured on any nodes that will coordinate the reindex.
- This feature should work with remote clusters of any version of Elasticsearch.
- This should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version.
-
WARNING: Elasticsearch does not support forward compatibility across major versions.
- For example, you cannot reindex from a 7.x cluster into a 6.x cluster.
-
To enable queries sent to older versions of Elasticsearch, the query parameter is sent directly to the remote host without validation or modification.
-
NOTE: Reindexing from remote clusters does not support manual or automatic slicing.
-
Reindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb.
- If the remote index includes very large documents you'll need to use a smaller batch size.
- It is also possible to set the socket read timeout on the remote connection with the socket_timeout field and the connection timeout with the connect_timeout field.
- Both default to 30 seconds.
-
Configuring SSL parameters
-
Reindex from remote supports configurable SSL settings.
- These must be specified in the elasticsearch.yml file, with the exception of the secure settings, which you add in the Elasticsearch keystore.
- It is not possible to configure SSL in the body of the reindex request.
-
-
- ``_
+
Refer to the linked documentation for examples of how to reindex documents.
+
+
+ ``_
:param dest: The destination you are copying to.
:param source: The source you are copying from.
@@ -4296,7 +4010,7 @@ async def reindex_rethrottle(
This behavior prevents scroll timeouts.
- ``_
+ ``_
:param task_id: The task identifier, which can be found by using the tasks API.
:param requests_per_second: The throttle for this request in sub-requests per
@@ -4342,7 +4056,7 @@ async def render_search_template(
human: t.Optional[bool] = None,
params: t.Optional[t.Mapping[str, t.Any]] = None,
pretty: t.Optional[bool] = None,
- source: t.Optional[str] = None,
+ source: t.Optional[t.Union[str, t.Mapping[str, t.Any]]] = None,
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
@@ -4352,7 +4066,7 @@ async def render_search_template(
Render a search template as a search request body.
- ``_
+ ``_
:param id: The ID of the search template to render. If no `source` is specified,
this or the `id` request body parameter is required.
@@ -4446,7 +4160,7 @@ async def scripts_painless_execute(
Each context requires a script, but additional parameters depend on the context you're using for that script.
- ``_
+ ``_
:param context: The context that the script should run in. NOTE: Result ordering
in the field contexts is not guaranteed.
@@ -4519,7 +4233,7 @@ async def scroll(
IMPORTANT: Results from a scrolling search reflect the state of the index at the time of the initial search request. Subsequent indexing or document changes only affect later search and scroll requests.
- ``_
+ ``_
:param scroll_id: The scroll ID of the search.
:param rest_total_hits_as_int: If true, the API response’s hit.total property
@@ -4724,7 +4438,7 @@ async def search(
This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases to
search. It supports wildcards (`*`). To search all data streams and indices,
@@ -4803,7 +4517,8 @@ async def search(
limit the impact of the search on the cluster in order to limit the number
of concurrent shard requests.
:param min_score: The minimum `_score` for matching documents. Documents with
- a lower `_score` are not included in the search results.
+ a lower `_score` are not included in search results and results collected
+ by aggregations.
:param pit: Limit the search to a point in time (PIT). If you provide a PIT,
you cannot specify an `` in the request path.
:param post_filter: Use the `post_filter` parameter to filter search results.
@@ -4830,11 +4545,11 @@ async def search(
of the specified nodes are available, select shards from any available node
using the default method. * `_prefer_nodes:,` to if possible,
run the search on the specified nodes IDs. If not, select shards using the
- default method. `_shards:,` to run the search only on the specified
- shards. You can combine this value with other `preference` values. However,
- the `_shards` value must come first. For example: `_shards:2,3|_local`. ``
- (any string that does not start with `_`) to route searches with the same
- `` to the same shards in the same order.
+ default method. * `_shards:,` to run the search only on the
+ specified shards. You can combine this value with other `preference` values.
+ However, the `_shards` value must come first. For example: `_shards:2,3|_local`.
+ * `` (any string that does not start with `_`) to route searches
+ with the same `` to the same shards in the same order.
:param profile: Set to `true` to return detailed timing information about the
execution of individual components in a search request. NOTE: This is a debugging
tool and adds significant overhead to search execution.
@@ -5170,51 +4885,6 @@ async def search_mvt(
Optionally, a geo_bounds aggregation on the <field>. The search only includes this aggregation if the exact_bounds parameter is true.
If the optional parameter with_labels is true, the internal search will include a dynamic runtime field that calls the getLabelPosition function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.
-
For example, Elasticsearch may translate a vector tile search API request with a grid_agg argument of geotile and an exact_bounds argument of true into the following search
The API returns results as a binary Mapbox vector tile.
Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:
@@ -5469,9 +5139,10 @@ async def search_mvt(
Some cells may intersect more than one vector tile.
To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level.
Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density.
+
Learn how to use the vector tile search API with practical examples in the Vector tile search examples guide.
- ``_
+ ``_
:param index: Comma-separated list of data streams, indices, or aliases to search
:param field: Field containing geospatial data to return
@@ -5645,7 +5316,7 @@ async def search_shards(
If the Elasticsearch security features are enabled, you must have the view_index_metadata or manage index privilege for the target data stream, index, or alias.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases to
search. It supports wildcards (`*`). To search all data streams and indices,
@@ -5658,7 +5329,7 @@ async def search_shards(
:param expand_wildcards: Type of index that wildcard patterns can match. If the
request can target data streams, this argument determines whether wildcard
expressions match hidden data streams. Supports comma-separated values, such
- as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.
+ as `open,hidden`.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
:param local: If `true`, the request retrieves information from the local node
@@ -5746,7 +5417,7 @@ async def search_template(
search_type: t.Optional[
t.Union[str, t.Literal["dfs_query_then_fetch", "query_then_fetch"]]
] = None,
- source: t.Optional[str] = None,
+ source: t.Optional[t.Union[str, t.Mapping[str, t.Any]]] = None,
typed_keys: t.Optional[bool] = None,
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
@@ -5756,7 +5427,7 @@ async def search_template(
Run a search with a search template.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases to
search. It supports wildcards (`*`).
@@ -5770,8 +5441,7 @@ async def search_template(
:param expand_wildcards: The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether
wildcard expressions match hidden data streams. Supports comma-separated
- values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`,
- `hidden`, `none`.
+ values, such as `open,hidden`.
:param explain: If `true`, returns detailed information about score calculation
as part of each hit. If you specify both this and the `explain` query parameter,
the API uses only the query parameter.
@@ -5899,7 +5569,7 @@ async def terms_enum(
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and index aliases
to search. Wildcard (`*`) expressions are supported. To search all data streams
@@ -5969,7 +5639,20 @@ async def terms_enum(
)
@_rewrite_parameters(
- body_fields=("doc", "filter", "per_field_analyzer"),
+ body_fields=(
+ "doc",
+ "field_statistics",
+ "fields",
+ "filter",
+ "offsets",
+ "payloads",
+ "per_field_analyzer",
+ "positions",
+ "routing",
+ "term_statistics",
+ "version",
+ "version_type",
+ ),
)
async def termvectors(
self,
@@ -5979,7 +5662,7 @@ async def termvectors(
doc: t.Optional[t.Mapping[str, t.Any]] = None,
error_trace: t.Optional[bool] = None,
field_statistics: t.Optional[bool] = None,
- fields: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ fields: t.Optional[t.Sequence[str]] = None,
filter: t.Optional[t.Mapping[str, t.Any]] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
human: t.Optional[bool] = None,
@@ -6032,10 +5715,11 @@ async def termvectors(
The information is only retrieved for the shard the requested document resides in.
The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context.
By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected.
- Use routing only to hit a particular shard.
+ Use routing only to hit a particular shard.
+ Refer to the linked documentation for detailed examples of how to use this API.
- ``_
+ ``_
:param index: The name of the index that contains the document.
:param id: A unique identifier for the document.
@@ -6046,9 +5730,9 @@ async def termvectors(
(the sum of document frequencies for all terms in this field). * The sum
of total term frequencies (the sum of total term frequencies of each term
in this field).
- :param fields: A comma-separated list or wildcard expressions of fields to include
- in the statistics. It is used as the default list unless a specific field
- list is provided in the `completion_fields` or `fielddata_fields` parameters.
+ :param fields: A list of fields to include in the statistics. It is used as the
+ default list unless a specific field list is provided in the `completion_fields`
+ or `fielddata_fields` parameters.
:param filter: Filter terms based on their tf-idf scores. This could be useful
in order find out a good characteristic vector of a document. This feature
works in a similar manner to the second phase of the More Like This Query.
@@ -6086,41 +5770,41 @@ async def termvectors(
__body: t.Dict[str, t.Any] = body if body is not None else {}
if error_trace is not None:
__query["error_trace"] = error_trace
- if field_statistics is not None:
- __query["field_statistics"] = field_statistics
- if fields is not None:
- __query["fields"] = fields
if filter_path is not None:
__query["filter_path"] = filter_path
if human is not None:
__query["human"] = human
- if offsets is not None:
- __query["offsets"] = offsets
- if payloads is not None:
- __query["payloads"] = payloads
- if positions is not None:
- __query["positions"] = positions
if preference is not None:
__query["preference"] = preference
if pretty is not None:
__query["pretty"] = pretty
if realtime is not None:
__query["realtime"] = realtime
- if routing is not None:
- __query["routing"] = routing
- if term_statistics is not None:
- __query["term_statistics"] = term_statistics
- if version is not None:
- __query["version"] = version
- if version_type is not None:
- __query["version_type"] = version_type
if not __body:
if doc is not None:
__body["doc"] = doc
+ if field_statistics is not None:
+ __body["field_statistics"] = field_statistics
+ if fields is not None:
+ __body["fields"] = fields
if filter is not None:
__body["filter"] = filter
+ if offsets is not None:
+ __body["offsets"] = offsets
+ if payloads is not None:
+ __body["payloads"] = payloads
if per_field_analyzer is not None:
__body["per_field_analyzer"] = per_field_analyzer
+ if positions is not None:
+ __body["positions"] = positions
+ if routing is not None:
+ __body["routing"] = routing
+ if term_statistics is not None:
+ __body["term_statistics"] = term_statistics
+ if version is not None:
+ __body["version"] = version
+ if version_type is not None:
+ __body["version_type"] = version_type
if not __body:
__body = None # type: ignore[assignment]
__headers = {"accept": "application/json"}
@@ -6203,10 +5887,11 @@ async def update(
The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.
The _source field must be enabled to use this API.
- In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).
+ In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).
+ For usage examples such as partial updates, upserts, and scripted updates, see the External documentation.
- ``_
+ ``_
:param index: The name of the target index. By default, the index is created
automatically if it doesn't exist.
@@ -6396,6 +6081,24 @@ async def update_by_query(
A bulk update request is performed for each batch of matching documents.
Any query or update failures cause the update by query request to fail and the failures are shown in the response.
Any update requests that completed successfully still stick, they are not rolled back.
+
Refreshing shards
+
Specifying the refresh parameter refreshes all shards once the request completes.
+ This is different to the update API's refresh parameter, which causes only the shard
+ that received the request to be refreshed. Unlike the update API, it does not support
+ wait_for.
+
Running update by query asynchronously
+
If the request contains wait_for_completion=false, Elasticsearch
+ performs some preflight checks, launches the request, and returns a
+ task you can use to cancel or get the status of the task.
+ Elasticsearch creates a record of this task as a document at .tasks/task/${taskId}.
+
Waiting for active shards
+
wait_for_active_shards controls how many copies of a shard must be active
+ before proceeding with the request. See wait_for_active_shards
+ for details. timeout controls how long each write request waits for unavailable
+ shards to become available. Both work exactly the way they work in the
+ Bulk API. Update by query uses scrolled searches, so you can also
+ specify the scroll parameter to control how long it keeps the search context
+ alive, for example ?scroll=10m. The default is 5 minutes.
Throttling update requests
To control the rate at which update by query issues batches of update operations, you can set requests_per_second to any positive decimal number.
This pads each batch with a wait time to throttle the rate.
@@ -6430,21 +6133,11 @@ async def update_by_query(
Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
Update performance scales linearly across available resources with the number of slices.
-
Whether query or update performance dominates the runtime depends on the documents being reindexed and cluster resources.
-
Update the document source
-
Update by query supports scripts to update the document source.
- As with the update API, you can set ctx.op to change the operation that is performed.
-
Set ctx.op = "noop" if your script decides that it doesn't have to make any changes.
- The update by query operation skips updating the document and increments the noop counter.
-
Set ctx.op = "delete" if your script decides that the document should be deleted.
- The update by query operation deletes the document and increments the deleted counter.
-
Update by query supports only index, noop, and delete.
- Setting ctx.op to anything else is an error.
- Setting any other field in ctx is an error.
- This API enables you to only modify the source of matching documents; you cannot move them.
-
-
- ``_
+
Whether query or update performance dominates the runtime depends on the documents being reindexed and cluster resources.
+ Refer to the linked documentation for examples of how to update documents using the _update_by_query API:
+
+
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases to
search. It supports wildcards (`*`). To search all data streams or indices,
@@ -6469,9 +6162,8 @@ async def update_by_query(
:param expand_wildcards: The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether
wildcard expressions match hidden data streams. It supports comma-separated
- values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`,
- `hidden`, `none`.
- :param from_: Starting offset (default: 0)
+ values, such as `open,hidden`.
+ :param from_: Skips the specified number of documents.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
:param lenient: If `true`, format-based query failures (such as providing text
@@ -6664,7 +6356,7 @@ async def update_by_query_rethrottle(
Rethrottling that speeds up the query takes effect immediately but rethrotting that slows down the query takes effect after completing the current batch to prevent scroll timeouts.
- ``_
+ ``_
:param task_id: The ID for the task.
:param requests_per_second: The throttle for this request in sub-requests per
diff --git a/elasticsearch/_async/client/_base.py b/elasticsearch/_async/client/_base.py
index dd0b0f44e..4e49e7156 100644
--- a/elasticsearch/_async/client/_base.py
+++ b/elasticsearch/_async/client/_base.py
@@ -174,7 +174,7 @@ async def sniff_callback(
"GET",
"/_nodes/_all/http",
headers={
- "accept": "application/vnd.elasticsearch+json; compatible-with=8"
+ "accept": "application/vnd.elasticsearch+json; compatible-with=9"
},
request_timeout=(
sniff_options.sniff_timeout
@@ -298,7 +298,6 @@ async def _perform_request(
def mimetype_header_to_compat(header: str) -> None:
# Converts all parts of a Accept/Content-Type headers
# from application/X -> application/vnd.elasticsearch+X
- nonlocal request_headers
mimetype = request_headers.get(header, None)
if mimetype:
request_headers[header] = _COMPAT_MIMETYPE_RE.sub(
diff --git a/elasticsearch/_async/client/async_search.py b/elasticsearch/_async/client/async_search.py
index b667d9463..7b7a76144 100644
--- a/elasticsearch/_async/client/async_search.py
+++ b/elasticsearch/_async/client/async_search.py
@@ -44,7 +44,7 @@ async def delete(
If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the cancel_task cluster privilege.
- ``_
+ ``_
:param id: A unique identifier for the async search.
"""
@@ -94,7 +94,7 @@ async def get(
If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.
- ``_
+ ``_
:param id: A unique identifier for the async search.
:param keep_alive: The length of time that the async search should be available
@@ -164,7 +164,7 @@ async def status(
- ``_
+ ``_
:param id: A unique identifier for the async search.
:param keep_alive: The length of time that the async search needs to be available.
@@ -345,7 +345,7 @@ async def submit(
The maximum allowed size for a stored async search response can be set by changing the search.max_async_search_response_size cluster level setting.
- ``_
+ ``_
:param index: A comma-separated list of index names to search; use `_all` or
empty string to perform the operation on all indices
@@ -401,7 +401,7 @@ async def submit(
limit the impact of the search on the cluster in order to limit the number
of concurrent shard requests
:param min_score: Minimum _score for matching documents. Documents with a lower
- _score are not included in the search results.
+ _score are not included in search results and results collected by aggregations.
:param pit: Limits the search to a point in time (PIT). If you provide a PIT,
you cannot specify an in the request path.
:param post_filter:
diff --git a/elasticsearch/_async/client/autoscaling.py b/elasticsearch/_async/client/autoscaling.py
index 5b41caa38..f0a3dd1a9 100644
--- a/elasticsearch/_async/client/autoscaling.py
+++ b/elasticsearch/_async/client/autoscaling.py
@@ -44,7 +44,7 @@ async def delete_autoscaling_policy(
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
- ``_
+ ``_
:param name: the name of the autoscaling policy
:param master_timeout: Period to wait for a connection to the master node. If
@@ -104,7 +104,7 @@ async def get_autoscaling_capacity(
Do not use this information to make autoscaling decisions.
- ``_
+ ``_
:param master_timeout: Period to wait for a connection to the master node. If
no response is received before the timeout expires, the request fails and
@@ -151,7 +151,7 @@ async def get_autoscaling_policy(
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
- ``_
+ ``_
:param name: the name of the autoscaling policy
:param master_timeout: Period to wait for a connection to the master node. If
@@ -206,7 +206,7 @@ async def put_autoscaling_policy(
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
- ``_
+ ``_
:param name: A comma-separated list of aliases to retrieve. Supports wildcards
(`*`). To retrieve all aliases, omit this parameter or use `*` or `_all`.
@@ -74,7 +101,8 @@ async def aliases(
values, such as `open,hidden`.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param master_timeout: The period to wait for a connection to the master node.
@@ -137,7 +165,48 @@ async def allocation(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "disk.avail",
+ "disk.indices",
+ "disk.indices.forecast",
+ "disk.percent",
+ "disk.total",
+ "disk.used",
+ "host",
+ "ip",
+ "node",
+ "node.role",
+ "shards",
+ "shards.undesired",
+ "write_load.forecast",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "disk.avail",
+ "disk.indices",
+ "disk.indices.forecast",
+ "disk.percent",
+ "disk.total",
+ "disk.used",
+ "host",
+ "ip",
+ "node",
+ "node.role",
+ "shards",
+ "shards.undesired",
+ "write_load.forecast",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
@@ -154,14 +223,15 @@ async def allocation(
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
- ``_
+ ``_
:param node_id: A comma-separated list of node identifiers or names used to limit
the returned information.
:param bytes: The unit used to display byte values.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
@@ -224,7 +294,36 @@ async def component_templates(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "alias_count",
+ "included_in",
+ "mapping_count",
+ "metadata_count",
+ "name",
+ "settings_count",
+ "version",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "alias_count",
+ "included_in",
+ "mapping_count",
+ "metadata_count",
+ "name",
+ "settings_count",
+ "version",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
@@ -243,13 +342,14 @@ async def component_templates(
They are not intended for use by applications. For application consumption, use the get component template API.
- ``_
+ ``_
:param name: The name of the component template. It accepts wildcard expressions.
If it is omitted, all component templates are returned.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
@@ -310,7 +410,12 @@ async def count(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[t.Union[str, t.Literal["count", "epoch", "timestamp"]]],
+ t.Union[str, t.Literal["count", "epoch", "timestamp"]],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
pretty: t.Optional[bool] = None,
@@ -327,14 +432,15 @@ async def count(
They are not intended for use by applications. For application consumption, use the count API.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases used
to limit the request. It supports wildcards (`*`). To target all data streams
and indices, omit this parameter or use `*` or `_all`.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param s: List of columns that determine how the table should be sorted. Sorting
@@ -389,7 +495,14 @@ async def fielddata(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[str, t.Literal["field", "host", "id", "ip", "node", "size"]]
+ ],
+ t.Union[str, t.Literal["field", "host", "id", "ip", "node", "size"]],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
pretty: t.Optional[bool] = None,
@@ -405,14 +518,15 @@ async def fielddata(
They are not intended for use by applications. For application consumption, use the nodes stats API.
- ``_
+ ``_
:param fields: Comma-separated list of fields used to limit returned information.
To retrieve all fields, omit this parameter.
:param bytes: The unit used to display byte values.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param s: List of columns that determine how the table should be sorted. Sorting
@@ -465,7 +579,52 @@ async def health(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "active_shards_percent",
+ "cluster",
+ "epoch",
+ "init",
+ "max_task_wait_time",
+ "node.data",
+ "node.total",
+ "pending_tasks",
+ "pri",
+ "relo",
+ "shards",
+ "status",
+ "timestamp",
+ "unassign",
+ "unassign.pri",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "active_shards_percent",
+ "cluster",
+ "epoch",
+ "init",
+ "max_task_wait_time",
+ "node.data",
+ "node.total",
+ "pending_tasks",
+ "pri",
+ "relo",
+ "shards",
+ "status",
+ "timestamp",
+ "unassign",
+ "unassign.pri",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
pretty: t.Optional[bool] = None,
@@ -491,11 +650,12 @@ async def health(
You also can use the API to track the recovery of a large cluster over a longer period of time.
- ``_
+ ``_
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param s: List of columns that determine how the table should be sorted. Sorting
@@ -549,7 +709,7 @@ async def help(self) -> TextApiResponse:
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
- ``_
+ ``_
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
@@ -892,7 +1370,7 @@ async def ml_data_frame_analytics(
application consumption, use the get data frame analytics jobs statistics API.
- ``_
+ ``_
:param id: The ID of the data frame analytics to fetch
:param allow_no_match: Whether to ignore if a wildcard expression matches no
@@ -1060,7 +1538,7 @@ async def ml_datafeeds(
application consumption, use the get datafeed statistics API.
- ``_
+ ``_
:param datafeed_id: A numerical character string that uniquely identifies the
datafeed.
@@ -1426,7 +1904,7 @@ async def ml_jobs(
application consumption, use the get anomaly detection job statistics API.
- ``_
+ ``_
:param job_id: Identifier for the anomaly detection job.
:param allow_no_match: Specifies what to do when the request: * Contains wildcard
@@ -1611,7 +2089,7 @@ async def ml_trained_models(
application consumption, use the get trained models statistics API.
- ``_
+ ``_
:param model_id: A unique identifier for the trained model.
:param allow_no_match: Specifies what to do when the request: contains wildcard
@@ -1687,7 +2165,24 @@ async def nodeattrs(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "attr", "host", "id", "ip", "node", "pid", "port", "value"
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "attr", "host", "id", "ip", "node", "pid", "port", "value"
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
@@ -1704,11 +2199,12 @@ async def nodeattrs(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
- ``_
+ ``_
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
@@ -1767,7 +2263,200 @@ async def nodes(
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
full_id: t.Optional[t.Union[bool, str]] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "build",
+ "completion.size",
+ "cpu",
+ "disk.avail",
+ "disk.total",
+ "disk.used",
+ "disk.used_percent",
+ "fielddata.evictions",
+ "fielddata.memory_size",
+ "file_desc.current",
+ "file_desc.max",
+ "file_desc.percent",
+ "flush.total",
+ "flush.total_time",
+ "get.current",
+ "get.exists_time",
+ "get.exists_total",
+ "get.missing_time",
+ "get.missing_total",
+ "get.time",
+ "get.total",
+ "heap.current",
+ "heap.max",
+ "heap.percent",
+ "http_address",
+ "id",
+ "indexing.delete_current",
+ "indexing.delete_time",
+ "indexing.delete_total",
+ "indexing.index_current",
+ "indexing.index_failed",
+ "indexing.index_failed_due_to_version_conflict",
+ "indexing.index_time",
+ "indexing.index_total",
+ "ip",
+ "jdk",
+ "load_15m",
+ "load_1m",
+ "load_5m",
+ "mappings.total_count",
+ "mappings.total_estimated_overhead_in_bytes",
+ "master",
+ "merges.current",
+ "merges.current_docs",
+ "merges.current_size",
+ "merges.total",
+ "merges.total_docs",
+ "merges.total_size",
+ "merges.total_time",
+ "name",
+ "node.role",
+ "pid",
+ "port",
+ "query_cache.evictions",
+ "query_cache.hit_count",
+ "query_cache.memory_size",
+ "query_cache.miss_count",
+ "ram.current",
+ "ram.max",
+ "ram.percent",
+ "refresh.time",
+ "refresh.total",
+ "request_cache.evictions",
+ "request_cache.hit_count",
+ "request_cache.memory_size",
+ "request_cache.miss_count",
+ "script.cache_evictions",
+ "script.compilations",
+ "search.fetch_current",
+ "search.fetch_time",
+ "search.fetch_total",
+ "search.open_contexts",
+ "search.query_current",
+ "search.query_time",
+ "search.query_total",
+ "search.scroll_current",
+ "search.scroll_time",
+ "search.scroll_total",
+ "segments.count",
+ "segments.fixed_bitset_memory",
+ "segments.index_writer_memory",
+ "segments.memory",
+ "segments.version_map_memory",
+ "shard_stats.total_count",
+ "suggest.current",
+ "suggest.time",
+ "suggest.total",
+ "uptime",
+ "version",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "build",
+ "completion.size",
+ "cpu",
+ "disk.avail",
+ "disk.total",
+ "disk.used",
+ "disk.used_percent",
+ "fielddata.evictions",
+ "fielddata.memory_size",
+ "file_desc.current",
+ "file_desc.max",
+ "file_desc.percent",
+ "flush.total",
+ "flush.total_time",
+ "get.current",
+ "get.exists_time",
+ "get.exists_total",
+ "get.missing_time",
+ "get.missing_total",
+ "get.time",
+ "get.total",
+ "heap.current",
+ "heap.max",
+ "heap.percent",
+ "http_address",
+ "id",
+ "indexing.delete_current",
+ "indexing.delete_time",
+ "indexing.delete_total",
+ "indexing.index_current",
+ "indexing.index_failed",
+ "indexing.index_failed_due_to_version_conflict",
+ "indexing.index_time",
+ "indexing.index_total",
+ "ip",
+ "jdk",
+ "load_15m",
+ "load_1m",
+ "load_5m",
+ "mappings.total_count",
+ "mappings.total_estimated_overhead_in_bytes",
+ "master",
+ "merges.current",
+ "merges.current_docs",
+ "merges.current_size",
+ "merges.total",
+ "merges.total_docs",
+ "merges.total_size",
+ "merges.total_time",
+ "name",
+ "node.role",
+ "pid",
+ "port",
+ "query_cache.evictions",
+ "query_cache.hit_count",
+ "query_cache.memory_size",
+ "query_cache.miss_count",
+ "ram.current",
+ "ram.max",
+ "ram.percent",
+ "refresh.time",
+ "refresh.total",
+ "request_cache.evictions",
+ "request_cache.hit_count",
+ "request_cache.memory_size",
+ "request_cache.miss_count",
+ "script.cache_evictions",
+ "script.compilations",
+ "search.fetch_current",
+ "search.fetch_time",
+ "search.fetch_total",
+ "search.open_contexts",
+ "search.query_current",
+ "search.query_time",
+ "search.query_total",
+ "search.scroll_current",
+ "search.scroll_time",
+ "search.scroll_total",
+ "segments.count",
+ "segments.fixed_bitset_memory",
+ "segments.index_writer_memory",
+ "segments.memory",
+ "segments.version_map_memory",
+ "shard_stats.total_count",
+ "suggest.current",
+ "suggest.time",
+ "suggest.total",
+ "uptime",
+ "version",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
include_unloaded_segments: t.Optional[bool] = None,
@@ -1787,23 +2476,24 @@ async def nodes(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
- ``_
+ ``_
:param bytes: The unit used to display byte values.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
:param full_id: If `true`, return the full node ID. If `false`, return the shortened
node ID.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param include_unloaded_segments: If true, the response includes information
from segments that are not loaded into memory.
- :param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
- :param time: Unit used to display time values.
+ :param master_timeout: The period to wait for a connection to the master node.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
+ :param time: The unit used to display time values.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str] = {}
@@ -1854,7 +2544,19 @@ async def pending_tasks(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal["insertOrder", "priority", "source", "timeInQueue"],
+ ]
+ ],
+ t.Union[
+ str, t.Literal["insertOrder", "priority", "source", "timeInQueue"]
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
@@ -1874,11 +2576,12 @@ async def pending_tasks(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the pending cluster tasks API.
- ``_
+ ``_
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
@@ -1936,7 +2639,19 @@ async def plugins(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal["component", "description", "id", "name", "version"],
+ ]
+ ],
+ t.Union[
+ str, t.Literal["component", "description", "id", "name", "version"]
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
include_bootstrap: t.Optional[bool] = None,
@@ -1954,11 +2669,12 @@ async def plugins(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
- ``_
+ ``_
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param include_bootstrap: Include bootstrap plugins in the response
@@ -2022,7 +2738,74 @@ async def recovery(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "bytes",
+ "bytes_percent",
+ "bytes_recovered",
+ "bytes_total",
+ "files",
+ "files_percent",
+ "files_recovered",
+ "files_total",
+ "index",
+ "repository",
+ "shard",
+ "snapshot",
+ "source_host",
+ "source_node",
+ "stage",
+ "start_time",
+ "start_time_millis",
+ "stop_time",
+ "stop_time_millis",
+ "target_host",
+ "target_node",
+ "time",
+ "translog_ops",
+ "translog_ops_percent",
+ "translog_ops_recovered",
+ "type",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "bytes",
+ "bytes_percent",
+ "bytes_recovered",
+ "bytes_total",
+ "files",
+ "files_percent",
+ "files_recovered",
+ "files_total",
+ "index",
+ "repository",
+ "shard",
+ "snapshot",
+ "source_host",
+ "source_node",
+ "stage",
+ "start_time",
+ "start_time_millis",
+ "stop_time",
+ "stop_time_millis",
+ "target_host",
+ "target_node",
+ "time",
+ "translog_ops",
+ "translog_ops_percent",
+ "translog_ops_recovered",
+ "type",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
pretty: t.Optional[bool] = None,
@@ -2042,7 +2825,7 @@ async def recovery(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index recovery API.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases used
to limit the request. Supports wildcards (`*`). To target all data streams
@@ -2053,13 +2836,14 @@ async def recovery(
shard recoveries.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
- :param time: Unit used to display time values.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
+ :param time: The unit used to display time values.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -2130,7 +2914,7 @@ async def repositories(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot repository API.
- ``_
+ ``_
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
@@ -2193,7 +2977,52 @@ async def segments(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "committed",
+ "compound",
+ "docs.count",
+ "docs.deleted",
+ "generation",
+ "id",
+ "index",
+ "ip",
+ "prirep",
+ "searchable",
+ "segment",
+ "shard",
+ "size",
+ "size.memory",
+ "version",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "committed",
+ "compound",
+ "docs.count",
+ "docs.deleted",
+ "generation",
+ "id",
+ "index",
+ "ip",
+ "prirep",
+ "searchable",
+ "segment",
+ "shard",
+ "size",
+ "size.memory",
+ "version",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
@@ -2211,7 +3040,7 @@ async def segments(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index segments API.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases used
to limit the request. Supports wildcards (`*`). To target all data streams
@@ -2219,7 +3048,8 @@ async def segments(
:param bytes: The unit used to display byte values.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
@@ -2227,9 +3057,9 @@ async def segments(
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
:param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -2285,7 +3115,162 @@ async def shards(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "completion.size",
+ "dataset.size",
+ "dense_vector.value_count",
+ "docs",
+ "dsparse_vector.value_count",
+ "fielddata.evictions",
+ "fielddata.memory_size",
+ "flush.total",
+ "flush.total_time",
+ "get.current",
+ "get.exists_time",
+ "get.exists_total",
+ "get.missing_time",
+ "get.missing_total",
+ "get.time",
+ "get.total",
+ "id",
+ "index",
+ "indexing.delete_current",
+ "indexing.delete_time",
+ "indexing.delete_total",
+ "indexing.index_current",
+ "indexing.index_failed",
+ "indexing.index_failed_due_to_version_conflict",
+ "indexing.index_time",
+ "indexing.index_total",
+ "ip",
+ "merges.current",
+ "merges.current_docs",
+ "merges.current_size",
+ "merges.total",
+ "merges.total_docs",
+ "merges.total_size",
+ "merges.total_time",
+ "node",
+ "prirep",
+ "query_cache.evictions",
+ "query_cache.memory_size",
+ "recoverysource.type",
+ "refresh.time",
+ "refresh.total",
+ "search.fetch_current",
+ "search.fetch_time",
+ "search.fetch_total",
+ "search.open_contexts",
+ "search.query_current",
+ "search.query_time",
+ "search.query_total",
+ "search.scroll_current",
+ "search.scroll_time",
+ "search.scroll_total",
+ "segments.count",
+ "segments.fixed_bitset_memory",
+ "segments.index_writer_memory",
+ "segments.memory",
+ "segments.version_map_memory",
+ "seq_no.global_checkpoint",
+ "seq_no.local_checkpoint",
+ "seq_no.max",
+ "shard",
+ "state",
+ "store",
+ "suggest.current",
+ "suggest.time",
+ "suggest.total",
+ "sync_id",
+ "unassigned.at",
+ "unassigned.details",
+ "unassigned.for",
+ "unassigned.reason",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "completion.size",
+ "dataset.size",
+ "dense_vector.value_count",
+ "docs",
+ "dsparse_vector.value_count",
+ "fielddata.evictions",
+ "fielddata.memory_size",
+ "flush.total",
+ "flush.total_time",
+ "get.current",
+ "get.exists_time",
+ "get.exists_total",
+ "get.missing_time",
+ "get.missing_total",
+ "get.time",
+ "get.total",
+ "id",
+ "index",
+ "indexing.delete_current",
+ "indexing.delete_time",
+ "indexing.delete_total",
+ "indexing.index_current",
+ "indexing.index_failed",
+ "indexing.index_failed_due_to_version_conflict",
+ "indexing.index_time",
+ "indexing.index_total",
+ "ip",
+ "merges.current",
+ "merges.current_docs",
+ "merges.current_size",
+ "merges.total",
+ "merges.total_docs",
+ "merges.total_size",
+ "merges.total_time",
+ "node",
+ "prirep",
+ "query_cache.evictions",
+ "query_cache.memory_size",
+ "recoverysource.type",
+ "refresh.time",
+ "refresh.total",
+ "search.fetch_current",
+ "search.fetch_time",
+ "search.fetch_total",
+ "search.open_contexts",
+ "search.query_current",
+ "search.query_time",
+ "search.query_total",
+ "search.scroll_current",
+ "search.scroll_time",
+ "search.scroll_total",
+ "segments.count",
+ "segments.fixed_bitset_memory",
+ "segments.index_writer_memory",
+ "segments.memory",
+ "segments.version_map_memory",
+ "seq_no.global_checkpoint",
+ "seq_no.local_checkpoint",
+ "seq_no.max",
+ "shard",
+ "state",
+ "store",
+ "suggest.current",
+ "suggest.time",
+ "suggest.total",
+ "sync_id",
+ "unassigned.at",
+ "unassigned.details",
+ "unassigned.for",
+ "unassigned.reason",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
@@ -2305,7 +3290,7 @@ async def shards(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
- ``_
+ ``_
:param index: A comma-separated list of data streams, indices, and aliases used
to limit the request. Supports wildcards (`*`). To target all data streams
@@ -2316,11 +3301,11 @@ async def shards(
:param h: List of columns to appear in the response. Supports simple wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
- :param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
- :param time: Unit used to display time values.
+ :param master_timeout: The period to wait for a connection to the master node.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
+ :param time: The unit used to display time values.
:param v: When set to `true` will enable verbose output.
"""
__path_parts: t.Dict[str, str]
@@ -2373,7 +3358,48 @@ async def snapshots(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "duration",
+ "end_epoch",
+ "end_time",
+ "failed_shards",
+ "id",
+ "indices",
+ "reason",
+ "repository",
+ "start_epoch",
+ "start_time",
+ "status",
+ "successful_shards",
+ "total_shards",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "duration",
+ "end_epoch",
+ "end_time",
+ "failed_shards",
+ "id",
+ "indices",
+ "reason",
+ "repository",
+ "start_epoch",
+ "start_time",
+ "status",
+ "successful_shards",
+ "total_shards",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
ignore_unavailable: t.Optional[bool] = None,
@@ -2394,14 +3420,15 @@ async def snapshots(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API.
- ``_
+ ``_
:param repository: A comma-separated list of snapshot repositories used to limit
the request. Accepts wildcard expressions. `_all` returns all repositories.
If any repository fails during the request, Elasticsearch returns an error.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param ignore_unavailable: If `true`, the response does not include information
@@ -2465,7 +3492,52 @@ async def tasks(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "action",
+ "id",
+ "ip",
+ "node",
+ "node_id",
+ "parent_task_id",
+ "port",
+ "running_time",
+ "running_time_ns",
+ "start_time",
+ "task_id",
+ "timestamp",
+ "type",
+ "version",
+ "x_opaque_id",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "action",
+ "id",
+ "ip",
+ "node",
+ "node_id",
+ "parent_task_id",
+ "port",
+ "running_time",
+ "running_time_ns",
+ "start_time",
+ "task_id",
+ "timestamp",
+ "type",
+ "version",
+ "x_opaque_id",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
nodes: t.Optional[t.Sequence[str]] = None,
@@ -2487,14 +3559,15 @@ async def tasks(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the task management API.
- ``_
+ ``_
:param actions: The task action names, which are used to limit the response.
:param detailed: If `true`, the response includes detailed information about
shard recoveries.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param nodes: Unique node identifiers, which are used to limit the response.
@@ -2563,7 +3636,24 @@ async def templates(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "composed_of", "index_patterns", "name", "order", "version"
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "composed_of", "index_patterns", "name", "order", "version"
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
@@ -2581,13 +3671,14 @@ async def templates(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get index template API.
- ``_
+ ``_
:param name: The name of the template to return. Accepts wildcard expressions.
If omitted, all templates are returned.
:param format: Specifies the format to return the columnar data in, can be set
to `text`, `json`, `cbor`, `yaml`, or `smile`.
- :param h: List of columns to appear in the response. Supports simple wildcards.
+ :param h: A comma-separated list of columns names to display. It supports simple
+ wildcards.
:param help: When set to `true` will output available columns. This option can't
be combined with any other query string option.
:param local: If `true`, the request computes the list of selected nodes from
@@ -2648,7 +3739,62 @@ async def thread_pool(
error_trace: t.Optional[bool] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
format: t.Optional[str] = None,
- h: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+ h: t.Optional[
+ t.Union[
+ t.Sequence[
+ t.Union[
+ str,
+ t.Literal[
+ "active",
+ "completed",
+ "core",
+ "ephemeral_id",
+ "host",
+ "ip",
+ "keep_alive",
+ "largest",
+ "max",
+ "name",
+ "node_id",
+ "node_name",
+ "pid",
+ "pool_size",
+ "port",
+ "queue",
+ "queue_size",
+ "rejected",
+ "size",
+ "type",
+ ],
+ ]
+ ],
+ t.Union[
+ str,
+ t.Literal[
+ "active",
+ "completed",
+ "core",
+ "ephemeral_id",
+ "host",
+ "ip",
+ "keep_alive",
+ "largest",
+ "max",
+ "name",
+ "node_id",
+ "node_name",
+ "pid",
+ "pool_size",
+ "port",
+ "queue",
+ "queue_size",
+ "rejected",
+ "size",
+ "type",
+ ],
+ ],
+ ]
+ ] = None,
help: t.Optional[bool] = None,
human: t.Optional[bool] = None,
local: t.Optional[bool] = None,
@@ -2669,7 +3815,7 @@ async def thread_pool(
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
- ``_
+ ``_
:param thread_pool_patterns: A comma-separated list of thread pool names used
to limit the request. Accepts wildcard expressions.
@@ -2682,10 +3828,10 @@ async def thread_pool(
the local cluster state. If `false` the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
- :param master_timeout: Period to wait for a connection to the master node.
- :param s: List of columns that determine how the table should be sorted. Sorting
- defaults to ascending and can be changed by setting `:asc` or `:desc` as
- a suffix to the column name.
+ :param master_timeout: The period to wait for a connection to the master node.
+ :param s: A comma-separated list of column names or aliases that determines the
+ sort order. Sorting defaults to ascending and can be changed by setting `:asc`
+ or `:desc` as a suffix to the column name.
:param time: The unit used to display time values.
:param v: When set to `true` will enable verbose output.
"""
@@ -2926,7 +4072,7 @@ async def transforms(
application consumption, use the get transform statistics API.
- ``_
+ ``_
:param transform_id: A transform identifier or a wildcard expression. If you
do not specify one of these options, the API returns information for all
diff --git a/elasticsearch/_async/client/ccr.py b/elasticsearch/_async/client/ccr.py
index a98428ffb..6617f2403 100644
--- a/elasticsearch/_async/client/ccr.py
+++ b/elasticsearch/_async/client/ccr.py
@@ -43,7 +43,7 @@ async def delete_auto_follow_pattern(
Delete a collection of cross-cluster replication auto-follow patterns.
- ``_
+ ``_
:param name: The auto-follow pattern collection to delete.
:param master_timeout: The period to wait for a connection to the master node.
@@ -130,7 +130,7 @@ async def follow(
When the API returns, the follower index exists and cross-cluster replication starts replicating operations from the leader index to the follower index.
- ``_
+ ``_
:param index: The name of the follower index.
:param leader_index: The name of the index in the leader cluster to follow.
@@ -259,7 +259,7 @@ async def follow_info(
For example, the results include follower index names, leader index names, replication options, and whether the follower indices are active or paused.
- ``_
+ ``_
:param index: A comma-delimited list of follower index patterns.
:param master_timeout: The period to wait for a connection to the master node.
@@ -311,7 +311,7 @@ async def follow_stats(
The API returns shard-level stats about the "following tasks" associated with each shard for the specified indices.
- ``_
+ ``_
:param index: A comma-delimited list of index patterns.
:param timeout: The period to wait for a response. If no response is received
@@ -380,7 +380,7 @@ async def forget_follower(
The only purpose of this API is to handle the case of failure to remove the following retention leases after the unfollow API is invoked.
- ``_
+ ``_
:param index: the name of the leader index for which specified follower retention
leases should be removed
@@ -445,7 +445,7 @@ async def get_auto_follow_pattern(
Get cross-cluster replication auto-follow patterns.
- ``_
+ ``_
:param name: The auto-follow pattern collection that you want to retrieve. If
you do not specify a name, the API returns information for all collections.
@@ -505,7 +505,7 @@ async def pause_auto_follow_pattern(
Remote indices that were created while the pattern was paused will also be followed, unless they have been deleted or closed in the interim.
- ``_
+ ``_
:param name: The name of the auto-follow pattern to pause.
:param master_timeout: The period to wait for a connection to the master node.
@@ -559,7 +559,7 @@ async def pause_follow(
You can pause and resume a follower index to change the configuration of the following task.
- ``_
+ ``_
:param index: The name of the follower index.
:param master_timeout: The period to wait for a connection to the master node.
@@ -648,7 +648,7 @@ async def put_auto_follow_pattern(
NOTE: Follower indices that were configured automatically before updating an auto-follow pattern will remain unchanged even if they do not match against the new patterns.
- ``_
+ ``_
:param name: The name of the collection of auto-follow patterns.
:param remote_cluster: The remote cluster containing the leader indices to match
@@ -782,7 +782,7 @@ async def resume_auto_follow_pattern(
Remote indices created while the pattern was paused will also be followed unless they have been deleted or closed in the interim.
- ``_
+ ``_
:param name: The name of the auto-follow pattern to resume.
:param master_timeout: The period to wait for a connection to the master node.
@@ -860,7 +860,7 @@ async def resume_follow(
When this API returns, the follower index will resume fetching operations from the leader index.
- ``_
+ ``_
:param index: The name of the follow index to resume following.
:param master_timeout: Period to wait for a connection to the master node.
@@ -951,7 +951,7 @@ async def stats(
This API returns stats about auto-following and the same shard-level stats as the get follower stats API.
- ``_
+ ``_
:param master_timeout: The period to wait for a connection to the master node.
If the master node is not available before the timeout expires, the request
@@ -1009,7 +1009,7 @@ async def unfollow(
- ``_
+ ``_
:param index: The name of the follower index.
:param master_timeout: The period to wait for a connection to the master node.
diff --git a/elasticsearch/_async/client/cluster.py b/elasticsearch/_async/client/cluster.py
index 074bdc0e8..ee8036536 100644
--- a/elasticsearch/_async/client/cluster.py
+++ b/elasticsearch/_async/client/cluster.py
@@ -51,10 +51,11 @@ async def allocation_explain(
Get explanations for shard allocations in the cluster.
For unassigned shards, it provides an explanation for why the shard is unassigned.
For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.
- This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.
+ This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.
+ Refer to the linked documentation for examples of how to troubleshoot allocation issues using this API.
- ``_
+ ``_
:param current_node: Specifies the node ID or the name of the node to only explain
a shard that is currently located on the specified node.
@@ -130,7 +131,7 @@ async def delete_component_template(
Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
- ``_
+ ``_
:param name: Comma-separated list or wildcard expression of component template
names used to limit the request.
@@ -185,7 +186,7 @@ async def delete_voting_config_exclusions(
Remove master-eligible nodes from the voting configuration exclusion list.
- ``_
+ ``_
:param master_timeout: Period to wait for a connection to the master node.
:param wait_for_removal: Specifies whether to wait for all excluded nodes to
@@ -239,7 +240,7 @@ async def exists_component_template(
Returns information about whether a particular component template exists.
- ``_
+ ``_
:param name: Comma-separated list of component template names used to limit the
request. Wildcard (*) expressions are supported.
@@ -290,6 +291,7 @@ async def get_component_template(
local: t.Optional[bool] = None,
master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
pretty: t.Optional[bool] = None,
+ settings_filter: t.Optional[t.Union[str, t.Sequence[str]]] = None,
) -> ObjectApiResponse[t.Any]:
"""
.. raw:: html
@@ -298,7 +300,7 @@ async def get_component_template(
Get information about component templates.
- ``_
+ ``_
:param name: Comma-separated list of component template names used to limit the
request. Wildcard (`*`) expressions are supported.
@@ -310,6 +312,8 @@ async def get_component_template(
:param master_timeout: Period to wait for a connection to the master node. If
no response is received before the timeout expires, the request fails and
returns an error.
+ :param settings_filter: Filter out results, for example to filter out sensitive
+ information. Supports wildcards or full settings keys
"""
__path_parts: t.Dict[str, str]
if name not in SKIP_IN_PATH:
@@ -335,6 +339,8 @@ async def get_component_template(
__query["master_timeout"] = master_timeout
if pretty is not None:
__query["pretty"] = pretty
+ if settings_filter is not None:
+ __query["settings_filter"] = settings_filter
__headers = {"accept": "application/json"}
return await self.perform_request( # type: ignore[return-value]
"GET",
@@ -365,7 +371,7 @@ async def get_settings(
By default, it returns only settings that have been explicitly defined.
- ``_
+ ``_
:param flat_settings: If `true`, returns settings in flat format.
:param include_defaults: If `true`, returns default cluster settings from the
@@ -441,7 +447,7 @@ async def health(
wait_for_no_relocating_shards: t.Optional[bool] = None,
wait_for_nodes: t.Optional[t.Union[int, str]] = None,
wait_for_status: t.Optional[
- t.Union[str, t.Literal["green", "red", "yellow"]]
+ t.Union[str, t.Literal["green", "red", "unavailable", "unknown", "yellow"]]
] = None,
) -> ObjectApiResponse[t.Any]:
"""
@@ -457,7 +463,7 @@ async def health(
The cluster status is controlled by the worst index status.
- ``_
+ ``_
:param index: Comma-separated list of data streams, indices, and index aliases
used to limit the request. Wildcard expressions (`*`) are supported. To target
@@ -565,7 +571,7 @@ async def info(
Returns basic information about the cluster.
- ``_
+ ``_
:param target: Limits the information returned to the specific target. Supports
a comma-separated list, such as http,ingest.
@@ -614,7 +620,7 @@ async def pending_tasks(
However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.
- ``_
+ ``_
:param local: If `true`, the request retrieves information from the local node
only. If `false`, information is retrieved from the master node.
@@ -680,7 +686,7 @@ async def post_voting_config_exclusions(
They are not required when removing master-ineligible nodes or when removing fewer than half of the master-eligible nodes.
- ``_
+ ``_
:param master_timeout: Period to wait for a connection to the master node.
:param node_ids: A comma-separated list of the persistent ids of the nodes to
@@ -731,6 +737,7 @@ async def put_component_template(
*,
name: str,
template: t.Optional[t.Mapping[str, t.Any]] = None,
+ cause: t.Optional[str] = None,
create: t.Optional[bool] = None,
deprecated: t.Optional[bool] = None,
error_trace: t.Optional[bool] = None,
@@ -761,7 +768,7 @@ async def put_component_template(
To be applied, a component template must be included in an index template's composed_of list.
- ``_
+ ``_
:param name: Name of the component template to create. Elasticsearch includes
the following built-in component templates: `logs-mappings`; `logs-settings`;
@@ -774,6 +781,7 @@ async def put_component_template(
update settings API.
:param template: The template to be applied which includes mappings, settings,
or aliases configuration.
+ :param cause: User defined reason for create the component template.
:param create: If `true`, this request cannot replace or update existing component
templates.
:param deprecated: Marks this index template as deprecated. When creating or
@@ -798,6 +806,8 @@ async def put_component_template(
__path = f'/_component_template/{__path_parts["name"]}'
__query: t.Dict[str, t.Any] = {}
__body: t.Dict[str, t.Any] = body if body is not None else {}
+ if cause is not None:
+ __query["cause"] = cause
if create is not None:
__query["create"] = create
if error_trace is not None:
@@ -866,13 +876,13 @@ async def put_settings(
If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.
- ``_
+ ``_
:param flat_settings: Return settings in flat format (default: false)
:param master_timeout: Explicit operation timeout for connection to master node
- :param persistent:
+ :param persistent: The settings that persist after the cluster restarts.
:param timeout: Explicit operation timeout
- :param transient:
+ :param transient: The settings that do not persist after the cluster restarts.
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_cluster/settings"
@@ -932,7 +942,7 @@ async def remote_info(
- ``_
+ ``_
"""
__path_parts: t.Dict[str, str] = {}
__path = "/_remote/info"
@@ -989,7 +999,7 @@ async def reroute(
Once the problem has been corrected, allocation can be manually retried by calling the reroute API with the ?retry_failed URI query parameter, which will attempt a single retry round for these shards.
- ``_
+ ``_
:param commands: Defines the commands to perform.
:param dry_run: If true, then the request simulates the operation. It will calculate
@@ -1094,7 +1104,7 @@ async def state(
Instead, obtain the information you require using other more stable cluster APIs.
- ``_
+ ``_
:param metric: Limit the information returned to the specified metrics
:param index: A comma-separated list of index names; use `_all` or empty string
@@ -1182,7 +1192,7 @@ async def stats(
Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).
- ``_
+ ``_
:param node_id: Comma-separated list of node filters used to limit returned information.
Defaults to all nodes in the cluster.
diff --git a/elasticsearch/_async/client/connector.py b/elasticsearch/_async/client/connector.py
index debf9e3ce..31fecb03c 100644
--- a/elasticsearch/_async/client/connector.py
+++ b/elasticsearch/_async/client/connector.py
@@ -49,7 +49,7 @@ async def check_in(
Update the last_seen field in the connector and set it to the current timestamp.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector to be checked in
"""
@@ -99,7 +99,7 @@ async def delete(
These need to be removed manually.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector to be deleted
:param delete_sync_jobs: A flag indicating if associated sync jobs should be
@@ -152,7 +152,7 @@ async def get(
Get the details about a connector.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector
:param include_deleted: A flag to indicate if the desired connector should be
@@ -256,7 +256,7 @@ async def last_sync(
This action is used for analytics and monitoring.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector to be updated
:param last_access_control_sync_error:
@@ -356,7 +356,7 @@ async def list(
Get information about all connectors.
- ``_
+ ``_
:param connector_name: A comma-separated list of connector names to fetch connector
documents for
@@ -441,7 +441,7 @@ async def post(
Self-managed connectors (Connector clients) are self-managed on your infrastructure.
- ``_
+ ``_
:param description:
:param index_name:
@@ -523,7 +523,7 @@ async def put(
Create or update a connector.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector to be created or
updated. ID is auto-generated if not provided.
@@ -598,7 +598,7 @@ async def sync_job_cancel(
The connector service is then responsible for setting the status of connector sync jobs to cancelled.
- ``_
+ ``_
:param connector_sync_job_id: The unique identifier of the connector sync job
"""
@@ -649,7 +649,7 @@ async def sync_job_check_in(
This service runs automatically on Elastic Cloud for Elastic managed connectors.
- ``_
+ ``_
:param connector_sync_job_id: The unique identifier of the connector sync job
to be checked in.
@@ -709,7 +709,7 @@ async def sync_job_claim(
This service runs automatically on Elastic Cloud for Elastic managed connectors.
- ``_
+ ``_
:param connector_sync_job_id: The unique identifier of the connector sync job.
:param worker_hostname: The host name of the current system that will run the
@@ -771,7 +771,7 @@ async def sync_job_delete(
This is a destructive action that is not recoverable.
- ``_
+ ``_
:param connector_sync_job_id: The unique identifier of the connector sync job
to be deleted
@@ -825,7 +825,7 @@ async def sync_job_error(
This service runs automatically on Elastic Cloud for Elastic managed connectors.
- ``_
+ ``_
:param connector_sync_job_id: The unique identifier for the connector sync job.
:param error: The error for the connector sync job error field.
@@ -879,7 +879,7 @@ async def sync_job_get(
Get a connector sync job.
- ``_
+ ``_
:param connector_sync_job_id: The unique identifier of the connector sync job
"""
@@ -952,7 +952,7 @@ async def sync_job_list(
Get information about all stored connector sync jobs listed by their creation date in ascending order.
- ``_
+ ``_
:param connector_id: A connector id to fetch connector sync jobs for
:param from_: Starting offset (default: 0)
@@ -1018,7 +1018,7 @@ async def sync_job_post(
Create a connector sync job document in the internal index and initialize its counters and timestamps with default values.
- ``_
+ ``_
:param id: The id of the associated connector
:param job_type:
@@ -1094,7 +1094,7 @@ async def sync_job_update_stats(
This service runs automatically on Elastic Cloud for Elastic managed connectors.
- ``_
+ ``_
:param connector_sync_job_id: The unique identifier of the connector sync job.
:param deleted_document_count: The number of documents the sync job deleted.
@@ -1177,7 +1177,7 @@ async def update_active_filtering(
Activates the valid draft filtering for a connector.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector to be updated
"""
@@ -1230,7 +1230,7 @@ async def update_api_key_id(
Self-managed connectors (connector clients) do not use this field.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector to be updated
:param api_key_id:
@@ -1289,7 +1289,7 @@ async def update_configuration(
Update the configuration field in the connector document.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector to be updated
:param configuration:
@@ -1349,7 +1349,7 @@ async def update_error(
Otherwise, if the error is reset to null, the connector status is updated to connected.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector to be updated
:param error:
@@ -1417,7 +1417,7 @@ async def update_features(
This service runs automatically on Elastic Cloud for Elastic managed connectors.
- ``_
+ ``_
:param connector_id: The unique identifier of the connector to be updated.
:param features:
@@ -1478,7 +1478,7 @@ async def update_filtering(
The filtering property is used to configure sync rules (both basic and advanced) for a connector.
- `