documentation

Author: miguelgrinberg

docs/reference/esql-query-builder.md

@@ -0,0 +1,145 @@
+# ES|QL Query Builder
+
+The ES|QL Query Builder allows you to construct ES|QL queries using Python syntax. Consider the following example:
+
+```python
+>>> from elasticsearch.esql import ESQL
+>>> query = (
+    ESQL.from_("employees")
+    .sort("emp_no")
+    .keep("first_name", "last_name", "height")
+    .eval(height_feet="height * 3.281", height_cm="height * 100")
+)
+```
+
+You can then see the assembled ES|QL query by printing the resulting query object:
+
+```python
+>>> query
+FROM employees
+| SORT emp_no
+| KEEP first_name, last_name, height
+| EVAL height_feet = height * 3.281, height_cm = height * 100
+```
+
+To execute this query, you can cast it to a string and pass the string to the `client.esql.query()` endpoint:
+
+```python
+>>> response = client.esql.query(query=str(query))
+```
+
+The response containts a `columns` attribute with the list of columns included in each result, and a `values` attribute with the list of results for the query.
+
+## Creating an ES|QL query
+
+To construct an ES|QL query you start from one of the ES|QL source commands:
+
+### `ESQL.from_`
+
+The `FROM` command selects the indices, data streams or aliases to be queried.
+
+Examples:
+
+```python
+from elasticsearch.esql import ESQL
+
+query1 = ESQL.from_("employees")
+query2 = ESQL.from_("<logs-{now/d}>")
+query3 = ESQL.from_("employees-00001", "other-employees-*")
+query4 = ESQL.from_("cluster_one:employees-00001", "cluster_two:other-employees-*")
+query5 = ESQL.from_("employees").metadata("_id")
+```
+
+Note how in the last example the optional 
+
+### `ESQL.row`
+
+The `ROW` command produces a row with one or more columns, with the values that you specify.
+
+Examples:
+
+```python
+from elasticsearch.esql import ESQL, functions
+
+query1 = ESQL.row(a=1, b="two", c=None)
+query2 = ESQL.row(a=[1, 2])
+query3 = ESQL.row(a=functions.round(1.23, 0))
+```
+
+### `ESQL.show`
+
+The `SHOW` command returns information about the deployment and its capabilities.
+
+Example:
+
+```python
+query = ESQL.show("INFO")
+```
+
+## Adding processing commands
+
+Once you have a query object, you can start adding processing commands to it. The following
+example shows how to create a query that uses the `WHERE` and `LIMIT` clauses to filter the
+results:
+
+```python
+query = ESQL.from_("employees").where("still_hired == true").limit(10)
+```
+
+For a complete list of available commands, review the methods of the [`ESQLBase` class](https://elasticsearch-py.readthedocs.io/en/stable/esql.html) in the Elasticsearch Python API documentation.
+
+## Creating Expressions and Conditions
+
+The ES|QL query builder for Python provides two different ways to create expressions and conditions in ES|QL queries.
+
+The most basic option is to provide expressions as strings. Consider the following example, which defines two expressions in the `EVAL` command:
+
+```python
+query = (
+    ESQL.from_("employees")
+    .sort("emp_no")
+    .keep("first_name", "last_name", "height")
+    .eval(height_feet="height * 3.281", height_cm="height * 100")
+)
+```
+
+A more advanced alternative is to use Python expressions, which are automatically translated to ES|QL. The following example is functionally equivalent to the above:
+
+```python
+from elasticsearch.esql import E
+
+query = (
+    ESQL.from_("employees")
+    .sort("emp_no")
+    .keep("first_name", "last_name", "height")
+    .eval(height_feet=E("height") * 3.281, height_cm=E("height") * 100)
+)
+```
+
+Here the `E()` helper function is used as a wrapper that accepts a column name and transforms it into an ES|QL expression that can be modified with Python operations.
+
+Here is a second example, which uses a function and a comparison in the `WHERE` command:
+
+```python
+query = (
+    ESQL.from_("employees")
+    .keep("first_name", "last_name", "height")
+    .where("LENGTH(first_name) < 4")
+)
+```
+
+Using Python syntax, the condition can be rewritten as follows:
+
+```python
+from elasticsearch.esql import E, functions
+
+query = (
+    ESQL.from_("employees")
+    .keep("first_name", "last_name", "height")
+    .where(functions.length("first_name") < 4)
+)
+```
+
+All available ES|QL functions have Python wrappers in the `esql.functions` module. Because the functions already return ES|QL expressions, it is not necessary to wrap them with the `E()` helper function, which is only used when starting an expression from a field name given as a string.
+
+You can find the complete list of available functions in the [API reference documentation](https://elasticsearch-py.readthedocs.io/en/stable/esql.html#module-elasticsearch.esql.functions).

docs/reference/toc.yml

@@ -5,6 +5,7 @@ toc:
   - file: connecting.md
   - file: configuration.md
   - file: querying.md
+  - file: esql-query-builder.md
   - file: async.md
   - file: integrations.md
     children:

docs/sphinx/esql.rst

@@ -1,6 +1,9 @@
 ES|QL Query Builder
 ===================
 
+Commands
+--------
+
 .. autoclass:: elasticsearch.esql.ESQL
    :inherited-members:
    :members:
@@ -81,3 +84,9 @@ ES|QL Query Builder
 .. autoclass:: elasticsearch.esql.esql.Where
    :members:
    :exclude-members: __init__
+
+Functions
+---------
+
+.. automodule:: elasticsearch.esql.functions
+   :members: