Registry /
workflow / apache-airflow-providers-opensearch
Install & Compatibility
Where this runs
tested against v1.9.3 · 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.920 runs
installs and imports cleanly · install 0.0s · import 5.456s · 255.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 23.2s · import 5.012s · 254MB
256MB installed
● package 256MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenSearchHook
✓ from airflow.providers.opensearch.hooks.opensearch import OpenSearchHook
OpenSearchOperator
✓ from airflow.providers.opensearch.operators.opensearch import OpenSearchOperator
OpenSearchIngestOperator
✓ from airflow.providers.opensearch.operators.opensearch_ingest import OpenSearchIngestOperator
✗ from airflow.providers.opensearch.operators.opensearch import OpenSearchIngestOperator
The Ingest Operator is in a separate module.
OpenSearchIndexSensor
✓ from airflow.providers.opensearch.sensors.opensearch import OpenSearchIndexSensor
This quickstart DAG demonstrates how to use the `OpenSearchOperator` to perform a simple GET request to the OpenSearch cluster's `_cluster/health` endpoint. Before running, ensure you have an OpenSearch connection configured in your Airflow environment with the `conn_id` set to `opensearch_default`.
from __future__ import annotations
import pendulum
from airflow.models.dag import DAG
from airflow.providers.opensearch.operators.opensearch import OpenSearchOperator
with DAG(
dag_id="opensearch_example_dag",
schedule=None,
start_date=pendulum.datetime(2023, 1, 1, tz="UTC"),
catchup=False,
tags=["opensearch", "example"],
) as dag:
# Configure an OpenSearch connection in Airflow UI (Admin -> Connections)
# with conn_id='opensearch_default'. Example:
# Conn Id: opensearch_default
# Conn Type: OpenSearch
# Host: http://localhost
# Port: 9200
# Scheme: http (or https)
# Verify SSL: False (for local dev, use True in prod)
check_opensearch_health = OpenSearchOperator(
task_id="check_opensearch_health",
conn_id="opensearch_default",
endpoint="_cluster/health",
method="GET",
log_response=True,
)
# You can also perform data ingestion
# ingest_document = OpenSearchOperator(
# task_id="ingest_example_document",
# conn_id="opensearch_default",
# endpoint="my_index/_doc/1",
# method="POST",
# data={"field": "value"},
# headers={"Content-Type": "application/json"},
# log_response=True,
# )
# check_opensearch_health >> ingest_document
airflow --version
Debug
Known issues
gotchaThe `conn_id` for OpenSearch connections (commonly `opensearch_default`) must be correctly configured in the Airflow UI or `airflow.cfg`. Missing or incorrect connection details are a frequent cause of 'Connection not found' or network errors.fixEnsure the connection with the specified `conn_id` exists, has 'OpenSearch' as connection type, and correct host, port, scheme, and credentials. Test the connection in the Airflow UI.
affects: All versions
breakingChanges in Airflow core or `opensearch-py` client library versions can lead to incompatibilities. Always check the provider's `min_airflow_version` and test against your specific OpenSearch cluster version.fixRefer to the official Airflow provider documentation for compatibility matrices. Upgrade both `apache-airflow` and `apache-airflow-providers-opensearch` to compatible versions. Pin `opensearch-py` if specific version is required by your OpenSearch cluster.
affects: Across major Airflow and `opensearch-py` releases.
gotchaSSL/TLS certificate verification errors are common when connecting to OpenSearch clusters using self-signed certificates or when the certificate chain is not properly trusted by the Airflow worker environment.fixFor development, you can set `verify_ssl=False` in the connection extra settings (though not recommended for production). For production, ensure the necessary CA certificates are installed on the Airflow worker machines or provide the certificate path in the connection configuration.
affects: All versions, depending on environment configuration.
gotchaThe OpenSearch provider was forked from the Elasticsearch provider. While largely compatible, be aware of specific OpenSearch features or API differences. Direct migration from `apache-airflow-providers-elasticsearch` might require minor adjustments.fixThoroughly review your DAGs and connection configurations when migrating. Consult OpenSearch documentation for any API changes compared to Elasticsearch.
affects: Users migrating from older Elasticsearch providers.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'airflow.providers.opensearch'
The `apache-airflow-providers-opensearch` package has not been installed in your Airflow environment.
fixRun `pip install apache-airflow-providers-opensearch` to install the provider.
airflow.exceptions.AirflowException: The conn_id 'opensearch_default' is not defined
Airflow cannot find a connection named 'opensearch_default' (or whatever `conn_id` you specified) in its metadata database.
fixGo to Airflow UI -> Admin -> Connections and create a new connection. Set 'Conn Id' to `opensearch_default` and 'Conn Type' to 'OpenSearch', then fill in the host, port, and other details for your OpenSearch instance.
opensearch.exceptions.ConnectionError: Connection refused
The Airflow worker cannot establish a network connection to the specified OpenSearch host and port. This could be due to an incorrect host/port, OpenSearch not running, or firewall issues.
fixVerify the OpenSearch service is running and accessible from your Airflow worker. Check the `Host` and `Port` in your OpenSearch connection configuration. Ensure no firewalls are blocking the connection.
opensearch.exceptions.TransportError(401, 'security_exception', 'no permissions for [cluster:monitor/health] and User [name=airflow, backend_roles=[], requestedTenant=null]')
The OpenSearch user configured in your connection does not have sufficient permissions to perform the requested operation.
fixEnsure the user/role associated with your OpenSearch connection has the necessary permissions (e.g., `cluster_monitor` for `_cluster/health`, `indices:data/write/document` for ingestion) in your OpenSearch Security configuration.
Upgrade
Version history
1.9.3latest on PyPI · released Jun 7, 2026
Audit
Dependencies
apache-airflowrequiredThis is an Airflow provider and requires Airflow to run.
opensearch-pyrequiredThe provider uses the official Python client for OpenSearch internally.