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

Download the latest version of Elasticsearch or sign-up for a free trial of Elastic Cloud.

## Installation

Install the `elasticsearch` package with pip:

    $ python -m pip install elasticsearch

If your application uses async/await in Python you can install with the `async` extra:

    $ 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

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

## Contents

- Quickstart
  - Requirements
  - Installation
  - Connecting
  - Using the client
    - Create an index with mappings
    - Indexing documents
    - Getting documents
    - Searching documents
    - Updating documents
    - Deleting documents
    - Deleting an index
- Interactive examples
  - Search notebooks
    - Quick start
    - Keyword, querying, filtering
    - Hybrid search
    - Semantic search with ELSER
    - Multilingual semantic search
    - Query rules
    - Synonyms API quick start
  - Other notebooks
- Elasticsearch API Reference
  - Elasticsearch
    - `Elasticsearch`
  - Async Search
    - `AsyncSearchClient`
  - Autoscaling
    - `AutoscalingClient`
  - Cat
    - `CatClient`
  - Cross-Cluster Replication (CCR)
    - `CcrClient`
  - Cluster
    - `ClusterClient`
  - Connector
    - `ConnectorClient`
  - Dangling Indices
    - `DanglingIndicesClient`
  - Enrich Policies
    - `EnrichClient`
  - Event Query Language (EQL)
    - `EqlClient`
  - ES|QL
    - `EsqlClient`
  - Fleet
    - `FleetClient`
  - Graph Explore
    - `GraphClient`
  - Index Lifecycle Management (ILM)
    - `IlmClient`
  - Indices
    - `IndicesClient`
  - Inference
    - `InferenceClient`
  - Ingest Pipelines
    - `IngestClient`
  - License
    - `LicenseClient`
  - Logstash
    - `LogstashClient`
  - Migration
    - `MigrationClient`
  - Machine Learning (ML)
    - `MlClient`
  - Monitoring
    - `MonitoringClient`
  - Nodes
    - `NodesClient`
  - Query rules
    - `QueryRulesClient`
  - Rollup Indices
    - `RollupClient`
  - Search Applications
    - `SearchApplicationClient`
  - Searchable Snapshots
    - `SearchableSnapshotsClient`
  - Security
    - `SecurityClient`
  - Shutdown
    - `ShutdownClient`
  - Simulate
    - `SimulateClient`
  - Snapshot Lifecycle Management (SLM)
    - `SlmClient`
  - Snapshots
    - `SnapshotClient`
  - Snapshottable Features
    - `FeaturesClient`
  - SQL
    - `SqlClient`
  - Synonyms
    - `SynonymsClient`
  - TLS/SSL
    - `SslClient`
  - Tasks
    - `TasksClient`
  - Text Structure
    - `TextStructureClient`
  - Transforms
    - `TransformClient`
  - Watcher
    - `WatcherClient`
  - X-Pack
    - `XPackClient`
- Exceptions & Warnings
  - API Errors
    - `ApiError`
    - `NotFoundError`
    - `ConflictError`
    - `RequestError`
    - `AuthenticationException`
    - `AuthorizationException`
    - `UnsupportedProductError`
  - Transport and Connection Errors
    - `TransportError`
    - `SerializationError`
    - `ConnectionError`
    - `ConnectionTimeout`
    - `SSLError`
  - Warnings
    - `ElasticsearchWarning`
- Using asyncio with Elasticsearch
  - Getting Started with Async
  - ASGI Applications and Elastic APM
  - Frequently Asked Questions
    - ValueError when initializing `AsyncElasticsearch`?
    - What about the `elasticsearch-async` package?
    - Receiving ‘Unclosed client session / connector’ warning?
  - Async Helpers
    - Bulk and Streaming Bulk
    - Scan
    - Reindex
  - API Reference
    - AsyncElasticsearch
- Helpers
  - Connecting
  - Bulk helpers
    - Example:
  - Scan
    - `scan()`
  - Reindex
    - `reindex()`
- Release Notes

## License

Copyright 2023 Elasticsearch B.V. Licensed under the Apache License, Version 2.0.

## Indices and tables

- Index

- Module Index

- Search Page