Install & Compatibility
Where this runs
tested against v0.2.13 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.784s · 56.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.6s · import 0.724s · 55MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
connect
✓ from es.elastic.api import connect
create_engine
✓ from sqlalchemy.engine import create_engine
Used with the 'elasticsearch+http://' or 'odelasticsearch+https://' dialect.
Demonstrates connecting to an Elasticsearch/OpenSearch instance using the DBAPI interface, executing a basic SQL query, and listing available indices (tables). It highlights the critical environment variable for Elasticsearch 8.x compatibility.
import os
from es.elastic.api import connect
# IMPORTANT: For Elasticsearch 8.x, set ELASTIC_CLIENT_APIVERSIONING=1
# in your environment or before connecting to enable compatibility mode.
# os.environ['ELASTIC_CLIENT_APIVERSIONING'] = '1'
# Configure host and port. Adjust as necessary for your setup.
# For OpenSearch, a common port is 19200.
ES_HOST = os.environ.get('ES_HOST', 'localhost')
ES_PORT = int(os.environ.get('ES_PORT', 9200))
try:
# Connect to Elasticsearch/OpenSearch via DBAPI
conn = connect(host=ES_HOST, port=ES_PORT)
curs = conn.cursor()
# Execute a simple SQL query
curs.execute("SELECT 1")
result = curs.fetchall()
print(f"Connection successful. Query 'SELECT 1' returned: {result}")
# Example: List available tables (indices)
curs.execute("SHOW TABLES")
tables = curs.fetchall()
print(f"First 5 available tables (indices): {tables[:5]}...")
curs.close()
conn.close()
print("Successfully connected, queried, and closed connection.")
except Exception as e:
print(f"Failed to connect or query Elasticsearch/OpenSearch: {e}")
print("Please ensure your Elasticsearch/OpenSearch instance is running and accessible at ")
print(f"'{ES_HOST}:{ES_PORT}'. For Elasticsearch 8.x, ensure ELASTIC_CLIENT_APIVERSIONING is set.")
Debug
Known issues
breakingTo connect to Elasticsearch 8.x, the `ELASTIC_CLIENT_APIVERSIONING` environment variable must be set to `1` in your Python application. Failing to do so will result in connection or query errors due to API incompatibilities.fixSet `os.environ['ELASTIC_CLIENT_APIVERSIONING'] = '1'` in your application or as a system environment variable before initiating connections.
affects: All versions when connecting to Elasticsearch 8.x
gotchaThis library defaults to complying with SQL v1. If your Elasticsearch/OpenSearch SQL endpoint requires v2, you must pass `v2=true` as a query parameter in the connection string (e.g., `connect(host='localhost', v2=True)`).fixAdd `v2=True` to the `connect` function call or `create_engine` URL if using SQLAlchemy (e.g., `elasticsearch+http://localhost:9200/?v2=true`).
affects: All versions
gotchaThere are known limitations including lack of support for array type columns (which are excluded by SQLAlchemy's `get_columns`) and issues with indexes whose names start with a dot ('.'). Specific limitations also exist for AWS ES/OpenDistro, such as only being able to `GROUP BY` keyword fields and problems with indices containing dots (e.g., 'audit_log.2021.01.20').fixAvoid using array type columns or querying indices with leading dots or specific dot patterns where possible. For AWS ES, review `GROUP BY` usage to ensure it targets keyword fields. Consider using aliases for problematic index names.
affects: All versions
gotchaThe maximum number of rows fetched by a single query is limited to 10000 by default. This can lead to truncated results for larger datasets.fixAdjust the `fetch_size` parameter during connection (e.g., `connect(host='localhost', fetch_size=50000)`) to a higher value if you expect more results. Be mindful of memory consumption with very large fetch sizes.
affects: All versions
gotchaThe `elasticsearch-dbapi` library relies on the underlying `elasticsearch-py` and `opensearch-py` clients. Breaking changes in major versions of Elasticsearch or OpenSearch, or in their official Python clients, can indirectly impact the functionality or require configuration adjustments in `elasticsearch-dbapi` even if `elasticsearch-dbapi` itself doesn't have a breaking change.fixAlways review the breaking changes documentation for the specific Elasticsearch/OpenSearch version you are targeting and the corresponding `elasticsearch-py` or `opensearch-py` client versions when upgrading your cluster or clients.
affects: Dependent on underlying client/Elasticsearch/OpenSearch versions
Errors
Common errors & fixes
NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:elasticsearch.http
This error occurs when SQLAlchemy cannot find the registered dialect for 'elasticsearch+http', typically because `elasticsearch-dbapi` or its dependencies are not correctly installed or registered with SQLAlchemy.
fixEnsure `elasticsearch-dbapi` is installed in the active Python environment: `pip install elasticsearch-dbapi`. If using an existing environment, a reinstallation or environment refresh might be needed to register the dialect properly.
OperationalError: Error connecting to Elasticsearch:
This is a generic connection error indicating that `elasticsearch-dbapi` was unable to establish a connection to the Elasticsearch or OpenSearch cluster, often due to incorrect host/port, network issues, or the cluster being unavailable.
fixVerify the Elasticsearch/OpenSearch cluster is running and accessible from the client machine. Double-check the connection string's host and port. Example: `engine = create_engine("elasticsearch+http://localhost:9200/")`. TransportError(405, 'Incorrect HTTP method for uri [/_sql/] and method [POST], allowed: [GET, PUT, DELETE, HEAD]')
This error typically indicates that the connected Elasticsearch or OpenSearch cluster either does not support the SQL REST API at the `/_sql` endpoint or is an older version that expects a different HTTP method (e.g., GET) for SQL queries, while `elasticsearch-dbapi` uses POST.
fixEnsure the Elasticsearch/OpenSearch cluster has the SQL plugin enabled and is running a compatible version (Elasticsearch 7.x/8.x or OpenSearch 2.x) that supports POST requests to the `/_sql` endpoint. Also, check the cluster's configuration for SQL API settings. If using OpenSearch, consider adding `v2=true` to the connection string for SQL v2 compatibility if applicable: `engine = create_engine("opensearch+http://localhost:9200/?v2=true")`. AuthenticationException(401, 'security_exception', 'missing authentication credentials for REST request')
This error signifies that the connection attempt to Elasticsearch or OpenSearch failed due to missing or incorrect authentication credentials, meaning the cluster requires a username and password (or API key) which were not provided or were invalid.
fixProvide valid authentication credentials in your connection string or `connect_args`. For basic authentication, include username and password: `engine = create_engine("elasticsearch+http://user:password@localhost:9200/")`. For Elasticsearch 8.x with API key, refer to `elasticsearch-py` documentation for API key usage or ensure `ELASTIC_CLIENT_APIVERSIONING=1` is set in your environment if using compatibility mode. Elasticsearch-py X.Y.Z conficts with the elasticsearch-dbapi-0.2.1 which requires Elasticsearch-py<A.B.C.
This is a dependency conflict where a version of the `elasticsearch-py` client library already installed (or being installed) is incompatible with the version range required by `elasticsearch-dbapi`.
fixDowngrade or upgrade `elasticsearch-py` to a version compatible with `elasticsearch-dbapi==0.2.12`. For example, `elasticsearch-dbapi` 0.2.1 requires `elasticsearch-py<7.14`, so you might need to run `pip install elasticsearch-py=='7.13.0'` (or another compatible version) before or after installing `elasticsearch-dbapi`.
Upgrade
Version history
0.2.13latest on PyPI · released May 7, 2026
Audit
Dependencies
elasticsearchrequiredRequired for connecting to Elasticsearch clusters.
opensearch-pyrequiredRequired for connecting to OpenSearch clusters.
SQLAlchemyrequiredRequired for using the SQLAlchemy dialect.