Skip to content

Commit 78bf280

Browse files
committed
[DOCS] Updates ES|QL query builder docs
1 parent 117888f commit 78bf280

File tree

1 file changed

+35
-1
lines changed

1 file changed

+35
-1
lines changed

docs/reference/esql.md

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,5 +128,39 @@ query.to_s
128128
=> "FROM sample | SORT @timestamp DESC | WHERE event_duration > 5000000 | LIMIT 3"
129129
```
130130

131-
The `elastic-esql` library works independently of the {{es}} client, so you can use it alongside any client — not just `elasticsearch-ruby`.
131+
The `elastic-esql` library works independently of the {{es}} client, so you can use it alongside any client — not just `elasticsearch-ruby`. But once you build a query object, you can pass it directly to the `esql.query` API in `elasticsearch-ruby`:
132+
133+
```ruby
134+
require 'elasticsearch'
135+
require 'elastic/esql'
136+
137+
client = Elasticsearch::Client.new
138+
index = 'sample_data'
139+
140+
query = Elastic::ESQL.from(index)
141+
.sort('@timestamp')
142+
.desc
143+
.where('event_duration > 5000000')
144+
.limit(3)
145+
.eval({ duration_ms: 'ROUND(event_duration/1000000.0, 1)' })
146+
client.esql.query(body: { query: query })
147+
```
148+
132149
For more information, see the gem [README](https://github.com/elastic/esql-ruby?tab=readme-ov-file#ruby-esql-query-builder).
150+
151+
### Preventing injection attacks
152+
153+
ES|QL, like most query languages, is vulnerable to [code injection attacks](https://en.wikipedia.org/wiki/Code_injection) if untrusted data provided by users is added to a query. To eliminate this risk, ES|QL allows untrusted data to be given separately from the query as parameters.
154+
155+
Let's assume an application needs a `find_employee_by_name()` function that searches for the name given as an argument. If this argument is received by the application from users, then it is considered untrusted and should not be added to the query directly. Here is how to code the function in a secure manner:
156+
157+
```ruby
158+
def find_employee_by_name(name)
159+
query = Elastic::ESQL.from('employees')
160+
.keep('first_name', 'last_name', 'height')
161+
.where('first_name == ?')
162+
@client.esql.query(body: { query: query, params: [name] })
163+
end
164+
```
165+
166+
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. The list of values given in the `params` argument to the query endpoint are assigned in order to the parameters defined in the query.

0 commit comments

Comments
 (0)