[DOCS] Add ES|QL doc structure

docs/guide/helpers/esql.asciidoc

@@ -0,0 +1,79 @@
+[[esql]]
+=== ES|QL in the Python client
+++++
+<titleabbrev>ES|QL</titleabbrev>
+++++
+
+This page helps you understand and use {ref}/esql.html[ES|QL] in the
+Python client.
+
+There are two ways to use ES|QL in the Python 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 Python-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 Python 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/guide/helpers.asciidoc → docs/guide/helpers/helper-functions.asciidoc

@@ -1,14 +1,14 @@
-[[client-helpers]]
-== Client helpers
+[[helper-functions]]
+=== Helper functions
 
-You can find here a collection of simple helper functions that abstract some 
+These simple helper functions abstract some 
 specifics of the raw API. For detailed examples, refer to 
 https://elasticsearch-py.readthedocs.io/en/stable/helpers.html[this page].
 
 
 [discrete]
 [[bulk-helpers]]
-=== Bulk helpers 
+==== Bulk helpers 
 
 There are several helpers for the bulk API since its requirement for specific 
 formatting and other considerations can make it cumbersome if used directly.
@@ -70,7 +70,7 @@ the `_op_type` field to specify an action (`_op_type` defaults to `index`):
 
 [discrete]
 [[scan]]
-=== Scan
+==== Scan
 
 Simple abstraction on top of the `scroll()` API - a simple iterator that yields 
 all hits as returned by underlining scroll requests.

docs/guide/helpers/index.asciidoc

@@ -0,0 +1,10 @@
+[[client-helpers]]
+== Client helpers
+
+The Python client includes the following helpers:
+
+* <<helper-functions>>
+* <<esql>>
+
+include::helper-functions.asciidoc[]
+include::esql.asciidoc[]

docs/guide/index.asciidoc

@@ -6,6 +6,9 @@ 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[]
@@ -22,6 +25,6 @@ include::integrations.asciidoc[]
 
 include::examples.asciidoc[]
 
-include::helpers.asciidoc[]
+include::helpers/index.asciidoc[]
 
 include::release-notes.asciidoc[]