Install & Compatibility
Where this runs
tested against v2.1.0 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.001s · 50MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.6s · import 0.884s · 48MB
43MB installed
● package 43MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenSearch
✓ from opensearchpy import OpenSearch
Search
✓ from opensearch_dsl import Search
Document
✓ from opensearch_dsl import Document
Text
✓ from opensearch_dsl import Text
Keyword
✓ from opensearch_dsl import Keyword
This quickstart demonstrates how to connect to an OpenSearch cluster, define a document schema using `opensearch-dsl.Document`, create an index, index a document, and perform a search query. It uses environment variables for OpenSearch connection details, which is recommended for production settings.
import os
from opensearchpy import OpenSearch
from opensearch_dsl import Document, Text, Keyword, Search
# Configuration from environment variables for security and flexibility
OPENSEARCH_HOST = os.environ.get('OPENSEARCH_HOST', 'localhost')
OPENSEARCH_PORT = int(os.environ.get('OPENSEARCH_PORT', 9200))
OPENSEARCH_USER = os.environ.get('OPENSEARCH_USER', 'admin')
OPENSEARCH_PASSWORD = os.environ.get('OPENSEARCH_PASSWORD', 'admin')
OPENSEARCH_CA_CERTS = os.environ.get('OPENSEARCH_CA_CERTS', None) # e.g., '/full/path/to/root-ca.pem'
# Create the OpenSearch client
client = OpenSearch(
hosts=[{'host': OPENSEARCH_HOST, 'port': OPENSEACH_PORT}],
http_compress=True, # enables gzip compression for request bodies
http_auth=(OPENSEARCH_USER, OPENSEARCH_PASSWORD),
use_ssl=True if OPENSEARCH_HOST != 'localhost' else False, # Use SSL for non-localhost
verify_certs=True,
ssl_assert_hostname=False, # Disable hostname verification for testing/local setups
ssl_show_warn=False,
ca_certs=OPENSEARCH_CA_CERTS
)
index_name = 'my-dsl-index'
# 1. Define a Document class
class MyDocument(Document):
title = Text(fields={'raw': Keyword()})
description = Text()
category = Keyword()
class Index:
name = index_name
settings = {
'number_of_shards': 1,
'number_of_replicas': 0
}
# 2. Create the index (if it doesn't exist)
if not client.indices.exists(index_name):
response = client.indices.create(index_name, body=MyDocument._index.to_dict())
print('Creating index:', response)
# 3. Index a document
doc = MyDocument(meta={'id': '1'}, title='Python Basics', description='A guide to Python programming', category='programming')
doc.save(using=client)
print('Indexed document:', doc.to_dict())
# 4. Refresh the index to make the document searchable
client.indices.refresh(index=index_name)
# 5. Search for the document
s = Search(using=client, index=index_name)
s = s.filter('term', category='programming').query('match', title='python')
response = s.execute()
print('\nSearch results:')
for hit in response:
print(f"Score: {hit.meta.score}, Title: {hit.title}, Category: {hit.category}")
# 6. Clean up: Delete the document and then the index (optional)
# client.delete(index=index_name, id='1', refresh=True)
# print('\nDeleted document with id 1')
# client.indices.delete(index=index_name)
# print('Deleted index:', index_name)
Debug
Known issues
deprecatedThe `opensearch-dsl-py` library is being deprecated after version 2.1.0. All its functionality has been merged into the lower-level `opensearch-py` client. Users are strongly encouraged to migrate to `opensearch-py` directly.fixMigrate your code to use `opensearch-py` directly. The DSL-like capabilities are now available within `opensearch-py`.
affects: 2.1.0 and later
breakingOpenSearch 2.0 (and thus `opensearch-dsl` 2.0+) removed the `_type` mapping parameter. This means that documents no longer have an explicit `_type` field for mapping.fixRemove any explicit usage of `_type` in your document definitions and queries. Indexes are now categorized by document type implicitly, and mapping types are no longer supported by the OpenSearch server.
affects: 2.0.0 and later
gotchaCompatibility between `opensearch-dsl` and OpenSearch server versions is crucial. For OpenSearch 2.0 and later, only OpenSearch clients (like `opensearch-dsl` 2.x and `opensearch-py` 2.x) are fully compatible. Using older Elasticsearch clients or mixing client/server versions carries a high risk of errors.fixAlways align your `opensearch-dsl` (or `opensearch-py`) client version with your OpenSearch cluster version (e.g., `opensearch-dsl` 2.x with OpenSearch 2.x).
affects: 2.0.0 and later
gotchaAfter migrating from `opensearch-dsl` to `opensearch-py` (which now includes DSL features), some users reported `mypy` type checking errors with ported resources like `Search` and `Response` objects due to incomplete type hints.fixThis might require temporary `# type: ignore` comments for affected lines, or contributing to the `opensearch-py` project to improve its type hints.
affects: `opensearch-py` versions after `opensearch-dsl` merger (e.g., 2.2.0+)
gotchaPost-deprecation, documentation for the DSL features within `opensearch-py` can be hard to find, leading to confusion for users transitioning from `opensearch-dsl-py`.fixRefer to the archived `opensearch-dsl-py` documentation or GitHub samples for common DSL patterns, and consult `opensearch-py`'s general client documentation. This is an ongoing documentation issue.
affects: Current `opensearch-py` versions
Upgrade
Version history
2.1.0latest on PyPI · released Mar 21, 2023
Audit
Dependencies
opensearch-pyrequired`opensearch-dsl` is built on top of `opensearch-py`, the low-level client.
Python >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*requiredMinimum Python version requirement.
Resources
No resource links recorded.