couchbase 3.0.0.alpha.4-universal-darwin-19 → 3.0.2-universal-darwin-19

data/lib/couchbase/query_options.rb

@@ -12,111 +12,10 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-require 'json'
+require "json"
 
 module Couchbase
   class Cluster
-
-    class QueryOptions
-      # @return [Integer] Timeout in milliseconds
-      attr_accessor :timeout
-
-      # @return [Boolean] Allows turning this request into a prepared statement query
-      attr_accessor :adhoc
-
-      # @return [String] Provides a custom client context ID for this query
-      attr_accessor :client_context_id
-
-      # @return [Integer] Allows overriding the default maximum parallelism for the query execution on the server side.
-      attr_accessor :max_parallelism
-
-      # @return [Boolean] Allows explicitly marking a query as being readonly and not mutating and documents on the server side.
-      attr_accessor :readonly
-
-      # Allows customizing how long (in milliseconds) the query engine is willing to wait until the index catches up to whatever scan consistency is asked for in this query.
-      #
-      # @note that if +:not_bounded+ consistency level is used, this method doesn't do anything
-      # at all. If no value is provided to this method, the server default is used.
-      #
-      # @return [Integer] The maximum duration (in milliseconds) the query engine is willing to wait before failing.
-      attr_accessor :scan_wait
-
-      # @return [Integer] Supports customizing the maximum buffered channel size between the indexer and the query service
-      attr_accessor :scan_cap
-
-      # @return [Integer] Supports customizing the number of items execution operators can batch for fetch from the KV layer on the server.
-      attr_accessor :pipeline_batch
-
-      # @return [Integer] Allows customizing the maximum number of items each execution operator can buffer between various operators on the server.
-      attr_accessor :pipeline_cap
-
-      # @return [Boolean] Enables per-request metrics in the trailing section of the query
-      attr_accessor :metrics
-
-      # @return [:off, :phases, :timings] Customize server profile level for this query
-      attr_accessor :profile
-
-      # @yieldparam [QueryOptions] self
-      def initialize
-        @timeout = 75_000 # ms
-        @adhoc = true
-        @raw_parameters = {}
-        @positional_parameters = nil
-        @named_parameters = nil
-        @scan_consistency = nil
-        @mutation_state = nil
-        yield self if block_given?
-      end
-
-      # Allows providing custom JSON key/value pairs for advanced usage
-      #
-      # @param [String] key the parameter name (key of the JSON property)
-      # @param [Object] value the parameter value (value of the JSON property)
-      def raw(key, value)
-        @raw_parameters[key] = JSON.generate(value)
-      end
-
-      # Customizes the consistency guarantees for this query
-      #
-      # @note overrides consistency level set by {#consistent_with}
-      #
-      # [+:not_bounded+] The indexer will return whatever state it has to the query engine at the time of query. This is the default (for single-statement requests).
-      #
-      # [+:request_plus+] The indexer will wait until all mutations have been processed at the time of request before returning to the query engine.
-      #
-      # @param [:not_bounded, :request_plus] level the index scan consistency to be used for this query
-      def scan_consistency=(level)
-        @mutation_state = nil if @mutation_state
-        @scan_consistency = level
-      end
-
-      # Sets the mutation tokens this query should be consistent with
-      #
-      # @note overrides consistency level set by {#scan_consistency=}
-      #
-      # @param [MutationState] mutation_state the mutation state containing the mutation tokens
-      def consistent_with(mutation_state)
-        @scan_consistency = nil if @scan_consistency
-        @mutation_state = mutation_state
-      end
-
-      # Sets positional parameters for the query
-      #
-      # @param [Array] positional the list of parameters that have to be substituted in the statement
-      def positional_parameters(positional)
-        @positional_parameters = positional
-        @named_parameters = nil
-      end
-
-      # Sets named parameters for the query
-      #
-      # @param [Hash] named the key/value map of the parameters to substitute in the statement
-      def named_parameters(named)
-        @named_parameters = named
-        @positional_parameters = nil
-      end
-    end
-
     class QueryResult
       # @return [QueryMetaData] returns object representing additional metadata associated with this query
       attr_accessor :meta_data
@@ -162,7 +61,7 @@ module Couchbase
       # @return [QueryMetrics] metrics as returned by the query engine, if enabled
       attr_accessor :metrics
 
-      # @return [List<QueryWarning>] list of warnings returned by the query engine
+      # @return [Array<QueryWarning>] list of warnings returned by the query engine
       attr_accessor :warnings
 
       # @yieldparam [QueryMetaData] self
@@ -172,10 +71,12 @@ module Couchbase
     end
 
     class QueryMetrics
-      # @return [Integer] The total time taken for the request, that is the time from when the request was received until the results were returned
+      # @return [Integer] The total time taken for the request, that is the time from when the request was received until the results were
+      #   returned.
       attr_accessor :elapsed_time
 
-      # @return [Integer] The time taken for the execution of the request, that is the time from when query execution started until the results were returned
+      # @return [Integer] The time taken for the execution of the request, that is the time from when query execution started until the
+      #   results were returned
       attr_accessor :execution_time
 
       # @return [Integer] the total number of results selected by the engine before restriction through LIMIT clause.

data/lib/couchbase/scope.rb

@@ -13,13 +13,14 @@
 #  limitations under the License.
 
 require "couchbase/collection"
+require "couchbase/query_options"
 
 module Couchbase
   class Scope
     attr_reader :bucket_name
     attr_reader :name
 
-    alias_method :inspect, :to_s
+    alias inspect to_s
 
     # @param [Couchbase::Backend] backend
     # @param [String] bucket_name name of the bucket
@@ -30,13 +31,6 @@ module Couchbase
       @name = scope_name
     end
 
-    # Opens the default collection for this scope
-    #
-    # @return [Collection]
-    def default_collection
-      Collection.new(@backend, @bucket_name, @name, :_default)
-    end
-
     # Opens the default collection for this scope
     #
     # @param [String] collection_name name of the collection
@@ -45,5 +39,48 @@ module Couchbase
     def collection(collection_name)
       Collection.new(@backend, @bucket_name, @name, collection_name)
     end
+
+    # Performs a query against the query (N1QL) services.
+    #
+    # The query will be implicitly scoped using current bucket and scope names.
+    #
+    # @see Options::Query#scope_qualifier
+    # @see Cluster#query
+    #
+    # @param [String] statement the N1QL query statement
+    # @param [Options::Query] options the custom options for this query
+    #
+    # @example Select first ten hotels from travel sample dataset
+    #   cluster.query("SELECT * FROM `travel-sample` WHERE type = $type LIMIT 10",
+    #                 Options::Query(named_parameters: {type: "hotel"}, metrics: true))
+    #
+    # @return [QueryResult]
+    def query(statement, options = Options::Query.new)
+      resp = @backend.document_query(statement, options.to_backend(scope_name: @name, bucket_name: @bucket_name))
+
+      Cluster::QueryResult.new do |res|
+        res.meta_data = Cluster::QueryMetaData.new do |meta|
+          meta.status = resp[:meta][:status]
+          meta.request_id = resp[:meta][:request_id]
+          meta.client_context_id = resp[:meta][:client_context_id]
+          meta.signature = JSON.parse(resp[:meta][:signature]) if resp[:meta][:signature]
+          meta.profile = JSON.parse(resp[:meta][:profile]) if resp[:meta][:profile]
+          meta.metrics = Cluster::QueryMetrics.new do |metrics|
+            if resp[:meta][:metrics]
+              metrics.elapsed_time = resp[:meta][:metrics][:elapsed_time]
+              metrics.execution_time = resp[:meta][:metrics][:execution_time]
+              metrics.sort_count = resp[:meta][:metrics][:sort_count]
+              metrics.result_count = resp[:meta][:metrics][:result_count]
+              metrics.result_size = resp[:meta][:metrics][:result_size]
+              metrics.mutation_count = resp[:meta][:metrics][:mutation_count]
+              metrics.error_count = resp[:meta][:metrics][:error_count]
+              metrics.warning_count = resp[:meta][:metrics][:warning_count]
+            end
+          end
+          res[:warnings] = resp[:warnings].map { |warn| QueryWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
+        end
+        res.instance_variable_set("@rows", resp[:rows])
+      end
+    end
   end
 end

data/lib/couchbase/search_options.rb

@@ -304,7 +304,8 @@ module Couchbase
         #
         # @note The lower boundary is considered inclusive by default on the server side.
         #
-        # @param [Time, String] time_point start time. When +Time+ object is passed {#date_time_parser} must be +nil+ (to use server default)
+        # @param [Time, String] time_point start time. When +Time+ object is passed {#date_time_parser} must be +nil+ (to use server
+        #   default)
         # @param [Boolean] inclusive
         def start_time(time_point, inclusive = nil)
           @start_time = time_point
@@ -332,13 +333,11 @@ module Couchbase
           yield self if block_given?
         end
 
-        DATE_FORMAT_RFC3339 = "%Y-%m-%dT%H:%M:%S%:z"
+        DATE_FORMAT_RFC3339 = "%Y-%m-%dT%H:%M:%S%:z".freeze
 
         # @return [String]
         def to_json(*args)
-          if @start_time.nil? && @end_time.nil?
-            raise ArgumentError, "either start_time or end_time must be set for DateRangeQuery"
-          end
+          raise ArgumentError, "either start_time or end_time must be set for DateRangeQuery" if @start_time.nil? && @end_time.nil?
 
           data = {}
           data["boost"] = boost if boost
@@ -415,9 +414,7 @@ module Couchbase
 
         # @return [String]
         def to_json(*args)
-          if @min.nil? && @max.nil?
-            raise ArgumentError, "either min or max must be set for NumericRangeQuery"
-          end
+          raise ArgumentError, "either min or max must be set for NumericRangeQuery" if @min.nil? && @max.nil?
 
           data = {}
           data["boost"] = boost if boost
@@ -485,9 +482,7 @@ module Couchbase
 
         # @return [String]
         def to_json(*args)
-          if @min.nil? && @max.nil?
-            raise ArgumentError, "either min or max must be set for TermRangeQuery"
-          end
+          raise ArgumentError, "either min or max must be set for TermRangeQuery" if @min.nil? && @max.nil?
 
           data = {}
           data["boost"] = boost if boost
@@ -540,8 +535,8 @@ module Couchbase
         # @return [String]
         def to_json(*args)
           data = {
-              "location" => [@longitude, @latitude],
-              "distance" => @distance
+            "location" => [@longitude, @latitude],
+            "distance" => @distance,
           }
           data["boost"] = boost if boost
           data["field"] = field if field
@@ -551,7 +546,7 @@ module Couchbase
 
       # Prepare {GeoBoundingBoxQuery} body
       #
-      # @yieldparam [GeoDistanceQuery] query
+      # @yieldparam [GeoBoundingBoxQuery] query
       #
       # @param [Float] top_left_longitude
       # @param [Float] top_left_latitude
@@ -589,8 +584,66 @@ module Couchbase
         # @return [String]
         def to_json(*args)
           data = {
-              "top_left" => [@top_left_longitude, @top_left_latitude],
-              "bottom_right" => [@bottom_right_longitude, @bottom_right_latitude]
+            "top_left" => [@top_left_longitude, @top_left_latitude],
+            "bottom_right" => [@bottom_right_longitude, @bottom_right_latitude],
+          }
+          data["boost"] = boost if boost
+          data["field"] = field if field
+          data.to_json(*args)
+        end
+      end
+
+      # A coordinate is a tuple of a latitude and a longitude.
+      #
+      # @see GeoPolygonQuery
+      # @see SearchQuery.geo_polygon
+      class Coordinate
+        # @return [Float]
+        attr_accessor :longitude
+
+        # @return [Float]
+        attr_accessor :latitude
+
+        def initialize(longitude, latitude)
+          @longitude = longitude
+          @latitude = latitude
+        end
+      end
+
+      # Prepare {GeoPolygonQuery} body
+      #
+      # @yieldparam [GeoPolygonQuery] query
+      #
+      # @param [Array<Coordinate>] coordinates list of coordinates that forms polygon
+      #
+      # @return [GeoPolygonQuery]
+      #
+      # @api uncommitted
+      def self.geo_polygon(coordinates, &block)
+        GeoPolygonQuery.new(coordinates, &block)
+      end
+
+      # A search query which allows to match inside a geo polygon.
+      class GeoPolygonQuery < SearchQuery
+        # @return [Float]
+        attr_accessor :boost
+
+        # @return [String]
+        attr_accessor :field
+
+        # @yieldparam [GeoPolygonQuery] self
+        #
+        # @param [Array<Coordinate>] coordinates list of coordinates that forms polygon
+        def initialize(coordinates)
+          super()
+          @coordinates = coordinates
+          yield self if block_given?
+        end
+
+        # @return [String]
+        def to_json(*args)
+          data = {
+            "polygon_points" => @coordinates.map { |coord| [coord.longitude, coord.latitude] },
           }
           data["boost"] = boost if boost
           data["field"] = field if field
@@ -633,6 +686,7 @@ module Couchbase
         # @return [String]
         def to_json(*args)
           raise ArgumentError, "compound conjunction query must have sub-queries" if @queries.nil? || @queries.empty?
+
           data = {"conjuncts" => @queries.uniq}
           data["boost"] = boost if boost
           data.to_json(*args)
@@ -677,9 +731,11 @@ module Couchbase
         # @return [String]
         def to_json(*args)
           raise ArgumentError, "compound disjunction query must have sub-queries" if @queries.nil? || @queries.empty?
+
           data = {"disjuncts" => @queries.uniq}
           if min
             raise ArgumentError, "disjunction query has fewer sub-queries than configured minimum" if @queries.size < min
+
             data["min"] = min
           end
           data["boost"] = boost if boost
@@ -739,6 +795,7 @@ module Couchbase
           if @must.empty? && @must_not.empty? && @should.empty?
             raise ArgumentError, "BooleanQuery must have at least one non-empty sub-query"
           end
+
           data = {}
           data["must"] = @must unless @must.empty?
           data["must_not"] = @must_not unless @must_not.empty?
@@ -758,7 +815,8 @@ module Couchbase
         TermQuery.new(term, &block)
       end
 
-      # A query that looks for **exact** matches of the term in the index (no analyzer, no stemming). Useful to check what the actual content of the index is. It can also apply fuzziness on the term. Usual better alternative is `MatchQuery`.
+      # A query that looks for **exact** matches of the term in the index (no analyzer, no stemming). Useful to check what the actual
+      # content of the index is. It can also apply fuzziness on the term. Usual better alternative is `MatchQuery`.
       class TermQuery < SearchQuery
         # @return [Float]
         attr_accessor :boost
@@ -840,7 +898,8 @@ module Couchbase
         PhraseQuery.new(*terms, &block)
       end
 
-      # A query that looks for **exact** match of several terms (in the exact order) in the index. Usual better alternative is {MatchPhraseQuery}.
+      # A query that looks for **exact** match of several terms (in the exact order) in the index. Usual better alternative is
+      # {MatchPhraseQuery}.
       class PhraseQuery < SearchQuery
         # @return [Float]
         attr_accessor :boost
@@ -958,6 +1017,7 @@ module Couchbase
 
         # @yieldparam [SearchSortScore]
         def initialize
+          super
           yield self if block_given?
         end
 
@@ -973,6 +1033,7 @@ module Couchbase
 
         # @yieldparam [SearchSortId]
         def initialize
+          super
           yield self if block_given?
         end
 
@@ -1001,6 +1062,7 @@ module Couchbase
         # @param [String] field the name of the filed for ordering
         # @yieldparam [SearchSortField]
         def initialize(field)
+          super()
           @field = field
           yield self if block_given?
         end
@@ -1032,6 +1094,7 @@ module Couchbase
         # @param [Float] latitude
         # @yieldparam [SearchSortGeoDistance]
         def initialize(field, longitude, latitude)
+          super()
           @field = field
           @longitude = longitude
           @latitude = latitude
@@ -1119,19 +1182,20 @@ module Couchbase
 
         # @param [String] field name of the field
         def initialize(field)
+          super()
           @field = field
           @ranges = []
           yield self if block_given?
         end
 
-        DATE_FORMAT_RFC3339 = "%Y-%m-%dT%H:%M:%S%:z"
+        DATE_FORMAT_RFC3339 = "%Y-%m-%dT%H:%M:%S%:z".freeze
 
         # @param [String] name the name of the range
         # @param [Time, String, nil] start_time lower bound of the range (pass +nil+ if there is no lower bound)
         # @param [Time, String, nil] end_time lower bound of the range (pass +nil+ if there is no lower bound)
         def add(name, start_time, end_time)
-          start_time = start_time.strftime(DATE_FORMAT_RFC3339) if start_time && start_time.respond_to?(:strftime)
-          end_time = end_time.strftime(DATE_FORMAT_RFC3339) if end_time && end_time.respond_to?(:strftime)
+          start_time = start_time.strftime(DATE_FORMAT_RFC3339) if start_time.respond_to?(:strftime)
+          end_time = end_time.strftime(DATE_FORMAT_RFC3339) if end_time.respond_to?(:strftime)
           @ranges.append({name: name, start: start_time, end: end_time})
         end
 
@@ -1142,83 +1206,6 @@ module Couchbase
       end
     end
 
-    class SearchOptions
-      # @return [Integer] Timeout in milliseconds
-      attr_accessor :timeout
-
-      # @return [Integer] limits the number of matches returned from the complete result set.
-      attr_accessor :limit
-
-      # @return [Integer] indicates how many matches are skipped on the result set before starting to return the matches
-      attr_accessor :skip
-
-      # @return [Boolean] triggers inclusion of additional search result score explanations. (Default: +false+)
-      attr_accessor :explain
-
-      # @return [:html, :ansi] the style of highlighting in the result excerpts (if not specified, the server default will be used)
-      attr_accessor :highlight_style
-
-      # @return [Array<String>] list of the fields to highlight
-      attr_accessor :highlight_fields
-
-      # @return [Array<String>] list of field values which should be retrieved for result documents, provided they were stored while indexing
-      attr_accessor :fields
-
-      # Customizes the consistency guarantees for this query
-      #
-      # @note overrides consistency level set by {#consistent_with}
-      #
-      # [+:not_bounded+] The engine will return whatever state it has at the time of query
-      #
-      # @param [:not_bounded] level the scan consistency to be used for this query
-      #
-      # @return [void]
-      def scan_consistency=(level)
-        @mutation_state = nil if @mutation_state
-        @scan_consistency = level
-      end
-
-      # Sets the mutation tokens this query should be consistent with
-      #
-      # @note overrides consistency level set by {#scan_consistency=}
-      #
-      # @param [MutationState] mutation_state the mutation state containing the mutation tokens
-      #
-      # @return [void]
-      def consistent_with(mutation_state)
-        @scan_consistency = nil if @scan_consistency
-        @mutation_state = mutation_state
-      end
-
-      # Ordering rules to apply to the results
-      #
-      # The list might contain either strings or special objects, that derive from {SearchSort}.
-      #
-      # In case of String, the value represents the name of the field with optional +-+ in front of the name, which will turn on descending mode for this field. One field is special is +"_score"+ which will sort results by their score.
-      #
-      # When nothing specified, the Server will order results by their score descending, which is equivalent of +"-_score"+.
-      #
-      # @return [Array<String, SearchSort>] list of ordering object
-      attr_accessor :sort
-
-      # Facets allow to aggregate information collected on a particular result set
-      #
-      # @return [Hash<String => SearchFacet>]
-      attr_accessor :facets
-
-      # @return [JsonTranscoder] transcoder to use for the results
-      attr_accessor :transcoder
-
-      # @yieldparam [SearchOptions] self
-      def initialize
-        @explain = false
-        @transcoder = JsonTranscoder.new
-        @scan_consistency = nil
-        @mutation_state = nil
-        yield self if block_given?
-      end
-    end
-
     class SearchRowLocation
       # @return [String]
       attr_accessor :field
@@ -1265,31 +1252,31 @@ module Couchbase
       #
       # @return [Array<String>]
       def fields
-        @locations.map { |location| location.field }.uniq
+        @locations.map(&:field).uniq
       end
 
       # Lists all terms in this locations, considering all fields
       #
       # @return [Array<String>]
       def terms
-        @locations.map { |location| location.term }.uniq
+        @locations.map(&:term).uniq
       end
 
       # Lists the terms for a given field
       #
       # @return [Array<String>]
       def terms_for_field(name)
-        get_for_field(name).map { |location| location.term }.uniq
+        get_for_field(name).map(&:term).uniq
       end
 
       # @param [Array<SearchRowLocation>] locations
       def initialize(locations)
+        super()
         @locations = locations
       end
     end
 
-    # An individual facet result has both metadata and details, as each facet can define ranges into which results are
-    # categorized
+    # An individual facet result has both metadata and details, as each facet can define ranges into which results are categorized
     class SearchFacetResult
       # @return [String]
       attr_accessor :name
@@ -1316,6 +1303,7 @@ module Couchbase
 
         # @yieldparam [TermFacetResult] self
         def initialize
+          super
           yield self if block_given?
         end
 
@@ -1327,6 +1315,7 @@ module Couchbase
           attr_reader :count
 
           def initialize(term, count)
+            super()
             @term = term
             @count = count
           end
@@ -1343,6 +1332,7 @@ module Couchbase
 
         # @yieldparam [DateRangeFacetResult] self
         def initialize
+          super
           yield self if block_given?
         end
 
@@ -1378,6 +1368,7 @@ module Couchbase
 
         # @yieldparam [NumericRangeFacetResult] self
         def initialize
+          super
           yield self if block_given?
         end
 
@@ -1483,6 +1474,10 @@ module Couchbase
       # @return [SearchMetaData]
       attr_accessor :meta_data
 
+      def success?
+        meta_data.errors.nil? || meta_data.errors.empty?
+      end
+
       # @yieldparam [SearchResult] self
       def initialize
         yield self if block_given?