From f135fe43882966a1cbef3831456e88ebbe35338a Mon Sep 17 00:00:00 2001 From: Fernando Briano Date: Wed, 16 Jul 2025 17:14:32 +0100 Subject: [PATCH 1/2] [DOCS] Adds information about elastic-esql gem --- docs/reference/esql.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/reference/esql.md b/docs/reference/esql.md index 6fea4bcdd..10522b0d6 100644 --- a/docs/reference/esql.md +++ b/docs/reference/esql.md @@ -14,6 +14,7 @@ There are two ways to use ES|QL in the Ruby client: * 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. * Use the Ruby ES|QL helper: The helper maps the raw response to an object that’s more readily usable by your application. +There is also a gem which can help you build ES|QL queries with Ruby code, [elastic-esql](#esql-ruby). ## ES|QL API [esql-how-to] @@ -108,3 +109,25 @@ puts response {"duration_ms"=>8.3, "message"=>"Connection error", "event.duration"=>"8268153", "client.ip"=>#, "@timestamp"=>#} ``` +## ES|QL Query Builder [esql-ruby] + +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. + +It allows you to build queries in Ruby like this: + +```ruby +query = Elastic::ESQL.from('sample') + .sort('@timestamp') + .desc + .where('event_duration > 5000000') + .limit(3) +``` + +You can see the generated query with `.to_s`: + +```ruby +query.to_s +=> "FROM sample | SORT @timestamp DESC | WHERE event_duration > 5000000 | LIMIT 3" +``` + +See [the README](https://github.com/elastic/esql-ruby?tab=readme-ov-file#ruby-esql-query-builder) for more information. From 64d68ef94d0529b6f75a74b56b089cf6403f62b5 Mon Sep 17 00:00:00 2001 From: Fernando Briano Date: Fri, 18 Jul 2025 09:40:59 +0100 Subject: [PATCH 2/2] Updates docs/reference/esql.md Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/reference/esql.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/reference/esql.md b/docs/reference/esql.md index 10522b0d6..0f2cb112b 100644 --- a/docs/reference/esql.md +++ b/docs/reference/esql.md @@ -14,7 +14,7 @@ There are two ways to use ES|QL in the Ruby client: * 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. * Use the Ruby ES|QL helper: The helper maps the raw response to an object that’s more readily usable by your application. -There is also a gem which can help you build ES|QL queries with Ruby code, [elastic-esql](#esql-ruby). +You can also try the [`elastic-esql`](#esql-ruby) gem, which helps you build ES|QL queries with Ruby. ## ES|QL API [esql-how-to] @@ -111,9 +111,7 @@ puts response ## ES|QL Query Builder [esql-ruby] -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. - -It allows you to build queries in Ruby like this: +The [`elastic-esql`](https://github.com/elastic/esql-ruby) gem helps you build queries for use with the [ES|QL query API](docs-content://explore-analyze/query-filter/languages/esql-rest.md). Here's an example: ```ruby query = Elastic::ESQL.from('sample') @@ -130,4 +128,5 @@ query.to_s => "FROM sample | SORT @timestamp DESC | WHERE event_duration > 5000000 | LIMIT 3" ``` -See [the README](https://github.com/elastic/esql-ruby?tab=readme-ov-file#ruby-esql-query-builder) for more information. +The `elastic-esql` library works independently of the {{es}} client, so you can use it alongside any client — not just `elasticsearch-ruby`. +For more information, see the gem [README](https://github.com/elastic/esql-ruby?tab=readme-ov-file#ruby-esql-query-builder).