### Setup and Run Integration Tests

Source: https://github.com/opensearch-project/opensearch-java/blob/main/DEVELOPER_GUIDE.md

Before running integration tests, build and start an OpenSearch cluster using Docker Compose. Specify the OpenSearch version for the cluster.

```bash
docker-compose --project-directory .ci/opensearch build --build-arg OPENSEARCH_VERSION=1.3.0
docker-compose --project-directory .ci/opensearch up -d
```

```bash
./gradlew clean integrationTest
```

--------------------------------

### Setup OpenSearch Client and Index Documents

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/search.md

Initializes the OpenSearch client with Apache HttpClient 5 and Jackson mapper. It then creates an index and indexes two sample documents.

```java
import org.apache.hc.core5.http.HttpHost;

final HttpHost[] hosts = new HttpHost[] {
    new HttpHost("http", "localhost", 9200)
  };

final OpenSearchTransport transport = ApacheHttpClient5TransportBuilder
    .builder(hosts)
    .setMapper(new JacksonJsonpMapper())
    .build();
OpenSearchClient client = new OpenSearchClient(transport);

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

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

indexData = new IndexData("Document 2", "Text for document 2");
indexRequest = new IndexRequest.Builder<IndexData>().index(index).id("2").document(indexData).build();
client.index(indexRequest);
```

--------------------------------

### Run k-NN Search with Painless Scripting Example

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/plugins/knn.md

Execute the Java sample for k-NN search using Painless scripting extensions. This command builds and runs the sample, displaying the process from index creation to search results and cleanup.

```bash
$ ./gradlew :samples:run -Dsamples.mainClass=knn.KnnPainlessScript
```

--------------------------------

### Run k-NN Search with knn_score Script Example

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/plugins/knn.md

Execute the Java sample for k-NN search using the 'knn_score' script. This command builds and runs the sample, showing index creation, data indexing, search results, and index deletion.

```bash
$ ./gradlew :samples:run -Dsamples.mainClass=knn.KnnScriptScore
```

--------------------------------

### Send a bodyless GET request with OpenSearchGenericClient

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/generic.md

Demonstrates sending a simple HTTP GET request without a payload using the generic client. Resources should be closed explicitly using try-with-resources.

```java
// compare with what the low level client outputs
try (Response response = javaClient().generic().execute(Requests.builder().endpoint("/").method("GET").build())) {
   // ...
}
```

--------------------------------

### Get OpenSearchGenericClient with default options

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/generic.md

Obtain an instance of OpenSearchGenericClient from the OpenSearchClient for generic HTTP communication.

```java
final OpenSearchGenericClient generic = javaClient().generic();
```

--------------------------------

### Use Generic Client for Raw HTTP Requests

Source: https://context7.com/opensearch-project/opensearch-java/llms.txt

Use OpenSearchGenericClient for direct HTTP access when typed APIs are insufficient. It supports simple GET requests, POST requests with JSON bodies, and even typed requests with a generic client.

```java
import org.opensearch.client.opensearch.generic.Requests;
import org.opensearch.client.opensearch.generic.Response;
import org.opensearch.client.opensearch.generic.Bodies;
import org.opensearch.client.opensearch.generic.OpenSearchGenericClient;
import org.opensearch.client.opensearch.indices.CreateIndexRequest;
import org.opensearch.client.opensearch.indices.CreateIndexResponse;

// Get generic client
OpenSearchGenericClient generic = client.generic();

// Simple GET request
try (Response response = generic.execute(
    Requests.builder()
        .endpoint("/")
        .method("GET")
        .build()
)) {
    System.out.println("Status: " + response.getStatus());
    String body = response.getBody().map(b -> b.getAsString()).orElse("");
    System.out.println("Body: " + body);
}

// POST request with JSON body
try (Response response = generic.execute(
    Requests.builder()
        .endpoint("/products/_search")
        .method("POST")
        .json("{\"query\": {\"match_all\": {}}}")
        .build()
)) {
    if (response.getStatus() == 200) {
        String results = response.getBody().map(b -> b.getAsString()).orElse("");
        System.out.println("Search results: " + results);
    }
}

// Using typed requests with generic client
var jsonpMapper = client._transport().jsonpMapper();
CreateIndexRequest createRequest = CreateIndexRequest.of(b -> b
    .index("generic-test")
    .mappings(m -> m.properties("name", p -> p.keyword(k -> k)))
);

try (Response response = generic.execute(
    Requests.builder()
        .endpoint("/generic-test")
        .method("PUT")
        .json(createRequest, jsonpMapper)
        .build()
)) {
    CreateIndexResponse createResponse = response.getBody()
        .map(b -> Bodies.json(b, CreateIndexResponse._DESERIALIZER, jsonpMapper))
        .orElse(null);
    System.out.println("Index acknowledged: " + createResponse.acknowledged());
}
```

--------------------------------

### Send a POST request with raw JSON payload using OpenSearchGenericClient

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/generic.md

Example of sending a POST request with a raw JSON body to an OpenSearch index and retrieving the response body as a simple string.

```java
 try (Response response = javaClient().generic()
        .execute(
            Requests.builder()
                .endpoint("/" + index + "/_search")
                .method("POST")
                .json("{"
                    + "    \"query\": {"
                    + "        \"match_all\": {}"
                    + "    }"
                    + "}"
                )
                .build())) {
   // Retrieve the response body as a simple string
   final String body = response.getBody().map(Body::getAsString).orElse("");
   // ...
}
```

--------------------------------

### Run k-NN Basic Sample

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/plugins/knn.md

Execute the basic k-NN Java sample using Gradle. This demonstrates the end-to-end workflow of creating an index, indexing vectors, searching, and cleaning up.

```bash
$ ./gradlew :samples:run -Dsamples.mainClass=knn.KnnBasics

[Main] INFO  - Running main class: org.opensearch.client.samples.knn.KnnBasics
[KnnBasics] INFO  - Server: opensearch@2.7.0
[KnnBasics] INFO  - Creating index my-index
[KnnBasics] INFO  - Indexing 10 vectors
[KnnBasics] INFO  - Waiting for indexing to finish
[KnnBasics] INFO  - Searching for vector [0.67, 0.67, 0.37, 0.0, 0.72]
[KnnBasics] INFO  - Found {values=[0.32, 0.96, 0.41, 0.04, 0.9]} with score 0.8050233
[KnnBasics] INFO  - Found {values=[0.04, 0.58, 0.13, 0.27, 0.37]} with score 0.6031363
[KnnBasics] INFO  - Found {values=[0.96, 0.88, 0.8, 0.41, 0.18]} with score 0.5640794
[KnnBasics] INFO  - Deleting index my-index
```

--------------------------------

### Get All Point-in-Time (PITs)

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/point_in_time.md

Retrieves a list of all active Point-in-Time (PIT) contexts currently managed by the OpenSearch cluster.

```java
GetAllPitsResponse getAllPitsResponse = client.getAllPits();
```

--------------------------------

### Get Data Stream Information

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/data_stream.md

Retrieves information about a specific data stream. This is useful for checking the status or configuration of an existing data stream.

```java
GetDataStreamRequest getDataStreamRequest = new GetDataStreamRequest.Builder().name(dataStreamName).build();
GetDataStreamResponse getDataStreamResponse = client.indices().getDataStream(getDataStreamRequest);
```

--------------------------------

### Create and Manage Point-in-Time (PIT) Snapshots

Source: https://context7.com/opensearch-project/opensearch-java/llms.txt

Demonstrates creating a PIT, using it for consistent search pagination, listing active PITs, and deleting a PIT when no longer needed. Ensure PITs are deleted to avoid resource leaks.

```java
import org.opensearch.client.opensearch._types.Time;
import org.opensearch.client.opensearch.core.CreatePitRequest;
import org.opensearch.client.opensearch.core.CreatePitResponse;
import org.opensearch.client.opensearch.core.DeletePitRequest;
import org.opensearch.client.opensearch.core.pit.GetAllPitsResponse;
import java.util.Collections;

// Create a Point-in-Time
CreatePitRequest createPitRequest = new CreatePitRequest.Builder()
    .targetIndexes(Collections.singletonList("products"))
    .keepAlive(new Time.Builder().time("5m").build())
    .build();

CreatePitResponse createPitResponse = client.createPit(createPitRequest);
String pitId = createPitResponse.pitId();
System.out.println("Created PIT: " + pitId);

// Use PIT in search for consistent pagination
var searchWithPit = client.search(s -> s
    .pit(p -> p.id(pitId).keepAlive(Time.of(t -> t.time("5m"))))
    .sort(so -> so.field(f -> f.field("_id")))
    .size(100),
    Product.class
);

// List all PITs
GetAllPitsResponse allPits = client.getAllPits();
System.out.println("Active PITs: " + allPits.pits().size());

// Delete PIT when done
DeletePitRequest deletePitRequest = new DeletePitRequest.Builder()
    .pitId(Collections.singletonList(pitId))
    .build();
client.deletePit(deletePitRequest);
System.out.println("PIT deleted");

```

--------------------------------

### Using Completion Suggester in Java

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/search.md

Demonstrates setting up and using the completion suggester for auto-completion. Requires a specific mapping for the field.

```java
String index = "completion-suggester";

Property intValueProp = new Property.Builder()
                .long_(v -> v)
                .build();
Property msgCompletionProp = new Property.Builder()
                .completion(c -> c)
                .build();
client.indices().create(c -> c
                .index(index)
                .mappings(m -> m
                                .properties("intValue", intValueProp)
                                .properties("msg", msgCompletionProp)));

AppData appData = new AppData();
appData.setIntValue(1337);
appData.setMsg("foo");

client.index(b -> b
                .index(index)
                .id("1")
                .document(appData)
                .refresh(Refresh.True));

appData.setIntValue(1338);
appData.setMsg("foobar");

client.index(b -> b
                .index(index)
                .id("2")
                .document(appData)
                .refresh(Refresh.True));

String suggesterName = "msgSuggester";

CompletionSuggester completionSuggester = FieldSuggesterBuilders.completion()
                .field("msg")
                .size(1)
                .build();
FieldSuggester fieldSuggester = new FieldSuggester.Builder().prefix("foo")
                .completion(completionSuggester)
                .build();
Suggester suggester = new Suggester.Builder()
                .suggesters(Collections.singletonMap(suggesterName, fieldSuggester))
                .build();
SearchRequest searchRequest = new SearchRequest.Builder()
                .index(index)
                .suggest(suggester)
                .build();

SearchResponse<AppData> response = client.search(searchRequest, AppData.class);
```

--------------------------------

### Get OpenSearchGenericClient to throw on HTTP errors

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/generic.md

Configure the OpenSearchGenericClient to raise an OpenSearchClientException for unsuccessful HTTP status codes instead of returning the raw response.

```java
final OpenSearchGenericClient generic = javaClient().generic().witClientOptions(ClientOptions.throwOnHttpErrors());
```

--------------------------------

### Run k-NN Boolean Filter Sample

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/plugins/knn.md

Execute the sample application to see the k-NN search with a boolean filter in action. This command runs the Java sample using Gradle and demonstrates the process from index creation to search results.

```bash
./gradlew :samples:run -Dsamples.mainClass=knn.KnnBooleanFilter
```

--------------------------------

### Get Data Stream Statistics

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/data_stream.md

Fetches statistics for a data stream, such as the number of documents and size of backing indices. This provides insights into the data stream's usage.

```java
DataStreamsStatsRequest dataStreamsStatsRequest = new DataStreamsStatsRequest.Builder().name(dataStreamName).build();
DataStreamsStatsResponse dataStreamsStatsResponse = client.indices().dataStreamsStats(dataStreamsStatsRequest);
```

--------------------------------

### Run k-NN Efficient Filter Sample

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/plugins/knn.md

Execute the k-NN efficient filter sample using Gradle. This command runs the main class responsible for setting up the index, indexing documents, performing the search, and cleaning up the index.

```bash
./gradlew :samples:run -Dsamples.mainClass=knn.KnnEfficientFilter
```

--------------------------------

### Using Term Suggester in Java

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/search.md

Demonstrates setting up and using the term suggester for finding terms similar to a given text. Does not require a special mapping.

```java
String index = "term-suggester";
        
// term suggester does not require a special mapping
client.indices().create(c -> c
                .index(index));

AppData appData = new AppData();
appData.setIntValue(1337);
appData.setMsg("foo");

client.index(b -> b
                .index(index)
                .id("1")
                .document(appData)
                .refresh(Refresh.True));

appData.setIntValue(1338);
appData.setMsg("foobar");

client.index(b -> b
                .index(index)
                .id("2")
                .document(appData)
                .refresh(Refresh.True));

String suggesterName = "msgSuggester";

TermSuggester termSuggester = FieldSuggesterBuilders.term()
                .field("msg")
                .size(1)
                .build();
FieldSuggester fieldSuggester = new FieldSuggester.Builder().text("fool")
                .term(termSuggester)
                .build();
Suggester suggester = new Suggester.Builder()
                .suggesters(Collections.singletonMap(suggesterName, fieldSuggester))
                .build();
SearchRequest searchRequest = new SearchRequest.Builder()
                .index(index)
                .suggest(suggester)
                .build();

SearchResponse<AppData> response = client.search(searchRequest, AppData.class);
```

--------------------------------

### Create Basic OpenSearch Client with Apache HttpClient5

Source: https://context7.com/opensearch-project/opensearch-java/llms.txt

Sets up a basic OpenSearch client using ApacheHttpClient5Transport. Includes configuration for self-signed certificates and basic authentication. Ensure you have the necessary dependencies for Apache HttpClient 5 and Jackson.

```java
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;

// Basic client setup
final HttpHost[] hosts = new HttpHost[] {
    new HttpHost("https", "localhost", 9200)
};

// Configure SSL context (for self-signed certificates)
final var sslContext = SSLContextBuilder.create()
    .loadTrustMaterial(null, (chains, authType) -> true)
    .build();

// Build transport with authentication
final var transport = ApacheHttpClient5TransportBuilder.builder(hosts)
    .setMapper(new JacksonJsonpMapper())
    .setHttpClientConfigCallback(httpClientBuilder -> {
        // Setup basic auth credentials
        final var credentialsProvider = new BasicCredentialsProvider();
        credentialsProvider.setCredentials(
            new AuthScope(hosts[0]),
            new UsernamePasswordCredentials("admin", "admin".toCharArray())
        );

        // Configure TLS
        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);

// Verify connection
var info = client.info();
System.out.println("Connected to: " + info.version().distribution() + "@" + info.version().number());
// Output: Connected to: opensearch@2.11.0

```

--------------------------------

### Build OpenSearch Java Client

Source: https://github.com/opensearch-project/opensearch-java/blob/main/DEVELOPER_GUIDE.md

Use this command to clean and build the Java client. Exclude tests during the build process.

```bash
./gradlew clean build -x test
```

--------------------------------

### Create Opensearch Index with Settings and Mappings

Source: https://context7.com/opensearch-project/opensearch-java/llms.txt

Use this snippet to create a new index with specified shard count, replica count, and field mappings. It first checks if the index already exists.

```java
import org.opensearch.client.opensearch._types.mapping.IntegerNumberProperty;
import org.opensearch.client.opensearch._types.mapping.Property;
import org.opensearch.client.opensearch._types.mapping.TypeMapping;
import org.opensearch.client.opensearch.indices.CreateIndexRequest;
import org.opensearch.client.opensearch.indices.IndexSettings;

String indexName = "products";

// Check if index exists
boolean exists = client.indices().exists(r -> r.index(indexName)).value();

if (!exists) {
    // Define index settings
    IndexSettings settings = new IndexSettings.Builder()
        .numberOfShards(2)
        .numberOfReplicas(1)
        .build();

    // Define field mappings
    TypeMapping mapping = new TypeMapping.Builder()
        .properties("name", Property.of(p -> p.text(t -> t.analyzer("standard"))))
        .properties("price", Property.of(p -> p.float_(f -> f)))
        .properties("category", Property.of(p -> p.keyword(k -> k)))
        .properties("stock", Property.of(p -> p.integer(new IntegerNumberProperty.Builder().build())))
        .build();

    // Create the index
    CreateIndexRequest createRequest = new CreateIndexRequest.Builder()
        .index(indexName)
        .settings(settings)
        .mappings(mapping)
        .build();

    var response = client.indices().create(createRequest);
    System.out.println("Index created: " + response.acknowledged());
    // Output: Index created: true
}
```

--------------------------------

### Create a SearchRequest Object

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/json.md

This code demonstrates how to create an instance of `SearchRequest` with specific index, aggregations, termination, and query criteria.

```java
SearchRequest searchRequest = SearchRequest.of(
        request -> request.index("index1", "index2")
                .aggregations(Collections.emptyMap())
                .terminateAfter(5L)
                .query(q -> q.match(t -> t.field("name").query(FieldValue.of("OpenSearch"))))
);

```

--------------------------------

### Apply Java Code Formatting

Source: https://github.com/opensearch-project/opensearch-java/blob/main/DEVELOPER_GUIDE.md

Use the spotlessApply task to automatically format Java code according to project standards. This can be applied project-wide or to specific subprojects.

```bash
./gradlew spotlessApply
```

--------------------------------

### Create Index with Custom Settings and Mappings

Source: https://github.com/opensearch-project/opensearch-java/blob/main/USER_GUIDE.md

Creates an OpenSearch index with specified shard count, replica count, and custom field mappings.

```java
String index = "sample-index";
IndexSettings settings = new IndexSettings.Builder()
        .numberOfShards("2")
        .numberOfReplicas("1")
        .build();
TypeMapping mapping = new TypeMapping.Builder()
        .properties("age", new Property.Builder().integer(new IntegerNumberProperty.Builder().build()).build())
        .build();
CreateIndexRequest createIndexRequest = new CreateIndexRequest.Builder()
        .index(index)
        .settings(settings)
        .mappings(mapping)
        .build();
client.indices().create(createIndexRequest);
```

--------------------------------

### Create Index Using Index Template

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/index_templates.md

This snippet demonstrates how to create a new index that will automatically inherit settings and mappings from a pre-defined index template. The index name must match the `indexPatterns` specified in the template.

```java
String indexName = "my-index-1";
client.indices().create(CreateIndexRequest.of(c -> c.index(indexName)));
```

--------------------------------

### Run Unit Tests for Java Client

Source: https://github.com/opensearch-project/opensearch-java/blob/main/DEVELOPER_GUIDE.md

Execute this command to run only the unit tests for the OpenSearch Java client.

```bash
./gradlew clean unitTest
```

--------------------------------

### Create Index Template with Component Templates

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/index_templates.md

This snippet shows how to create an index template composed of two component templates: one for index settings (shard count, replicas, slowlog) and another for field mappings. Ensure the OpenSearch client is properly initialized before executing.

```java
import org.apache.hc.core5.http.HttpHost;

final HttpHost[] hosts = new HttpHost[] {
    new HttpHost("http", "localhost", 9200)
  };

final OpenSearchTransport transport = ApacheHttpClient5TransportBuilder
    .builder(hosts)
    .setMapper(new JacksonJsonpMapper())
    .build();
OpenSearchClient client = new OpenSearchClient(transport);

final var indexSettingsComponentTemplate = "index-settings";
PutComponentTemplateRequest putComponentTemplateRequest = PutComponentTemplateRequest.of(
    c -> c.name(indexSettingsComponentTemplate)
        .settings(
            s -> s.numberOfShards("2")
                .numberOfReplicas("1")
                .indexing(
                    i -> i.slowlog(
                        sl -> sl.level("info")
                            .reformat(true)
                            .threshold(th -> th.index(ith -> ith.warn(Time.of(t -> t.time("2s")))))
                    )
                )
                .search(
                    se -> se.slowlog(sl -> sl.level("info").threshold(th -> th.query(q -> q.warn(Time.of(t -> t.time("2s"))))))
                )
        )
);
client.cluster().putComponentTemplate(putComponentTemplateRequest);

final var indexMappingsComponentTemplate = "index-mappings";
putComponentTemplateRequest = PutComponentTemplateRequest.of(
    c -> c.name(indexMappingsComponentTemplate).mappings(m -> m.properties("age", p -> p.integer(i -> i)))
);
client.cluster().putComponentTemplate(putComponentTemplateRequest);

final var indexTemplateName = "my-index-template";
PutIndexTemplateRequest putIndexTemplateRequest = PutIndexTemplateRequest.of(
    it -> it.name(indexTemplateName)
        .indexPatterns("my-index-*")
        .composedOf(List.of(indexSettingsComponentTemplate, indexMappingsComponentTemplate))
);

client.indices().putIndexTemplate(putIndexTemplateRequest);
```

--------------------------------

### Create Index Templates with Component Templates

Source: https://context7.com/opensearch-project/opensearch-java/llms.txt

This snippet shows how to create reusable settings and mappings component templates, then combine them into a master index template. New indices matching the pattern will automatically adopt these settings and mappings.

```java
import org.opensearch.client.opensearch._types.Time;
import org.opensearch.client.opensearch.cluster.PutComponentTemplateRequest;
import org.opensearch.client.opensearch.indices.PutIndexTemplateRequest;
import java.util.List;

// Create settings component template
String settingsTemplate = "my-settings";
client.cluster().putComponentTemplate(PutComponentTemplateRequest.of(c -> c
    .name(settingsTemplate)
    .settings(s -> s
        .numberOfShards(2)
        .numberOfReplicas(1)
        .indexing(i -> i.slowlog(sl -> sl
            .level("info")
            .reformat(true)
            .threshold(th -> th.index(ith -> ith.warn(Time.of(t -> t.time("2s"))))))) // Corrected closing parenthesis
        .search(se -> se.slowlog(sl -> sl
            .level("info")
            .threshold(th -> th.query(q -> q.warn(Time.of(t -> t.time("2s"))))))) // Corrected closing parenthesis
    )
));
System.out.println("Settings component template created");

// Create mappings component template
String mappingsTemplate = "my-mappings";
client.cluster().putComponentTemplate(PutComponentTemplateRequest.of(c -> c
    .name(mappingsTemplate)
    .mappings(m -> m
        .properties("timestamp", p -> p.date(d -> d))
        .properties("message", p -> p.text(t -> t))
        .properties("level", p -> p.keyword(k -> k))
    )
));
System.out.println("Mappings component template created");

// Create index template using component templates
String indexTemplateName = "logs-template";
client.indices().putIndexTemplate(PutIndexTemplateRequest.of(it -> it
    .name(indexTemplateName)
    .indexPatterns("logs-*")
    .composedOf(List.of(settingsTemplate, mappingsTemplate))
    .priority(100)
));
System.out.println("Index template created");

// New indices matching the pattern will use the template
client.indices().create(c -> c.index("logs-2024-01"));
var mappings = client.indices().getMapping(m -> m.index("logs-2024-01"));
System.out.println("Index created with template mappings: " + mappings.result().keySet());

```

--------------------------------

### Create and Manage Data Streams

Source: https://context7.com/opensearch-project/opensearch-java/llms.txt

Illustrates creating an index template for data streams, creating a data stream, retrieving its information and statistics, and finally deleting the data stream. This is useful for managing time-series data.

```java
import org.opensearch.client.opensearch.indices.CreateDataStreamRequest;
import org.opensearch.client.opensearch.indices.DataStreamsStatsRequest;
import org.opensearch.client.opensearch.indices.DeleteDataStreamRequest;
import org.opensearch.client.opensearch.indices.GetDataStreamRequest;
import org.opensearch.client.opensearch.indices.PutIndexTemplateRequest;
import org.opensearch.client.opensearch.indices.DataStream;

// Step 1: Create index template for data stream
String templateName = "logs-template";
String timestampField = "timestamp";
String namePattern = "logs-*";

PutIndexTemplateRequest templateRequest = new PutIndexTemplateRequest.Builder()
    .name(templateName)
    .indexPatterns(namePattern)
    .dataStream(new DataStream.Builder()
        .timestampField(t -> t.name(timestampField))
        .build())
    .build();
client.indices().putIndexTemplate(templateRequest);
System.out.println("Index template created");

// Step 2: Create data stream
String dataStreamName = "logs-application";
CreateDataStreamRequest createRequest = new CreateDataStreamRequest.Builder()
    .name(dataStreamName)
    .build();
client.indices().createDataStream(createRequest);
System.out.println("Data stream created: " + dataStreamName);

// Step 3: Get data stream info
GetDataStreamRequest getRequest = new GetDataStreamRequest.Builder()
    .name(dataStreamName)
    .build();
var getResponse = client.indices().getDataStream(getRequest);
getResponse.dataStreams().forEach(ds ->
    System.out.println("Data stream: " + ds.name() + ", indices: " + ds.indices().size())
);

// Step 4: Get data stream stats
DataStreamsStatsRequest statsRequest = new DataStreamsStatsRequest.Builder()
    .name(dataStreamName)
    .build();
var statsResponse = client.indices().dataStreamsStats(statsRequest);
System.out.println("Total shards: " + statsResponse.shards().total());

// Cleanup: Delete data stream
DeleteDataStreamRequest deleteRequest = new DeleteDataStreamRequest.Builder()
    .name(dataStreamName)
    .build();
client.indices().deleteDataStream(deleteRequest);

```

--------------------------------

### Index a Single Document in Opensearch

Source: https://context7.com/opensearch-project/opensearch-java/llms.txt

This snippet demonstrates how to index a single document into an Opensearch index. It includes a sample Product class and shows indexing using both explicit request objects and a fluent API.

```java
import org.opensearch.client.opensearch.core.IndexRequest;
import org.opensearch.client.opensearch.core.IndexResponse;

// Define a document class
public class Product {
    private String name;
    private String text;

    public Product() {}
    public Product(String name, String text) {
        this.name = name;
        this.text = text;
    }
    // Getters and setters...
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public String getText() { return text; }
    public void setText(String text) { this.text = text; }
}

// Index a single document
Product product = new Product("Laptop", "High-performance gaming laptop with RTX 4080");

IndexRequest<Product> indexRequest = new IndexRequest.Builder<Product>()
    .index("products")
    .id("prod-001")
    .document(product)
    .build();

IndexResponse response = client.index(indexRequest);
System.out.println("Indexed document ID: " + response.id() + ", version: " + response.version());
// Output: Indexed document ID: prod-001, version: 1
```

```java
// Index using fluent API
var response2 = client.index(i -> i
    .index("products")
    .id("prod-002")
    .document(new Product("Keyboard", "Mechanical gaming keyboard with RGB"))
);
System.out.println("Indexed: " + response2.result());
// Output: Indexed: Created
```

--------------------------------

### Configure Phrase Suggester with Custom Analyzer

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/search.md

This snippet demonstrates how to configure a phrase suggester with a custom analyzer, including shingle token filters, and then use it to index documents and perform a search.

```java
String index = "test-phrase-suggester";

ShingleTokenFilter shingleTokenFilter = new ShingleTokenFilter.Builder().minShingleSize("2")
                .maxShingleSize("3")
                .build();

Analyzer analyzer = new Analyzer.Builder()
                .custom(new CustomAnalyzer.Builder().tokenizer("standard")
                                .filter(Arrays.asList("lowercase", "shingle")).build())
                .build();

TokenFilter tokenFilter = new TokenFilter.Builder()
                .definition(new TokenFilterDefinition.Builder()
                                .shingle(shingleTokenFilter).build())
                .build();

IndexSettingsAnalysis indexSettingsAnalysis = new IndexSettingsAnalysis.Builder()
                .analyzer("trigram", analyzer)
                .filter("shingle", tokenFilter)
                .build();

IndexSettings settings = new IndexSettings.Builder().analysis(indexSettingsAnalysis).build();

TypeMapping mapping = new TypeMapping.Builder().properties("msg", new Property.Builder()
                .text(new TextProperty.Builder().fields("trigram", new Property.Builder() 
                                .text(new TextProperty.Builder().analyzer("trigram").build())
                                .build()).build())
                .build()).build();

client.indices().create(c -> c
                .index(index)
                .settings(settings)
                .mappings(mapping));

AppData appData = new AppData();
appData.setIntValue(1337);
appData.setMsg("Design Patterns");

client.index(b -> b
                .index(index)
                .id("1")
                .document(appData)
                .refresh(Refresh.True));

appData.setIntValue(1338);
appData.setMsg("Software Architecture Patterns Explained");

client.index(b -> b
                .index(index)
                .id("2")
                .document(appData)
                .refresh(Refresh.True));

String suggesterName = "msgSuggester";

PhraseSuggester phraseSuggester = FieldSuggesterBuilders.phrase()
                .field("msg.trigram")
                .build();
FieldSuggester fieldSuggester = new FieldSuggester.Builder().text("design paterns")
                .phrase(phraseSuggester)
                .build();
Suggester suggester = new Suggester.Builder()
                .suggesters(Collections.singletonMap(suggesterName, fieldSuggester))
                .build();
SearchRequest searchRequest = new SearchRequest.Builder()
                .index(index)
                .suggest(suggester)
                .build();

SearchResponse<AppData> response = client.search(searchRequest, AppData.class);
```

--------------------------------

### Perform Terms and Average Aggregations

Source: https://context7.com/opensearch-project/opensearch-java/llms.txt

This snippet shows how to set up and execute terms and average aggregations. Use `size(0)` to disable document retrieval and focus solely on aggregation results. The output processing logic handles both terms and average aggregation results.

```java
import org.opensearch.client.opensearch._types.aggregations.Aggregation;
import org.opensearch.client.opensearch._types.aggregations.Aggregate;
import org.opensearch.client.opensearch._types.aggregations.CompositeAggregation;
import org.opensearch.client.opensearch._types.aggregations.CompositeAggregationSource;
import org.opensearch.client.opensearch._types.SortOrder;
import java.util.HashMap;
import java.util.Map;

// Terms aggregation
SearchRequest aggRequest = new SearchRequest.Builder()
    .index("products")
    .size(0)  // Don't return documents, only aggregations
    .aggregations("categories", new Aggregation.Builder()
        .terms(t -> t.field("category.keyword").size(10))
        .build())
    .aggregations("avg_price", new Aggregation.Builder()
        .avg(a -> a.field("price"))
        .build())
    .build();

SearchResponse<Product> aggResponse = client.search(aggRequest, Product.class);

// Process terms aggregation
for (Map.Entry<String, Aggregate> entry : aggResponse.aggregations().entrySet()) {
    System.out.println("Aggregation: " + entry.getKey());
    if (entry.getValue().isSterms()) {
        entry.getValue().sterms().buckets().array().forEach(bucket ->
            System.out.printf("  %s: %d documents%n", bucket.key().stringValue(), bucket.docCount())
        );
    }
    if (entry.getValue().isAvg()) {
        System.out.printf("  Average: %.2f%n", entry.getValue().avg().value());
    }
}
// Output:
// Aggregation: categories
//   electronics: 45 documents
//   clothing: 32 documents
// Aggregation: avg_price
//   Average: 299.50
```

--------------------------------

### Create OpenSearch Index

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/point_in_time.md

Before creating a Point-in-Time (PIT), an index must exist. This snippet demonstrates how to create a new index using the Java client.

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

--------------------------------

### Close OpenSearchGenericClient Response using try-with-resources

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/generic.md

Illustrates the recommended try-with-resources pattern for ensuring proper closure of Response instances and freeing up allocated resources.

```java
try (Response response = javaClient().generic().execute(...)) {
   // ...
}
```

--------------------------------

### Create OpenSearch Client with ApacheHttpClient5Transport

Source: https://github.com/opensearch-project/opensearch-java/blob/main/USER_GUIDE.md

Instantiate an OpenSearch client using the default ApacheHttpClient5Transport. Ensure JacksonJsonpMapper is configured for JSON serialization.

```java
import org.apache.hc.core5.http.HttpHost;

final HttpHost[] hosts = new HttpHost[] {
    new HttpHost("http", "localhost", 9200)
  };

final OpenSearchTransport transport = ApacheHttpClient5TransportBuilder
    .builder(hosts)
    .setMapper(new JacksonJsonpMapper())
    .build();
OpenSearchClient client = new OpenSearchClient(transport);
```

--------------------------------

### Add OpenSearch Java Client Dependency (Maven)

Source: https://github.com/opensearch-project/opensearch-java/blob/main/USER_GUIDE.md

Add the OpenSearch Java client as a Maven dependency to your project.

```xml
<dependency>
  <groupId>org.opensearch.client</groupId>
  <artifactId>opensearch-java</artifactId>
  <version>2.6.0</version>
</dependency>
```

--------------------------------

### Run Java Code Formatting Check

Source: https://github.com/opensearch-project/opensearch-java/blob/main/DEVELOPER_GUIDE.md

Execute the spotlessJavaCheck task to verify Java code formatting. This command can be run for the entire project or specific subprojects.

```bash
./gradlew spotlessJavaCheck
```

```bash
./gradlew :java-client:spotlessJavaCheck
```

```bash
./gradlew :samples:spotlessJavaCheck
```

--------------------------------

### Perform Search with Terms Aggregation

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/search.md

This snippet shows how to construct a search request with a match query and a terms aggregation on a keyword field, then process the aggregation results.

```java
SearchRequest searchRequest = new SearchRequest.Builder().query(q -> q.match(m -> m.field("title")
                                                                                   .query(FieldValue.of("Document 1"))))
                                                         .aggregations("titles", new Aggregation.Builder().terms(t -> t.field("title.keyword"))
                                                                                                              .build())
                                                         .build();

SearchResponse<IndexData> searchResponse = client.search(searchRequest, IndexData.class);
for (Map.Entry<String, Aggregate> entry : searchResponse.aggregations().entrySet()) {
  System.out.println("Agg - " + entry.getKey());
  entry.getValue().sterms().buckets().array().forEach(b -> System.out.printf("%s : %d%n", b.key(), b.docCount()));
}
```

--------------------------------

### Search Documents Using a Match Query

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/search.md

Constructs and executes a search request using a `match` query on the 'text' field. It then prints the source of each matching document.

```java
SearchRequest searchRequest = new SearchRequest.Builder().query(q -> q.match(m -> m.field("text")
                                                                                   .query(FieldValue.of("Text for document 2"))))
                                                             .build();

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

--------------------------------

### Configure ApacheHttpClient5Transport with Micrometer

Source: https://github.com/opensearch-project/opensearch-java/blob/main/USER_GUIDE.md

Add `ObservationExecChainHandler` during `OpenSearchTransport` construction for ApacheHttpClient5. This enables Micrometer's tracing capabilities.

```java
final ObservationRegistry observationRegistry = ...;
final OpenSearchTransport transport = ApacheHttpClient5TransportBuilder
  .builder(hosts)
  .setHttpClientConfigCallback(httpClientBuilder -> {
      return httpClientBuilder.addExecInterceptorAfter(
        ChainElement.RETRY.name(), "micrometer", 
          new ObservationExecChainHandler(observationRegistry));
  })
  .build();
OpenSearchClient client = new OpenSearchClient(transport);
```

--------------------------------

### Create Data Stream and Index Template

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/data_stream.md

Creates an index template with a custom timestamp field and then creates a data stream matching the template's pattern. Ensure the index template is created before the data stream.

```java
String dataStreamIndexTemplateName = "sample-data-stream-template";
String timestampFieldName = "my_timestamp_field";
String namePattern = "sample-data-stream-*";
String dataStreamName = "sample-data-stream-1";

// Create an index template which configures data stream
PutIndexTemplateRequest putIndexTemplateRequest = new PutIndexTemplateRequest.Builder()
        .name(dataStreamIndexTemplateName)
        .indexPatterns(namePattern)
        .dataStream(new DataStream.Builder()
                .timestampField(t -> t.name(timestampFieldName))
                .build())
        .build();
PutIndexTemplateResponse putIndexTemplateResponse = client.indices().putIndexTemplate(putIndexTemplateRequest);

// Create a data stream
CreateDataStreamRequest createDataStreamRequest = new CreateDataStreamRequest.Builder().name(dataStreamName).build();
CreateDataStreamResponse createDataStreamResponse = client.indices().createDataStream(createDataStreamRequest);
```

--------------------------------

### Add OpenSearch Java Client Dependency (Gradle)

Source: https://github.com/opensearch-project/opensearch-java/blob/main/USER_GUIDE.md

Add the OpenSearch Java client as a Gradle dependency to your project.

```gradle
dependencies {
  implementation 'org.opensearch.client:opensearch-java:2.6.0'
}
```

--------------------------------

### Retrieve Nodes Information Sorted by CPU

Source: https://context7.com/opensearch-project/opensearch-java/llms.txt

This snippet demonstrates fetching node information from the cluster using the CAT API, sorted by CPU utilization.

```java
import org.opensearch.client.opensearch.cat.NodesResponse;

// Cat nodes
NodesResponse nodesResponse = client.cat().nodes(r -> r.sort("cpu"));
nodesResponse.valueBody().forEach(node ->
    System.out.printf("Node: %s, CPU: %s%%, Memory: %s%n",
        node.name(), node.cpu(), node.ramCurrent())
);

```

--------------------------------

### Bulk Indexing with BulkIngester

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/bulk.md

Use `BulkIngester` for simplified bulk indexing. It automatically buffers operations and flushes them based on configurable thresholds like the number of operations, total size, or time interval. It also supports backpressure and retries.

```java
String indexName = "sample-index";

// Create a BulkIngester with custom settings
BulkIngester<Void> ingester = BulkIngester.of(b -> b
    .client(client)
    .maxOperations(1000)           // Flush every 1000 operations
    .flushInterval(5, TimeUnit.SECONDS)  // Or every 5 seconds
    .maxConcurrentRequests(2)       // Allow 2 concurrent bulk requests
);

// Add operations - they are automatically buffered and flushed
IndexData doc1 = new IndexData("Document 1", "The text of document 1");
ingester.add(op -> op.index(i -> i.index(indexName).id("id1").document(doc1)));

IndexData doc2 = new IndexData("Document 2", "The text of document 2");
ingester.add(op -> op.index(i -> i.index(indexName).id("id2").document(doc2)));

IndexData doc3 = new IndexData("Document 3", "The text of document 3");
ingester.add(op -> op.index(i -> i.index(indexName).id("id3").document(doc3)));

// Close the ingester - this flushes any remaining buffered operations
ingester.close();
```

--------------------------------

### Execute Composite Aggregation

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/search.md

This snippet demonstrates how to define and execute a composite aggregation with terms sources, allowing for pagination and flexible bucketing, and then iterating over the results.

```java
final Map<String, CompositeAggregationSource> comAggrSrcMap = new HashMap<>();
CompositeAggregationSource compositeAggregationSource1 = new CompositeAggregationSource.Builder().terms(
    termsAggrBuilder -> termsAggrBuilder.field("title.keyword").missingBucket(false).order(SortOrder.Asc)
).build();
comAggrSrcMap.put("titles", compositeAggregationSource1);

CompositeAggregation compAgg = new CompositeAggregation.Builder().sources(comAggrSrcMap).build();
Aggregation aggregation = new Aggregation.Builder().composite(compAgg).build();

SearchRequest request = SearchRequest.of(r -> r.index(indexName).query(q -> q.match(m -> m.field("title").query(FieldValue.of("Document 1")))).aggregations("my_buckets", aggregation));
SearchResponse<IndexData> response = client.search(request, IndexData.class);
for (Map.Entry<String, Aggregate> entry : response.aggregations().entrySet()) {
  LOGGER.info("Agg - {}", entry.getKey());
  entry.getValue().composite().buckets().array().forEach(b -> LOGGER.info("{} : {}", b.key(), b.docCount()));
}
```

--------------------------------

### Create Index with Flat Object Mappings

Source: https://github.com/opensearch-project/opensearch-java/blob/main/USER_GUIDE.md

Creates an OpenSearch index with a flat object mapping for a specified property. This requires OpenSearch version 2.7.0 or later.

```java
final CreateIndexRequest createIndexRequest = new CreateIndexRequest.Builder().index(indexName)
                    .mappings(m -> m.properties("issue", Property.of(p -> p.flatObject(new FlatObjectProperty.Builder().build()))))
                    .build();
client.indices().create(createIndexRequest);
```

--------------------------------

### k-NN Search with Painless Scripting Extensions

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/plugins/knn.md

This snippet demonstrates an exact k-NN search using Painless scripting extensions. It allows for custom scoring logic directly within the script source.

```java
var searchResponse = client.search(s -> s
        .index(indexName)
        .query(q -> q
                .scriptScore(ss -> ss
                        .query(qq -> qq.matchAll(m -> m))
                        .script(sss -> sss
                                .inline(i -> i
                                        .source("1.0 + cosineSimilarity(params.query_value, doc[params.field])")
                                        .params("field", JsonData.of("values"))
                                        .params("query_value", JsonData.of(searchVector)))))),
        Doc.class);
```

--------------------------------

### Create k-NN Index

Source: https://github.com/opensearch-project/opensearch-java/blob/main/guides/plugins/knn.md

Create an index specifically for k-NN vector data. Ensure the 'knn' setting is enabled and map a field as a knnVector with the specified dimensions.

```java
final var indexName = "my-index";
final var dimensions = 5;

client.indices().create(r -> r
        .index(indexName)
        .settings(s -> s.knn(true))
        .mappings(m -> m
                .properties("values", p -> p
                        .knnVector(k -> k.dimension(dimensions))))));
```

--------------------------------

### Initialize RestClientTransport

Source: https://github.com/opensearch-project/opensearch-java/blob/main/USER_GUIDE.md

Initializes the RestClient and RestClientTransport for connecting to OpenSearch. SSL and TLS are enabled by default.

```java
import org.apache.hc.core5.http.HttpHost;

final HttpHost[] hosts = new HttpHost[] {
    new HttpHost("http", "localhost", 9200)
  };

// Initialize the client with SSL and TLS enabled
final RestClient restClient = RestClient
  .builder(hosts)
  .build();

OpenSearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper()); 
OpenSearchClient client = new OpenSearchClient(transport);
```

--------------------------------

### Run AWS Transport Integration Tests

Source: https://github.com/opensearch-project/opensearch-java/blob/main/DEVELOPER_GUIDE.md

Execute integration tests for the AWS transport client. Ensure AWS credentials are configured and specify the OpenSearch domain host, region, and service name.

```bash
./gradlew integrationTest --tests "*AwsSdk2*" -Dtests.awsSdk2support.domainHost=search-...us-west-2.es.amazonaws.com -Dtests.awsSdk2support.domainRegion=us-west-2 -Dtests.awsSdk2support.serviceName=es
```

```bash
./gradlew integrationTest --tests "*AwsSdk2*" -Dtests.awsSdk2support.domainHost=....us-west-2.aoss.amazonaws.com -Dtests.awsSdk2support.domainRegion=us-west-2 -Dtests.awsSdk2support.serviceName=aoss
```

--------------------------------

### Add Micrometer Dependency

Source: https://github.com/opensearch-project/opensearch-java/blob/main/USER_GUIDE.md

Include the `micrometer-observation` dependency in your project. Ensure the version matches your stack's requirements.

```xml
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-observation</artifactId>
    <version>...</version>
</dependency>
```