From f3fbf3c359597fe2b7e882057e4f46fbcbf6dfb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 3 Jun 2024 16:54:32 +0200 Subject: [PATCH] [DOCS] Adds the structure of the ES|QL docs (#789) * [DOCS] Adds the structure of the ES|QL docs. * [DOCS] Amends structure. * Apply suggestions from code review * Apply suggestions from code review * [DOCS] Fine-tunes blueprint content. * Apply suggestions from code review Co-authored-by: Marci Windsheimer <333176+marciw@users.noreply.github.com> * Update docs/usage/esql.asciidoc * added code examples * removed columnar adapter * [DOCS] Adjusts code block layout. --------- Co-authored-by: Marci Windsheimer <333176+marciw@users.noreply.github.com> Co-authored-by: Laura Trotta --- docs/usage/esql.asciidoc | 131 ++++++++++++++++++++++++++++++++++++++ docs/usage/index.asciidoc | 2 + 2 files changed, 133 insertions(+) create mode 100644 docs/usage/esql.asciidoc diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc new file mode 100644 index 000000000..865eba69a --- /dev/null +++ b/docs/usage/esql.asciidoc @@ -0,0 +1,131 @@ +[[esql]] +=== ES|QL in the Java client + +This page helps you understand and use {ref}/esql.html[ES|QL] in the +Java client. + +There are two ways to use ES|QL in the {java-client}: + +* Use the Elasticsearch {es-docs}/esql-apis.html[ES|QL API] directly: This +is the most flexible approach, but it's also the most complex because you must handle +results in their raw form. You can choose the precise format of results, +such as JSON, CSV, or text. +* Use ES|QL mapping helpers: These mappers take care of parsing the raw +response into something readily usable by the application. Several mappers are +available for different use cases, such as object mapping, cursor +traversal of results, and dataframes. You can also define your own mapper for specific +use cases. + + + +[discrete] +[[esql-how-to]] +==== How to use the ES|QL API + +The {es-docs}/esql-query-api.html[ES|QL query API] allows you to specify how +results should be returned. You can choose a +{es-docs}/esql-rest.html#esql-rest-format[response format] such as CSV, text, or +JSON, then fine-tune it with parameters like column separators +and locale. + +Because the response varies widely depending on the format, the +{java-client} has a BinaryData object you can use according to the +format specified in the request. + +The following example gets ES|QL results as CSV and parses them: + +[source,java] +------------------------------------ +String queryAuthor = + """ + from books + | where author == "Isaac Asimov" + | sort year desc + | limit 10 + """; + +BinaryResponse response = client.esql().query(q -> q + .format("csv") + .delimiter(",") + .query(queryAuthor)); + +String result = new BufferedReader(new InputStreamReader(response.content())) + .lines().collect(Collectors.joining("\n")); +------------------------------------ + + +[discrete] +[[esql-consume-results]] +==== Consume ES|QL results + +The previous example showed that although the raw ES|QL API offers maximum +flexibility, additional work is required in order to make use of the +result data. + +To simplify things, try working with these three main representations of ES|QL +results (each with its own mapping helper): + +* **Objects**, where each row in the results is mapped to an object from your +application domain. This is similar to what ORMs (object relational mappers) +commonly do. ++ +-- + +[source,java] +------------------------------------ +List queryRes = (List) client.esql().query(ObjectsEsqlAdapter.of(Book.class), queryAuthor); + +------------------------------------ +-- +* **Cursors**, where you scan the results row by row and access the data using +column names. This is similar to database access libraries. ++ +-- +[source,java] +------------------------------------ +ResultSet resultSet = client.esql().query(ResultSetEsqlAdapter.INSTANCE, queryAuthor); +------------------------------------ +-- + + +[discrete] +[[esql-custom-mapping]] +==== Define your own mapping + +Although the mappers provided by the {java-client} cover many use cases, your +application might require a custom mapping. +You can write your own mapper and use it in a similar way as the +built-in ones. + +Note that mappers are meant to provide a more usable representation of ES|QL +results—not to process the result data. Data processing should be based on +the output of a result mapper. + +Here's an example mapper that returns a simple column-oriented +representation of the data: + +[source,java] +------------------------------------ +public class CustomStringAdapter extends EsqlAdapterBase { + + public static final CustomStringAdapter INSTANCE = new CustomStringAdapter(); + + @Override + public String format() { + return "json"; + } + + @Override + public boolean columnar() { + return true; + } + + @Override + public String deserialize(ApiClient client, QueryRequest request, + BinaryResponse response) + throws IOException { + return new BufferedReader(new InputStreamReader(response.content())) + .lines().collect(Collectors.joining("\n")); + } +} +------------------------------------ diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc index c71aa34f3..854ef8ab4 100644 --- a/docs/usage/index.asciidoc +++ b/docs/usage/index.asciidoc @@ -7,6 +7,7 @@ For a full reference, see the {es-docs}/[Elasticsearch documentation] and in par If you're new to Elasticsearch, make sure also to read {es-docs}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. +* <> * <> * <> * <> @@ -19,6 +20,7 @@ If you're new to Elasticsearch, make sure also to read {es-docs}/getting-started NOTE: This is still a work in progress, more sections will be added in the near future. +include::esql.asciidoc[] include::indexing.asciidoc[] include::indexing-bulk.asciidoc[] include::reading.asciidoc[]