couchbase 3.8.1 → 3.9.0

data/lib/couchbase/options.rb

@@ -24,12 +24,14 @@ module Couchbase
     # Base class for most of the options
     class Base
       attr_accessor :timeout # @return [Integer, #in_milliseconds, nil]
-      attr_accessor :retry_strategy # @return [Proc, nil]
+      attr_accessor :retry_strategy # @return [Symbol, nil]
       attr_accessor :client_context # @return [Hash, nil]
       attr_accessor :parent_span # @return [Span, nil]
 
       # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+, honoured by key/value operations
+      #   other than {Collection#get_any_replica}, {Collection#get_all_replicas} and range scans; the cluster's
+      #   default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -42,7 +44,8 @@ module Couchbase
         @retry_strategy = retry_strategy
         @client_context = client_context
         @parent_span = parent_span
-        yield self if block_given?
+        # A subclass yields at the end of its own initialize, once its defaults are set.
+        yield self if block_given? && instance_of?(Base)
       end
 
       # @api private
@@ -65,7 +68,7 @@ module Couchbase
       # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding
       #
       # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -114,6 +117,7 @@ module Couchbase
       def to_backend
         options = {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
         }
         options.update(with_expiry: true) if @with_expiry
         unless @projections.nil? || @projections.empty?
@@ -138,7 +142,7 @@ module Couchbase
       # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding
       #
       # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -157,6 +161,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
         }
       end
 
@@ -173,7 +178,7 @@ module Couchbase
       # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -192,6 +197,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
         }
       end
 
@@ -208,7 +214,7 @@ module Couchbase
       # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -227,6 +233,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
         }
       end
 
@@ -247,7 +254,7 @@ module Couchbase
       #  +:selected_server_group+:: restrict to nodes in {Cluster#preferred_server_group}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy ignored by this operation
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -289,7 +296,7 @@ module Couchbase
       #  +:selected_server_group+:: restrict to nodes in {Cluster#preferred_server_group}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy ignored by this operation
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -318,12 +325,50 @@ module Couchbase
       DEFAULT = GetAnyReplica.new.freeze
     end
 
+    # Options for {Collection#get_replica}
+    #
+    # @since 3.9.0
+    class GetReplica < Base
+      attr_accessor :transcoder # @return [JsonTranscoder, #decode(String, Integer)]
+
+      # Creates an instance of options for {Collection#get_replica}
+      #
+      # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding
+      #
+      # @param [Integer, #in_milliseconds, nil] timeout
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
+      # @param [Hash, nil] client_context the client context data, if set
+      # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+      #
+      # @yieldparam [GetReplica] self
+      def initialize(transcoder: JsonTranscoder.new,
+                     timeout: nil,
+                     retry_strategy: nil,
+                     client_context: nil,
+                     parent_span: nil)
+        super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span, &nil)
+        @transcoder = transcoder
+        yield self if block_given?
+      end
+
+      # @api private
+      def to_backend
+        {
+          timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
+        }
+      end
+
+      # @api private
+      DEFAULT = GetReplica.new.freeze
+    end
+
     # Options for {Collection#exists}
     class Exists < Base
       # Creates an instance of options for {Collection#exists}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -340,6 +385,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
         }
       end
 
@@ -352,7 +398,7 @@ module Couchbase
       # Creates an instance of options for {Collection#touch}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -369,6 +415,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
         }
       end
 
@@ -381,7 +428,7 @@ module Couchbase
       # Creates an instance of options for {Collection#unlock}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -398,6 +445,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
         }
       end
 
@@ -440,7 +488,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -469,6 +517,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           durability_level: @durability_level,
           persist_to: @persist_to,
           replicate_to: @replicate_to,
@@ -513,7 +562,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -540,6 +589,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           durability_level: @durability_level,
           persist_to: @persist_to,
           replicate_to: @replicate_to,
@@ -587,7 +637,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -618,6 +668,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           expiry: Utils::Time.extract_expiry_time(@expiry),
           durability_level: @durability_level,
           persist_to: @persist_to,
@@ -669,7 +720,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -701,6 +752,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           expiry: Utils::Time.extract_expiry_time(@expiry),
           preserve_expiry: @preserve_expiry,
           durability_level: @durability_level,
@@ -753,7 +805,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -785,6 +837,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           expiry: Utils::Time.extract_expiry_time(@expiry),
           preserve_expiry: @preserve_expiry,
           durability_level: @durability_level,
@@ -839,7 +892,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -873,6 +926,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           expiry: Utils::Time.extract_expiry_time(@expiry),
           preserve_expiry: @preserve_expiry,
           durability_level: @durability_level,
@@ -935,7 +989,7 @@ module Couchbase
       # @param [JsonTranscoder, #encode(Object)] transcoder used for encoding
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -976,6 +1030,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           expiry: Utils::Time.extract_expiry_time(@expiry),
           preserve_expiry: @preserve_expiry,
           durability_level: @durability_level,
@@ -1010,7 +1065,7 @@ module Couchbase
       # @param [JsonTranscoder, #decode(String)] transcoder used for encoding
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -1031,6 +1086,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           access_deleted: @access_deleted,
         }
       end
@@ -1056,7 +1112,7 @@ module Couchbase
       #  +:selected_server_group+:: restrict to nodes in {Cluster#preferred_server_group}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy ignored by this operation
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -1102,7 +1158,7 @@ module Couchbase
       #  +:selected_server_group+:: restrict to nodes in {Cluster#preferred_server_group}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy ignored by this operation
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -1153,7 +1209,7 @@ module Couchbase
       #   defaults to 1
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy ignored by this operation
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -1239,7 +1295,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -1269,6 +1325,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           cas: @cas,
           durability_level: @durability_level,
           persist_to: @persist_to,
@@ -1317,7 +1374,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -1347,6 +1404,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           cas: @cas,
           durability_level: @durability_level,
           persist_to: @persist_to,
@@ -1397,7 +1455,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -1439,6 +1497,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           delta: @delta,
           initial_value: @initial,
           expiry: Utils::Time.extract_expiry_time(@expiry),
@@ -1491,7 +1550,7 @@ module Couchbase
       #  +:four+:: wait for persistence to four nodes (active and replicas).
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy +:best_effort+ or +:fail_fast+; the cluster's default when +nil+
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -1533,6 +1592,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          retry_strategy: @retry_strategy,
           delta: @delta,
           initial_value: @initial,
           expiry: Utils::Time.extract_expiry_time(@expiry),
@@ -1919,20 +1979,25 @@ module Couchbase
       attr_accessor :report_id # @return [String]
       attr_accessor :service_types # @return [Array<Symbol>]
       attr_accessor :timeout # @return [Integer, #in_milliseconds]
+      attr_accessor :parent_span # @return [Span, nil]
 
       # Creates an instance of options for {Couchbase::Bucket#ping}
       #
       # @param [String] report_id Holds custom report id.
-      # @@param [Array<Symbol>] service_types The service types to limit this diagnostics request
+      # @param [Array<Symbol>] service_types The service types to limit this ping request
       # @param [Integer, #in_milliseconds] timeout
+      # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
       # @yieldparam [Ping] self
       def initialize(report_id: nil,
                      service_types: [:kv, :query, :analytics, :search, :views, :management],
-                     timeout: nil)
+                     timeout: nil,
+                     parent_span: nil)
         @report_id = report_id
         @service_types = service_types
         @timeout = timeout
+        @parent_span = parent_span
+
         yield self if block_given?
       end
 
@@ -1949,6 +2014,41 @@ module Couchbase
       DEFAULT = Ping.new.freeze
     end
 
+    # Options for {Couchbase::Cluster#wait_until_ready} and {Couchbase::Bucket#wait_until_ready}
+    class WaitUntilReady
+      attr_accessor :desired_state # @return [Symbol]
+      attr_accessor :service_types # @return [Array<Symbol>, nil]
+
+      # Creates an instance of options for {Couchbase::Cluster#wait_until_ready} and {Couchbase::Bucket#wait_until_ready}
+      #
+      # @param [Symbol] desired_state the state to wait for
+      #   +:online+:: every endpoint the ping reports for each requested service responds
+      #   +:degraded+:: at least one endpoint the ping reports for each requested service responds
+      # @param [Array<Symbol>, nil] service_types the service types to wait for (same names as {Ping#service_types}).
+      #   When +nil+ or empty, every service in the ping report is considered. A requested service that no node runs
+      #   is never ready, so the wait times out.
+      #
+      # @yieldparam [WaitUntilReady] self
+      def initialize(desired_state: :online,
+                     service_types: nil)
+        @desired_state = desired_state
+        @service_types = service_types
+
+        yield self if block_given?
+      end
+
+      # @api private
+      def to_backend
+        {
+          desired_state: @desired_state,
+          service_types: @service_types,
+        }
+      end
+
+      # @api private
+      DEFAULT = WaitUntilReady.new.freeze
+    end
+
     # Options for {Couchbase::Cluster#analytics_query}
     class Analytics < Base
       attr_accessor :client_context_id # @return [String]
@@ -1986,7 +2086,7 @@ module Couchbase
       #   The qualifier must be in form +{bucket_name}.{scope_name}+ or +default:{bucket_name}.{scope_name}+.
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy ignored by this operation
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -2038,10 +2138,10 @@ module Couchbase
 
       # Allows providing custom JSON key/value pairs for advanced usage
       #
-      # @param [String] key the parameter name (key of the JSON property)
+      # @param [String, Symbol] key the parameter name (key of the JSON property), converted with +to_s+
       # @param [Object] value the parameter value (value of the JSON property)
       def raw(key, value)
-        @raw_parameters[key] = JSON.generate(value)
+        @raw_parameters[key.to_s] = JSON.generate(value)
       end
 
       # @api private
@@ -2157,7 +2257,7 @@ module Couchbase
       #   Overrides +scan_consistency+.
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy ignored by this operation
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -2215,10 +2315,10 @@ module Couchbase
 
       # Allows providing custom JSON key/value pairs for advanced usage
       #
-      # @param [String] key the parameter name (key of the JSON property)
+      # @param [String, Symbol] key the parameter name (key of the JSON property), converted with +to_s+
       # @param [Object] value the parameter value (value of the JSON property)
       def raw(key, value)
-        @raw_parameters[key] = JSON.generate(value)
+        @raw_parameters[key.to_s] = JSON.generate(value)
       end
 
       # Customizes the consistency guarantees for this query
@@ -2324,7 +2424,12 @@ module Couchbase
       attr_accessor :highlight_style # @return [Symbol]
       attr_accessor :highlight_fields # @return [Array<String>]
       attr_accessor :fields # @return [Array<String>]
-      attr_accessor :disable_scoring # @return [Boolean]
+
+      # @deprecated Use +scoring+ with {SearchScoring.none} instead
+      # @return [Boolean]
+      attr_accessor :disable_scoring
+
+      attr_accessor :scoring # @return [SearchScoring, nil]
       attr_accessor :include_locations # @return [Boolean]
       attr_accessor :collections # @return [Array<String>, nil]
       attr_accessor :sort # @return [Array<String, Cluster::SearchSort>]
@@ -2341,7 +2446,12 @@ module Couchbase
       # @param [Array<String>] fields list of field values which should be retrieved for result documents, provided they
       #   were stored while indexing
       # @param [MutationState] mutation_state the mutation tokens this query should be consistent with
-      # @param [Boolean] disable_scoring If set to true, the server will not perform any scoring on the hits
+      # @param [Boolean] disable_scoring DEPRECATED: Use +scoring+ with {SearchScoring.none} instead. If set to true,
+      #   the server will not perform any scoring on the hits.
+      # @param [SearchScoring, nil] scoring specifies the scoring mode used for the request. For a
+      #   hybrid search (a traditional FTS query combined with one or more vector queries) a fusion strategy
+      #   controls how the FTS and vector result sets are merged into a single ranked list. Must not be used
+      #   together with +disable_scoring+.
       # @param [Boolean] include_locations UNCOMMITTED: If set to true, will include the vector of search_location in rows
       # @param [Array<String>, nil] collections list of collections by which to filter the results
       # @param [Array<String, Cluster::SearchSort>] sort Ordering rules to apply to the results. The list might contain
@@ -2354,7 +2464,7 @@ module Couchbase
       # @param [JsonTranscoder, #decode(String)] transcoder to use for the results
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy ignored by this operation
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -2367,6 +2477,7 @@ module Couchbase
                      fields: nil,
                      mutation_state: nil,
                      disable_scoring: false,
+                     scoring: nil,
                      include_locations: false,
                      collections: nil,
                      sort: nil,
@@ -2384,6 +2495,7 @@ module Couchbase
         @highlight_fields = highlight_fields
         @fields = fields
         @disable_scoring = disable_scoring
+        @scoring = scoring
         @include_locations = include_locations
         @collections = collections
         @sort = sort
@@ -2427,14 +2539,22 @@ module Couchbase
       # @return [Symbol]
       attr_reader :scan_consistency
 
+      # @api private
+      def validate_scoring
+        raise Error::InvalidArgument, "disable_scoring and scoring must not be used together" if @disable_scoring && !@scoring.nil?
+      end
+
       # @api private
       def to_backend(show_request: nil)
+        validate_scoring
+
         {
           timeout: Utils::Time.extract_duration(@timeout),
           limit: @limit,
           skip: @skip,
           explain: @explain,
           disable_scoring: @disable_scoring,
+          scoring: @scoring&.to_backend,
           include_locations: @include_locations,
           collections: @collections,
           highlight_style: @highlight_style,
@@ -2515,7 +2635,7 @@ module Couchbase
       # @param [Boolean, nil] debug allows to return debug information as part of the view response
       #
       # @param [Integer, #in_milliseconds, nil] timeout
-      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Symbol, nil] retry_strategy ignored by this operation
       # @param [Hash, nil] client_context the client context data, if set
       # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
       #
@@ -2541,7 +2661,7 @@ module Couchbase
                      retry_strategy: nil,
                      client_context: nil,
                      parent_span: nil)
-        super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span)
+        super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span, &nil)
 
         @scan_consistency = scan_consistency
         @namespace = namespace
@@ -2560,15 +2680,24 @@ module Couchbase
         @reduce = reduce
         @on_error = on_error
         @debug = debug
+        @raw_parameters = {}
         yield self if block_given?
       end
 
-      # Allows providing custom JSON key/value pairs for advanced usage
+      # Allows providing custom query-string parameters 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)
+      # The SDK form-encodes the name and the value. A parameter that shares its name with a typed option is sent
+      # in addition to it.
+      #
+      # @param [String, Symbol] key the parameter name
+      # @param [Object] value the parameter value. A String must already be in the form the view engine expects,
+      #   such as JSON for +key+ or +keys+. Any other value is converted with +JSON.generate+.
+      #
+      # @example Pass parameters as raw values
+      #   options.raw("limit", 2)       # limit=2
+      #   options.raw(:key, '"k2"')     # key="k2", form-encoded
       def raw(key, value)
-        @raw_parameters[key] = JSON.generate(value)
+        @raw_parameters[key.to_s] = value.is_a?(String) ? value : JSON.generate(value)
       end
 
       # @api private
@@ -2591,6 +2720,7 @@ module Couchbase
           reduce: @reduce,
           on_error: @on_error,
           debug: @debug,
+          raw_parameters: @raw_parameters,
         }
       end
 
@@ -2669,6 +2799,13 @@ module Couchbase
       GetAnyReplica.new(**args)
     end
 
+    # Construct {GetReplica} options for {Collection#get_replica}
+    #
+    # @return [GetReplica]
+    def GetReplica(**args)
+      GetReplica.new(**args)
+    end
+
     # Construct {Exists} options for {Collection#exists}
     #
     # @example Check if the document exists without fetching its contents