Elasticsearch Client Builder

Common errors

• ModuleNotFoundError: No module named 'elasticsearch8'

  cause Attempting to run `es-client` v9.x code with an environment or dependency list that still expects `elasticsearch8`, which was replaced by `elasticsearch9` in `es-client` v9.0.0.
  fix Ensure `elasticsearch9` is installed and `es-client` is updated to a 9.x version. You might need `pip install elasticsearch9` and `pip install --upgrade es-client`.

• AttributeError: 'Elasticsearch' object has no attribute 'helpers'

  cause Trying to use the `helpers` submodule (e.g., `client.helpers.bulk`) directly from an `es-client` v9.x `client` instance. The `helpers` submodule was removed from `es_client` and the official `elasticsearch-py` client in v9.0.0.
  fix Import `helpers` directly from `elasticsearch`: `from elasticsearch import helpers`. Then call functions like `helpers.bulk(client, actions)`.

• ConnectionError: Connection refused

  cause Incorrect Elasticsearch host configuration, network issues, firewall blocking, or credentials missing/incorrect. For `es-client` specifically, older versions (pre-9.0.2/8.19.4) sometimes mishandled URL paths.
  fix Verify that your `configdict['elasticsearch']['client']['hosts']` contains the correct and accessible Elasticsearch endpoints. Ensure any required `api_key`, `username`, `password`, or `ca_certs` are correctly provided. If using URL paths, ensure `es-client` is v9.0.2+ or v8.19.4+.

• TypeError: 'Builder' object is not callable

  cause Attempting to use the `Builder` instance directly as the Elasticsearch client (e.g., `builder.info()`) before explicitly retrieving the client object.
  fix After calling `builder.connect()`, you must access the actual Elasticsearch client instance via `client = builder.client`. All subsequent Elasticsearch API calls should be made using this `client` object.

Warnings

• breaking es-client v9.0.0 is a major version bump that replaced the `elasticsearch8` dependency with `elasticsearch9` and removed the `helpers` submodule. Code relying on `elasticsearch8` or the `es_client.helpers` submodule will break.
  Fix: Update your `pip install` to `elasticsearch9` and ensure your Elasticsearch cluster is version 9.x. Rewrite any code using the `helpers` submodule to use `elasticsearch.helpers` directly or the native `elasticsearch` client methods.
• breaking The `elasticsearch-dsl` package is now integrated directly into the `elasticsearch` client as of `elasticsearch-py` v8.18.0. If you were using `elasticsearch-dsl` alongside `es-client`, you should uninstall `elasticsearch-dsl` and change imports from `elasticsearch_dsl` to `elasticsearch.dsl`.
  Fix: Uninstall `elasticsearch-dsl` and modify import statements from `from elasticsearch_dsl import Search` to `from elasticsearch.dsl import Search`.
• gotcha URL paths in client configuration were not always respected, leading to connection issues or incorrect endpoint targeting.
  Fix: Upgrade to `es-client` v9.0.2 or later, or `v8.19.4` or later patches in the 8.x series. Verify your `hosts` configuration carefully, especially when using paths in the URL.
• gotcha es-client v8.19.0 introduced a `click` dependency that inadvertently broke compatibility with Python 3.8 and 3.9. While fixed in a subsequent patch, users on these Python versions should be aware.
  Fix: Ensure you are using `es-client` v8.19.2 or a later patch within the 8.x series to maintain compatibility with Python 3.8 and 3.9 if `click` related issues arise.
• breaking Using the Elasticsearch Python client version 9.0.0 or later (which es-client v9.x depends on) against an Elasticsearch 8.x server will fail due to incompatible APIs. Compatibility requires the server version to match or be newer.
  Fix: Always upgrade your Elasticsearch cluster to version 9.x *before* upgrading your `es-client` library to 9.0.0 or later.

Install

• pip install es-client Install latest version

Imports

• Builder

  from es_client import Builder

Quickstart

This quickstart demonstrates how to initialize the es-client Builder with a configuration dictionary, establish a connection to an Elasticsearch cluster, and then retrieve the underlying Elasticsearch client to perform basic operations like checking cluster info and creating an index. Sensitive connection details are sourced from environment variables for security.

import os
from es_client import Builder

# Configure Elasticsearch connection using environment variables for sensitive data
config = {
    'elasticsearch': {
        'client': {
            'hosts': os.environ.get('ES_HOSTS', 'https://localhost:9200').split(','),
            'api_key': os.environ.get('ES_API_KEY', ''),
            'ca_certs': os.environ.get('ES_CA_CERTS', ''), # e.g., '/etc/elasticsearch/certs/ca.crt'
            'request_timeout': 60,
        },
        'other_settings': {
            'master_only': False,
            'username': os.environ.get('ES_USERNAME', ''),
            'password': os.environ.get('ES_PASSWORD', ''),
        }
    },
    'logging': {
        'loglevel': 'INFO',
        'logfile': '', # Path to log file, e.g., '/var/log/es_client.log'
        'logformat': 'default',
    }
}

builder = Builder(configdict=config)
try:
    builder.connect()
    client = builder.client # Get the connected Elasticsearch client instance
    
    # Example: Check cluster info
    info = client.info()
    print("Connected to Elasticsearch cluster:", info['cluster_name'])
    
    # Example: Create an index
    index_name = "my_test_index"
    if not client.indices.exists(index=index_name):
        client.indices.create(index=index_name)
        print(f"Index '{index_name}' created.")
    else:
        print(f"Index '{index_name}' already exists.")

except Exception as e:
    print(f"An error occurred: {e}")