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

* Add ES|QL docs structure

* Fix variable; adjust TOC entry

* add examples to ES|QL documentation

* Small edit

---------

Co-authored-by: marciw <333176+marciw@users.noreply.github.com>

.doc/index.asciidoc

@@ -6,6 +6,8 @@ include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[]
 
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
+:es-docs: https://www.elastic.co/guide/en/elasticsearch/reference/{branch} 
+
 include::overview.asciidoc[]
 
 include::getting-started.asciidoc[]

.doc/typedapi/esql.asciidoc

@@ -0,0 +1,139 @@
+[[esql]]
+=== ES|QL in the Go client
+++++
+<titleabbrev>Using ES|QL</titleabbrev>
+++++
+
+This page helps you understand and use {ref}/esql.html[ES|QL] in the
+Go client.
+
+There are two ways to use ES|QL in the Go 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. Helpers are
+available for object mapping and iterative objects.
+
+
+
+[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,go]
+------------------------------------
+queryAuthor := `from library
+    | where author == "Isaac Asimov"
+    | sort release_date desc
+    | limit 10`
+
+response, err := client.Esql.Query().
+    Query(queryAuthor).
+    Format("csv").
+    Do(context.Background())
+if err != nil {
+    log.Fatal(err)
+}
+
+reader := csv.NewReader(bytes.NewReader(response))
+rows, err := reader.ReadAll()
+for _, row := range rows {
+    fmt.Println(row)
+}
+------------------------------------
+
+
+[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 two 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,go]
+------------------------------------
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/elastic/go-elasticsearch/v8"
+	"github.com/elastic/go-elasticsearch/v8/typedapi/esql/query"
+)
+
+type Book struct {
+	Name        string `json:"name"`
+	Author      string `json:"author"`
+	ReleaseDate string `json:"release_date"`
+	PageCount   int    `json:"page_count"`
+}
+
+func main() {
+	client, err := elasticsearch.NewTypedClient(elasticsearch.Config{Addresses: []string{"ELASTICSEARCH_URL"}})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	queryAuthor := `from library
+        | where author == "Isaac Asimov"
+        | sort release_date desc
+        | limit 10`
+
+	qry := client.Esql.Query().Query(queryAuthor)
+	books, err := query.Helper[Book](context.Background(), qry)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	for _, book := range books {
+		fmt.Println(book)
+	}
+}
+
+------------------------------------
+
+* **Iterative Objects**, where each row in the results is mapped to an object from your
+application domain, one at a time.
+
+[source,go]
+------------------------------------
+queryAuthor := `from library
+    | where author == "Isaac Asimov"
+    | sort release_date desc
+    | limit 10`
+
+qry := client.Esql.Query().Query(queryAuthor)
+books, err := query.NewIteratorHelper[Book](context.Background(), qry)
+if err != nil {
+    log.Fatal(err)
+}
+
+for books.More() {
+    book, err := books.Next()
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Println(book)
+}
+------------------------------------

.doc/typedapi/index.asciidoc

@@ -34,4 +34,5 @@ https://github.com/elastic/elasticsearch-specification[elasticsearch-specificati
 
 include::conventions/index.asciidoc[]
 include::queries.asciidoc[]
+include::esql.asciidoc[]
 include::examples/index.asciidoc[]