Skip to content

Commit b24f5d8

Browse files
committed
[DOCS] Adds information about elastic-esql gem
1 parent b23d928 commit b24f5d8

File tree

1 file changed

+23
-0
lines changed

1 file changed

+23
-0
lines changed

docs/reference/esql.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ There are two ways to use ES|QL in the Ruby client:
1414
* Use the Elasticsearch [ES|QL API](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-esql) directly: This is the most flexible approach, but it’s also the most complex because you must handle results in their raw form. You can choose the precise format of results, such as JSON, CSV, or text.
1515
* Use the Ruby ES|QL helper: The helper maps the raw response to an object that’s more readily usable by your application.
1616

17+
There is also a gem which can help you build ES|QL queries with Ruby code, [elastic-esql](#esql-ruby).
1718

1819
## ES|QL API [esql-how-to]
1920

@@ -108,3 +109,25 @@ puts response
108109
{"duration_ms"=>8.3, "message"=>"Connection error", "event.duration"=>"8268153", "client.ip"=>#<IPAddr: IPv4:172.21.3.15/255.255.255.255>, "@timestamp"=>#<DateTime: 2023-10-23T13:52:55+00:00 ((2460241j,49975s,15000000n),+0s,2299161j)>}
109110
```
110111

112+
## ES|QL Query Builder [esql-ruby]
113+
114+
The [elastic-esql](https://github.com/elastic/esql-ruby) gem allows you to build ES|QL queries to use with Elastic's ES|QL `query` API. The library doesn't depend on an Elasticsearch client - its sole purpose is to facilitate building ES|QL queries in Ruby. This makes it possible to use it with any Elasticsearch client.
115+
116+
It allows you to build queries in Ruby like this:
117+
118+
```ruby
119+
query = Elastic::ESQL.from('sample')
120+
.sort('@timestamp')
121+
.desc
122+
.where('event_duration > 5000000')
123+
.limit(3)
124+
```
125+
126+
You can see the generated query with `.to_s`:
127+
128+
```ruby
129+
query.to_s
130+
=> "FROM sample | SORT @timestamp DESC | WHERE event_duration > 5000000 | LIMIT 3"
131+
```
132+
133+
See [the README](https://github.com/elastic/esql-ruby?tab=readme-ov-file#use) for more information.

0 commit comments

Comments
 (0)