作者：来自 Elastic Fernando Briano

学习如何使用最近发布的 Elasticsearch Ruby Client 的 ES|QL 查询生成器。一个用 Ruby 代码更轻松构建 ES|QL 查询的工具。

亲身体验 Elasticsearch：深入我们的示例笔记本，开始免费的云试用，或立即在本地机器上尝试 Elastic。

我们最近发布了 elastic-esql，这是一个在 Apache 2 许可下发布的 Ruby gem。这个 gem 允许你用地道的 Ruby 构建 Elastic 的 ES|QL 查询，然后你可以将其与 ES|QL 查询 API 一起使用。ES|QL 允许开发者通过查询过滤、转换和分析存储在 Elasticsearch 中的数据。它使用 “管道” ( | ) 来逐步处理数据。而这个 gem 则使用 Ruby 函数，你可以将这些函数链式连接到原始对象以构建更复杂的查询：

ESQL:

FROM sample_data | LIMIT 2 | SORT @timestamp DESC

Ruby:

Elastic::ESQL.from('sample_data').limit(2).sort('@timestamp').descending

安装

这个 gem 可以通过 RubyGems 安装：

gem install elastic-esql

或者它可以添加到项目的 Gemfile 中：

gem 'elastic-esql'

用法

你可以一次性构建完整查询，或者使用 from 或 row 这样的 source 命令创建一个查询对象，然后链式调用 ES|QL 方法来扩展它。

query = Elastic::ESQL.from('sample_data')
query.limit(2).sort('@timestamp')

这个 gem 会在 to_s 方法中将代码转换为 ES|QL，因此当它被打印或转换为 String 时会返回 ES|QL 查询：

query = Elastic::ESQL.from('sample_data').limit(2).sort('@timestamp').descending
query.to_s
# => "FROM sample_data | LIMIT 2 | SORT @timestamp DESC"

你可以通过使用每个函数对应的 ! 版本来实例化一个查询对象并修改其初始状态：

query = Elastic::ESQL.from('sample_data')
query.to_s
# => "FROM sample_data"
query.limit!(2).sort!('@timestamp')
query.to_s
# => "FROM sample_data | LIMIT 2 | SORT @timestamp"

该工具提供了方便的方法将额外步骤链式添加到 ES|QL 函数中，比如 enrich 和 sort。一旦你在 Elastic::ESQL 对象上调用 enrich，就可以在其后链式调用 on 和 with：

esql.enrich!('policy').on('a').with({ name: 'language_name' })

在使用 sort 之后，你也可以将 desc、asc、nulls_first 和 nulls_last 链式添加到查询中：

Elastic::ESQL.from('sample_data').sort('@timestamp').asc.to_s
# => 'FROM sample_data | SORT @timestamp ASC'

Elastic::ESQL.from('sample_data').sort('@timestamp').desc.nulls_first.to_s
# => 'FROM sample_data | SORT @timestamp DESC NULLS FIRST'

它还支持自定义 Strings，以防你想自己编写 ES|QL 查询，或使用库中尚未添加的功能。custom 会在查询末尾连接这些字符串。它会按传入函数时的形式添加，不会加入任何管道字符。它们会通过空格字符与查询的其他部分组合。

esql = Elastic::ESQL.from('sample_data')
esql.custom('| MY_VALUE = "test value"').to_s
# => 'FROM sample_data | MY_VALUE = "test value"'

你也可以链式调用自定义函数：

esql.custom('| MY_VALUE = "test value"').custom('| ANOTHER, VALUE')
'FROM sample_data | MY_VALUE = "test value" | ANOTHER, VALUE'

在 Ruby client 中使用 ES|QL 查询生成器

你可以通过将查询对象发送给 elasticsearch-ruby 和 esql.query API，直接使用查询生成器：

require 'elasticsearch'
require 'elastic/esql'

client = Elasticsearch::Client.new
index = 'sample_data'

query = Elastic::ESQL.from(index)
                     .sort('@timestamp')
                     .desc
                     .where('event_duration > 5000000')
                     .limit(3)
                     .eval({ duration_ms: 'ROUND(event_duration/1000000.0, 1)' })
client.esql.query(body: { query: query })

你也可以将它与 Elasticsearch Ruby client 的 ES|QL Helper 一起使用，了解更多信息：

require 'elasticsearch/helpers/esql_helper'

Elasticsearch::Helpers::ESQLHelper.query(client, query)

作为独立工具

这个 gem 设计为一个独立工具，以地道的方式构建 ES|QL 查询。它没有运行时依赖；你可以将它与官方 Elasticsearch Ruby client 一起使用，或者单独使用。

生成的查询可以通过 esql.query API 用于应用与 Elasticsearch API（无论是否使用 Ruby）的任何交互。一旦使用 elastic-esql 构建了查询，生成的 String 可以作为请求体中的 query 参数发送到 API。

我之前写过关于如何使用流行 Ruby 工具与 Elasticsearch 交互的文章。这个 gem 可以与任何流行的 Ruby 工具一起使用，通过 ES|QL 查询 Elasticsearch。

结论

这个库正在积极开发中，最终 API 尚未完成。目前它以技术预览版发布。如果你对当前 API 或一般使用有任何反馈，请随时提交新 issue。请参考 README 了解更多关于 Ruby ES|QL 查询生成器的信息。

原文：https://www.elastic.co/search-labs/blog/esql-query-builder-elasticsearch-ruby-client