Registry / database / opensearch-dsl

opensearch-dsl

JSON →
library2.1.0pypiunverified

The `opensearch-dsl` library provides a high-level, declarative Python client for OpenSearch, enabling users to work with OpenSearch entities like documents and search queries as Python objects. It simplifies query construction and common OpenSearch operations, building on top of the lower-level `opensearch-py` client. The current version is 2.1.0. It has been announced that this library will be deprecated after version 2.1.0, with its functionality merged into `opensearch-py`.

pip install opensearch-dsl
INSTALL
IMPORT
SIG · OPENSEARCH-DSL
O
opensearch-dsl
databaseenv2.1.0
Install
3.6s avg
Import
943ms
Disk
43MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
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
musl
py 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.001s · 50MB
glibc
py 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.
fix
Migrate 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.
fix
Remove 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.
fix
Always 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.
fix
This 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`.
fix
Refer 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.
Agent activity
16 hits · last 30 days
node
12
Resources

No resource links recorded.

opensearch-dsl — pip install opensearch-dsl · libregistry