Tweak TOC

docs/esql.asciidoc

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

@@ -6,6 +6,8 @@
 include::{docs-root}/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 +24,8 @@ include::operations.asciidoc[]
 
 include::helpers.asciidoc[]
 
+include::esql.asciidoc[]
+
 include::release-notes.asciidoc[]
 
 include::redirects.asciidoc[]