jay_api 27.1.0

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'query_clause'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class QueryClauses
+        # Represents a Terms query in Elasticsearch.
+        # Information about this type of query can be found here:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-query.html
+        class Terms < ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::QueryClause
+          attr_reader :field, :terms
+
+          # @param [String, Symbol] field The name of the field to search.
+          # @param [Array<String>] terms The array of terms to search for.
+          def initialize(field:, terms:)
+            super()
+
+            @field = field
+            @terms = terms
+          end
+
+          # @return [Hash] The Hash that represents this query (in
+          #   Elasticsearch's DSL)
+          def to_h
+            {
+              terms: {
+                field => terms
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_builder/query_clauses/wildcard.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'query_clause'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class QueryClauses
+        # Represents a Wildcard query in Elasticsearch
+        # Documentation for this type of query can be found here:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-wildcard-query.html
+        class Wildcard < ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::QueryClause
+          attr_accessor :field, :value
+
+          # @param [String, Symbol] field The name of the field to search
+          # @param [String] value The wildcard pattern.
+          def initialize(field:, value:)
+            @field = field
+            @value = value
+          end
+
+          # @return [Hash] The Hash that represents this query (in
+          #   Elasticsearch's format)
+          def to_h
+            {
+              wildcard: {
+                "#{field}": {
+                  value: value
+                }
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require_relative 'errors/query_builder_error'
+require_relative 'query_clauses/bool'
+require_relative 'query_clauses/match_clauses'
+require_relative 'query_clauses/negator'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      # Represents the set of query clauses in an Elasticsearch query.
+      # An empty set of clauses produces a "match all" query clause.
+      class QueryClauses
+        extend Forwardable
+
+        include ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::MatchClauses
+
+        def_delegator :top_level_clause, :nil?, :empty?
+
+        # Turns the query into a Compound Boolean query by adding a +bool+
+        # clause and yields the latter so that sub-clauses can be added to it.
+        # If the query is already a boolean query the current boolean clause is
+        # yielded.
+        # @raise [JayAPI::Elasticsearch::QueryBuilder::Errors::QueryBuilderError]
+        #   If the query already has a top-level query.
+        # @yield [JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Bool]
+        #   Yields the +bool+ query clause to the given block (if there is any).
+        # @return [self, JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Bool]
+        #   If a block is given then +self+ is returned, if no block is given
+        #   then the +bool+ query clause is returned.
+        def bool
+          clause ||= boolean_clause || ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Bool.new
+          replace_top_level_clause(clause, force: boolean_query?)
+
+          if block_given?
+            yield clause
+            self
+          else
+            clause
+          end
+        end
+
+        # Adds the given query clause as top-level clause if none exists yet.
+        # @param [JayAPI::Elasticsearch::QueryBuilder::QueryClauses::QueryClause]
+        #   query_clause The query clause to add.
+        # @return [JayAPI::Elasticsearch::QueryBuilder::QueryClauses] Returns
+        #   itself so that other methods can be chained.
+        # @raise [JayAPI::Elasticsearch::QueryBuilder::Errors::QueryBuilderError]
+        #   If there is already a top level clause.
+        def <<(query_clause)
+          replace_top_level_clause(query_clause)
+        end
+
+        # @return [Hash] The Hash representation of the Query Clauses set.
+        # @raise [JayAPI::Elasticsearch::QueryBuilder::Errors::QueryBuilderError]
+        #   If a boolean query was created but no inner clauses were added.
+        def to_h
+          return self.class.new.match_all.to_h if empty?
+
+          top_level_clause.to_h
+        end
+
+        # @return [Boolean] True if the current Query Clauses set includes a
+        #   +bool+ clause, false otherwise.
+        def boolean_query?
+          top_level_clause.is_a?(::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Bool)
+        end
+
+        # Clones the receiver and the enclosed top-level clause (if any).
+        # @return [self] A copy of the receiver.
+        def clone
+          self.class.new.tap do |copy|
+            copy << top_level_clause.clone
+          end
+        end
+
+        # Creates a new +QueryClauses+ object by merging the receiver with the
+        # given object. The individual top-query clauses are merged together
+        # using a boolean clause.
+        # @param [self] other The +QueryClauses+ object the receiver should be
+        #   merged with.
+        # @return [self] A new +QueryClauses+ object which is a combination of
+        #   the receiver and the given object.
+        def merge(other)
+          klass = self.class
+          raise TypeError, "Cannot merge #{klass} with #{other.class}" unless other.is_a?(klass)
+
+          if other.empty?
+            clone
+          elsif empty?
+            other.clone
+          else
+            klass.new.tap do |merged|
+              merged.bool.merge!(top_level_clause).merge!(other.top_level_clause)
+            end
+          end
+        end
+
+        # Negates the receiver by wrapping its top-level query clause in a
+        # +must_not+ boolean clause or replacing it by its inverse clause.
+        # @return [self] Returns itself.
+        def negate!
+          if top_level_clause
+            @top_level_clause = ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Negator.new(top_level_clause)
+                                                                                            .negate
+          else
+            match_none
+          end
+
+          self
+        end
+
+        # @return [self] A negated version of the receiver (with its top-level
+        #   query clause wrapped in a +must_not+ boolean query or replaced by
+        #   its inverse clause)
+        def negate
+          clone.negate!
+        end
+
+        protected
+
+        attr_reader :top_level_clause
+
+        private
+
+        # Replaces the current top-level clause with the given clause.
+        # @param [JayAPI::Elasticsearch::QueryBuilder::QueryClauses::QueryClause]
+        #   query_clause The query clause to add.
+        # @param [Boolean] force Forces the replacement of the top-level clause
+        #   even if there is already a top-level clause in place.
+        # @return [JayAPI::Elasticsearch::QueryBuilder::QueryClauses] Returns
+        #   itself so that other methods can be chained.
+        # @raise [JayAPI::Elasticsearch::QueryBuilder::Errors::QueryBuilderError]
+        #   If there is already a top level clause and +force+ is +false+.
+        def replace_top_level_clause(query_clause, force: false)
+          single_top_level_clause! unless force
+          @top_level_clause = query_clause
+          self
+        end
+
+        # @return [JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Bool, nil]
+        #   The current top-level clause if it is a Boolean clause, +nil+
+        #   otherwise.
+        def boolean_clause
+          boolean_query? ? top_level_clause : nil
+        end
+
+        # @raise [JayAPI::Elasticsearch::QueryBuilder::Errors::QueryBuilderError]
+        #   If there is already a top level clause.
+        def single_top_level_clause!
+          return unless top_level_clause
+
+          raise ::JayAPI::Elasticsearch::QueryBuilder::Errors::QueryBuilderError,
+                'Queries can only have one top-level query clause, ' \
+                'to use multiple clauses add a compound query, ' \
+                'for example: `bool`'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      # Represents a scripted element in a query. This scripted element can be
+      # used in different places. It can be used in a query clause, but can
+      # also be used to create custom aggregations.
+      class Script
+        attr_reader :source, :lang, :params
+
+        # @param [String] source The source for the script element.
+        # @param [String] lang The language the script is written in.
+        # @param [Hash] params A +Hash+ with key-value pairs for the script's
+        #   parameters.
+        def initialize(source:, lang: 'painless', params: nil)
+          @source = source
+          @lang = lang
+
+          # Keeps the parameters from being modified from the outside after the
+          # class has been initialized.
+          @params = params.dup.freeze
+        end
+
+        # @return [Hash] The hash representation of the scripted element.
+        def to_h
+          {
+            source: source,
+            lang: lang,
+            params: params
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_builder.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative 'query_builder/aggregations'
+require_relative 'query_builder/query_clauses'
+require_relative 'query_builder/script'
+
+module JayAPI
+  module Elasticsearch
+    # A helper class to build simple and common queries for Elasticsearch.
+    # Queries are created with the Elasticsearch Query DSL:
+    # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
+    class QueryBuilder
+      # @return [JayAPI::Elasticsearch::QueryBuilder::Aggregations]
+      attr_reader :aggregations
+
+      # @return [JayAPI::Elasticsearch::QueryBuilder::QueryClauses] The current
+      #   set of query clauses
+      attr_reader :query
+
+      # Creates a new instance of the class.
+      # A new instance of the class will produce an empty query.
+      def initialize
+        @from = nil
+        @size = nil
+        @source = nil
+        @sort = {}
+        @collapse = nil
+        @query = ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses.new
+        @aggregations = JayAPI::Elasticsearch::QueryBuilder::Aggregations.new
+      end
+
+      # Adds a +from+ clause to the query.
+      # @param [Integer] from The value for the from clause.
+      # @return [QueryBuilder] itself so that other methods can be chained.
+      def from(from)
+        check_argument(from, 'from', Integer)
+        check_positive_argument(from, 'from')
+        @from = from
+        self
+      end
+
+      # Adds a +size+ clause to the query.
+      # @param [Integer] size The value for the size clause.
+      # @return [QueryBuilder] itself so that other methods can be chained.
+      def size(size)
+        check_argument(size, 'size', Integer)
+        check_positive_argument(size, 'size')
+        @size = size
+        self
+      end
+
+      # Adds a +sort+ clause to the query.
+      # This method can be called with multiple fields at once or called
+      # multiple times.
+      #
+      # Example:
+      #
+      #   query_builder.sort(name: 'asc', age: 'desc')
+      #
+      # or
+      #
+      #   query_builder.sort(name: 'asc')
+      #   query_builder.sort(age: 'desc')
+      #
+      # Both will produce the same +sort+ clause.
+      # @param [Hash] sort A Hash whose keys are the name of the fields
+      #   and the keys are the direction of the sorting, either +asc+ or
+      #   +desc+.
+      # @return [QueryBuilder] itself so that other methods can be chained.
+      def sort(sort)
+        check_argument(sort, 'sort', Hash)
+        @sort.merge!(sort)
+        self
+      end
+
+      # Adds a +collapse+ clause to the query.
+      # @param [String] field The field to use for collapsing the results.
+      # @return [QueryBuilder] itself so that other methods can be chained.
+      def collapse(field)
+        check_argument(field, 'field', String)
+        @collapse = field
+        self
+      end
+
+      # Adds a +_source+ clause to the query.
+      # @param [String] filter_expr Expression used for filtering source.
+      # @return [QueryBuilder] itself so that other methods can be chained.
+      def source(filter_expr)
+        check_argument(filter_expr, 'source', String)
+        @source = filter_expr
+        self
+      end
+
+      # @return [Hash] The generated query.
+      def to_h
+        build_query
+      end
+
+      alias to_query to_h
+
+      # Returns a new +QueryBuilder+ object which is the result of merging the
+      # receiver with +other+.
+      # @param [self] other Another instance of +QueryBuilder+.
+      # @return [self] A new +QueryBuilder+, the result of the merge of both
+      #   objects.
+      # @raise [TypeError] If the given object is not a +QueryBuilder+.
+      def merge(other)
+        klass = self.class
+        raise TypeError, "Cannot merge #{klass} and #{other.class}" unless other.is_a?(klass)
+
+        other.combine(
+          from: @from, size: @size, source: @source, collapse: @collapse,
+          sort: @sort, query: @query, aggregations: @aggregations
+        )
+      end
+
+      protected
+
+      attr_writer :from, :size, :source, :collapse, :sort, :query, :aggregations
+
+      # Creates a new +QueryBuilder+ object whose attributes are a combination
+      # of the receiver's attributes and the provided values. The receiver's
+      # attributes take precedence over the given ones.
+      # @param [Integer, nil] from See {#from}
+      # @param [Integer, nil] size See {#size}
+      # @param [String, nil] source See {#source}
+      # @param [String, nil] collapse See {#collapse}
+      # @param [Hash] sort See {#sort}
+      # @param [JayAPI::Elasticsearch::QueryBuilder::QueryClauses] query See {#query}
+      # @param [JayAPI::Elasticsearch::QueryBuilder::Aggregations] aggregations See {#aggregations}
+      # @return [self] A new +QueryBuilder+ object.
+      def combine(from:, size:, source:, collapse:, sort:, query:, aggregations:)
+        self.class.new.tap do |combined|
+          combined.from = @from || from
+          combined.size = @size || size
+          # TODO: Improve the merging of this kind of clause (https://esrlabs.atlassian.net/browse/JAY-495)
+          combined.source = @source || source
+          combined.collapse = @collapse || collapse
+          combined.sort = sort.merge(@sort)
+          combined.query = query.merge(self.query)
+          combined.aggregations = aggregations.merge(self.aggregations)
+        end
+      end
+
+      private
+
+      # :reek:FeatureEnvy (cannot be avoided, is checking the argument)
+      # Checks that the given argument is an instance of the specified class.
+      # @param [Object] value The value of the argument.
+      # @param [String] argument_name The name of the argument (for the error
+      #   message).
+      # @param [Class] expected_type The expected type of +value+
+      # @raise [ArgumentError] If the value is not an instance of the class.
+      def check_argument(value, argument_name, expected_type)
+        return if value.is_a?(expected_type)
+
+        raise ArgumentError, "Expected `#{argument_name}` to be #{expected_type}, #{value.class} given"
+      end
+
+      # Checks that the given argument is positive (>= 0)
+      # @param [Numeric] value The value of the argument.
+      # @param [String] argument_name The name of the argument (for the error
+      #   message).
+      # @raise [ArgumentError] If the value is not positive.
+      def check_positive_argument(value, argument_name)
+        return if value >= 0
+
+        raise ArgumentError, "`#{argument_name}` should be a positive integer"
+      end
+
+      # Builds the query.
+      # @return [Hash] The Elasticsearch DSL Query.
+      def build_query
+        query_hash = {}
+        query_hash[:from] = @from if @from
+        query_hash[:size] = @size if @size
+        query_hash[:_source] = @source if @source
+        query_hash[:query] = query.to_h
+
+        if @sort.any?
+          query_hash[:sort] = @sort.map do |field, direction|
+            { field => { order: direction } }
+          end
+        end
+
+        if @collapse
+          query_hash[:collapse] = {
+            field: @collapse
+          }
+        end
+
+        query_hash.merge(aggregations.to_h)
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_results.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'forwardable'
+
+require_relative 'errors/end_of_query_results_error'
+require_relative 'batch_counter'
+
+module JayAPI
+  module Elasticsearch
+    # Represents the results of an Elasticsearch query.
+    # It provides a facade in front of the returned Hash and allows more
+    # results to be fetched dynamically.
+    class QueryResults
+      extend Forwardable
+
+      attr_reader :index, :query, :response, :batch_counter
+
+      def_delegators :batch_counter, :batch_size, :start_next
+      def_delegators :response, :hits, :total, :size, :count, :first, :last, :any?, :empty?, :aggregations
+
+      # Creates a new instance of the class.
+      # @param [JayAPI::Elasticsearch::Index] index The Elasticsearch
+      #   index used to perform the query.
+      # @param [Hash] query The query that produced the results.
+      # @param [JayAPI::Elasticsearch::Results] response An object containing Docs retrieved from Elasticsearch.
+      # @param [JayAPI::Elasticsearch::BatchCounter] batch_counter An object keeping track of the current batch.
+      def initialize(index:, query:, response:, batch_counter: nil)
+        @index = index
+        @query = query.with_indifferent_access
+        @response = response
+        @batch_counter = batch_counter
+      end
+
+      # @return [Boolean] True if there are still more documents matched by the
+      #   query and a call to next_batch can be performed.
+      def more?
+        start_next < total
+      end
+
+      # Calls the given block for every document in the QueryResults object or
+      # returns an Enumerator with all the documents if no block is given.
+      # @yield [Hash] Each document in the current QueryResults object.
+      # @return [Enumerator, Array] An enumerator with all the objects in the
+      #   QueryResults object if no block is given, or an array of all the
+      #   documents in the QueryResults object.
+      def each(&block)
+        hits.each(&block)
+      end
+
+      # Allows the entire set of documents to be iterated in batches.
+      #
+      #  - If the method is invoked with a block, the given block will be called
+      #    for every document in the +QueryResults+ object. Upon reaching the
+      #    end of the collection the next batch will be requested and the block
+      #    will be called again for each of the documents in the next batch, the
+      #    process will continue until there are no more documents. At the end,
+      #    the last batch of documents will be returned.
+      #
+      #  - If the method is called without a block an +Enumerator+ object will
+      #    be returned. Said +Enumerator+ can be used to iterate through the
+      #    whole set of documents. The +#all+ method will take care of fetching
+      #    them in batches and yielding them to the enumerator.
+      #
+      # @yield [Hash] Each document in the current QueryResults object.
+      # @return [JayAPI::Elasticsearch::QueryResults, Enumerator] If a block is
+      #   given the object with the last batch of documents (can be the receiver
+      #   if there is only one batch) will be returned. If no block is given
+      #   an +Enumerator+ will be returned.
+      def all(&block)
+        return enum_for(:all) { total - start_current } unless block
+
+        data = self
+
+        loop do
+          data.each(&block)
+          break unless data.more? && data.any?
+
+          data = data.next_batch
+        end
+
+        data
+      end
+
+      # Fetches the next batch of documents.
+      # @return [JayAPI::Elasticsearch::QueryResults] A new instance of the
+      #   QueryResults that contains the next batch of documents fetched from
+      #   Elasticsearch.
+      # @raise [Elasticsearch::Transport::Transport::ServerError] If the
+      #   query fails.
+      def next_batch
+        raise Errors::EndOfQueryResultsError unless more?
+
+        modified_query = adapt_query
+        index.search(modified_query, batch_counter: batch_counter)
+      end
+
+      private
+
+      def_delegators :batch_counter, :start_current
+
+      def adapt_query
+        query.dup.tap do |modified_query|
+          modified_query[:size] = batch_size
+          modified_query[:from] = start_next
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/response.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module JayAPI
+  module Elasticsearch
+    # The `Response` class encapsulates and processes the results received
+    # from an Elasticsearch query. It provides a uniform interface for accessing
+    # and working with the retrieved data.
+    class Response
+      extend Forwardable
+
+      # @!attribute [r] raw_response
+      #   @return [Hash] The raw results data returned from Elasticsearch
+      attr_reader :raw_response
+
+      def_delegators :hits, :size, :count, :first, :last, :any?, :empty?
+
+      # @param [Hash] raw_response The raw results data from Elasticsearch
+      def initialize(raw_response)
+        @raw_response = raw_response
+      end
+
+      # @return [Hash, nil] The aggregations present in the current result set
+      #   (if there are any).
+      def aggregations
+        @aggregations ||= raw_response['aggregations']
+      end
+
+      # The actual "hits" results from the Elasticsearch response
+      # @return [Array<Hash>]
+      def hits
+        @hits ||= raw_response.dig('hits', 'hits') || []
+      end
+
+      # The total count of results that match the query criteria
+      # @return [Integer]
+      def total
+        @total ||= raw_response.dig('hits', 'total', 'value') || hits.size
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/search_after_results.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'errors/search_after_error'
+require_relative 'query_results'
+
+module JayAPI
+  module Elasticsearch
+    # A QueryResults class for the 'search_after' type of query.
+    # See more: https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html
+    class SearchAfterResults < QueryResults
+      # The default 'from' attribute for the 'search_after' query. See the link for more details.
+      # https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#:~:text=(default)%20or-,%2D1,-.
+      DEFAULT_FROM = -1
+
+      # @return [true] It should always be assumed that there are more results when
+      #   using 'search_after' parameter
+      def more?
+        true
+      end
+
+      # Fetches the next batch of documents.
+      # @return [JayAPI::Elasticsearch::QueryResults] A new instance of the
+      #   QueryResults that contains the next batch of documents fetched from
+      #   Elasticsearch.
+      def next_batch
+        index.search(adapt_query, batch_counter: batch_counter, type: :search_after)
+      end
+
+      private
+
+      # @raise [JayAPI::Elasticsearch::Errors::SearchAfterError]
+      def raise_sort
+        raise(
+          JayAPI::Elasticsearch::Errors::SearchAfterError,
+          "'sort' attribute must be specified in the query when using 'search_after' parameter"
+        )
+      end
+
+      # @return [String] the 'sort' attribute of the last Doc hash in the batch.
+      # @raise [JayAPI::Elasticsearch::Errors::SearchAfterError] If 'sort' is not found in the Doc.
+      def sort
+        @sort ||= last['sort'] || raise_sort
+      end
+
+      # Adapts the query for the next batch.
+      # * The 'from' attribute must be set to a special value.
+      # * The 'search_after' attribute must contain the 'sort' attribute of the
+      #   last received Doc.
+      # @return [Hash]
+      def adapt_query
+        super.tap do |modified_query|
+          modified_query[:from]         = DEFAULT_FROM
+          modified_query[:search_after] = sort
+        end
+      end
+    end
+  end
+end