0
# OpenSearch
1

2
OpenSearch is a distributed, RESTful search and analytics engine built as a community-driven fork of Elasticsearch. It provides a comprehensive Java API for building search-enabled applications, managing distributed clusters, and extending functionality through a rich plugin ecosystem.
3

4
## Package Information
5

6
- **Package Name**: org.opensearch:opensearch
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>org.opensearch</groupId>
14
    <artifactId>opensearch</artifactId>
15
    <version>3.1.0</version>
16
</dependency>
17
```
18

19
Or Gradle `build.gradle`:
20

21
```groovy
22
implementation 'org.opensearch:opensearch:3.1.0'
23
```
24

25
## Core Imports
26

27
```java
28
// Core client interfaces
29
import org.opensearch.transport.client.Client;
30
import org.opensearch.transport.client.AdminClient;
31
import org.opensearch.client.RestClient;
32
import org.opensearch.OpenSearchException;
33

34
// Action framework
35
import org.opensearch.core.action.ActionRequest;
36
import org.opensearch.core.action.ActionResponse;
37
import org.opensearch.core.action.ActionListener;
38
import org.opensearch.common.action.ActionFuture;
39

40
// Document operations
41
import org.opensearch.action.index.IndexRequest;
42
import org.opensearch.action.index.IndexResponse;
43
import org.opensearch.action.index.IndexRequestBuilder;
44
import org.opensearch.action.get.GetRequest;
45
import org.opensearch.action.get.GetResponse;
46
import org.opensearch.action.get.GetRequestBuilder;
47
import org.opensearch.action.update.UpdateRequest;
48
import org.opensearch.action.update.UpdateResponse;
49
import org.opensearch.action.delete.DeleteRequest;
50
import org.opensearch.action.delete.DeleteResponse;
51
import org.opensearch.action.bulk.BulkRequest;
52
import org.opensearch.action.bulk.BulkResponse;
53

54
// Search operations  
55
import org.opensearch.action.search.SearchRequest;
56
import org.opensearch.action.search.SearchResponse;
57
import org.opensearch.action.search.SearchRequestBuilder;
58
import org.opensearch.search.builder.SearchSourceBuilder;
59

60
// Point-in-time operations
61
import org.opensearch.action.search.CreatePitRequest;
62
import org.opensearch.action.search.CreatePitResponse;
63
import org.opensearch.action.search.DeletePitRequest;
64
import org.opensearch.action.search.DeletePitResponse;
65

66
// Query DSL
67
import org.opensearch.index.query.QueryBuilders;
68
import org.opensearch.index.query.QueryBuilder;
69
import org.opensearch.index.query.BoolQueryBuilder;
70
import org.opensearch.index.query.MatchQueryBuilder;
71

72
// Settings and configuration
73
import org.opensearch.common.settings.Settings;
74
```
75

76
## Basic Usage
77

78
```java
79
import org.opensearch.client.RestClient;
80
import org.opensearch.client.RestClientBuilder;
81
import org.opensearch.action.index.IndexRequest;
82
import org.opensearch.action.index.IndexResponse;
83
import org.opensearch.action.search.SearchRequest;
84
import org.opensearch.action.search.SearchResponse;
85
import org.opensearch.search.builder.SearchSourceBuilder;
86
import org.opensearch.index.query.QueryBuilders;
87
import org.apache.http.HttpHost;
88

89
// Create REST client
90
RestClient restClient = RestClient.builder(
91
    new HttpHost("localhost", 9200, "http")
92
).build();
93

94
// Index a document
95
IndexRequest indexRequest = new IndexRequest("products")
96
    .id("1")
97
    .source("name", "Laptop", "price", 999.99, "category", "electronics");
98

99
// Perform search
100
SearchRequest searchRequest = new SearchRequest("products");
101
SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
102
searchSourceBuilder.query(QueryBuilders.matchQuery("category", "electronics"));
103
searchSourceBuilder.size(10);
104
searchRequest.source(searchSourceBuilder);
105

106
// Handle response (using high-level client pattern)
107
SearchResponse searchResponse = /* execute search */;
108
System.out.println("Total hits: " + searchResponse.getHits().getTotalHits().value);
109

110
// Always close resources
111
restClient.close();
112
```
113

114
## Architecture
115

116
OpenSearch's Java API is built around several key architectural components:
117

118
### Core Client Layer
119
- **Client Interface**: Unified interface for all OpenSearch operations
120
- **REST Client**: Low-level HTTP client for direct REST API access
121
- **Transport Client**: Internal cluster communication layer
122
- **Node Client**: Direct in-process node access
123

124
### Action Framework
125
- **Actions**: Typed operations (search, index, delete, cluster management)
126
- **Requests/Responses**: Strongly-typed request and response objects
127
- **Builders**: Fluent API for constructing complex requests
128
- **Listeners**: Async callback patterns for non-blocking operations
129

130
### Search Engine
131
- **Query DSL**: Comprehensive query language with builders
132
- **Aggregation Framework**: Statistical and analytical computations
133
- **Search Phases**: Multi-phase search execution (query, fetch, etc.)
134
- **Source Builders**: Composable search request construction
135

136
### Index Management
137
- **Index APIs**: Creation, deletion, configuration of indices
138
- **Mapping Management**: Field type definitions and analysis
139
- **Settings**: Index-level and cluster-level configuration
140
- **Lifecycle Operations**: Open, close, refresh, merge operations
141

142
### Cluster Coordination
143
- **Cluster State**: Distributed state management
144
- **Node Discovery**: Automatic cluster member detection  
145
- **Shard Management**: Data distribution and replication
146
- **Health Monitoring**: Cluster and index health reporting
147

148
### Extension Framework
149
- **Plugin System**: Modular extension points throughout the system
150
- **Custom Actions**: User-defined operations and endpoints
151
- **Analysis Plugins**: Custom text processing and tokenization
152
- **Engine Plugins**: Alternative storage implementations
153

154
## Capabilities
155

156
### Client APIs
157

158
Core client interfaces and transport mechanisms for connecting to and communicating with OpenSearch clusters.
159

160
```java { .api }
161
interface Client extends OpenSearchClient, Releasable {
162
    // Administrative client access
163
    AdminClient admin();
164
    
165
    // Document operations
166
    ActionFuture<IndexResponse> index(IndexRequest request);
167
    void index(IndexRequest request, ActionListener<IndexResponse> listener);
168
    IndexRequestBuilder prepareIndex();
169
    IndexRequestBuilder prepareIndex(String index);
170
    
171
    ActionFuture<GetResponse> get(GetRequest request);
172
    void get(GetRequest request, ActionListener<GetResponse> listener);
173
    GetRequestBuilder prepareGet();
174
    GetRequestBuilder prepareGet(String index, String id);
175
    
176
    ActionFuture<UpdateResponse> update(UpdateRequest request);
177
    void update(UpdateRequest request, ActionListener<UpdateResponse> listener);
178
    UpdateRequestBuilder prepareUpdate();
179
    UpdateRequestBuilder prepareUpdate(String index, String id);
180
    
181
    ActionFuture<DeleteResponse> delete(DeleteRequest request);
182
    void delete(DeleteRequest request, ActionListener<DeleteResponse> listener);
183
    DeleteRequestBuilder prepareDelete();
184
    DeleteRequestBuilder prepareDelete(String index, String id);
185
    
186
    // Bulk operations
187
    ActionFuture<BulkResponse> bulk(BulkRequest request);
188
    void bulk(BulkRequest request, ActionListener<BulkResponse> listener);
189
    BulkRequestBuilder prepareBulk();
190
    BulkRequestBuilder prepareBulk(String globalIndex);
191
    
192
    // Search operations
193
    ActionFuture<SearchResponse> search(SearchRequest request);
194
    void search(SearchRequest request, ActionListener<SearchResponse> listener);
195
    SearchRequestBuilder prepareSearch(String... indices);
196
    
197
    ActionFuture<SearchResponse> searchScroll(SearchScrollRequest request);
198
    void searchScroll(SearchScrollRequest request, ActionListener<SearchResponse> listener);
199
    SearchScrollRequestBuilder prepareSearchScroll(String scrollId);
200
    
201
    // Point-in-time operations
202
    void createPit(CreatePitRequest createPITRequest, ActionListener<CreatePitResponse> listener);
203
    void deletePits(DeletePitRequest deletePITRequest, ActionListener<DeletePitResponse> listener);
204
    void getAllPits(GetAllPitNodesRequest getAllPitNodesRequest, ActionListener<GetAllPitNodesResponse> listener);
205
    void pitSegments(PitSegmentsRequest pitSegmentsRequest, ActionListener<IndicesSegmentResponse> listener);
206
    
207
    // Multi-operations
208
    ActionFuture<MultiGetResponse> multiGet(MultiGetRequest request);
209
    void multiGet(MultiGetRequest request, ActionListener<MultiGetResponse> listener);
210
    MultiGetRequestBuilder prepareMultiGet();
211
    
212
    ActionFuture<MultiSearchResponse> multiSearch(MultiSearchRequest request);
213
    void multiSearch(MultiSearchRequest request, ActionListener<MultiSearchResponse> listener);
214
    MultiSearchRequestBuilder prepareMultiSearch();
215
    
216
    // Advanced operations
217
    ActionFuture<TermVectorsResponse> termVectors(TermVectorsRequest request);
218
    void termVectors(TermVectorsRequest request, ActionListener<TermVectorsResponse> listener);
219
    TermVectorsRequestBuilder prepareTermVectors();
220
    TermVectorsRequestBuilder prepareTermVectors(String index, String id);
221
    
222
    ActionFuture<ExplainResponse> explain(ExplainRequest request);
223
    void explain(ExplainRequest request, ActionListener<ExplainResponse> listener);
224
    ExplainRequestBuilder prepareExplain(String index, String id);
225
    
226
    ActionFuture<FieldCapabilitiesResponse> fieldCaps(FieldCapabilitiesRequest request);
227
    void fieldCaps(FieldCapabilitiesRequest request, ActionListener<FieldCapabilitiesResponse> listener);
228
    FieldCapabilitiesRequestBuilder prepareFieldCaps(String... indices);
229
    
230
    // View operations
231
    void searchView(SearchViewAction.Request request, ActionListener<SearchResponse> listener);
232
    ActionFuture<SearchResponse> searchView(SearchViewAction.Request request);
233
    void listViewNames(ListViewNamesAction.Request request, ActionListener<ListViewNamesAction.Response> listener);
234
    ActionFuture<ListViewNamesAction.Response> listViewNames(ListViewNamesAction.Request request);
235
    
236
    // Utility methods
237
    Settings settings();
238
    Client filterWithHeader(Map<String, String> headers);
239
    Client getRemoteClusterClient(String clusterAlias);
240
    void close();
241
}
242
```
243

244
[Client APIs](./client-apis.md)
245

246
### Search APIs
247

248
Comprehensive search functionality including the Query DSL, aggregations, search builders, and advanced search features like scrolling and point-in-time.
249

250
```java { .api }
251
class SearchRequest extends ActionRequest {
252
    SearchRequest(String... indices);
253
    SearchRequest source(SearchSourceBuilder sourceBuilder);
254
    SearchRequest routing(String routing);
255
    SearchRequest timeout(String timeout);
256
}
257

258
class SearchSourceBuilder {
259
    SearchSourceBuilder query(QueryBuilder query);
260
    SearchSourceBuilder aggregation(AggregationBuilder aggregation);
261
    SearchSourceBuilder size(int size);
262
    SearchSourceBuilder from(int from);
263
}
264
```
265

266
[Search APIs](./search-apis.md)
267

268
### Index Management
269

270
APIs for creating, configuring, and managing indices including mappings, settings, and index lifecycle operations.
271

272
```java { .api }
273
class CreateIndexRequest extends ActionRequest {
274
    CreateIndexRequest(String index);
275
    CreateIndexRequest mapping(String source, XContentType xContentType);
276
    CreateIndexRequest settings(Settings settings);
277
}
278

279
class GetMappingsRequest extends ActionRequest {
280
    GetMappingsRequest(String... indices);
281
    GetMappingsRequest local(boolean local);
282
}
283
```
284

285
[Index Management](./index-management.md)
286

287
### Cluster Management
288

289
Cluster state monitoring, node management, health checks, and cluster-wide settings configuration.
290

291
```java { .api }
292
class ClusterHealthRequest extends ActionRequest {
293
    ClusterHealthRequest(String... indices);
294
    ClusterHealthRequest timeout(String timeout);
295
    ClusterHealthRequest waitForStatus(ClusterHealthStatus status);
296
}
297

298
class NodesInfoRequest extends ActionRequest {
299
    NodesInfoRequest(String... nodeIds);
300
    NodesInfoRequest addMetrics(String... metrics);
301
}
302
```
303

304
[Cluster Management](./cluster-management.md)
305

306
### Action Framework
307

308
Core action system for document operations, bulk processing, and the underlying request/response infrastructure.
309

310
```java { .api }
311
abstract class ActionRequest implements Streamable {
312
    ActionRequest validate();
313
}
314

315
class IndexRequest extends DocWriteRequest<IndexRequest> {
316
    IndexRequest(String index);
317
    IndexRequest source(String source, XContentType xContentType);
318
    IndexRequest id(String id);
319
}
320

321
class BulkRequest extends ActionRequest {
322
    BulkRequest add(DocWriteRequest<?> request);
323
    BulkRequest timeout(String timeout);
324
}
325
```
326

327
[Action Framework](./action-framework.md)
328

329
### Plugin Framework
330

331
Extensible plugin system for adding custom functionality including actions, search components, analysis, and storage engines.
332

333
```java { .api }
334
abstract class Plugin {
335
    Collection<Module> createGuiceModules();
336
    Settings additionalSettings();
337
}
338

339
interface ActionPlugin {
340
    List<ActionHandler<? extends ActionRequest, ? extends ActionResponse>> getActions();
341
    List<RestHandler> getRestHandlers(Settings settings, RestController restController, 
342
        ClusterSettings clusterSettings, IndexScopedSettings indexScopedSettings);
343
}
344
```
345

346
[Plugin Framework](./plugin-framework.md)
347

348
## Exception Handling
349

350
OpenSearch uses a hierarchical exception system for comprehensive error handling:
351

352
```java { .api }
353
class OpenSearchException extends RuntimeException {
354
    RestStatus status();
355
    String getIndex();
356
    Integer getShardId();
357
    String getResourceId();
358
    Map<String, List<String>> getMetadata();
359
}
360

361
// Timeout and execution exceptions
362
class OpenSearchTimeoutException extends OpenSearchException {}
363
class ClusterBlockException extends OpenSearchException {}
364
class UnavailableShardsException extends OpenSearchException {}
365

366
// Security and authorization
367
class OpenSearchSecurityException extends OpenSearchException {}
368

369
// Resource management exceptions
370
class ResourceNotFoundException extends OpenSearchException {}
371
class ResourceAlreadyExistsException extends OpenSearchException {}
372
class IndexNotFoundException extends ResourceNotFoundException {}
373
class DocumentMissingException extends ResourceNotFoundException {}
374

375
// Index and mapping exceptions
376
class IndexClosedException extends OpenSearchException {}
377
class InvalidIndexNameException extends OpenSearchException {}
378
class TypeMissingException extends OpenSearchException {}
379
class MapperParsingException extends OpenSearchException {}
380

381
// Search and query exceptions
382
class SearchPhaseExecutionException extends OpenSearchException {}
383
class QueryShardException extends OpenSearchException {}
384
class ParsingException extends OpenSearchException {}
385

386
// Cluster and node exceptions
387
class ClusterManagerNotDiscoveredException extends OpenSearchException {}
388
class NodeNotConnectedException extends OpenSearchException {}
389

390
// Validation and configuration
391
class ActionRequestValidationException extends OpenSearchException {}
392
class SettingsException extends OpenSearchException {}
393

394
// Versioning and conflict resolution
395
class VersionConflictEngineException extends OpenSearchException {}
396
class StrictDynamicMappingException extends OpenSearchException {}
397
```
398

399
## Common Types
400

401
Core types used across the OpenSearch API:
402

403
```java { .api }
404
// Settings and configuration
405
class Settings implements Iterable<Setting<?>> {
406
    static Builder builder();
407
    String get(String key);
408
    <T> T get(Setting<T> setting);
409
    
410
    static class Builder {
411
        Builder put(String key, String value);
412
        Builder put(Setting<?> setting, String value);
413
        Settings build();
414
    }
415
}
416

417
// Action execution
418
interface ActionListener<Response> {
419
    void onResponse(Response response);
420
    void onFailure(Exception e);
421
}
422

423
// Streaming and serialization
424
interface Streamable {
425
    void readFrom(StreamInput in) throws IOException;
426
    void writeTo(StreamOutput out) throws IOException;
427
}
428
```