or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

action-framework.mdclient-apis.mdcluster-management.mdindex-management.mdindex.mdplugin-framework.mdsearch-apis.md
tile.json

tessl/maven-org-opensearch--opensearch

OpenSearch is a distributed, RESTful search and analytics engine built as a community-driven fork of Elasticsearch.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.opensearch/opensearch@3.1.x

To install, run

npx @tessl/cli install tessl/maven-org-opensearch--opensearch@3.1.0

index.mddocs/

OpenSearch

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.

Package Information

  • Package Name: org.opensearch:opensearch
  • Package Type: maven
  • Language: Java
  • Installation: Add to Maven pom.xml:
<dependency>
    <groupId>org.opensearch</groupId>
    <artifactId>opensearch</artifactId>
    <version>3.1.0</version>
</dependency>

Or Gradle build.gradle:

implementation 'org.opensearch:opensearch:3.1.0'

Core Imports

// Core client interfaces
import org.opensearch.transport.client.Client;
import org.opensearch.transport.client.AdminClient;
import org.opensearch.client.RestClient;
import org.opensearch.OpenSearchException;

// Action framework
import org.opensearch.core.action.ActionRequest;
import org.opensearch.core.action.ActionResponse;
import org.opensearch.core.action.ActionListener;
import org.opensearch.common.action.ActionFuture;

// Document operations
import org.opensearch.action.index.IndexRequest;
import org.opensearch.action.index.IndexResponse;
import org.opensearch.action.index.IndexRequestBuilder;
import org.opensearch.action.get.GetRequest;
import org.opensearch.action.get.GetResponse;
import org.opensearch.action.get.GetRequestBuilder;
import org.opensearch.action.update.UpdateRequest;
import org.opensearch.action.update.UpdateResponse;
import org.opensearch.action.delete.DeleteRequest;
import org.opensearch.action.delete.DeleteResponse;
import org.opensearch.action.bulk.BulkRequest;
import org.opensearch.action.bulk.BulkResponse;

// Search operations  
import org.opensearch.action.search.SearchRequest;
import org.opensearch.action.search.SearchResponse;
import org.opensearch.action.search.SearchRequestBuilder;
import org.opensearch.search.builder.SearchSourceBuilder;

// Point-in-time operations
import org.opensearch.action.search.CreatePitRequest;
import org.opensearch.action.search.CreatePitResponse;
import org.opensearch.action.search.DeletePitRequest;
import org.opensearch.action.search.DeletePitResponse;

// Query DSL
import org.opensearch.index.query.QueryBuilders;
import org.opensearch.index.query.QueryBuilder;
import org.opensearch.index.query.BoolQueryBuilder;
import org.opensearch.index.query.MatchQueryBuilder;

// Settings and configuration
import org.opensearch.common.settings.Settings;

Basic Usage

import org.opensearch.client.RestClient;
import org.opensearch.client.RestClientBuilder;
import org.opensearch.action.index.IndexRequest;
import org.opensearch.action.index.IndexResponse;
import org.opensearch.action.search.SearchRequest;
import org.opensearch.action.search.SearchResponse;
import org.opensearch.search.builder.SearchSourceBuilder;
import org.opensearch.index.query.QueryBuilders;
import org.apache.http.HttpHost;

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

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

// Perform search
SearchRequest searchRequest = new SearchRequest("products");
SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
searchSourceBuilder.query(QueryBuilders.matchQuery("category", "electronics"));
searchSourceBuilder.size(10);
searchRequest.source(searchSourceBuilder);

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

// Always close resources
restClient.close();

Architecture

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

Core Client Layer

  • Client Interface: Unified interface for all OpenSearch operations
  • REST Client: Low-level HTTP client for direct REST API access
  • Transport Client: Internal cluster communication layer
  • Node Client: Direct in-process node access

Action Framework

  • Actions: Typed operations (search, index, delete, cluster management)
  • Requests/Responses: Strongly-typed request and response objects
  • Builders: Fluent API for constructing complex requests
  • Listeners: Async callback patterns for non-blocking operations

Search Engine

  • Query DSL: Comprehensive query language with builders
  • Aggregation Framework: Statistical and analytical computations
  • Search Phases: Multi-phase search execution (query, fetch, etc.)
  • Source Builders: Composable search request construction

Index Management

  • Index APIs: Creation, deletion, configuration of indices
  • Mapping Management: Field type definitions and analysis
  • Settings: Index-level and cluster-level configuration
  • Lifecycle Operations: Open, close, refresh, merge operations

Cluster Coordination

  • Cluster State: Distributed state management
  • Node Discovery: Automatic cluster member detection
  • Shard Management: Data distribution and replication
  • Health Monitoring: Cluster and index health reporting

Extension Framework

  • Plugin System: Modular extension points throughout the system
  • Custom Actions: User-defined operations and endpoints
  • Analysis Plugins: Custom text processing and tokenization
  • Engine Plugins: Alternative storage implementations

Capabilities

Client APIs

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

interface Client extends OpenSearchClient, Releasable {
    // Administrative client access
    AdminClient admin();
    
    // Document operations
    ActionFuture<IndexResponse> index(IndexRequest request);
    void index(IndexRequest request, ActionListener<IndexResponse> listener);
    IndexRequestBuilder prepareIndex();
    IndexRequestBuilder prepareIndex(String index);
    
    ActionFuture<GetResponse> get(GetRequest request);
    void get(GetRequest request, ActionListener<GetResponse> listener);
    GetRequestBuilder prepareGet();
    GetRequestBuilder prepareGet(String index, String id);
    
    ActionFuture<UpdateResponse> update(UpdateRequest request);
    void update(UpdateRequest request, ActionListener<UpdateResponse> listener);
    UpdateRequestBuilder prepareUpdate();
    UpdateRequestBuilder prepareUpdate(String index, String id);
    
    ActionFuture<DeleteResponse> delete(DeleteRequest request);
    void delete(DeleteRequest request, ActionListener<DeleteResponse> listener);
    DeleteRequestBuilder prepareDelete();
    DeleteRequestBuilder prepareDelete(String index, String id);
    
    // Bulk operations
    ActionFuture<BulkResponse> bulk(BulkRequest request);
    void bulk(BulkRequest request, ActionListener<BulkResponse> listener);
    BulkRequestBuilder prepareBulk();
    BulkRequestBuilder prepareBulk(String globalIndex);
    
    // Search operations
    ActionFuture<SearchResponse> search(SearchRequest request);
    void search(SearchRequest request, ActionListener<SearchResponse> listener);
    SearchRequestBuilder prepareSearch(String... indices);
    
    ActionFuture<SearchResponse> searchScroll(SearchScrollRequest request);
    void searchScroll(SearchScrollRequest request, ActionListener<SearchResponse> listener);
    SearchScrollRequestBuilder prepareSearchScroll(String scrollId);
    
    // Point-in-time operations
    void createPit(CreatePitRequest createPITRequest, ActionListener<CreatePitResponse> listener);
    void deletePits(DeletePitRequest deletePITRequest, ActionListener<DeletePitResponse> listener);
    void getAllPits(GetAllPitNodesRequest getAllPitNodesRequest, ActionListener<GetAllPitNodesResponse> listener);
    void pitSegments(PitSegmentsRequest pitSegmentsRequest, ActionListener<IndicesSegmentResponse> listener);
    
    // Multi-operations
    ActionFuture<MultiGetResponse> multiGet(MultiGetRequest request);
    void multiGet(MultiGetRequest request, ActionListener<MultiGetResponse> listener);
    MultiGetRequestBuilder prepareMultiGet();
    
    ActionFuture<MultiSearchResponse> multiSearch(MultiSearchRequest request);
    void multiSearch(MultiSearchRequest request, ActionListener<MultiSearchResponse> listener);
    MultiSearchRequestBuilder prepareMultiSearch();
    
    // Advanced operations
    ActionFuture<TermVectorsResponse> termVectors(TermVectorsRequest request);
    void termVectors(TermVectorsRequest request, ActionListener<TermVectorsResponse> listener);
    TermVectorsRequestBuilder prepareTermVectors();
    TermVectorsRequestBuilder prepareTermVectors(String index, String id);
    
    ActionFuture<ExplainResponse> explain(ExplainRequest request);
    void explain(ExplainRequest request, ActionListener<ExplainResponse> listener);
    ExplainRequestBuilder prepareExplain(String index, String id);
    
    ActionFuture<FieldCapabilitiesResponse> fieldCaps(FieldCapabilitiesRequest request);
    void fieldCaps(FieldCapabilitiesRequest request, ActionListener<FieldCapabilitiesResponse> listener);
    FieldCapabilitiesRequestBuilder prepareFieldCaps(String... indices);
    
    // View operations
    void searchView(SearchViewAction.Request request, ActionListener<SearchResponse> listener);
    ActionFuture<SearchResponse> searchView(SearchViewAction.Request request);
    void listViewNames(ListViewNamesAction.Request request, ActionListener<ListViewNamesAction.Response> listener);
    ActionFuture<ListViewNamesAction.Response> listViewNames(ListViewNamesAction.Request request);
    
    // Utility methods
    Settings settings();
    Client filterWithHeader(Map<String, String> headers);
    Client getRemoteClusterClient(String clusterAlias);
    void close();
}

Client APIs

Search APIs

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

class SearchRequest extends ActionRequest {
    SearchRequest(String... indices);
    SearchRequest source(SearchSourceBuilder sourceBuilder);
    SearchRequest routing(String routing);
    SearchRequest timeout(String timeout);
}

class SearchSourceBuilder {
    SearchSourceBuilder query(QueryBuilder query);
    SearchSourceBuilder aggregation(AggregationBuilder aggregation);
    SearchSourceBuilder size(int size);
    SearchSourceBuilder from(int from);
}

Search APIs

Index Management

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

class CreateIndexRequest extends ActionRequest {
    CreateIndexRequest(String index);
    CreateIndexRequest mapping(String source, XContentType xContentType);
    CreateIndexRequest settings(Settings settings);
}

class GetMappingsRequest extends ActionRequest {
    GetMappingsRequest(String... indices);
    GetMappingsRequest local(boolean local);
}

Index Management

Cluster Management

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

class ClusterHealthRequest extends ActionRequest {
    ClusterHealthRequest(String... indices);
    ClusterHealthRequest timeout(String timeout);
    ClusterHealthRequest waitForStatus(ClusterHealthStatus status);
}

class NodesInfoRequest extends ActionRequest {
    NodesInfoRequest(String... nodeIds);
    NodesInfoRequest addMetrics(String... metrics);
}

Cluster Management

Action Framework

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

abstract class ActionRequest implements Streamable {
    ActionRequest validate();
}

class IndexRequest extends DocWriteRequest<IndexRequest> {
    IndexRequest(String index);
    IndexRequest source(String source, XContentType xContentType);
    IndexRequest id(String id);
}

class BulkRequest extends ActionRequest {
    BulkRequest add(DocWriteRequest<?> request);
    BulkRequest timeout(String timeout);
}

Action Framework

Plugin Framework

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

abstract class Plugin {
    Collection<Module> createGuiceModules();
    Settings additionalSettings();
}

interface ActionPlugin {
    List<ActionHandler<? extends ActionRequest, ? extends ActionResponse>> getActions();
    List<RestHandler> getRestHandlers(Settings settings, RestController restController, 
        ClusterSettings clusterSettings, IndexScopedSettings indexScopedSettings);
}

Plugin Framework

Exception Handling

OpenSearch uses a hierarchical exception system for comprehensive error handling:

class OpenSearchException extends RuntimeException {
    RestStatus status();
    String getIndex();
    Integer getShardId();
    String getResourceId();
    Map<String, List<String>> getMetadata();
}

// Timeout and execution exceptions
class OpenSearchTimeoutException extends OpenSearchException {}
class ClusterBlockException extends OpenSearchException {}
class UnavailableShardsException extends OpenSearchException {}

// Security and authorization
class OpenSearchSecurityException extends OpenSearchException {}

// Resource management exceptions
class ResourceNotFoundException extends OpenSearchException {}
class ResourceAlreadyExistsException extends OpenSearchException {}
class IndexNotFoundException extends ResourceNotFoundException {}
class DocumentMissingException extends ResourceNotFoundException {}

// Index and mapping exceptions
class IndexClosedException extends OpenSearchException {}
class InvalidIndexNameException extends OpenSearchException {}
class TypeMissingException extends OpenSearchException {}
class MapperParsingException extends OpenSearchException {}

// Search and query exceptions
class SearchPhaseExecutionException extends OpenSearchException {}
class QueryShardException extends OpenSearchException {}
class ParsingException extends OpenSearchException {}

// Cluster and node exceptions
class ClusterManagerNotDiscoveredException extends OpenSearchException {}
class NodeNotConnectedException extends OpenSearchException {}

// Validation and configuration
class ActionRequestValidationException extends OpenSearchException {}
class SettingsException extends OpenSearchException {}

// Versioning and conflict resolution
class VersionConflictEngineException extends OpenSearchException {}
class StrictDynamicMappingException extends OpenSearchException {}

Common Types

Core types used across the OpenSearch API:

// Settings and configuration
class Settings implements Iterable<Setting<?>> {
    static Builder builder();
    String get(String key);
    <T> T get(Setting<T> setting);
    
    static class Builder {
        Builder put(String key, String value);
        Builder put(Setting<?> setting, String value);
        Settings build();
    }
}

// Action execution
interface ActionListener<Response> {
    void onResponse(Response response);
    void onFailure(Exception e);
}

// Streaming and serialization
interface Streamable {
    void readFrom(StreamInput in) throws IOException;
    void writeTo(StreamOutput out) throws IOException;
}