PolarDB:Connect to PolarSearch using a client

Apache HttpClient5 (Recommended)

Maven — add to pom.xml:

<!-- OpenSearch Java client core library -->
<dependency>
  <groupId>org.opensearch.client</groupId>
  <artifactId>opensearch-java</artifactId>
  <version>2.19.0</version>
</dependency>

<!-- Apache HttpClient 5 transport layer -->
<dependency>
  <groupId>org.apache.httpcomponents.client5</groupId>
  <artifactId>httpclient5</artifactId>
  <version>5.2.1</version>
</dependency>

Gradle — add to build.gradle:

dependencies {
    // OpenSearch Java client core library
    implementation 'org.opensearch.client:opensearch-java:2.19.0'

    // Apache HttpClient 5 transport layer
    implementation 'org.apache.httpcomponents.client5:httpclient5:5.2.1'
}

RestClient

If you prefer RestClient over Apache HttpClient 5, replace the transport-layer dependency:

Maven:

<!-- RestClient transport layer -->
<dependency>
  <groupId>org.opensearch.client</groupId>
  <artifactId>opensearch-rest-client</artifactId>
  <version>2.19.0</version>
</dependency>

Gradle:

// RestClient transport layer
implementation 'org.opensearch.client:opensearch-rest-client:2.19.0'

Apache HttpClient5

Apache HttpClient 5 — this example disables SSL for local testing:

import org.apache.hc.client5.http.auth.AuthScope;
import org.apache.hc.client5.http.auth.UsernamePasswordCredentials;
import org.apache.hc.client5.http.impl.auth.BasicCredentialsProvider;
import org.apache.hc.client5.http.impl.nio.PoolingAsyncClientConnectionManagerBuilder;
import org.apache.hc.client5.http.ssl.ClientTlsStrategyBuilder;
import org.apache.hc.client5.http.ssl.NoopHostnameVerifier;
import org.apache.hc.core5.http.HttpHost;
import org.apache.hc.core5.ssl.SSLContextBuilder;
import org.opensearch.client.json.jackson.JacksonJsonpMapper;
import org.opensearch.client.opensearch.OpenSearchClient;
import org.opensearch.client.transport.httpclient5.ApacheHttpClient5TransportBuilder;

public class CreateClient {
    public static void main(String[] args) throws Exception {
        var env = System.getenv();
        var hostname = env.getOrDefault("HOST", "<polarsearch_host>");
        var port = Integer.parseInt(env.getOrDefault("PORT", "<polarsearch_port>"));
        var user = env.getOrDefault("USERNAME", "<polarsearch_username>");
        var pass = env.getOrDefault("PASSWORD", "<polarsearch_password>");

        final var hosts = new HttpHost[] { new HttpHost("http", hostname, port) };

        final var sslContext = SSLContextBuilder.create()
            .loadTrustMaterial(null, (chains, authType) -> true)
            .build();

        final var transport = ApacheHttpClient5TransportBuilder.builder(hosts)
            .setMapper(new JacksonJsonpMapper())
            .setHttpClientConfigCallback(httpClientBuilder -> {
                final var credentialsProvider = new BasicCredentialsProvider();
                for (final var host : hosts) {
                    credentialsProvider.setCredentials(
                        new AuthScope(host),
                        new UsernamePasswordCredentials(user, pass.toCharArray())
                    );
                }

                // Disable SSL/TLS verification for local testing clusters with self-signed certificates
                final var tlsStrategy = ClientTlsStrategyBuilder.create()
                    .setSslContext(sslContext)
                    .setHostnameVerifier(NoopHostnameVerifier.INSTANCE)
                    .build();

                final var connectionManager = PoolingAsyncClientConnectionManagerBuilder.create()
                    .setTlsStrategy(tlsStrategy)
                    .build();

                return httpClientBuilder
                    .setDefaultCredentialsProvider(credentialsProvider)
                    .setConnectionManager(connectionManager);
            })
            .build();

        OpenSearchClient client = new OpenSearchClient(transport);
    }
}

RestClient

RestClient — this example disables SSL for local testing:

import org.apache.hc.client5.http.ssl.NoopHostnameVerifier;
import org.apache.hc.core5.ssl.SSLContextBuilder;
import org.opensearch.client.RestClient;
import org.opensearch.client.json.jackson.JacksonJsonpMapper;
import org.opensearch.client.opensearch.OpenSearchClient;
import org.opensearch.client.transport.rest_client.RestClientTransport;

public class CreateRestClient {
    public static void main(String[] args) throws Exception {
        var env = System.getenv();
        var hostname = env.getOrDefault("HOST", "<polarsearch_host>");
        var port = Integer.parseInt(env.getOrDefault("PORT", "<polarsearch_port>"));
        var user = env.getOrDefault("USERNAME", "<polarsearch_username>");
        var pass = env.getOrDefault("PASSWORD", "<polarsearch_password>");

        final org.apache.http.HttpHost[] restHosts = new org.apache.http.HttpHost[] {
            new org.apache.http.HttpHost(hostname, port, "http")
        };

        RestClient restClient = RestClient.builder(restHosts)
            .setHttpClientConfigCallback(httpClientBuilder -> {
                final org.apache.http.impl.client.BasicCredentialsProvider credentialsProvider =
                    new org.apache.http.impl.client.BasicCredentialsProvider();
                for (final org.apache.http.HttpHost ignored : restHosts) {
                    credentialsProvider.setCredentials(
                        org.apache.http.auth.AuthScope.ANY,
                        new org.apache.http.auth.UsernamePasswordCredentials(user, pass)
                    );
                }
                try {
                    return httpClientBuilder
                        .setDefaultCredentialsProvider(credentialsProvider)
                        // Disable SSL for local testing
                        .setSSLHostnameVerifier(NoopHostnameVerifier.INSTANCE)
                        .setSSLContext(SSLContextBuilder.create()
                            .loadTrustMaterial(null, (chains, authType) -> true)
                            .build());
                } catch (Exception e) {
                    throw new RuntimeException(e);
                }
            }).build();

        final RestClientTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
        final OpenSearchClient client = new OpenSearchClient(transport);
    }
}

Create an index

Create an index

String index = "sample-index";
CreateIndexRequest createIndexRequest = new CreateIndexRequest.Builder().index(index).build();
client.indices().create(createIndexRequest);

Writing to a document

Index a document

IndexData indexData = new IndexData("first_name", "Bruce");
IndexRequest<IndexData> indexRequest = new IndexRequest.Builder<IndexData>()
    .index(index).id("1").document(indexData).build();
client.index(indexRequest);

Search for documents

Search for documents

SearchResponse<IndexData> searchResponse = client.search(s -> s.index(index), IndexData.class);
for (int i = 0; i < searchResponse.hits().hits().size(); i++) {
    System.out.println(searchResponse.hits().hits().get(i).source());
}

Delete a document

Delete a document

client.delete(b -> b.index(index).id("1"));

Delete an index

Delete an index

DeleteIndexRequest deleteIndexRequest = new DeleteIndexRequest.Builder().index(index).build();
DeleteIndexResponse deleteIndexResponse = client.indices().delete(deleteIndexRequest);

Create an index

Create an index

// Create an index with custom settings and mappings
CreateIndexRequest createIndexRequest = new CreateIndexRequest("custom-index");
createIndexRequest.settings(Settings.builder()
    .put("index.number_of_shards", 4)
    .put("index.number_of_replicas", 3)
);
HashMap<String, String> typeMapping = new HashMap<String, String>();
typeMapping.put("type", "integer");
HashMap<String, Object> ageMapping = new HashMap<String, Object>();
ageMapping.put("age", typeMapping);
HashMap<String, Object> mapping = new HashMap<String, Object>();
mapping.put("properties", ageMapping);
createIndexRequest.mapping(mapping);
CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest, RequestOptions.DEFAULT);

Writing to a document

Index a document

// Add data to the index
IndexRequest request = new IndexRequest("custom-index");
request.id("1");

HashMap<String, String> stringMapping = new HashMap<String, String>();
stringMapping.put("message:", "Testing Java REST client");
request.source(stringMapping);
IndexResponse indexResponse = client.index(request, RequestOptions.DEFAULT);

Search for a document

Get a document

GetRequest getRequest = new GetRequest("custom-index", "1");
GetResponse getResponse = client.get(getRequest, RequestOptions.DEFAULT);
System.out.println("Retrieved document: " + getResponse.getSourceAsString());

Delete a document

Delete a document

DeleteRequest deleteDocumentRequest = new DeleteRequest("custom-index", "1");
DeleteResponse deleteResponse = client.delete(deleteDocumentRequest, RequestOptions.DEFAULT);
System.out.println("Document deleted with result: " + deleteResponse.getResult());

Delete an index

Delete an index

DeleteIndexRequest deleteIndexRequest = new DeleteIndexRequest("custom-index");
AcknowledgedResponse deleteIndexResponse = client.indices().delete(deleteIndexRequest, RequestOptions.DEFAULT);
System.out.println("Index deletion acknowledged: " + deleteIndexResponse.isAcknowledged());

Create an index

Create an index

Use client.indices.create() to create a new index.

index_name = 'python-test-index'
index_body = {
    'settings': {
        'index': {
            'number_of_shards': 4
        }
    }
}

response = client.indices.create(index=index_name, body=index_body)

Writing to a document

Index a document

Use client.index() to add a document to an index.

document = {
    'title': 'Moneyball',
    'director': 'Bennett Miller',
    'year': '2011'
}

response = client.index(
    index='python-test-index',
    body=document,
    id='1',
    refresh=True
)

Perform batch operations

Perform bulk operations

Use client.bulk() to execute multiple operations at once. Separate operations with \n.

movies = '{ "index" : { "_index" : "my-dsl-index", "_id" : "2" } } \n { "title" : "Interstellar", "director" : "Christopher Nolan", "year" : "2014"} \n { "create" : { "_index" : "my-dsl-index", "_id" : "3" } } \n { "title" : "Star Trek Beyond", "director" : "Justin Lin", "year" : "2015"} \n { "update" : {"_id" : "3", "_index" : "my-dsl-index" } } \n { "doc" : {"year" : "2016"} }'

client.bulk(body=movies)

Search for documents

Search for documents

Use client.search() to search by query criteria.

q = 'miller'
query = {
    'size': 5,
    'query': {
        'multi_match': {
            'query': q,
            'fields': ['title^2', 'director']
        }
    }
}

response = client.search(
    body=query,
    index='python-test-index'
)

Delete a document

Delete a document

Use client.delete() to delete a document by ID.

response = client.delete(
    index='python-test-index',
    id='1'
)

Delete an index

Delete an index

Use client.indices.delete() to delete an entire index.

response = client.indices.delete(
    index='python-test-index'
)