0
# OpenSearch Python Client
1

2
A comprehensive Python client library for OpenSearch, an open-source search and analytics engine. The client provides both synchronous and asynchronous APIs for performing search operations, document indexing, cluster management, and administrative tasks with advanced features including SSL/TLS configuration, authentication mechanisms, connection pooling, and extensive plugin support.
3

4
## Package Information
5

6
- **Package Name**: opensearch-py
7
- **Language**: Python
8
- **Installation**: `pip install opensearch-py`
9
- **Version**: 3.0.0
10

11
## Core Imports
12

13
Basic client import:
14

15
```python
16
from opensearchpy import OpenSearch
17
```
18

19
Async client import:
20

21
```python
22
from opensearchpy import AsyncOpenSearch
23
```
24

25
DSL imports for search and document modeling:
26

27
```python
28
from opensearchpy import Search, Q, A, Document, Mapping
29
```
30

31
Helper function imports:
32

33
```python
34
from opensearchpy.helpers import bulk, scan, reindex
35
```
36

37
Analysis function imports:
38

39
```python
40
from opensearchpy import analyzer, tokenizer, token_filter, char_filter, normalizer
41
```
42

43
Authentication imports:
44

45
```python
46
from opensearchpy import RequestsAWSV4SignerAuth
47
```
48

49
## Basic Usage
50

51
### Basic Client Setup
52

53
```python
54
from opensearchpy import OpenSearch
55

56
# Basic client with host and port
57
client = OpenSearch(
58
    hosts=[{'host': 'localhost', 'port': 9200}],
59
    http_compress=True,
60
    use_ssl=True,
61
    verify_certs=True,
62
    ssl_assert_hostname=False,
63
    ssl_show_warn=False,
64
)
65

66
# Test connection
67
response = client.ping()
68
print(response)  # True if successful
69

70
# Get cluster info
71
info = client.info()
72
print(info)
73
```
74

75
### Basic Search Operations
76

77
```python
78
# Index a document
79
doc = {
80
    'title': 'OpenSearch Python Client',
81
    'content': 'This is a sample document for indexing',
82
    'timestamp': '2024-01-01T00:00:00'
83
}
84

85
response = client.index(
86
    index='sample-index',
87
    id='1',
88
    body=doc
89
)
90

91
# Search for documents
92
search_body = {
93
    'query': {
94
        'match': {
95
            'title': 'OpenSearch'
96
        }
97
    }
98
}
99

100
results = client.search(
101
    index='sample-index',
102
    body=search_body
103
)
104

105
print(results['hits']['hits'])
106
```
107

108
### Basic DSL Usage
109

110
```python
111
from opensearchpy import Search, Q
112

113
# Create a search object
114
s = Search(using=client, index='sample-index')
115

116
# Add a query using Q object
117
s = s.query(Q('match', title='OpenSearch'))
118

119
# Execute the search
120
response = s.execute()
121

122
for hit in response:
123
    print(hit.title, hit.content)
124
```
125

126
## Architecture
127

128
The OpenSearch Python client provides a multi-layered architecture:
129

130
- **Client Layer**: `OpenSearch` and `AsyncOpenSearch` classes provide the main interface
131
- **Namespaced APIs**: Specialized clients for different OpenSearch APIs (cat, cluster, indices, etc.)
132
- **Plugin Support**: Dedicated clients for OpenSearch plugins (security, alerting, ML, etc.)
133
- **Transport Layer**: HTTP transport handling with connection pooling and retry logic
134
- **DSL Layer**: Domain-specific language for query building and document modeling
135
- **Helper Functions**: High-level utilities for common operations like bulk indexing
136

137
## Capabilities
138

139
### Core Client Operations
140

141
Essential OpenSearch operations including document indexing, searching, updating, and deletion. Provides both low-level API access and high-level convenience methods for interacting with OpenSearch clusters.
142

143
```python { .api }
144
class OpenSearch:
145
    def ping(self, **kwargs): ...
146
    def info(self, **kwargs): ...
147
    def search(self, index=None, body=None, **kwargs): ...
148
    def index(self, index, body, id=None, **kwargs): ...
149
    def get(self, index, id, **kwargs): ...
150
    def update(self, index, id, body, **kwargs): ...
151
    def delete(self, index, id, **kwargs): ...
152
    def bulk(self, body, index=None, **kwargs): ...
153
    def count(self, index=None, body=None, **kwargs): ...
154
    def exists(self, index, id, **kwargs): ...
155
```
156

157
[Core Client Operations](./core-client.md)
158

159
### Namespaced APIs
160

161
Specialized clients for different aspects of OpenSearch cluster management including indices, cluster operations, node management, and administrative functions.
162

163
```python { .api }
164
class OpenSearch:
165
    @property
166
    def indices(self) -> IndicesClient: ...
167
    @property 
168
    def cluster(self) -> ClusterClient: ...
169
    @property
170
    def cat(self) -> CatClient: ...
171
    @property
172
    def nodes(self) -> NodesClient: ...
173
    @property
174
    def ingest(self) -> IngestClient: ...
175
    @property
176
    def snapshot(self) -> SnapshotClient: ...
177
    @property
178
    def tasks(self) -> TasksClient: ...
179
```
180

181
[Namespaced APIs](./namespaced-apis.md)
182

183
### Plugin APIs
184

185
Dedicated clients for OpenSearch plugins providing advanced functionality like security, machine learning, alerting, and specialized search capabilities.
186

187
```python { .api }
188
class OpenSearch:
189
    @property
190
    def security(self) -> SecurityClient: ...
191
    @property
192
    def ml(self) -> MlClient: ...
193
    @property
194
    def alerting(self) -> AlertingClient: ...
195
    @property
196
    def sql(self) -> SqlClient: ...
197
    @property
198
    def knn(self) -> KnnClient: ...
199
    @property
200
    def neural(self) -> NeuralClient: ...
201
    @property
202
    def geospatial(self) -> GeospatialClient: ...
203
    @property
204
    def observability(self) -> ObservabilityClient: ...
205
    @property
206
    def replication(self) -> ReplicationClient: ...
207
    @property
208
    def search_relevance(self) -> SearchRelevanceClient: ...
209
    @property
210
    def ltr(self) -> LtrClient: ...
211
    @property
212
    def query(self) -> QueryClient: ...
213
```
214

215
[Plugin APIs](./plugin-apis.md)
216

217
### DSL and Query Building
218

219
Domain-specific language for building complex search queries, aggregations, and document models with a Pythonic API that abstracts OpenSearch's JSON-based query syntax.
220

221
```python { .api }
222
class Search:
223
    def __init__(self, using=None, index=None): ...
224
    def query(self, query): ...
225
    def filter(self, filter): ...
226
    def aggs(self, aggs): ...
227
    def sort(self, *keys): ...
228
    def execute(self): ...
229

230
class Q:
231
    @classmethod
232
    def match(cls, **kwargs): ...
233
    @classmethod
234
    def term(cls, **kwargs): ...
235
    @classmethod
236
    def range(cls, **kwargs): ...
237
    @classmethod
238
    def bool(cls, **kwargs): ...
239
```
240

241
[DSL and Query Building](./dsl-queries.md)
242

243
### Document Modeling
244

245
Object-relational mapping (ORM) style document modeling with field definitions, automatic mapping generation, and validation for structured data handling in OpenSearch.
246

247
```python { .api }
248
class Document:
249
    def __init__(self, **kwargs): ...
250
    def save(self, **kwargs): ...
251
    def delete(self, **kwargs): ...
252
    @classmethod
253
    def get(cls, id, **kwargs): ...
254
    @classmethod
255
    def search(cls): ...
256

257
class Mapping:
258
    def __init__(self): ...
259
    def field(self, name, field_type, **kwargs): ...
260
    def save(self, index, **kwargs): ...
261
```
262

263
[Document Modeling](./document-modeling.md)
264

265
### Helper Functions
266

267
High-level utility functions for common operations like bulk indexing, scanning large result sets, and data reindexing with built-in error handling and performance optimizations.
268

269
```python { .api }
270
def bulk(client, actions, **kwargs):
271
    """
272
    Perform bulk indexing operations.
273
    
274
    Parameters:
275
    - client: OpenSearch client instance
276
    - actions: iterable of action dictionaries
277
    - chunk_size: number of docs per chunk (default: 500)
278
    - max_chunk_bytes: max size per chunk in bytes
279
    - thread_count: number of parallel threads
280
    
281
    Returns:
282
    Tuple of (success_count, failed_actions)
283
    """
284

285
def scan(client, query=None, scroll='5m', **kwargs):
286
    """
287
    Scan search results for large datasets.
288
    
289
    Parameters:
290
    - client: OpenSearch client instance  
291
    - query: search query body
292
    - scroll: scroll timeout
293
    - index: index name(s)
294
    
295
    Yields:
296
    Individual document hits
297
    """
298
```
299

300
[Helper Functions](./helper-functions.md)
301

302
### Authentication and Security
303

304
Authentication mechanisms including AWS IAM integration, SSL/TLS configuration, and security features for secure connections to OpenSearch clusters.
305

306
```python { .api }
307
class RequestsAWSV4SignerAuth:
308
    def __init__(self, credentials, region, service='es'): ...
309

310
class OpenSearch:
311
    def __init__(
312
        self,
313
        hosts=None,
314
        http_auth=None,
315
        use_ssl=False,
316
        verify_certs=True,
317
        ssl_context=None,
318
        **kwargs
319
    ): ...
320
```
321

322
[Authentication and Security](./authentication.md)
323

324
### Async Operations
325

326
Asynchronous client operations using Python's asyncio for high-performance applications requiring concurrent OpenSearch operations.
327

328
```python { .api }
329
class AsyncOpenSearch:
330
    async def ping(self, **kwargs): ...
331
    async def info(self, **kwargs): ...
332
    async def search(self, index=None, body=None, **kwargs): ...
333
    async def index(self, index, body, id=None, **kwargs): ...
334
    async def bulk(self, body, index=None, **kwargs): ...
335
```
336

337
[Async Operations](./async-operations.md)
338

339
## Exception Handling
340

341
The client provides a comprehensive exception hierarchy for handling different types of errors:
342

343
```python { .api }
344
class OpenSearchException(Exception): ...
345
class TransportError(OpenSearchException): ...
346
class ConnectionError(TransportError): ...
347
class RequestError(TransportError): ...  # HTTP 400
348
class AuthenticationException(RequestError): ...  # HTTP 401
349
class AuthorizationException(RequestError): ...  # HTTP 403
350
class NotFoundError(RequestError): ...  # HTTP 404
351
class ConflictError(RequestError): ...  # HTTP 409
352
```
353

354
## Version Information
355

356
```python { .api }
357
__version__: tuple  # Version tuple (major, minor, patch)
358
__versionstr__: str  # Version string
359
VERSION: tuple  # Version tuple alias
360
```
361

362
## Type Definitions
363

364
### Core Types
365

366
```python { .api }
367
from typing import Any, Dict, List, Optional, Union
368

369
# Common type aliases used throughout the API
370
JsonDict = Dict[str, Any]
371
JsonList = List[Any]
372
JsonValue = Union[str, int, float, bool, None, JsonDict, JsonList]
373

374
# Client configuration types
375
HostConfig = Union[str, Dict[str, Any]]
376
HostsList = List[HostConfig]
377

378
# Authentication types  
379
AuthType = Union[tuple, callable, Any]
380
```