diff --git a/docs/getting-started.asciidoc b/docs/getting-started.asciidoc new file mode 100644 index 000000000..268f8db18 --- /dev/null +++ b/docs/getting-started.asciidoc @@ -0,0 +1,168 @@ +[[getting-started-java]] +== Getting started + +This page guides you through the installation process of the Java client, shows +you how to instantiate the client, and how to perform basic Elasticsearch +operations with it. + +[discrete] +=== 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. + +[discrete] +=== Installation + +[discrete] +==== Installation in a Gradle project by using Jackson + +["source","groovy",subs="attributes+"] +-------------------------------------------------- +dependencies { + implementation 'co.elastic.clients:elasticsearch-java:{version}' + implementation 'com.fasterxml.jackson.core:jackson-databind:2.12.3' +} +-------------------------------------------------- + +[discrete] +==== Installation in a Maven project by using Jackson + +In the `pom.xml` of your project, add the following repository definition and +dependencies: + +["source","xml",subs="attributes+"] +-------------------------------------------------- + + + + + co.elastic.clients + elasticsearch-java + {version} + + + + com.fasterxml.jackson.core + jackson-databind + 2.12.3 + + + + +-------------------------------------------------- + + +Refer to the <> page to learn more. + + +[discrete] +=== Connecting + +You can connect to the Elastic Cloud using an API key and the Elasticsearch +endpoint. + +["source","java"] +-------------------------------------------------- +include-tagged::{doc-tests-src}/getting_started/ConnectingTest.java[create-client] +-------------------------------------------------- + +Your Elasticsearch endpoint can be found on the **My deployment** page of your +deployment: + +image::images/es-endpoint.jpg[alt="Finding Elasticsearch endpoint",align="center"] + +You can generate an API key on the **Management** page under Security. + +image::images/create-api-key.png[alt="Create API key",align="center"] + +For other connection options, refer to the <> section. + + +[discrete] +=== Operations + +Time to use Elasticsearch! This section walks you through the basic, and most +important, operations of Elasticsearch. For more operations and more advanced +examples, refer to the <> page. + + +[discrete] +==== Creating an index + +This is how you create the `product` index: + +["source","java"] +-------------------------------------------------- +include-tagged::{doc-tests-src}/usage/IndexingTest.java[create-products-index] +-------------------------------------------------- + +[discrete] +==== Indexing documents + +This is a simple way of indexing a document, here a `Product` application object: + +["source","java"] +-------------------------------------------------- +include-tagged::{doc-tests-src}/usage/IndexingTest.java[single-doc-dsl] +-------------------------------------------------- + +[discrete] +==== Getting documents + +You can get documents by using the following code: + +["source","java"] +-------------------------------------------------- +include-tagged::{doc-tests-src}/usage/ReadingTest.java[get-by-id] +-------------------------------------------------- +<1> The get request, with the index name and identifier. +<2> The target class, here `Product`. + + +[discrete] +==== Searching documents + +This is how you can create a single match query with the Java client: + +["source","java"] +-------------------------------------------------- +include-tagged::{doc-tests-src}/usage/SearchingTest.java[search-getting-started] +-------------------------------------------------- + +[discrete] +==== Updating documents + +This is how you can update a document, for example to add a new field: + +["source","java"] +-------------------------------------------------- +include-tagged::{doc-tests-src}/usage/IndexingTest.java[single-doc-update] +-------------------------------------------------- + + + +[discrete] +==== Deleting documents + +["source","java"] +-------------------------------------------------- +include-tagged::{doc-tests-src}/usage/IndexingTest.java[single-doc-delete] +-------------------------------------------------- + + +[discrete] +==== Deleting an index + +["source","java"] +-------------------------------------------------- +include-tagged::{doc-tests-src}/usage/IndexingTest.java[create-products-index] +-------------------------------------------------- + + +[discrete] +== Further reading + +* Learn more about the <> of the Java client. diff --git a/docs/images/create-api-key.png b/docs/images/create-api-key.png new file mode 100644 index 000000000..d75c23030 Binary files /dev/null and b/docs/images/create-api-key.png differ diff --git a/docs/images/es-endpoint.jpg b/docs/images/es-endpoint.jpg new file mode 100644 index 000000000..6da2e7565 Binary files /dev/null and b/docs/images/es-endpoint.jpg differ diff --git a/docs/index-custom-title-page.html b/docs/index-custom-title-page.html index 29a20ec8b..ddae54a03 100644 --- a/docs/index-custom-title-page.html +++ b/docs/index-custom-title-page.html @@ -63,7 +63,7 @@

Documentation

The Java API client provides strongly typed requests and responses for all Elasticsearch APIs.

- +

diff --git a/docs/index.asciidoc b/docs/index.asciidoc index dec8a0751..29b4e6cd9 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -27,7 +27,8 @@ ifeval::["{release-state}"!="unreleased"] endif::[] include::introduction.asciidoc[] -include::getting-started/index.asciidoc[] +include::getting-started.asciidoc[] +include::setup/index.asciidoc[] include::api-conventions/index.asciidoc[] include::usage/index.asciidoc[] diff --git a/docs/getting-started/connecting.asciidoc b/docs/setup/connecting.asciidoc similarity index 100% rename from docs/getting-started/connecting.asciidoc rename to docs/setup/connecting.asciidoc diff --git a/docs/getting-started/index.asciidoc b/docs/setup/index.asciidoc similarity index 92% rename from docs/getting-started/index.asciidoc rename to docs/setup/index.asciidoc index 785ba634b..dd5f3f122 100644 --- a/docs/getting-started/index.asciidoc +++ b/docs/setup/index.asciidoc @@ -1,4 +1,4 @@ -== Getting started +== Setup * <> * <> diff --git a/docs/getting-started/installation.asciidoc b/docs/setup/installation.asciidoc similarity index 100% rename from docs/getting-started/installation.asciidoc rename to docs/setup/installation.asciidoc diff --git a/docs/getting-started/migrate-hlrc.asciidoc b/docs/setup/migrate-hlrc.asciidoc similarity index 100% rename from docs/getting-started/migrate-hlrc.asciidoc rename to docs/setup/migrate-hlrc.asciidoc diff --git a/java-client/src/test/java/co/elastic/clients/documentation/getting_started/ConnectingTest.java b/java-client/src/test/java/co/elastic/clients/documentation/getting_started/ConnectingTest.java index 182b6549c..9f343ada7 100644 --- a/java-client/src/test/java/co/elastic/clients/documentation/getting_started/ConnectingTest.java +++ b/java-client/src/test/java/co/elastic/clients/documentation/getting_started/ConnectingTest.java @@ -27,10 +27,12 @@ import co.elastic.clients.transport.ElasticsearchTransport; import co.elastic.clients.transport.TransportUtils; import co.elastic.clients.transport.rest_client.RestClientTransport; +import org.apache.http.Header; import org.apache.http.HttpHost; import org.apache.http.auth.AuthScope; import org.apache.http.auth.UsernamePasswordCredentials; import org.apache.http.impl.client.BasicCredentialsProvider; +import org.apache.http.message.BasicHeader; import org.elasticsearch.client.RestClient; import org.junit.jupiter.api.Disabled; import org.junit.jupiter.api.Test; @@ -44,20 +46,28 @@ public class ConnectingTest { @Test public void createClient() throws Exception { //tag::create-client + // URL and API key + String serverUrl = "https://localhost:9200"; + String apiKey = "VnVhQ2ZHY0JDZGJrU..."; + // Create the low-level client - RestClient restClient = RestClient.builder( - new HttpHost("localhost", 9200)).build(); + 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 client = new ElasticsearchClient(transport); + ElasticsearchClient esClient = new ElasticsearchClient(transport); //end::create-client //tag::first-request - SearchResponse search = client.search(s -> s + SearchResponse search = esClient.search(s -> s .index("products") .query(q -> q .term(t -> t diff --git a/java-client/src/test/java/co/elastic/clients/documentation/usage/IndexingTest.java b/java-client/src/test/java/co/elastic/clients/documentation/usage/IndexingTest.java index 57318ba3f..44192bcbe 100644 --- a/java-client/src/test/java/co/elastic/clients/documentation/usage/IndexingTest.java +++ b/java-client/src/test/java/co/elastic/clients/documentation/usage/IndexingTest.java @@ -27,6 +27,7 @@ import co.elastic.clients.elasticsearch.core.IndexResponse; import co.elastic.clients.elasticsearch.model.ModelTestCase; import co.elastic.clients.json.JsonData; +import org.junit.jupiter.api.Disabled; import org.junit.jupiter.api.Test; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -51,6 +52,26 @@ public class IndexingTest extends ModelTestCase { .shards(s -> s.total(1).successful(1).failed(0)) ); + @Test + @Disabled + public void createIndex() throws Exception { + //tag::create-products-index + esClient.indices().create(c -> c + .index("products") + ); + //end::create-products-index + } + + @Test + @Disabled + public void deleteIndex() throws Exception { + //tag::delete-products-index + esClient.indices().delete(d -> d + .index("products") + ); + //end::delete-products-index + } + @Test public void singleDocumentDSL() throws Exception { @@ -162,4 +183,26 @@ public void singleDocumentJson() throws Exception { toJson(request) ); } + + @Test + public void deleteDocument() throws Exception { + //tag::single-doc-delete + esClient.delete(d -> d.index("products").id("bk-1")); + //end::single-doc-delete + } + + @Test + @Disabled + public void updateDoc() throws Exception { + //tag::single-doc-update + Product product = new Product("bk-1", "City bike", 123.0); + + esClient.update(u -> u + .index("products") + .id("bk-1") + .upsert(product), + Product.class + ); + //end::single-doc-update + } } diff --git a/java-client/src/test/java/co/elastic/clients/documentation/usage/SearchingTest.java b/java-client/src/test/java/co/elastic/clients/documentation/usage/SearchingTest.java index cf02ca0bb..caa88c073 100644 --- a/java-client/src/test/java/co/elastic/clients/documentation/usage/SearchingTest.java +++ b/java-client/src/test/java/co/elastic/clients/documentation/usage/SearchingTest.java @@ -61,6 +61,25 @@ public class SearchingTest { ) ); + @Test + public void searchSimpleMatch() throws Exception { + transport.setResult(searchResponse); + + //tag::search-getting-started + String searchText = "bike"; + + SearchResponse response = esClient.search(s -> s + .index("products") + .query(q -> q + .match(t -> t + .field("name") + .query(searchText) + ) + ), + Product.class + ); + //end::search-getting-started + } @Test public void searchMatch() throws Exception {