Class: Couchbase::Options::Query

Inherits:
Base
  • Object
show all
Defined in:
lib/couchbase/options.rb,
/home/runner/work/couchbase-ruby-client/couchbase-ruby-client/lib/couchbase/options.rb

Overview

Options for Cluster#query

Instance Attribute Summary collapse

Attributes inherited from Base

#client_context, #parent_span, #retry_strategy, #timeout

Instance Method Summary collapse

Constructor Details

#initialize(adhoc: true, client_context_id: nil, max_parallelism: nil, readonly: false, scan_wait: nil, scan_cap: nil, pipeline_cap: nil, pipeline_batch: nil, metrics: nil, profile: :off, flex_index: nil, preserve_expiry: nil, use_replica: nil, scope_qualifier: nil, scan_consistency: :not_bounded, mutation_state: nil, transcoder: JsonTranscoder.new, positional_parameters: nil, named_parameters: nil, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) {|self| ... } ⇒ Query

Note:

Either positional_parameters or named_parameters may be specified.

Creates new instance of options for Cluster#query

Parameters:

  • adhoc (Boolean) (defaults to: true) —

    allows turning this request into a prepared statement query

  • client_context_id (String, nil) (defaults to: nil) —

    provides a custom client context ID for this query

  • max_parallelism (Integer, nil) (defaults to: nil) —

    allows overriding the default maximum parallelism for the query execution on the server side.

  • readonly (Boolean, nil) (defaults to: false) —

    allows explicitly marking a query as being readonly and not mutating any documents on the server side.

  • scan_wait (Integer, #in_milliseconds, nil) (defaults to: nil) —

    The maximum duration (in milliseconds) the query engine is willing to wait before failing. 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.

  • scan_cap (Integer, nil) (defaults to: nil) —

    customize the maximum buffered channel size between the indexer and the query service

  • pipeline_cap (Integer, nil) (defaults to: nil) —

    customize the number of items execution operators can batch for fetch from the Key Value layer on the server.

  • pipeline_batch (Integer, nil) (defaults to: nil) —

    customize the maximum number of items each execution operator can buffer between various operators on the server.

  • metrics (Boolean, nil) (defaults to: nil) —

    enables per-request metrics in the trailing section of the query

  • profile (Symbol) (defaults to: :off) —

    customize server profile level for this query :off::

    No profiling information is added to the query response

    :phases::

    The query response includes a profile section with stats and details about various phases of the query plan
and execution. Three phase times will be included in the +system:active_requests+ and
+system:completed_requests+ monitoring keyspaces.

    :timings::

    Besides the phase times, the profile section of the query response document will include a full query plan
with timing and information about the number of processed documents at each phase. This information will be
included in the system:active_requests and system:completed_requests keyspaces.
  • scan_consistency (Symbol, nil) (defaults to: :not_bounded) —

    Sets the mutation tokens this query should be consistent with. Overrides mutation_state. :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.
  • flex_index (Boolean, nil) (defaults to: nil) —

    Tells the query engine to use a flex index (utilizing the search service)

  • preserve_expiry (Boolean, nil) (defaults to: nil) —

    Tells the query engine to preserve expiration values set on any documents modified by this query.

  • use_replica (Boolean, nil) (defaults to: nil) —

    Specifies that the query engine should use replica nodes for KV fetches if the active node is down. If not provided, the server default will be used

  • scope_qualifier (String, nil) (defaults to: nil) —

    Associate scope qualifier (also known as query_context) with the query. The qualifier must be in form {bucket_name}.{scope_name} or default:{bucket_name}.{scope_name}.

  • transcoder (JsonTranscoder) (defaults to: JsonTranscoder.new) —

    to decode rows

  • positional_parameters (Array<#to_json>, nil) (defaults to: nil) —

    parameters to be used as substitution for numbered macros like $1, $2 in query string

  • named_parameters (Hash<String => #to_json>, nil) (defaults to: nil) —

    parameters to be used as substitution for named macros like $name in query string.

  • mutation_state (MutationState, nil) (defaults to: nil) —

    Sets the mutation tokens this query should be consistent with. Overrides scan_consistency.

  • timeout (Integer, #in_milliseconds, nil) (defaults to: nil)
  • retry_strategy (Symbol, nil) (defaults to: nil) —

    ignored by this operation

  • client_context (Hash, nil) (defaults to: nil) —

    the client context data, if set

  • parent_span (Span, nil) (defaults to: nil) —

    if set holds the parent span, that should be used for this request

Yield Parameters:

Raises:

  • (ArgumentError) 


2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
 
# File 'lib/couchbase/options.rb', line 2267

def initialize(adhoc: true,
               client_context_id: nil,
               max_parallelism: nil,
               readonly: false,
               scan_wait: nil,
               scan_cap: nil,
               pipeline_cap: nil,
               pipeline_batch: nil,
               metrics: nil,
               profile: :off,
               flex_index: nil,
               preserve_expiry: nil,
               use_replica: nil,
               scope_qualifier: nil,
               scan_consistency: :not_bounded,
               mutation_state: nil,
               transcoder: JsonTranscoder.new,
               positional_parameters: nil,
               named_parameters: nil,
               timeout: nil,
               retry_strategy: nil,
               client_context: nil,
               parent_span: nil)
  raise ArgumentError, "Cannot pass positional and named parameters at the same time" if positional_parameters && named_parameters

  super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span)
  @adhoc = adhoc
  @client_context_id = client_context_id
  @max_parallelism = max_parallelism
  @readonly = readonly
  @scan_wait = scan_wait
  @scan_cap = scan_cap
  @pipeline_cap = pipeline_cap
  @pipeline_batch = pipeline_batch
  @metrics = metrics
  @profile = profile
  @flex_index = flex_index
  @preserve_expiry = preserve_expiry
  @use_replica = use_replica
  @scope_qualifier = scope_qualifier
  @scan_consistency = scan_consistency
  @mutation_state = mutation_state
  @transcoder = transcoder
  @positional_parameters = positional_parameters
  @named_parameters = named_parameters
  @raw_parameters = {}
  yield self if block_given?
end

Instance Attribute Details

#adhoc ⇒ Boolean

Returns:

  • (Boolean) 


2188
2189
2190
 
# File 'lib/couchbase/options.rb', line 2188

def adhoc
  @adhoc
end

#client_context_id ⇒ String

Returns:

  • (String) 


2189
2190
2191
 
# File 'lib/couchbase/options.rb', line 2189

def client_context_id
  @client_context_id
end

#flex_index ⇒ Boolean

Returns:

  • (Boolean) 


2198
2199
2200
 
# File 'lib/couchbase/options.rb', line 2198

def flex_index
  @flex_index
end

#max_parallelism ⇒ Integer

Returns:

  • (Integer) 


2190
2191
2192
 
# File 'lib/couchbase/options.rb', line 2190

def max_parallelism
  @max_parallelism
end

#metrics ⇒ Boolean

Returns:

  • (Boolean) 


2196
2197
2198
 
# File 'lib/couchbase/options.rb', line 2196

def metrics
  @metrics
end

#pipeline_batch ⇒ Integer

Returns:

  • (Integer) 


2194
2195
2196
 
# File 'lib/couchbase/options.rb', line 2194

def pipeline_batch
  @pipeline_batch
end

#pipeline_cap ⇒ Integer

Returns:

  • (Integer) 


2195
2196
2197
 
# File 'lib/couchbase/options.rb', line 2195

def pipeline_cap
  @pipeline_cap
end

#preserve_expiry ⇒ Boolean

Returns:

  • (Boolean) 


2199
2200
2201
 
# File 'lib/couchbase/options.rb', line 2199

def preserve_expiry
  @preserve_expiry
end

#profile ⇒ Symbol

Returns:

  • (Symbol) 


2197
2198
2199
 
# File 'lib/couchbase/options.rb', line 2197

def profile
  @profile
end

#readonly ⇒ Boolean

Returns:

  • (Boolean) 


2191
2192
2193
 
# File 'lib/couchbase/options.rb', line 2191

def readonly
  @readonly
end

#scan_cap ⇒ Integer

Returns:

  • (Integer) 


2193
2194
2195
 
# File 'lib/couchbase/options.rb', line 2193

def scan_cap
  @scan_cap
end

#scan_wait ⇒ Integer, #in_milliseconds

Returns:

  • (Integer, #in_milliseconds) 


2192
2193
2194
 
# File 'lib/couchbase/options.rb', line 2192

def scan_wait
  @scan_wait
end

#scope_qualifier ⇒ String

Returns:

  • (String) 


2201
2202
2203
 
# File 'lib/couchbase/options.rb', line 2201

def scope_qualifier
  @scope_qualifier
end

#transcoder ⇒ JsonTranscoder, #decode(String)

Returns:



2202
2203
2204
 
# File 'lib/couchbase/options.rb', line 2202

def transcoder
  @transcoder
end

#use_replica ⇒ Boolean?

Returns:

  • (Boolean, nil) 


2200
2201
2202
 
# File 'lib/couchbase/options.rb', line 2200

def use_replica
  @use_replica
end

Instance Method Details

#consistent_with(mutation_state) ⇒ Object

Note:

overrides consistency level set by #scan_consistency=

Sets the mutation tokens this query should be consistent with

Parameters:

  • mutation_state (MutationState) —

    the mutation state containing the mutation tokens



2345
2346
2347
2348
 
# File 'lib/couchbase/options.rb', line 2345

def consistent_with(mutation_state)
  @scan_consistency = nil if @scan_consistency
  @mutation_state = mutation_state
end

#named_parameters(named) ⇒ Object

Sets named parameters for the query

Parameters:

  • named (Hash) —

    the key/value map of the parameters to substitute in the statement



2367
2368
2369
2370
 
# File 'lib/couchbase/options.rb', line 2367

def named_parameters(named)
  @named_parameters = named
  @positional_parameters = nil
end

#positional_parameters(positional) ⇒ Object

Sets positional parameters for the query

Parameters:

  • positional (Array) —

    the list of parameters that have to be substituted in the statement



2353
2354
2355
2356
 
# File 'lib/couchbase/options.rb', line 2353

def positional_parameters(positional)
  @positional_parameters = positional
  @named_parameters = nil
end

#raw(key, value) ⇒ Object

Allows providing custom JSON key/value pairs for advanced usage

Parameters:

  • key (String, Symbol) —

    the parameter name (key of the JSON property), converted with to_s

  • value (Object) —

    the parameter value (value of the JSON property)



2320
2321
2322
 
# File 'lib/couchbase/options.rb', line 2320

def raw(key, value)
  @raw_parameters[key.to_s] = JSON.generate(value)
end

#scan_consistency=(level) ⇒ Object

Note:

overrides consistency level set by #consistent_with

Customizes the consistency guarantees for this query

[+: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.

Parameters:

  • level (:not_bounded, :request_plus) —

    the index scan consistency to be used for this query



2335
2336
2337
2338
 
# File 'lib/couchbase/options.rb', line 2335

def scan_consistency=(level)
  @mutation_state = nil if @mutation_state
  @scan_consistency = level
end