couchbase 3.0.0.alpha.3 → 3.0.1

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
@@ -315,7 +316,7 @@ module Couchbase
         #
         # @note The upper boundary is considered exclusive by default on the server side.
         #
-        # @param [Time, String] time_point end time. When {Time} object is passed {#date_time_parser} must be +nil+ (to use server default)
+        # @param [Time, String] time_point end time. When +Time+ object is passed {#date_time_parser} must be +nil+ (to use server default)
         # @param [Boolean] inclusive
         def end_time(time_point, inclusive = nil)
           @end_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
 
@@ -1161,9 +1225,22 @@ module Couchbase
       # @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
+      # @return [Array<String>] list of field values which should be retrieved for result documents, provided they were stored while
+      #   indexing
       attr_accessor :fields
 
+      # @return [:not_bounded] specifies level of consistency for the query
+      attr_reader :scan_consistency
+
+      # @api private
+      # @return [MutationState]
+      attr_reader :mutation_state
+
+      # @api uncommitted
+      # If set to true, the server will not perform any scoring on the hits
+      # @return [Boolean]
+      attr_accessor :disable_scoring
+
       # Customizes the consistency guarantees for this query
       #
       # @note overrides consistency level set by {#consistent_with}
@@ -1194,7 +1271,8 @@ module Couchbase
       #
       # 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.
+      # 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"+.
       #
@@ -1203,7 +1281,7 @@ module Couchbase
 
       # Facets allow to aggregate information collected on a particular result set
       #
-      # @return [Hash<String, SearchFacet]
+      # @return [Hash<String => SearchFacet>]
       attr_accessor :facets
 
       # @return [JsonTranscoder] transcoder to use for the results
@@ -1211,6 +1289,8 @@ module Couchbase
 
       # @yieldparam [SearchOptions] self
       def initialize
+        super
+        @disable_scoring = false
         @explain = false
         @transcoder = JsonTranscoder.new
         @scan_consistency = nil
@@ -1265,31 +1345,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 +1396,7 @@ module Couchbase
 
         # @yieldparam [TermFacetResult] self
         def initialize
+          super
           yield self if block_given?
         end
 
@@ -1327,6 +1408,7 @@ module Couchbase
           attr_reader :count
 
           def initialize(term, count)
+            super()
             @term = term
             @count = count
           end
@@ -1343,6 +1425,7 @@ module Couchbase
 
         # @yieldparam [DateRangeFacetResult] self
         def initialize
+          super
           yield self if block_given?
         end
 
@@ -1378,6 +1461,7 @@ module Couchbase
 
         # @yieldparam [NumericRangeFacetResult] self
         def initialize
+          super
           yield self if block_given?
         end
 
@@ -1420,7 +1504,7 @@ module Couchbase
       # @return [Hash]
       attr_accessor :explanation
 
-      # @return [Hash<String, Array<String>>]
+      # @return [Hash<String => Array<String>>]
       attr_accessor :fragments
 
       # @return [JsonTranscoder] transcoder to use for the fields
@@ -1463,7 +1547,7 @@ module Couchbase
       # @return [SearchMetrics]
       attr_accessor :metrics
 
-      # @return [Hash<String, String>]
+      # @return [Hash<String => String>]
       attr_accessor :errors
 
       # @yieldparam [SearchMetaData] self
@@ -1477,12 +1561,16 @@ module Couchbase
       # @return [Array<SearchRow>]
       attr_accessor :rows
 
-      # @return [Hash<String, SearchFacetResult>]
+      # @return [Hash<String => SearchFacetResult>]
       attr_accessor :facets
 
       # @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?

data/lib/couchbase/subdoc.rb

@@ -16,10 +16,18 @@ module Couchbase
   class LookupInSpec
     # Fetches the content from a field (if present) at the given path
     #
-    # @param [String] path the path identifying where to get the value
+    # @param [String, Symbol] path the path identifying where to get the value. When path is a symbol, the library will try to expand it as
+    #   macro.
     # @return [LookupInSpec]
     def self.get(path)
-      new(path.empty? ? :get_doc : :get, path)
+      case path
+      when Symbol
+        new(:get, expand_macro(path))
+      when ""
+        new(:get_doc, "")
+      else
+        new(:get, path)
+      end
     end
 
     # Checks if a value at the given path exists in the document
@@ -30,7 +38,7 @@ module Couchbase
       new(:exists, path)
     end
 
-    # Counts the number of values at a given path in teh document
+    # Counts the number of values at a given path in the document
     #
     # @param [String] path the path identifying where to count the values
     # @return [LookupInSpec]
@@ -50,11 +58,41 @@ module Couchbase
     attr_reader :type
     attr_reader :path
 
+    # @api private
+    #
+    # @param [Symbol] macro
+    # @raise [Error::XattrUnknownMacro] if the macro cannot be expanded
+    def self.expand_macro(macro)
+      case macro
+      when :document
+        "$document"
+      when :expiry_time, :expiration_time
+        "$document.exptime"
+      when :cas
+        "$document.CAS"
+      when :seq_no, :sequence_number
+        "$document.seqno"
+      when :last_modified
+        "$document.last_modified"
+      when :is_deleted
+        "$document.deleted"
+      when :value_size_bytes
+        "$document.value_bytes"
+      when :rev_id, :revision_id
+        "$document.revid"
+      else
+        raise Error::XattrUnknownMacro, "unknown macro #{macro}"
+      end
+    end
+
+    private_class_method :expand_macro
+
     private
 
     # @param [:get_doc, :get, :exists, :count] type of the lookup
     # @param [String] path
     def initialize(type, path)
+      @xattr = false
       @type = type
       @path = path
     end
@@ -67,11 +105,12 @@ module Couchbase
     # error if the last element of the path does not exist.
     #
     # @param [String] path the path identifying where to replace the value.
-    # @param [Object] value the value to replace with.
+    # @param [Object, Symbol] value the value to replace with.
+    #   When symbol specified and it is matches to known macro, it will be expanded
     #
     # @return [MutateInSpec]
     def self.replace(path, value)
-      new(:replace, path, value)
+      new(path.empty? ? :set_doc : :replace, path, value)
     end
 
     # Creates a command with the intention of inserting a new value in a JSON object.
@@ -79,10 +118,11 @@ module Couchbase
     # Will error if the last element of the path already exists.
     #
     # @param [String] path the path identifying where to insert the value.
-    # @param [Object] value the value to insert
+    # @param [Object, Symbol] value the value to insert.
+    #   When symbol specified and it is matches to known macro, it will be expanded
     #
     # @return [MutateInSpec]
-    def self.dict_add(path, value)
+    def self.insert(path, value)
       new(:dict_add, path, value)
     end
 
@@ -102,10 +142,11 @@ module Couchbase
     # That is, the value will be replaced if the path already exists, or inserted if not.
     #
     # @param [String] path the path identifying where to upsert the value.
-    # @param [Object] value the value to upsert.
+    # @param [Object, Symbol] value the value to upsert.
+    #   When symbol specified and it is matches to known macro, it will be expanded
     #
     # @return [MutateInSpec]
-    def self.dict_upsert(path, value)
+    def self.upsert(path, value)
       new(:dict_upsert, path, value)
     end
 
@@ -118,7 +159,7 @@ module Couchbase
     #
     # @return [MutateInSpec]
     def self.array_append(path, values)
-      new(:array_append, path, values)
+      new(:array_push_last, path, values)
     end
 
     # Creates a command with the intention of prepending a value to an existing JSON array.
@@ -130,7 +171,7 @@ module Couchbase
     #
     # @return [MutateInSpec]
     def self.array_prepend(path, values)
-      new(:array_prepend, path, values)
+      new(:array_push_first, path, values)
     end
 
     # Creates a command with the intention of inserting a value into an existing JSON array.
@@ -151,7 +192,7 @@ module Couchbase
     # Will error if the last element of the path does not exist or is not an array.
     #
     # @param [String] path the path identifying an array to which to append the value, and an index.  E.g. "foo.bar[3]"
-    # @param [Object] value the value to insert.
+    # @param [Object, Symbol] value the value to insert.
     #
     # @return [MutateInSpec]
     def self.array_add_unique(path, value)
@@ -187,8 +228,8 @@ module Couchbase
       self
     end
 
-    def create_parents
-      @create_parents = true
+    def create_path
+      @create_path = true
       self
     end
 
@@ -196,17 +237,17 @@ module Couchbase
       @xattr
     end
 
-    def create_parents?
-      @create_parents
+    def create_path?
+      @create_path
     end
 
     def expand_macros?
       @expand_macros
     end
 
-    CAS = "${Mutation.CAS}"
-    SEQ_NO = "${Mutation.seqno}"
-    VALUE_CRC_32C = "${Mutation.value_crc32c}"
+    CAS = "${Mutation.CAS}".freeze
+    SEQ_NO = "${Mutation.seqno}".freeze
+    VALUE_CRC32C = "${Mutation.value_crc32c}".freeze
 
     attr_reader :type
     attr_reader :path
@@ -215,12 +256,35 @@ module Couchbase
     private
 
     def initialize(type, path, param)
+      @create_path = false
+      @param = nil
+      @xattr = false
       @type = type
       @path = path
-      @expand_macros = [CAS, SEQ_NO, VALUE_CRC_32C].include?(@param)
-      if !@expand_macros && !param.nil?
-        @param = JSON.generate(param)
-      end
+      @param =
+        case param
+        when :cas
+          CAS
+        when :seq_no, :sequence_number
+          SEQ_NO
+        when :value_crc32c, :value_crc
+          VALUE_CRC32C
+        else
+          param
+        end
+      @expand_macros = [CAS, SEQ_NO, VALUE_CRC32C].include?(@param)
+      @xattr = true if @expand_macros
+      return if @param.nil?
+
+      @param =
+        case type
+        when :counter
+          @param.to_i
+        when :array_push_first, :array_push_last, :array_insert
+          @param.map { |entry| JSON.generate(entry) }.join(",")
+        else
+          JSON.generate(@param)
+        end
     end
   end
 end