[DOCS] Add ES|QL doc structure (#8193)

* Add ES|QL doc structure

* Tweak TOC

* Match TOC

* Fix heading levels

* Update ESQL document

* Small edits

---------

Co-authored-by: Florian Bernd <[email protected]>

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,69 @@
+[[esql]]
+== ES|QL in the .NET client
+++++
+<titleabbrev>Using ES|QL</titleabbrev>
+++++
+
+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 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 (in development), and dataframes (in development).
+
+[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.
+
+The following example gets ES|QL results as CSV and parses them:
+
+[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]]
+=== 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.
+
+[source,charp]
+----
+// ObjectAPI example
+var response = await client.Esql.QueryAsObjectsAsync<Person>(x => x.Query("FROM index"));
+foreach (var person in response)
+{
+    // ...
+}
+----

docs/usage/index.asciidoc

@@ -10,8 +10,10 @@ If you're new to {es}, make sure also to read {ref}/getting-started.html[Elastic
 
 * <<recommendations, Usage recommendations>>
 * <<examples, CRUD usage examples>>
+* <<esql, Using ES|QL>>
 
 NOTE: This is still a work in progress, more sections will be added in the near future.
 
 include::recommendations.asciidoc[]
 include::examples.asciidoc[]
+include::esql.asciidoc[]