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/semantic_text.py

@@ -21,7 +21,7 @@
 
 Requirements:
 
-$ pip install "elasticsearch" tqdm
+$ pip install elasticsearch tqdm
 
 Before running this example, an ELSER inference endpoint must be created in the
 Elasticsearch cluster. This can be done manually from Kibana, or with the

examples/dsl/sparse_vectors.py

@@ -20,7 +20,7 @@
 
 Requirements:
 
-$ pip install nltk tqdm "elasticsearch"
+$ pip install nltk tqdm elasticsearch
 
 Before running this example, the ELSER v2 model must be downloaded and deployed
 to the Elasticsearch cluster, and an ingest pipeline must be defined. This can

examples/dsl/vectors.py

@@ -20,7 +20,7 @@
 
 Requirements:
 
-$ pip install nltk sentence_transformers tqdm "elasticsearch"
+$ pip install nltk sentence_transformers tqdm elasticsearch
 
 To run the example:
 

utils/run-unasync-dsl.py

@@ -121,7 +121,7 @@ def main(check=False):
                 [
                     "sed",
                     "-i.bak",
-                    "s/elasticsearch\\[async\\]/elasticsearch/",
+                    's/"elasticsearch\\[async\\]"/elasticsearch/',
                     f"{output_dir}{file}",
                 ]
             )