Add ES|QL doc structure

Author: marciw

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

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

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.
 
 * <<recommendations, Usage recommendations>>
+* <<esql>>
 * <<examples, CRUD usage examples>>
 
+
 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[]