当前位置：首页 > news >正文

在 Ruby 客户端里用 ES|QL

news 2025/8/25 6:15:09

一、两种使用姿势概览

直接用 ES|QL API（client.esql.query）

最灵活：能选择 JSON / CSV / text 等返回格式，并细调分隔符、locale 等。
默认返回：{"columns":[...], "values":[...]} 的 Hash。

Ruby ES|QL Helper（Elasticsearch::Helpers::ESQLHelper）

把上面的原始结构映射成按列名键入的数组/哈希，更贴近业务代码。
还能对列指定 Proc 做类型转换（如时间→DateTime，IP→IPAddr）。

还可以配合 elastic-esql 这个 gem 用 Ruby 风格链式构建 ES|QL 语句。

二、方式一：直接调用 ES|QL API（最灵活）

query = <<~ESQLFROM sample_data| EVAL duration_ms = ROUND(event.duration / 1000000.0, 1)
ESQLresponse = client.esql.query(body: { query: query })
puts response

默认响应结构（示意）：

{"columns" => [{"name"=>"@timestamp", "type"=>"date"},{"name"=>"client.ip", "type"=>"ip"},{"name"=>"event.duration", "type"=>"long"},{"name"=>"message", "type"=>"keyword"},{"name"=>"duration_ms", "type"=>"double"}],"values" => [["2023-10-23T12:15:03.360Z", "172.21.2.162", 3450233, "Connected to 10.1.0.3", 3.5],...]
}

适合需要控制返回格式、自己做映射/导出（如 CSV）的场景。

三、方式二：ES|QL Helper（拿到“即用型” Ruby 对象）

require 'elasticsearch/helpers/esql_helper'response = Elasticsearch::Helpers::ESQLHelper.query(client, query)
response.each { |row| puts row }

输出示意（每行都是 Hash）：

{"duration_ms"=>3.5, "message"=>"Connected to 10.1.0.3","event.duration"=>3450233, "client.ip"=>"172.21.2.162","@timestamp"=>"2023-10-23T12:15:03.360Z"}

列级类型转换（parser）

给每个列名配一个 Proc，在“映射到对象”的同时完成转换：

require 'elasticsearch/helpers/esql_helper'
require 'ipaddr'
require 'date'parser = {'@timestamp'    => ->(t) { DateTime.parse(t) },'client.ip'     => ->(i) { IPAddr.new(i) },'event.duration'=> ->(d) { d.to_s }
}rows = Elasticsearch::Helpers::ESQLHelper.query(client, query, parser: parser)
puts rows.first
# => {"duration_ms"=>3.5, "message"=>"Connected ...",
#     "event.duration"=>"3450233", "client.ip"=>#<IPAddr: IPv4:...>,
#     "@timestamp"=>#<DateTime: 2023-10-23T12:15:03+00:00 ...>}

这样你在业务层直接面对 Ruby 类型，而不是原始字符串。

四、用 elastic-esql 构建 ES|QL（更易读、可组合）

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 })

查看生成的 ES|QL 字符串：

query.to_s
# "FROM sample_data | SORT @timestamp DESC | WHERE event_duration > 5000000 | LIMIT 3 | EVAL duration_ms = ROUND(event_duration/1000000.0, 1)"

该库不依赖 elasticsearch-ruby，本质是一个查询构建器；写好 query 后可直接喂给 client.esql.query。

五、防注入：参数化查询是必须的

和 SQL 一样，不要把用户输入直接拼进查询。ES|QL 支持把不可信数据作为 params 单独传入，用 ? 占位：

def find_employee_by_name(name)query = Elastic::ESQL.from('employees').keep('first_name', 'last_name', 'height').where('first_name == ?')@client.esql.query(body: { query: query, params: [name] })
end