[DOCS] Updates docs

Author: picandocodigo

docs/helpers.asciidoc

@@ -165,7 +165,9 @@ scroll_helper.clear
 [[esql-helper]]
 === ES|QL Helper
 
-This helper provides an object response from the ESQL `query` API instead of the default JSON value.
+This functionality is Experimental and may be changed or removed completely in a future release. If you have any feedback on this helper, please https://github.com/elastic/elasticsearch-ruby/issues/new/choose[let us know].
+
+The helper provides an object response from the ESQL `query` API instead of the default JSON value.
 
 To use the ES|QL helper, require it in your code:
 
@@ -208,32 +210,48 @@ The helper returns an array of hashes with the columns as keys and the respectiv
 
 [source,ruby]
 ----
-require 'elasticsearch/helpers/esql_helper'
 response = Elasticsearch::Helpers::ESQLHelper.query(client, query)
 
 puts response
-[
-  {"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"}
-  {"duration_ms"=>2.8, "message"=>"Connected to 10.1.0.2", "event.duration"=>2764889, "client.ip"=>"172.21.2.113", "@timestamp"=>"2023-10-23T12:27:28.948Z"}
-  {"duration_ms"=>1.2, "message"=>"Disconnected", "event.duration"=>1232382, "client.ip"=>"172.21.0.5", "@timestamp"=>"2023-10-23T13:33:34.937Z"}
-  {"duration_ms"=>0.7, "message"=>"Connection error", "event.duration"=>725448, "client.ip"=>"172.21.3.15", "@timestamp"=>"2023-10-23T13:51:54.732Z"}
-  {"duration_ms"=>8.3, "message"=>"Connection error", "event.duration"=>8268153, "client.ip"=>"172.21.3.15", "@timestamp"=>"2023-10-23T13:52:55.015Z"}
-  {"duration_ms"=>5.0, "message"=>"Connection error", "event.duration"=>5033755, "client.ip"=>"172.21.3.15", "@timestamp"=>"2023-10-23T13:53:55.832Z"}
-  {"duration_ms"=>1.8, "message"=>"Connected to 10.1.0.1", "event.duration"=>1756467, "client.ip"=>"172.21.3.15", "@timestamp"=>"2023-10-23T13:55:01.543Z"}
-]
+
+{"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"}
+{"duration_ms"=>2.8, "message"=>"Connected to 10.1.0.2", "event.duration"=>2764889, "client.ip"=>"172.21.2.113", "@timestamp"=>"2023-10-23T12:27:28.948Z"}
+{"duration_ms"=>1.2, "message"=>"Disconnected", "event.duration"=>1232382, "client.ip"=>"172.21.0.5", "@timestamp"=>"2023-10-23T13:33:34.937Z"}
+{"duration_ms"=>0.7, "message"=>"Connection error", "event.duration"=>725448, "client.ip"=>"172.21.3.15", "@timestamp"=>"2023-10-23T13:51:54.732Z"}
+{"duration_ms"=>8.3, "message"=>"Connection error", "event.duration"=>8268153, "client.ip"=>"172.21.3.15", "@timestamp"=>"2023-10-23T13:52:55.015Z"}
 ----
 
-Additionally, a block can be specified to transform the response data. Pass in a block to `query` and it will yield each item in the array of responses.
+Additionally, you can transform the data in the response by passing in a Hash of `column => Proc` values. You could use this for example to convert '@timestamp' into a DateTime object. Pass in a Hash to `query` as a `parser` defining a `Proc` for each value you'd like to parse:
 
-You could use this for example to convert '@timestamp' into a DateTime object:
 [source,ruby]
 ----
 require 'elasticsearch/helpers/esql_helper'
 
-response = esql_helper.query(client, query).each do |r|
-             r['@timestamp'] = DateTime.parse(r['@timestamp'])
-           end
-
+parser = {
+  '@timestamp' => Proc.new { |t| DateTime.parse(t) }
+}
+response = Elasticsearch::Helpers::ESQLHelper.query(client, query, parser: parser)
 response.first['@timestamp']
 # <DateTime: 2023-10-23T12:15:03+00:00 ((2460241j,44103s,360000000n),+0s,2299161j)>
 ----
+
+You can pass in as many Procs as there are columns in the response. For example:
+
+[source,ruby]
+----
+parser = {
+  '@timestamp' => Proc.new { |t| DateTime.parse(t) },
+  'client.ip' => Proc.new { |i| IPAddr.new(i) },
+  'event.duration' => Proc.new { |d| d.to_s }
+}
+
+response = Elasticsearch::Helpers::ESQLHelper.query(client, query, parser: parser)
+
+puts response
+
+{"duration_ms"=>3.5, "message"=>"Connected to 10.1.0.3", "event.duration"=>"3450233", "client.ip"=>#<IPAddr: IPv4:172.21.2.162/255.255.255.255>, "@timestamp"=>#<DateTime: 2023-10-23T12:15:03+00:00 ((2460241j,44103s,360000000n),+0s,2299161j)>}
+{"duration_ms"=>2.8, "message"=>"Connected to 10.1.0.2", "event.duration"=>"2764889", "client.ip"=>#<IPAddr: IPv4:172.21.2.113/255.255.255.255>, "@timestamp"=>#<DateTime: 2023-10-23T12:27:28+00:00 ((2460241j,44848s,948000000n),+0s,2299161j)>}
+{"duration_ms"=>1.2, "message"=>"Disconnected", "event.duration"=>"1232382", "client.ip"=>#<IPAddr: IPv4:172.21.0.5/255.255.255.255>, "@timestamp"=>#<DateTime: 2023-10-23T13:33:34+00:00 ((2460241j,48814s,937000000n),+0s,2299161j)>}
+{"duration_ms"=>0.7, "message"=>"Connection error", "event.duration"=>"725448", "client.ip"=>#<IPAddr: IPv4:172.21.3.15/255.255.255.255>, "@timestamp"=>#<DateTime: 2023-10-23T13:51:54+00:00 ((2460241j,49914s,732000000n),+0s,2299161j)>}
+{"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)>}
+----

elasticsearch/lib/elasticsearch/helpers/esql_helper.rb

@@ -25,16 +25,26 @@ module ESQLHelper
       # Query helper for ES|QL
       #
       # By default, the `esql.query` API returns a Hash response with the following keys:
-      # - `columns` with the value being an Array of { name: type } Hashes for each column
-      # - `values` with the value being an Array of Arrays with the values for each row.
+      #
+      # * `columns` with the value being an Array of `{ name: type }` Hashes for each column.
+      #
+      # * `values` with the value being 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 }.
+      # values: `{ column['name'] => value }`.
       #
       # @param client [Elasticsearch::Client] an instance of the Client to use for the query.
       # @param query [Hash, String] The query to be passed to the ES|QL query API.
       # @param params [Hash] options to pass to the ES|QL query API.
-      # @param convert_datetime [Boolean] Converts datetime values from the response into DateTime
-      # objects in Ruby. Default: true.
+      # @param parser [Hash] Hash of column name keys and Proc values to transform the value of
+      #   a given column.
+      # @example Using the ES|QL helper
+      #   require 'elasticsearch/helpers/esql_helper'
+      #   query = <<~ESQL
+      #             FROM sample_data
+      #             | EVAL duration_ms = ROUND(event.duration / 1000000.0, 1)
+      #           ESQL
+      #   response = Elasticsearch::Helpers::ESQLHelper.query(client, query)
       #
       # @example Using the ES|QL helper with a parser
       #     response = Elasticsearch::Helpers::ESQLHelper.query(