Skip to content

Commit 09a1f99

Browse files
miguelgrinbergmiguelgrinberg
committed
documentation
1 parent 27d8977 commit 09a1f99

File tree

3 files changed

+220
-0
lines changed

3 files changed

+220
-0
lines changed

‎docs/reference/esql-query-builder.md

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# ES|QL Query Builder
2+
3+
The ES|QL Query Builder allows you to construct ES|QL queries using Python syntax. Consider the following example:
4+
5+
```python
6+
>>> from elasticsearch.esql import ESQL
7+
>>> query = (
8+
ESQL.from_("employees")
9+
.sort("emp_no")
10+
.keep("first_name", "last_name", "height")
11+
.eval(height_feet="height * 3.281", height_cm="height * 100")
12+
.limit(3)
13+
)
14+
```
15+
16+
You can then see the assembled ES|QL query by printing the resulting query object:
17+
18+
```python
19+
>>> query
20+
FROM employees
21+
| SORT emp_no
22+
| KEEP first_name, last_name, height
23+
| EVAL height_feet = height * 3.281, height_cm = height * 100
24+
| LIMIT 3
25+
```
26+
27+
To execute this query, you can cast it to a string and pass the string to the `client.esql.query()` endpoint:
28+
29+
```python
30+
>>> from elasticsearch import Elasticsearch
31+
>>> client = Elasticsearch(hosts=[os.environ['ELASTICSEARCH_URL']])
32+
>>> response = client.esql.query(query=str(query))
33+
```
34+
35+
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:
36+
37+
```python
38+
>>> from pprint import pprint
39+
>>> pprint(response.body)
40+
{'columns': [{'name': 'first_name', 'type': 'text'},
41+
{'name': 'last_name', 'type': 'text'},
42+
{'name': 'height', 'type': 'double'},
43+
{'name': 'height_feet', 'type': 'double'},
44+
{'name': 'height_cm', 'type': 'double'}],
45+
'is_partial': False,
46+
'took': 11,
47+
'values': [['Adrian',
48+
'Wells',
49+
2.424,
50+
7.953144,
51+
242.4],
52+
['Aaron',
53+
'Gonzalez',
54+
1.584,
55+
5.1971,
56+
158.4],
57+
['Miranda',
58+
'Kramer',
59+
1.55,
60+
5.08555,
61+
155]]}
62+
```
63+
64+
## Creating an ES|QL query
65+
66+
To construct an ES|QL query you start from one of the ES|QL source commands:
67+
68+
### `ESQL.from_`
69+
70+
The `FROM` command selects the indices, data streams or aliases to be queried.
71+
72+
Examples:
73+
74+
```python
75+
from elasticsearch.esql import ESQL
76+
77+
query1 = ESQL.from_("employees")
78+
query2 = ESQL.from_("<logs-{now/d}>")
79+
query3 = ESQL.from_("employees-00001", "other-employees-*")
80+
query4 = ESQL.from_("cluster_one:employees-00001", "cluster_two:other-employees-*")
81+
query5 = ESQL.from_("employees").metadata("_id")
82+
```
83+
84+
Note how in the last example the optional `METADATA` clause of the `FROM` command is added as a chained method.
85+
86+
### `ESQL.row`
87+
88+
The `ROW` command produces a row with one or more columns, with the values that you specify.
89+
90+
Examples:
91+
92+
```python
93+
from elasticsearch.esql import ESQL, functions
94+
95+
query1 = ESQL.row(a=1, b="two", c=None)
96+
query2 = ESQL.row(a=[1, 2])
97+
query3 = ESQL.row(a=functions.round(1.23, 0))
98+
```
99+
100+
### `ESQL.show`
101+
102+
The `SHOW` command returns information about the deployment and its capabilities.
103+
104+
Example:
105+
106+
```python
107+
from elasticsearch.esql import ESQL
108+
109+
query = ESQL.show("INFO")
110+
```
111+
112+
## Adding processing commands
113+
114+
Once you have a query object, you can add one or more processing commands to it. The following
115+
example shows how to create a query that uses the `WHERE` and `LIMIT` commands to filter the
116+
results:
117+
118+
```python
119+
from elasticsearch.esql import ESQL
120+
121+
query = ESQL.from_("employees").where("still_hired == true").limit(10)
122+
```
123+
124+
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.
125+
126+
## Creating ES|QL Expressions and Conditions
127+
128+
The ES|QL query builder for Python provides two ways to create expressions and conditions in ES|QL queries.
129+
130+
The simplest option is to provide all ES|QL expressions and conditionals as strings. The following example uses this approach to add two calculated columns to the results using the `EVAL` command:
131+
132+
```python
133+
from elasticsearch.esql import ESQL
134+
135+
query = (
136+
ESQL.from_("employees")
137+
.sort("emp_no")
138+
.keep("first_name", "last_name", "height")
139+
.eval(height_feet="height * 3.281", height_cm="height * 100")
140+
)
141+
```
142+
143+
A more advanced alternative is to replace the strings with Python expressions, which are automatically translated to ES|QL when the query object is rendered to a string. The following example is functionally equivalent to the one above:
144+
145+
```python
146+
from elasticsearch.esql import ESQL, E
147+
148+
query = (
149+
ESQL.from_("employees")
150+
.sort("emp_no")
151+
.keep("first_name", "last_name", "height")
152+
.eval(height_feet=E("height") * 3.281, height_cm=E("height") * 100)
153+
)
154+
```
155+
156+
Here the `E()` helper function is used as a wrapper to the column name that initiates an ES|QL expression. The `E()` function transforms the given column into an ES|QL expression that can be modified with Python operators.
157+
158+
Here is a second example, which uses a conditional expression in the `WHERE` command:
159+
160+
```python
161+
from elasticsearch.esql import ESQL, E
162+
163+
query = (
164+
ESQL.from_("employees")
165+
.keep("first_name", "last_name", "height")
166+
.where('first_name == "Larry"')
167+
)
168+
```
169+
170+
Using Python syntax, the condition can be rewritten as follows:
171+
172+
```python
173+
from elasticsearch.esql import ESQL, E
174+
175+
query = (
176+
ESQL.from_("employees")
177+
.keep("first_name", "last_name", "height")
178+
.where(E("first_name") == "Larry")
179+
)
180+
```
181+
182+
## Using ES|QL functions
183+
184+
The ES|QL language includes a rich set of functions that can be used in expressions and conditionals, and these can be included in expressions that are given as strings, as shown in the example below:
185+
186+
```python
187+
from elasticsearch.esql import ESQL
188+
189+
query = (
190+
ESQL.from_("employees")
191+
.keep("first_name", "last_name", "height")
192+
.where("LENGTH(first_name) < 4")
193+
)
194+
```
195+
196+
All available ES|QL functions have Python wrappers in the `elasticsearch.esql.functions` module, which can be used when building expressions using Python syntax. Below is the same example coded using Python syntax:
197+
198+
```python
199+
from elasticsearch.esql import ESQL, functions
200+
201+
query = (
202+
ESQL.from_("employees")
203+
.keep("first_name", "last_name", "height")
204+
.where(functions.length(E("first_name")) < 4)
205+
)
206+
```
207+
208+
Note that arguments passed to functions are assumed to be literals. When passing field names, it is necessary to wrap them with the `E()` helper function so that they are interpreted correctly.
209+
210+
You can find the complete list of available functions in the [ES|QL API reference documentation](https://elasticsearch-py.readthedocs.io/en/stable/esql.html#module-elasticsearch.esql.functions).

‎docs/reference/toc.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ toc:
55
- file: connecting.md
66
- file: configuration.md
77
- file: querying.md
8+
- file: esql-query-builder.md
89
- file: async.md
910
- file: integrations.md
1011
children:

‎docs/sphinx/esql.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
ES|QL Query Builder
22
===================
33

4+
Commands
5+
--------
6+
47
.. autoclass:: elasticsearch.esql.ESQL
58
:inherited-members:
69
:members:
@@ -81,3 +84,9 @@ ES|QL Query Builder
8184
.. autoclass:: elasticsearch.esql.esql.Where
8285
:members:
8386
:exclude-members: __init__
87+
88+
Functions
89+
---------
90+
91+
.. automodule:: elasticsearch.esql.functions
92+
:members:

0 commit comments

Comments
 (0)