[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 <[email protected]>

* Update docs/usage/esql.asciidoc

* added code examples

* removed columnar adapter

* [DOCS] Adjusts code block layout.

---------

Co-authored-by: Marci Windsheimer <[email protected]>
Co-authored-by: Laura Trotta <[email protected]>

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<Book> queryRes = (List<Book>) 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<String> {
+
+    public static final CustomStringAdapter INSTANCE = new CustomStringAdapter();
+
+    @Override
+    public String format() {
+        return "json";
+    }
+
+    @Override
+    public boolean columnar() {
+        return true;
+    }
+
+    @Override
+    public String deserialize(ApiClient<ElasticsearchTransport, ?> client, QueryRequest request,
+                              BinaryResponse response)
+        throws IOException {
+        return new BufferedReader(new InputStreamReader(response.content()))
+            .lines().collect(Collectors.joining("\n"));
+    }
+}
+------------------------------------

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.
 
+* <<esql>>
 * <<indexing>>
 * <<indexing-bulk>>
 * <<reading>>
@@ -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[]