{"id":8977,"library":"es-client","title":"Elasticsearch Client Builder","description":"es-client is an Elasticsearch Client builder for Python, complete with advanced schema validation. It provides features like master-only detection, Elasticsearch version checking, and robust configuration value validation, including file paths for SSL certificates. The library is currently at version 9.0.1 and maintains an active development cycle with frequent updates and patches.","status":"active","version":"9.0.1","language":"en","source_language":"en","source_url":"https://github.com/untergeek/es_client","tags":["elasticsearch","client","builder","validation","schema","python"],"install":[{"cmd":"pip install es-client","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for connecting to Elasticsearch 9.x clusters. This replaced elasticsearch8 in v9.0.0.","package":"elasticsearch9","optional":false},{"reason":"Used for structured logging and debugging within the client.","package":"tiered-debug","optional":false},{"reason":"Ensures up-to-date CA certificates for secure connections.","package":"certifi","optional":false},{"reason":"Used for command-line interface utilities; compatibility with older Python versions was a past concern in 8.x series.","package":"click","optional":false}],"imports":[{"symbol":"Builder","correct":"from es_client import Builder"}],"quickstart":{"code":"import os\nfrom es_client import Builder\n\n# Configure Elasticsearch connection using environment variables for sensitive data\nconfig = {\n    'elasticsearch': {\n        'client': {\n            'hosts': os.environ.get('ES_HOSTS', 'https://localhost:9200').split(','),\n            'api_key': os.environ.get('ES_API_KEY', ''),\n            'ca_certs': os.environ.get('ES_CA_CERTS', ''), # e.g., '/etc/elasticsearch/certs/ca.crt'\n            'request_timeout': 60,\n        },\n        'other_settings': {\n            'master_only': False,\n            'username': os.environ.get('ES_USERNAME', ''),\n            'password': os.environ.get('ES_PASSWORD', ''),\n        }\n    },\n    'logging': {\n        'loglevel': 'INFO',\n        'logfile': '', # Path to log file, e.g., '/var/log/es_client.log'\n        'logformat': 'default',\n    }\n}\n\nbuilder = Builder(configdict=config)\ntry:\n    builder.connect()\n    client = builder.client # Get the connected Elasticsearch client instance\n    \n    # Example: Check cluster info\n    info = client.info()\n    print(\"Connected to Elasticsearch cluster:\", info['cluster_name'])\n    \n    # Example: Create an index\n    index_name = \"my_test_index\"\n    if not client.indices.exists(index=index_name):\n        client.indices.create(index=index_name)\n        print(f\"Index '{index_name}' created.\")\n    else:\n        print(f\"Index '{index_name}' already exists.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Uninstall `elasticsearch-dsl` and modify import statements from `from elasticsearch_dsl import Search` to `from elasticsearch.dsl import Search`.","message":"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`.","severity":"breaking","affected_versions":"elasticsearch-py >=8.18.0"},{"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.","message":"URL paths in client configuration were not always respected, leading to connection issues or incorrect endpoint targeting.","severity":"gotcha","affected_versions":"<9.0.2 (for 9.x series) and <8.19.4 (for 8.x series)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"8.19.0 - 8.19.1"},{"fix":"Always upgrade your Elasticsearch cluster to version 9.x *before* upgrading your `es-client` library to 9.0.0 or later.","message":"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.","severity":"breaking","affected_versions":"es-client >=9.0.0 (when connecting to Elasticsearch <9.0.0)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"ModuleNotFoundError: No module named 'elasticsearch8'"},{"fix":"Import `helpers` directly from `elasticsearch`: `from elasticsearch import helpers`. Then call functions like `helpers.bulk(client, actions)`.","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.","error":"AttributeError: 'Elasticsearch' object has no attribute 'helpers'"},{"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+.","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.","error":"ConnectionError: Connection refused"},{"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.","cause":"Attempting to use the `Builder` instance directly as the Elasticsearch client (e.g., `builder.info()`) before explicitly retrieving the client object.","error":"TypeError: 'Builder' object is not callable"}]}