jay_api 27.1.0

data/lib/jay_api/elasticsearch/query_builder/aggregations/max.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'aggregation'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        # Represents a +max+ aggregation in Elasticsearch.
+        # Information on this type of aggregation can be found here:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html
+        class Max < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
+          attr_reader :field, :missing
+
+          # @param [String] name The name used by Elasticsearch to identify each
+          #   of the aggregations.
+          # @param [String] field The field whose values should be added-up
+          def initialize(name, field:)
+            super(name)
+
+            @field = field
+            @missing = missing
+          end
+
+          # @raise [JayAPI::Elasticsearch::QueryBuilder::Aggregations::Errors::AggregationsError]
+          #   Is always raised. The Max aggregation cannot have nested aggregations.
+          def aggs
+            no_nested_aggregations('Max')
+          end
+
+          # @return [self] A copy of the receiver.
+          def clone
+            self.class.new(name, field: field)
+          end
+
+          # @return [Hash] The Hash representation of the +Aggregation+.
+          #   Properly formatted for Elasticsearch.
+          def to_h
+            super do
+              {
+                max: {
+                  field: field
+                }
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_builder/aggregations/scripted_metric.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'aggregation'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        # Represents a +scripted_metric+ aggregation in Elasticsearch.
+        # Information about this type of aggregation can be found in:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-scripted-metric-aggregation.html
+        class ScriptedMetric < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
+          attr_reader :init_script, :map_script, :combine_script, :reduce_script
+
+          # @param [String] name The name used by Elasticsearch to identify each
+          #   of the aggregations.
+          # @param [String] init_script The script that gets executed prior to
+          #   any collection of documents. Allows the aggregation to set up any
+          #   initial state.
+          # @param [String] map_script The script that gets executed once per
+          #   document collected. This is a required script.
+          # @param [String] combine_script The script that gets executed once on
+          #   each shard after document collection is complete. Allows the
+          #   aggregation to consolidate the state returned from each shard.
+          # @param [String] reduce_script The script that gets executed once on
+          #   the coordinating node after all shards have returned their
+          #   results. The script is provided with access to a variable +states+
+          #   which is an array of the result of the combine_script on each
+          #   shard.
+          def initialize(name, map_script:, combine_script:, reduce_script:, init_script: nil)
+            super(name)
+
+            @init_script = init_script
+            @map_script = map_script
+            @combine_script = combine_script
+            @reduce_script = reduce_script
+          end
+
+          # @raise [JayAPI::Elasticsearch::QueryBuilder::Aggregations::Errors::AggregationsError]
+          #   Is always raised. The Scripted Metric aggregation cannot have
+          #   nested aggregations.
+          def aggs
+            no_nested_aggregations('Scripted Metric')
+          end
+
+          # @return [self] A copy of the receiver.
+          def clone
+            self.class.new(
+              name, map_script: map_script, combine_script: combine_script,
+                    reduce_script: reduce_script, init_script: init_script
+            )
+          end
+
+          # @return [Hash] The Hash representation of the +Aggregation+.
+          #   Properly formatted for Elasticsearch.
+          def to_h
+            super do
+              {
+                scripted_metric: {
+                  init_script: init_script,
+                  map_script: map_script,
+                  combine_script: combine_script,
+                  reduce_script: reduce_script
+                }.compact
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_builder/aggregations/sum.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'aggregation'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        # Represents a +sum+ aggregation in Elasticsearch.
+        # Information on this type of aggregation can be found here:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-sum-aggregation.html
+        class Sum < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
+          # TODO: Add script support to the aggregation
+
+          attr_reader :field, :missing
+
+          # @param [String] name The name used by Elasticsearch to identify each
+          #   of the aggregations.
+          # @param [String] field The field whose values should be added-up
+          # @param [Numeric] missing The value to use when the field doesn't
+          #   have a value. The type of the parameter depends on the type of the
+          #   field in Elasticsearch.
+          def initialize(name, field:, missing: nil)
+            super(name)
+
+            @field = field
+            @missing = missing
+          end
+
+          # @raise [JayAPI::Elasticsearch::QueryBuilder::Aggregations::Errors::AggregationsError]
+          #   Is always raised. The Sum aggregation cannot have nested aggregations.
+          def aggs
+            no_nested_aggregations('Sum')
+          end
+
+          # @return [self] A copy of the receiver.
+          def clone
+            self.class.new(name, field: field, missing: missing)
+          end
+
+          # @return [Hash] The Hash representation of the +Aggregation+.
+          #   Properly formatted for Elasticsearch.
+          def to_h
+            super do
+              {
+                sum: {
+                  field: field,
+                  missing: missing
+                }.compact
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_builder/aggregations/terms.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/object/deep_dup'
+
+require_relative 'aggregation'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        # Represents a +terms+ aggregation in Elasticsearch.
+        # Information about this type of aggregation can be found in:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html
+        class Terms < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
+          attr_reader :field, :script, :size, :order
+
+          # @param [String] name The name used by Elasticsearch to identify each
+          #   of the aggregations.
+          # @param [String] field The field whose unique values should be counted.
+          # @param [JayAPI::Elasticsearch::QueryBuilder::Script] script If a
+          #   script is given the aggregation will count the unique values
+          #   returned by the script instead of the unique values in a specific
+          #   field.
+          # @param [Integer] size By default the aggregation returns the top 10
+          #   unique values (the ones with the higher frequency). By specifying
+          #   a size this can be changed.
+          # @param [Hash] order A custom order for the buckets produced by the
+          #   aggregation. By default, the +terms+ aggregation orders terms by
+          #   descending document +_count+. This can be changed by providing a
+          #   custom +order+ hash.
+          # @raise [ArgumentError] If neither a +field+ nor a +script+ are given
+          #   or if both of them are given. Only one should be present.
+          def initialize(name, field: nil, script: nil, size: nil, order: nil)
+            if (field.present? && script.present?) || (field.blank? && script.blank?)
+              raise ArgumentError, "Either 'field' or 'script' must be provided"
+            end
+
+            super(name)
+
+            @field = field
+            @script = script
+            @size = size
+            @order = order
+          end
+
+          # @return [self] A copy of the receiver.
+          def clone
+            self.class.new(name, field: field, script: script, size: size, order: order&.deep_dup).tap do |copy|
+              copy.aggregations = aggregations.clone
+            end
+          end
+
+          # @return [Hash] The Hash representation of the +Aggregation+.
+          #   Properly formatted for Elasticsearch.
+          def to_h
+            super do
+              {
+                terms: {
+                  field: field,
+                  size: size,
+                  script: script&.to_h,
+                  order: order
+                }.compact
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_builder/aggregations/top_hits.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/string/inflections'
+
+require_relative '../query_clauses'
+require_relative 'aggregation'
+require_relative 'errors/aggregations_error'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        # Represents a +filter+ aggregation in Elasticsearch.
+        # Information on this type of aggregation can be found here:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-filter-aggregation.html
+        class TopHits < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
+          attr_reader :size
+
+          # @param [String] name The name used by Elasticsearch to identify each
+          #   of the aggregations.
+          # @param [String] size The number of hits that will be returned.
+          def initialize(name, size:)
+            super(name)
+
+            @size = size
+          end
+
+          # @return [self] A copy of the receiver.
+          def clone
+            self.class.new(name, size: size)
+          end
+
+          # @return [Hash] The Hash representation of the +Aggregation+.
+          #   Properly formatted for Elasticsearch.
+          def to_h
+            super do
+              {
+                top_hits: {
+                  size: size
+                }
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_builder/aggregations/value_count.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'aggregation'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        # Represents a +value_count+ aggregation in Elasticsearch.
+        # Information about this type of aggregation can be found in:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-valuecount-aggregation.html
+        class ValueCount < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
+          # TODO: Add script support to the aggregation
+
+          attr_reader :field
+
+          # @param [String] field The whose non-empty values should be counted.
+          def initialize(name, field:)
+            @field = field
+            super(name)
+          end
+
+          # @raise [JayAPI::Elasticsearch::QueryBuilder::Aggregations::Errors::AggregationsError]
+          #   Is always raised. The Value Count aggregation cannot have nested
+          #   aggregations.
+          def aggs
+            no_nested_aggregations('Value Count')
+          end
+
+          # @return [self] A copy of the receiver.
+          def clone
+            self.class.new(name, field: field)
+          end
+
+          # @return [Hash] The Hash representation of the +Aggregation+.
+          #   Properly formatted for Elasticsearch.
+          def to_h
+            super do
+              {
+                value_count: {
+                  field: field
+                }
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_builder/aggregations.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require_relative 'aggregations/aggregation'
+require_relative 'aggregations/avg'
+require_relative 'aggregations/filter'
+require_relative 'aggregations/scripted_metric'
+require_relative 'aggregations/sum'
+require_relative 'aggregations/max'
+require_relative 'aggregations/terms'
+require_relative 'aggregations/value_count'
+require_relative 'aggregations/top_hits'
+require_relative 'aggregations/errors'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      # The list of aggregations to be included in an Elasticsearch query.
+      class Aggregations
+        extend Forwardable
+
+        def_delegators :aggregations, :any?, :none?
+
+        def initialize
+          @aggregations = []
+        end
+
+        # Adds a +terms+ type aggregation. For information about the parameters
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::Terms#initialize
+        def terms(name, field: nil, script: nil, size: nil, order: nil)
+          add(
+            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Terms.new(
+              name, field: field, script: script, size: size, order: order
+            )
+          )
+        end
+
+        # Adds an +avg+ type aggregation. For information about the parameters
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::Avg#initialize
+        def avg(name, field:, missing: nil)
+          add(
+            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Avg.new(
+              name, field: field, missing: missing
+            )
+          )
+        end
+
+        # Adds a +sum+ type aggregation. For information about the parameters
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::Sum#initialize
+        def sum(name, field:, missing: nil)
+          add(
+            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Sum.new(
+              name, field: field, missing: missing
+            )
+          )
+        end
+
+        # Adds a +value_count+ type aggregation. For information about the parameters
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::ValueCount#initialize
+        def value_count(name, field:)
+          add(
+            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::ValueCount.new(
+              name, field: field
+            )
+          )
+        end
+
+        # Adds a +top_hits+ type aggregation. For more information about the parameters
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::TopHits#initialize
+        def top_hits(name, size:)
+          add(::JayAPI::Elasticsearch::QueryBuilder::Aggregations::TopHits.new(name, size: size))
+        end
+
+        # Adds an +scripted_metric+ type aggregation. For information about the parameters
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::ScriptedMetric#initialize
+        def scripted_metric(name, map_script:, combine_script:, reduce_script:, init_script: nil)
+          add(
+            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::ScriptedMetric.new(
+              name, map_script: map_script, combine_script: combine_script,
+                    reduce_script: reduce_script, init_script: init_script
+            )
+          )
+        end
+
+        # Adds a +max+ type aggregation. For information about the parameters
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::Max#initialize
+        def max(name, field:)
+          add(
+            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Max.new(
+              name, field: field
+            )
+          )
+        end
+
+        # Adds a +filter+ type aggregation. For more information about the parameters
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::Filter#initialize
+        def filter(name, &block)
+          add(::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Filter.new(name, &block))
+        end
+
+        # Returns a Hash with the correct format for the current list of
+        # aggregations. For example:
+        #
+        #   {
+        #     "aggs" => {
+        #       "my-agg-name" => {
+        #         "terms" => {
+        #           "field" => "my_field"
+        #         }
+        #       },
+        #       "my-average" => {
+        #         "avg" => {
+        #           "field" => "my_numeric_field"
+        #         }
+        #       }
+        #     }
+        #   }
+        #
+        # @return [Hash] A Hash with the list of aggregations
+        def to_h
+          return {} if none?
+
+          {
+            aggs: aggregations.inject({}) do |hash, aggregation|
+              hash.merge(aggregation.to_h)
+            end
+          }
+        end
+
+        # @param [self] other The object to merge with the receiver.
+        # @return [self] A new object, which represents the combination of the
+        #   aggregations in the receiver and +other+.
+        # @raise [TypeError] If +other+ is not an instance of the same class
+        #   (or a subclass of it).
+        def merge(other)
+          klass = self.class
+          raise TypeError, "Cannot merge #{klass} with #{other.class}" unless other.is_a?(klass)
+
+          klass.new.tap do |merged|
+            merged.aggregations = aggregations.map(&:clone) + other.aggregations.map(&:clone)
+          end
+        end
+
+        # @return [self] A copy of the receiver.
+        def clone
+          self.class.new.tap do |clone|
+            clone.aggregations = aggregations.map(&:clone)
+          end
+        end
+
+        protected
+
+        attr_accessor :aggregations
+
+        # Adds the given +aggregation+ to the +aggregations+ array.
+        # @return [JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation]
+        #   The added aggregation. This has two reasons:
+        #    * To keep the inner +aggregations+ array from leaking out.
+        #    * To allow nesting of aggregations in the future.
+        def add(aggregation)
+          aggregations << aggregation
+          aggregation
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_builder/errors/query_builder_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative '../../../errors/error'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      module Errors
+        # An error to be raised when the user tries to build a query which would
+        # result in an invalid query for Elasticsearch.
+        class QueryBuilderError < JayAPI::Errors::Error
+        end
+      end
+    end
+  end
+end