getting-started.mdx

id	slug	title	description	date	tags
gettingStartedServerlessJava	/serverless-java/docs/getting-started	Getting started with the Serverless Java client	This page contains quickstart information about the Serverless Java client.	2023-06-27	serverless Java client docs getting started Java

This page guides you through the installation process of the Serverless Java client, shows you how to instantiate the client, and how to perform basic Elasticsearch operations with it.

Requirements

• Java 8 or later.
• A JSON object mapping library to allow seamless integration of your application classes with the Elasticsearch API. The examples below show usage with Jackson.

Installation

You can add the Elasticsearch Serverless Java client to your Java project using either Gradle or Maven.

Using Gradle

dependencies {
    implementation 'co.elastic.clients:elasticsearch-java-serverless:1.0.0-20231031'
    implementation 'com.fasterxml.jackson.core:jackson-databind:2.17.0'
}

Using Maven

In the pom.xml of your project, add the following dependencies:

<project>
    <dependencies>

        <dependency>
            <groupId>co.elastic.clients</groupId>
            <artifactId>elasticsearch-java-serverless</artifactId>
            <version>1.0.0-20231031</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.17.0</version>
        </dependency>

    </dependencies>
</project>

Instantiate a client

You can connect to the Elasticsearch Service using an API key and the Elasticsearch endpoint:

// URL and API key
String serverUrl = "https://...elastic.cloud";
String apiKey = "VnVhQ2ZHY0JDZGJrU...";

// Create the low-level client
RestClient restClient = RestClient
    .builder(HttpHost.create(serverUrl))
    .setDefaultHeaders(new Header[]{
        new BasicHeader("Authorization", "ApiKey " + apiKey)
    })
    .build();

// Create the transport with a Jackson mapper
ElasticsearchTransport transport = new RestClientTransport(
    restClient, new JacksonJsonpMapper());

// And create the API client
ElasticsearchClient esClient = new ElasticsearchClient(transport);

You can find the Elasticsearch endpoint on the Cloud deployment management page.

You can create a new API Key under Stack Management > Security:

Using the API

After you instantiated a client with your API key and Elasticsearch endpoint, you can start ingesting documents into the Elasticsearch Service.

Creating an index and ingesting documents

You can call the bulk API with a body parameter, an array of hashes that define the action, and a document.

The following is an example of indexing a document, here a Product application object in the products index:

Product product = new Product("bk-1", "City bike", 123.0);

IndexResponse response = esClient.index(i -> i
    .index("products")
    .id(product.getSku())
    .document(product)
);

logger.info("Indexed with version " + response.version());

Searching

Now that some data is available, you can search your documents using the Search API:

String searchText = "bike";

SearchResponse<Product> response = esClient.search(s -> s
    .index("products")
    .query(q -> q
        .match(t -> t
            .field("name")
            .query(searchText)
        )
    ),
    Product.class
);

A few things to note in the above example:

• the search query is built using a hierarchy of lambda expressions that closely follows the Elasticsearch JSON API. Lambda expressions allows you to be guided by your IDE's autocompletion, without having to import (or even know!) the actual classes representing a query.
• The last parameter Product.class instructs the client to return results as Product application objects instead of raw JSON.

Updating

You can update your documents using the Update API:

Product product = new Product("bk-1", "City bike", 123.0);

esClient.update(u -> u
        .index("products")
        .id("bk-1")
        .upsert(product),
    Product.class
);

Delete

You can also delete documents:

esClient.delete(d -> d.index("products").id("bk-1"));