Skip to content

Commit 3404a9f

Browse files
miguelgrinbergmiguelgrinberg
committed
md to asciidoc docs translation
1 parent 1ee529d commit 3404a9f

File tree

2 files changed

+259
-2
lines changed

2 files changed

+259
-2
lines changed

‎docs/guide/esql-query-builder.asciidoc

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
[[esql-query-builder]]
2+
== ES|QL Query Builder
3+
4+
WARNING: This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
5+
6+
The ES|QL Query Builder allows you to construct ES|QL queries using Python syntax. Consider the following example:
7+
8+
[source, python]
9+
----------------------------
10+
>>> from elasticsearch.esql import ESQL
11+
>>> query = (
12+
ESQL.from_("employees")
13+
.sort("emp_no")
14+
.keep("first_name", "last_name", "height")
15+
.eval(height_feet="height * 3.281", height_cm="height * 100")
16+
.limit(3)
17+
)
18+
----------------------------
19+
20+
You can then see the assembled ES|QL query by printing the resulting query object:
21+
22+
[source, python]
23+
----------------------------
24+
>>> query
25+
FROM employees
26+
| SORT emp_no
27+
| KEEP first_name, last_name, height
28+
| EVAL height_feet = height * 3.281, height_cm = height * 100
29+
| LIMIT 3
30+
----------------------------
31+
32+
To execute this query, you can cast it to a string and pass the string to the `client.esql.query()` endpoint:
33+
34+
[source, python]
35+
----------------------------
36+
>>> from elasticsearch import Elasticsearch
37+
>>> client = Elasticsearch(hosts=[os.environ['ELASTICSEARCH_URL']])
38+
>>> response = client.esql.query(query=str(query))
39+
----------------------------
40+
41+
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:
42+
43+
[source, python]
44+
----------------------------
45+
>>> from pprint import pprint
46+
>>> pprint(response.body)
47+
{'columns': [{'name': 'first_name', 'type': 'text'},
48+
{'name': 'last_name', 'type': 'text'},
49+
{'name': 'height', 'type': 'double'},
50+
{'name': 'height_feet', 'type': 'double'},
51+
{'name': 'height_cm', 'type': 'double'}],
52+
'is_partial': False,
53+
'took': 11,
54+
'values': [['Adrian', 'Wells', 2.424, 7.953144, 242.4],
55+
['Aaron', 'Gonzalez', 1.584, 5.1971, 158.4],
56+
['Miranda', 'Kramer', 1.55, 5.08555, 155]]}
57+
----------------------------
58+
59+
=== Creating an ES|QL query
60+
61+
To construct an ES|QL query you start from one of the ES|QL source commands:
62+
63+
==== `ESQL.from_`
64+
65+
The `FROM` command selects the indices, data streams or aliases to be queried.
66+
67+
Examples:
68+
69+
[source, python]
70+
----------------------------
71+
from elasticsearch.esql import ESQL
72+
73+
# FROM employees
74+
query1 = ESQL.from_("employees")
75+
76+
# FROM <logs-{now/d}>
77+
query2 = ESQL.from_("<logs-{now/d}>")
78+
79+
# FROM employees-00001, other-employees-*
80+
query3 = ESQL.from_("employees-00001", "other-employees-*")
81+
82+
# FROM cluster_one:employees-00001, cluster_two:other-employees-*
83+
query4 = ESQL.from_("cluster_one:employees-00001", "cluster_two:other-employees-*")
84+
85+
# FROM employees METADATA _id
86+
query5 = ESQL.from_("employees").metadata("_id")
87+
----------------------------
88+
89+
Note how in the last example the optional `METADATA` clause of the `FROM` command is added as a chained method.
90+
91+
==== `ESQL.row`
92+
93+
The `ROW` command produces a row with one or more columns, with the values that you specify.
94+
95+
Examples:
96+
97+
[source, python]
98+
----------------------------
99+
from elasticsearch.esql import ESQL, functions
100+
101+
# ROW a = 1, b = "two", c = null
102+
query1 = ESQL.row(a=1, b="two", c=None)
103+
104+
# ROW a = [1, 2]
105+
query2 = ESQL.row(a=[1, 2])
106+
107+
# ROW a = ROUND(1.23, 0)
108+
query3 = ESQL.row(a=functions.round(1.23, 0))
109+
----------------------------
110+
111+
==== `ESQL.show`
112+
113+
The `SHOW` command returns information about the deployment and its capabilities.
114+
115+
Example:
116+
117+
[source, python]
118+
----------------------------
119+
from elasticsearch.esql import ESQL
120+
121+
# SHOW INFO
122+
query = ESQL.show("INFO")
123+
----------------------------
124+
125+
=== Adding processing commands
126+
127+
Once you have a query object, you can add one or more processing commands to it. The following
128+
example shows how to create a query that uses the `WHERE` and `LIMIT` commands to filter the
129+
results:
130+
131+
[source, python]
132+
----------------------------
133+
from elasticsearch.esql import ESQL
134+
135+
# FROM employees
136+
# | WHERE still_hired == true
137+
# | LIMIT 10
138+
query = ESQL.from_("employees").where("still_hired == true").limit(10)
139+
----------------------------
140+
141+
For a complete list of available commands, review the methods of the https://elasticsearch-py.readthedocs.io/en/stable/esql.html[`ESQLBase` class] in the Elasticsearch Python API documentation.
142+
143+
=== Creating ES|QL Expressions and Conditions
144+
145+
The ES|QL query builder for Python provides two ways to create expressions and conditions in ES|QL queries.
146+
147+
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:
148+
149+
[source, python]
150+
----------------------------
151+
from elasticsearch.esql import ESQL
152+
153+
# FROM employees
154+
# | SORT emp_no
155+
# | KEEP first_name, last_name, height
156+
# | EVAL height_feet = height * 3.281, height_cm = height * 100
157+
query = (
158+
ESQL.from_("employees")
159+
.sort("emp_no")
160+
.keep("first_name", "last_name", "height")
161+
.eval(height_feet="height * 3.281", height_cm="height * 100")
162+
)
163+
----------------------------
164+
165+
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:
166+
167+
[source, python]
168+
----------------------------
169+
from elasticsearch.esql import ESQL, E
170+
171+
# FROM employees
172+
# | SORT emp_no
173+
# | KEEP first_name, last_name, height
174+
# | EVAL height_feet = height * 3.281, height_cm = height * 100
175+
query = (
176+
ESQL.from_("employees")
177+
.sort("emp_no")
178+
.keep("first_name", "last_name", "height")
179+
.eval(height_feet=E("height") * 3.281, height_cm=E("height") * 100)
180+
)
181+
----------------------------
182+
183+
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.
184+
185+
Here is a second example, which uses a conditional expression in the `WHERE` command:
186+
187+
[source, python]
188+
----------------------------
189+
from elasticsearch.esql import ESQL
190+
191+
# FROM employees
192+
# | KEEP first_name, last_name, height
193+
# | WHERE first_name == "Larry"
194+
query = (
195+
ESQL.from_("employees")
196+
.keep("first_name", "last_name", "height")
197+
.where('first_name == "Larry"')
198+
)
199+
----------------------------
200+
201+
Using Python syntax, the condition can be rewritten as follows:
202+
203+
[source, python]
204+
----------------------------
205+
from elasticsearch.esql import ESQL, E
206+
207+
# FROM employees
208+
# | KEEP first_name, last_name, height
209+
# | WHERE first_name == "Larry"
210+
query = (
211+
ESQL.from_("employees")
212+
.keep("first_name", "last_name", "height")
213+
.where(E("first_name") == "Larry")
214+
)
215+
----------------------------
216+
217+
=== Using ES|QL functions
218+
219+
The ES|QL language includes a rich set of functions that can be used in expressions and conditionals. These can be included in expressions given as strings, as shown in the example below:
220+
221+
[source, python]
222+
----------------------------
223+
from elasticsearch.esql import ESQL
224+
225+
# FROM employees
226+
# | KEEP first_name, last_name, height
227+
# | WHERE LENGTH(first_name) < 4"
228+
query = (
229+
ESQL.from_("employees")
230+
.keep("first_name", "last_name", "height")
231+
.where("LENGTH(first_name) < 4")
232+
)
233+
----------------------------
234+
235+
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 example above coded using Python syntax:
236+
237+
[source, python]
238+
----------------------------
239+
from elasticsearch.esql import ESQL, functions
240+
241+
# FROM employees
242+
# | KEEP first_name, last_name, height
243+
# | WHERE LENGTH(first_name) < 4"
244+
query = (
245+
ESQL.from_("employees")
246+
.keep("first_name", "last_name", "height")
247+
.where(functions.length(E("first_name")) < 4)
248+
)
249+
----------------------------
250+
251+
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.
252+
253+
You can find the complete list of available functions in the Python client's https://elasticsearch-py.readthedocs.io/en/stable/esql.html#module-elasticsearch.esql.functions[ES|QL API reference documentation].

‎docs/guide/index.asciidoc

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,18 @@ include::connecting.asciidoc[]
1616

1717
include::configuration.asciidoc[]
1818

19+
include::esql-query-builder.asciidoc[]
20+
21+
include::async.asciidoc[]
22+
1923
include::migration.asciidoc[]
2024

2125
include::integrations.asciidoc[]
2226

2327
include::examples.asciidoc[]
2428

25-
include::elasticsearch-dsl.asciidoc[]
26-
2729
include::helpers.asciidoc[]
2830

31+
include::elasticsearch-dsl.asciidoc[]
32+
2933
include::release-notes.asciidoc[]

0 commit comments

Comments
 (0)