From 00f43c75f70fe1098a9d0762d3fdb5edc6cc6772 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Tue, 21 May 2024 20:38:40 -0400 Subject: [PATCH 1/6] Add ES|QL doc structure --- docs/index.asciidoc | 2 ++ docs/usage/esql.asciidoc | 76 +++++++++++++++++++++++++++++++++++++++ docs/usage/index.asciidoc | 3 ++ 3 files changed, 81 insertions(+) create mode 100644 docs/usage/esql.asciidoc diff --git a/docs/index.asciidoc b/docs/index.asciidoc index c70fe7f73a5..59a48269c40 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -8,6 +8,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :net-client: Elasticsearch .NET Client :latest-version: 8.1.0 +:es-docs: https://www.elastic.co/guide/en/elasticsearch/reference/{branch} + include::intro.asciidoc[] include::getting-started.asciidoc[] diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc new file mode 100644 index 00000000000..349491e7828 --- /dev/null +++ b/docs/usage/esql.asciidoc @@ -0,0 +1,76 @@ +[[esql]] +== ES|QL in the .NET client + +This page helps you understand and use {ref}/esql.html[ES|QL] in the +.NET client. + +There are two ways to use ES|QL in the .NET 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. + +// Add any .NET-specific usage notes + +The following example gets ES|QL results as CSV and parses them: + +// Code example to be written + + +[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. +* **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]] +==== Define your own mapping + +Although the mappers provided by the .NET 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: + +// Code example to be written \ No newline at end of file diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc index 06bc4250ddd..65da45c7932 100644 --- a/docs/usage/index.asciidoc +++ b/docs/usage/index.asciidoc @@ -9,9 +9,12 @@ For a full reference, see the {ref}/[Elasticsearch documentation] and in particu If you're new to {es}, make sure also to read {ref}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. * <> +* <> * <> + NOTE: This is still a work in progress, more sections will be added in the near future. include::recommendations.asciidoc[] +include::esql.asciidoc[] include::examples.asciidoc[] From 5e56d80032176479f807d12403cd40baa801e794 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Wed, 22 May 2024 13:41:01 -0400 Subject: [PATCH 2/6] Tweak TOC --- docs/usage/esql.asciidoc | 3 +++ docs/usage/index.asciidoc | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 349491e7828..269954f90e5 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -1,5 +1,8 @@ [[esql]] == ES|QL in the .NET client +++++ +Using ES|QL +++++ This page helps you understand and use {ref}/esql.html[ES|QL] in the .NET client. diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc index 65da45c7932..7d7a7c7362b 100644 --- a/docs/usage/index.asciidoc +++ b/docs/usage/index.asciidoc @@ -9,12 +9,12 @@ For a full reference, see the {ref}/[Elasticsearch documentation] and in particu If you're new to {es}, make sure also to read {ref}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. * <> -* <> +* <> * <> NOTE: This is still a work in progress, more sections will be added in the near future. include::recommendations.asciidoc[] -include::esql.asciidoc[] include::examples.asciidoc[] +include::esql.asciidoc[] \ No newline at end of file From 5c3b5d303046355548b22fc526a39e20b1a6513e Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Wed, 22 May 2024 18:30:29 -0400 Subject: [PATCH 3/6] Match TOC --- docs/usage/index.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc index 7d7a7c7362b..1d5aa7e086b 100644 --- a/docs/usage/index.asciidoc +++ b/docs/usage/index.asciidoc @@ -9,9 +9,8 @@ For a full reference, see the {ref}/[Elasticsearch documentation] and in particu If you're new to {es}, make sure also to read {ref}/getting-started.html[Elasticsearch's quick start] that provides a good introduction. * <> -* <> * <> - +* <> NOTE: This is still a work in progress, more sections will be added in the near future. From 350aa67f1e9fcff01d7bcd5a478b109c6282230f Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Wed, 22 May 2024 19:42:34 -0400 Subject: [PATCH 4/6] Fix heading levels --- 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 269954f90e5..413abcfdff2 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -23,7 +23,7 @@ use cases. [discrete] [[esql-how-to]] -==== How to use the ES|QL API +=== 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 @@ -40,7 +40,7 @@ The following example gets ES|QL results as CSV and parses them: [discrete] [[esql-consume-results]] -==== Consume ES|QL 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 @@ -62,7 +62,7 @@ allows efficient processing of column data. [discrete] [[esql-custom-mapping]] -==== Define your own mapping +=== Define your own mapping Although the mappers provided by the .NET client cover many use cases, your application might require a custom mapping. From 455fc67c5dfcb636c49f7432e6fe779da1ce6755 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Thu, 6 Jun 2024 10:12:00 +0200 Subject: [PATCH 5/6] Update ESQL document --- docs/usage/esql.asciidoc | 50 ++++++++++++++++------------------------ 1 file changed, 20 insertions(+), 30 deletions(-) diff --git a/docs/usage/esql.asciidoc b/docs/usage/esql.asciidoc index 413abcfdff2..2f356c7fdcc 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -13,13 +13,10 @@ There are two ways to use ES|QL in the .NET client: 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 +* Use ES|QL high level helpers: These helpers take care of parsing the raw +response into something readily usable by the application. Several helpers 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. - - +traversal of results (WiP), and dataframes (WiP). [discrete] [[esql-how-to]] @@ -31,12 +28,16 @@ results should be returned. You can choose a JSON, then fine-tune it with parameters like column separators and locale. -// Add any .NET-specific usage notes - The following example gets ES|QL results as CSV and parses them: -// Code example to be written - +[source,charp] +---- +var response = await client.Esql.QueryAsync(r => r + .Query("FROM index") + .Format("csv") +); +var csvContents = Encoding.UTF8.GetString(response.Data); +---- [discrete] [[esql-consume-results]] @@ -57,23 +58,12 @@ 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]] -=== Define your own mapping - -Although the mappers provided by the .NET 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: - -// Code example to be written \ No newline at end of file +[source,charp] +---- +// ObjectAPI example +var response = await client.Esql.QueryAsObjectsAsync(x => x.Query("FROM index")); +foreach (var person in response) +{ + // ... +} +---- From e0923cd6a6324e63ed8ca4689ed398a8ef7fd8a5 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Thu, 6 Jun 2024 07:49:02 -0400 Subject: [PATCH 6/6] Small edits --- 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 2f356c7fdcc..7b7c1a0fe42 100644 --- a/docs/usage/esql.asciidoc +++ b/docs/usage/esql.asciidoc @@ -13,10 +13,10 @@ There are two ways to use ES|QL in the .NET client: 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 high level helpers: These helpers take care of parsing the raw +* Use ES|QL high-level helpers: These helpers take care of parsing the raw response into something readily usable by the application. Several helpers are available for different use cases, such as object mapping, cursor -traversal of results (WiP), and dataframes (WiP). +traversal of results (in development), and dataframes (in development). [discrete] [[esql-how-to]]