add esql+dsl example

Author: miguelgrinberg

docs/reference/dsl_how_to_guides.md

@@ -1479,12 +1479,12 @@ Katherine Ramirez from Kimberlyton is 1.83m tall
 ...
 ```
 
-To search for specific documents you can extend the base query with additional ES|QL commands that narrow the search criteria. The next example searches for documents that include only employees that are 2m tall or more, sorted by their last name. It also limits the results to 4 people:
+To search for specific documents you can extend the base query with additional ES|QL commands that narrow the search criteria. The next example searches for documents that include only employees that are taller than 2 meters, sorted by their last name. It also limits the results to 4 people:
 
 ```python
 query = (
     Employee.esql_from()
-    .where(Employee.height >= 2)
+    .where(Employee.height > 2)
     .sort(Employee.last_name)
     .limit(4)
 )

docs/reference/esql-query-builder.md

@@ -28,12 +28,12 @@ FROM employees
 | LIMIT 3
 ```
 
-To execute this query, you can cast it to a string and pass the string to the `client.esql.query()` endpoint:
+To execute this query, you can pass it to the `client.esql.query()` endpoint:
 
 ```python
 >>> from elasticsearch import Elasticsearch
 >>> client = Elasticsearch(hosts=[os.environ['ELASTICSEARCH_URL']])
->>> response = client.esql.query(query=str(query))
+>>> response = client.esql.query(query=query)
 ```
 
 The response body contains a `columns` attribute with the list of columns included in the results, and a `values` attribute with the list of results for the query, each given as a list of column values. Here is a possible response body returned by the example query given above:
@@ -216,7 +216,7 @@ def find_employee_by_name(name):
         .keep("first_name", "last_name", "height")
         .where(E("first_name") == E("?"))
     )
-    return client.esql.query(query=str(query), params=[name])
+    return client.esql.query(query=query, params=[name])
 ```
 
 Here the part of the query in which the untrusted data needs to be inserted is replaced with a parameter, which in ES|QL is defined by the question mark. When using Python expressions, the parameter must be given as `E("?")` so that it is treated as an expression and not as a literal string.

elasticsearch/esql/__init__.py

@@ -16,4 +16,4 @@
 #  under the License.
 
 from ..dsl import E  # noqa: F401
-from .esql import ESQL, and_, not_, or_  # noqa: F401
+from .esql import ESQL, ESQLBase, and_, not_, or_  # noqa: F401

elasticsearch/esql/functions.py

@@ -649,7 +649,7 @@ def min_over_time(field: ExpressionType) -> InstrumentedExpression:
 
 
 def multi_match(
-    query: ExpressionType, fields: ExpressionType, options: ExpressionType = None
+    query: ExpressionType, *fields: ExpressionType, options: ExpressionType = None
 ) -> InstrumentedExpression:
     """Use `MULTI_MATCH` to perform a multi-match query on the specified field.
     The multi_match query builds on the match query to allow multi-field queries.
@@ -661,11 +661,11 @@ def multi_match(
     """
     if options is not None:
         return InstrumentedExpression(
-            f"MULTI_MATCH({_render(query)}, {_render(fields)}, {_render(options)})"
+            f'MULTI_MATCH({_render(query)}, {", ".join([_render(c) for c in fields])}, {_render(options)})'
         )
     else:
         return InstrumentedExpression(
-            f"MULTI_MATCH({_render(query)}, {_render(fields)})"
+            f'MULTI_MATCH({_render(query)}, {", ".join([_render(c) for c in fields])})'
         )
 
 

examples/dsl/async/esql_employees.py

@@ -0,0 +1,170 @@
+#  Licensed to Elasticsearch B.V. under one or more contributor
+#  license agreements. See the NOTICE file distributed with
+#  this work for additional information regarding copyright
+#  ownership. Elasticsearch B.V. licenses this file to you under
+#  the Apache License, Version 2.0 (the "License"); you may
+#  not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing,
+#  software distributed under the License is distributed on an
+#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#  KIND, either express or implied.  See the License for the
+#  specific language governing permissions and limitations
+#  under the License.
+
+"""
+# ES|QL query builder example
+
+Requirements:
+
+$ pip install "elasticsearch[async]" faker
+
+To run the example:
+
+$ python esql_employees.py "name to search"
+
+The index will be created automatically with a list of 1000 randomly generated
+employees if it does not exist. Add `--recreate-index` or `-r` to the command
+to regenerate it.
+
+Examples:
+
+$ python esql_employees "Mark"  # employees named Mark (first or last names)
+$ python esql_employees "Sarah" --limit 10  # up to 10 employees named Sarah
+$ python esql_employees "Sam" --sort height  # sort results by height
+$ python esql_employees "Sam" --sort name  # sort results by last name
+"""
+
+import argparse
+import asyncio
+import os
+import random
+
+from faker import Faker
+
+from elasticsearch.dsl import AsyncDocument, InnerDoc, M, async_connections
+from elasticsearch.esql import ESQLBase
+from elasticsearch.esql.functions import concat, multi_match
+
+fake = Faker()
+
+
+class Address(InnerDoc):
+    address: M[str]
+    city: M[str]
+    zip_code: M[str]
+
+
+class Employee(AsyncDocument):
+    emp_no: M[int]
+    first_name: M[str]
+    last_name: M[str]
+    height: M[float]
+    still_hired: M[bool]
+    address: M[Address]
+
+    class Index:
+        name = "employees"
+
+    @property
+    def name(self) -> str:
+        return f"{self.first_name} {self.last_name}"
+
+    def __repr__(self) -> str:
+        return f"<Employee[{self.meta.id}]: {self.first_name} {self.last_name}>"
+
+
+async def create(num_employees: int = 1000) -> None:
+    print("Creating a new employee index...")
+    if await Employee._index.exists():
+        await Employee._index.delete()
+    await Employee.init()
+
+    for i in range(num_employees):
+        address = Address(
+            address=fake.address(), city=fake.city(), zip_code=fake.zipcode()
+        )
+        emp = Employee(
+            emp_no=10000 + i,
+            first_name=fake.first_name(),
+            last_name=fake.last_name(),
+            height=int((random.random() * 0.8 + 1.5) * 1000) / 1000,
+            still_hired=random.random() >= 0.5,
+            address=address,
+        )
+        await emp.save()
+    await Employee._index.refresh()
+
+
+async def search(query: str, limit: int, sort: str) -> None:
+    q: ESQLBase = (
+        Employee.esql_from()
+        .where(multi_match(query, Employee.first_name, Employee.last_name))
+        .eval(full_name=concat(Employee.first_name, " ", Employee.last_name))
+    )
+    if sort == "height":
+        q = q.sort(Employee.height.desc())
+    else:
+        q = q.sort(Employee.last_name.asc())
+    q = q.limit(limit)
+    async for result in Employee.esql_execute(q, return_additional=True):
+        assert type(result) == tuple
+        employee = result[0]
+        full_name = result[1]["full_name"]
+        print(
+            f"{full_name:<20}",
+            f"{'Hired' if employee.still_hired else 'Not hired':<10}",
+            f"{employee.height:5.2f}m",
+            f"{employee.address.city:<20}",
+        )
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Employee ES|QL example")
+    parser.add_argument(
+        "--recreate-index",
+        "-r",
+        action="store_true",
+        help="Recreate and populate the index",
+    )
+    parser.add_argument(
+        "--limit",
+        action="store",
+        type=int,
+        default=100,
+        help="Maximum number or employees to return (default: 100)",
+    )
+    parser.add_argument(
+        "--sort",
+        action="store",
+        type=str,
+        default="name",
+        help='Sort by "name" (ascending) or by "height" (descending) (default: name)',
+    )
+    parser.add_argument(
+        "query", action="store", help="The name or partial name to search for"
+    )
+    return parser.parse_args()
+
+
+async def main() -> None:
+    args = parse_args()
+
+    # initiate the default connection to elasticsearch
+    async_connections.create_connection(hosts=[os.environ["ELASTICSEARCH_URL"]])
+
+    if args.recreate_index or not await Employee._index.exists():
+        await create()
+    await Employee.init()
+
+    await search(args.query, args.limit, args.sort)
+
+    # close the connection
+    await async_connections.get_connection().close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())