[Gem] Adds ES|QL Helper

Author: picandocodigo

elasticsearch/lib/elasticsearch/helpers/esql_helper.rb

@@ -0,0 +1,43 @@
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module Elasticsearch
+  module Helpers
+    # Elasticsearch Client Helper for the ES|QL API
+    #
+    # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-query-api.html
+    #
+    module ESQLHelper
+      # By default, the `query` API returns a Hash response with a `columns` key whose value is an
+      # Array of { name: type } Hashes for each column and a `values` key whose value is an Array of
+      # Arrays with the values for each row.
+      # This helper function returns an Array of hashes with the columns as keys and the respective
+      # values: { column['name'] => value }
+      #
+      def self.query(client, query, params = {})
+        response = client.esql.query({ body: { query: query }, format: 'json' }.merge(params))
+
+        columns = response['columns']
+        response['values'].map do |value|
+          (value.length - 1).downto(0).map do |index|
+            { columns[index]['name'] => value[index] }
+          end.reduce({}, :merge)
+        end
+      end
+    end
+  end
+end

elasticsearch/spec/integration/client_integration_spec.rb

@@ -54,7 +54,7 @@
   end
 
   context 'Reports the right meta header' do
-    it 'Reports es service name and gem versio' do
+    it 'Reports es service name and gem version' do
       headers = client.transport.connections.first.connection.headers
       version = Class.new.extend(Elastic::Transport::MetaHeader).send(:client_meta_version, Elasticsearch::VERSION)
       expect(headers['x-elastic-client-meta']).to match /^es=#{version}/

elasticsearch/spec/integration/helpers/esql_helper_spec.rb

@@ -0,0 +1,70 @@
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+require_relative 'helpers_spec_helper'
+require 'elasticsearch/helpers/esql_helper'
+
+context 'Elasticsearch client helpers' do
+  let(:index) { 'esql_helper_test' }
+  let(:body) { { size: 12, query: { match_all: {} } } }
+  let(:esql_helper) { Elasticsearch::Helpers::ESQLHelper }
+
+  before do
+    client.indices.create(
+      index: index,
+      body: {
+        mappings: {
+          properties: { 'client.ip' => { type: 'ip' }, message: { type: 'keyword' } }
+        }
+      }
+    )
+    client.bulk(
+      index: index,
+      body: [
+        {'index': {}},
+        {'@timestamp' => '2023-10-23T12:15:03.360Z', 'client.ip' => '172.21.2.162', message: 'Connected to 10.1.0.3', 'event.duration' => 3450233},
+        {'index': {}},
+        {'@timestamp' => '2023-10-23T12:27:28.948Z', 'client.ip' => '172.21.2.113', message: 'Connected to 10.1.0.2', 'event.duration' => 2764889},
+        {'index': {}},
+        {'@timestamp' => '2023-10-23T13:33:34.937Z', 'client.ip' => '172.21.0.5', message: 'Disconnected', 'event.duration' => 1232382},
+        {'index': {}},
+        {'@timestamp' => '2023-10-23T13:51:54.732Z', 'client.ip' => '172.21.3.15', message: 'Connection error', 'event.duration' => 725448},
+        {'index': {}},
+        {'@timestamp' => '2023-10-23T13:52:55.015Z', 'client.ip' => '172.21.3.15', message: 'Connection error', 'event.duration' => 8268153},
+        {'index': {}},
+        {'@timestamp' => '2023-10-23T13:53:55.832Z', 'client.ip' => '172.21.3.15', message: 'Connection error', 'event.duration' => 5033755},
+        {'index': {}},
+        {'@timestamp' => '2023-10-23T13:55:01.543Z', 'client.ip' => '172.21.3.15', message: 'Connected to 10.1.0.1', 'event.duration' => 1756467}
+      ],
+      refresh: true
+    )
+  end
+
+  after do
+    client.indices.delete(index: index)
+  end
+
+  it 'returns an ESQL response as a relational key/value object' do
+    query = <<~ESQL
+        FROM #{index}
+        | EVAL duration_ms = ROUND(event.duration / 1000000.0, 1)
+    ESQL
+    response = esql_helper.query(client, query)
+
+    expect(response.count).to eq 7
+    expect(response.first.keys).to eq ['duration_ms', 'message', 'event.duration', 'client.ip', '@timestamp']
+  end
+end