From 1ba3eb31080ca1125a2c5d24a4ddccf7f9c86262 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 29 Apr 2024 14:37:31 +0200 Subject: [PATCH 01/10] [DOCS] Adds the structure of the ES|QL docs. --- docs/usage/esql.asciidoc | 35 +++++++++++++++++++++++++++++++++++ docs/usage/index.asciidoc | 2 ++ 2 files changed, 37 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..98ec699c6 --- /dev/null +++ b/docs/usage/esql.asciidoc @@ -0,0 +1,35 @@ +[discrete] +[[esql]] +=== ES|QL in the Java client + +This page enables you to understand and use {ref}/esql.html[ES|QL] utilizing the +Java client. + + +[discrete] +[[esql-how-to]] +==== How to use the ES|QL API + +[TO DO] + +// This section describes the use of the "raw" ES|QL API. + + +[discrete] +[[esql-consume-results]] +==== Consuming ES|QL results + +[TO DO] + +// This section demonstrates the various ways to consume ES|QL results (Object, +// Cursor, DataFrame, etc.). + + +[discrete] +[[esql-custom-mapping]] +==== Defining your own mapping + +[TO DO] + +// This section describes how to come up with your own way of consuming ES|QL +// results. \ No newline at end of file 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[] From 17401e506a05e00d9d4712cc33df7c7353bba520 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 29 Apr 2024 15:03:52 +0200 Subject: [PATCH 02/10] [DOCS] Amends structure. --- docs/usage/esql.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 98ec699c6..08d8bb5dc 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -1,4 +1,3 @@ -[discrete] [[esql]] === ES|QL in the Java client From c0d67a835f98257465eb79fd3ff5748d7aee6b30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 30 Apr 2024 09:16:03 +0200 Subject: [PATCH 03/10] Apply suggestions from code review --- docs/usage/esql.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 08d8bb5dc..236cf472a 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -1,7 +1,7 @@ [[esql]] === ES|QL in the Java client -This page enables you to understand and use {ref}/esql.html[ES|QL] utilizing the +This page enables you to understand and use {ref}/esql.html[ES|QL] in the Java client. From 65e26d332e26fb0d4b7833a132f103ceb60f2f79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 30 Apr 2024 09:18:05 +0200 Subject: [PATCH 04/10] Apply suggestions from code review --- docs/usage/esql.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 236cf472a..94ffabaf0 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -16,7 +16,7 @@ Java client. [discrete] [[esql-consume-results]] -==== Consuming ES|QL results +==== Consume ES|QL results [TO DO] @@ -26,7 +26,7 @@ Java client. [discrete] [[esql-custom-mapping]] -==== Defining your own mapping +==== Define your own mapping [TO DO] From 1faa04e6a169812dbbd8c70d3ae56c3203af14dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Fri, 17 May 2024 14:44:58 +0200 Subject: [PATCH 05/10] [DOCS] Fine-tunes blueprint content. --- docs/usage/esql.asciidoc | 60 ++++++++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 8 deletions(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 08d8bb5dc..e7be52fa1 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -4,31 +4,75 @@ This page enables you to understand and use {ref}/esql.html[ES|QL] utilizing the Java client. +There are two ways to use ES|QL in the {java-client): + +* by using the Elasticsearch {es-docs}/esql-apis.html[ES|QL API] directly. This +is the most flexible approach, but also the most complex since you must handle +results in their raw form. You can also choose the precise format of results, +such as JSON, CSV or text. +* by using ES|QL mapping helpers. These mappers take care of parsing the raw +response into something readily usable by the application. Several mappers are +available that are suited to different use cases such as object mapping, cursor +traversal of results or dataframes. You can also define your own for specific +use cases. + + [discrete] [[esql-how-to]] ==== How to use the ES|QL API -[TO DO] +The {es-docs}/esql-query-api.html[ES|QL query API] allows you to choose how +results should be returned. This includes the +{es-docs}/esql-rest.html#esql-rest-format[response format] such as CSV, text or +JSON, which can be further fine-tuned with parameters such as column separators +or locale. + +Since the response format varies widely depending on the chosen format, the +{java-client) as a BinaryData object, which you can then use according to the +format chosen in the request. + +The example below shows how to get ES|QL results as CSV and parse them: -// This section describes the use of the "raw" ES|QL API. +// Code example to be written [discrete] [[esql-consume-results]] ==== Consuming ES|QL results -[TO DO] +The previous example showed that while using the raw ES|QL API gives maximum +flexibility, it is low level and requires quite some work to make use of the +result data. -// This section demonstrates the various ways to consume ES|QL results (Object, -// Cursor, DataFrame, etc.). +To simplify things, we have identified three main ways to represent ES|QL +results and provide mapping helpers for each of them: + +* 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. +* Cursors, where you scan the results row by row and access the data using +column names. This is similar to database access libraries. +* Dataframes, where results are organized in a column-oriented structure that +allows efficient processing of column data. + +// Code examples to be written for each of them, depending on availability in the language [discrete] [[esql-custom-mapping]] ==== Defining your own mapping -[TO DO] +While the mappers provided by the {java-client} cover many use cases, your +application may require some specific mapping not covered by the provided +mappers. You can write your own mapper and used 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, and not to process the result data. Data processing should be based on +the output of a result mapper. + +As an example, let's write a mapper that returns a simple column-oriented +representation of the data: -// This section describes how to come up with your own way of consuming ES|QL -// results. \ No newline at end of file +// Code example to be written \ No newline at end of file From 2e24a68558a95e447862484143c9009434c150f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 21 May 2024 13:53:27 +0200 Subject: [PATCH 06/10] Apply suggestions from code review Co-authored-by: Marci Windsheimer <333176+marciw@users.noreply.github.com> --- docs/usage/esql.asciidoc | 54 ++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 9a5a80282..299c09092 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -1,19 +1,19 @@ [[esql]] === ES|QL in the Java client -This page enables you to understand and use {ref}/esql.html[ES|QL] in the +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): +There are two ways to use ES|QL in the {java-client}: -* by using the Elasticsearch {es-docs}/esql-apis.html[ES|QL API] directly. This -is the most flexible approach, but also the most complex since you must handle -results in their raw form. You can also choose the precise format of results, -such as JSON, CSV or text. -* by using ES|QL mapping helpers. These mappers take care of parsing the raw +* 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 that are suited to different use cases such as object mapping, cursor -traversal of results or dataframes. You can also define your own for specific +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. @@ -22,17 +22,17 @@ use cases. [[esql-how-to]] ==== How to use the ES|QL API -The {es-docs}/esql-query-api.html[ES|QL query API] allows you to choose how -results should be returned. This includes the -{es-docs}/esql-rest.html#esql-rest-format[response format] such as CSV, text or -JSON, which can be further fine-tuned with parameters such as column separators -or locale. +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. -Since the response format varies widely depending on the chosen format, the -{java-client) as a BinaryData object, which you can then use according to the -format chosen in the request. +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 example below shows how to get ES|QL results as CSV and parse them: +The following example gets ES|QL results as CSV and parses them: // Code example to be written @@ -41,12 +41,12 @@ The example below shows how to get ES|QL results as CSV and parse them: [[esql-consume-results]] ==== Consume ES|QL results -The previous example showed that while using the raw ES|QL API gives maximum -flexibility, it is low level and requires quite some work to make use of the +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, we have identified three main ways to represent ES|QL -results and provide mapping helpers for each of them: +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) @@ -63,16 +63,16 @@ allows efficient processing of column data. [[esql-custom-mapping]] ==== Define your own mapping -While the mappers provided by the {java-client} cover many use cases, your -application may require some specific mapping not covered by the provided -mappers. You can write your own mapper and used it in a similar way as the +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, and not to process the result data. Data processing should be based on +results—not to process the result data. Data processing should be based on the output of a result mapper. -As an example, let's write a mapper that returns a simple column-oriented +Here's an example mapper that returns a simple column-oriented representation of the data: // Code example to be written \ No newline at end of file From 5c9b91d3edfad2704e7461992846c9481e79d7f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 21 May 2024 13:56:48 +0200 Subject: [PATCH 07/10] Update docs/usage/esql.asciidoc --- docs/usage/esql.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 299c09092..cbae85741 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -48,12 +48,12 @@ 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 +* **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. -* Cursors, where you scan the results row by row and access the data using +* **Cursors**, where you scan the results row by row and access the data using column names. This is similar to database access libraries. -* Dataframes, where results are organized in a column-oriented structure that +* **Dataframes**, where results are organized in a column-oriented structure that allows efficient processing of column data. // Code examples to be written for each of them, depending on availability in the language From 14046f7c0ddff504e05ee8c8cb82257ab9142b23 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Wed, 29 May 2024 18:21:05 +0200 Subject: [PATCH 08/10] added code examples --- docs/usage/esql.asciidoc | 58 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 3 deletions(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index cbae85741..945d100d4 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -34,7 +34,23 @@ format specified in the request. The following example gets ES|QL results as CSV and parses them: -// Code example to be written +``` +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] @@ -51,12 +67,25 @@ 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. + +``` +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. +``` +ResultSet resultSet = client.esql().query(ResultSetEsqlAdapter.INSTANCE, queryAuthor); +``` * **Dataframes**, where results are organized in a column-oriented structure that allows efficient processing of column data. +``` +BinaryResponse response = client.esql().query(q -> q + .format("json") + .columnar(true) + .query(queryAuthor)); +``` -// Code examples to be written for each of them, depending on availability in the language [discrete] @@ -75,4 +104,27 @@ the output of a result mapper. Here's an example mapper that returns a simple column-oriented representation of the data: -// Code example to be written \ No newline at end of file +``` +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")); + } +} +``` From 0a7737f56648fdb4fcffe56cc93c607c0a1c3a12 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Mon, 3 Jun 2024 15:54:27 +0200 Subject: [PATCH 09/10] removed columnar adapter --- docs/usage/esql.asciidoc | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 945d100d4..096c28396 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -77,15 +77,6 @@ column names. This is similar to database access libraries. ``` ResultSet resultSet = client.esql().query(ResultSetEsqlAdapter.INSTANCE, queryAuthor); ``` -* **Dataframes**, where results are organized in a column-oriented structure that -allows efficient processing of column data. -``` -BinaryResponse response = client.esql().query(q -> q - .format("json") - .columnar(true) - .query(queryAuthor)); -``` - [discrete] From 51063779f44faafe8aa143fca9b72f4f3d2152d7 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:25:50 +0200 Subject: [PATCH 10/10] [DOCS] Adjusts code block layout. --- docs/usage/esql.asciidoc | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 096c28396..865eba69a 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -34,7 +34,8 @@ format specified in the request. The following example gets ES|QL results as CSV and parses them: -``` +[source,java] +------------------------------------ String queryAuthor = """ from books @@ -50,7 +51,7 @@ BinaryResponse response = client.esql().query(q -> q String result = new BufferedReader(new InputStreamReader(response.content())) .lines().collect(Collectors.joining("\n")); -``` +------------------------------------ [discrete] @@ -67,16 +68,24 @@ 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] @@ -95,7 +104,8 @@ 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(); @@ -118,4 +128,4 @@ public class CustomStringAdapter extends EsqlAdapterBase { .lines().collect(Collectors.joining("\n")); } } -``` +------------------------------------