Class: Couchbase::Options::Query

Inherits:
Base
  • Object
show all
Defined in:
lib/couchbase/options.rb

Overview

Options for Cluster#query

Constant Summary collapse

DEFAULT =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

Query.new.freeze

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 (Proc, nil) (defaults to: nil) —

    the custom retry strategy, if set

  • 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) 


2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
 
# File 'lib/couchbase/options.rb', line 2101

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) 


2022
2023
2024
 
# File 'lib/couchbase/options.rb', line 2022

def adhoc
  @adhoc
end

#client_context_id ⇒ String

Returns:

  • (String) 


2023
2024
2025
 
# File 'lib/couchbase/options.rb', line 2023

def client_context_id
  @client_context_id
end

#flex_index ⇒ Boolean

Returns:

  • (Boolean) 


2032
2033
2034
 
# File 'lib/couchbase/options.rb', line 2032

def flex_index
  @flex_index
end

#max_parallelism ⇒ Integer

Returns:

  • (Integer) 


2024
2025
2026
 
# File 'lib/couchbase/options.rb', line 2024

def max_parallelism
  @max_parallelism
end

#metrics ⇒ Boolean

Returns:

  • (Boolean) 


2030
2031
2032
 
# File 'lib/couchbase/options.rb', line 2030

def metrics
  @metrics
end

#mutation_state ⇒ MutationState (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:



2214
2215
2216
 
# File 'lib/couchbase/options.rb', line 2214

def mutation_state
  @mutation_state
end

#pipeline_batch ⇒ Integer

Returns:

  • (Integer) 


2028
2029
2030
 
# File 'lib/couchbase/options.rb', line 2028

def pipeline_batch
  @pipeline_batch
end

#pipeline_cap ⇒ Integer

Returns:

  • (Integer) 


2029
2030
2031
 
# File 'lib/couchbase/options.rb', line 2029

def pipeline_cap
  @pipeline_cap
end

#preserve_expiry ⇒ Boolean

Returns:

  • (Boolean) 


2033
2034
2035
 
# File 'lib/couchbase/options.rb', line 2033

def preserve_expiry
  @preserve_expiry
end

#profile ⇒ Symbol

Returns:

  • (Symbol) 


2031
2032
2033
 
# File 'lib/couchbase/options.rb', line 2031

def profile
  @profile
end

#raw_parameters ⇒ Hash<String => #to_json> (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Hash<String => #to_json>) 


2218
2219
2220
 
# File 'lib/couchbase/options.rb', line 2218

def raw_parameters
  @raw_parameters
end

#readonly ⇒ Boolean

Returns:

  • (Boolean) 


2025
2026
2027
 
# File 'lib/couchbase/options.rb', line 2025

def readonly
  @readonly
end

#scan_cap ⇒ Integer

Returns:

  • (Integer) 


2027
2028
2029
 
# File 'lib/couchbase/options.rb', line 2027

def scan_cap
  @scan_cap
end

#scan_wait ⇒ Integer, #in_milliseconds

Returns:

  • (Integer, #in_milliseconds) 


2026
2027
2028
 
# File 'lib/couchbase/options.rb', line 2026

def scan_wait
  @scan_wait
end

#scope_qualifier ⇒ String

Returns:

  • (String) 


2035
2036
2037
 
# File 'lib/couchbase/options.rb', line 2035

def scope_qualifier
  @scope_qualifier
end

#transcoder ⇒ JsonTranscoder, #decode(String)

Returns:



2036
2037
2038
 
# File 'lib/couchbase/options.rb', line 2036

def transcoder
  @transcoder
end

#use_replica ⇒ Boolean?

Returns:

  • (Boolean, nil) 


2034
2035
2036
 
# File 'lib/couchbase/options.rb', line 2034

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



2179
2180
2181
2182
 
# File 'lib/couchbase/options.rb', line 2179

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

#export_named_parameters ⇒ Hash<String => String>?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Hash<String => String>, nil) 


2208
2209
2210
 
# File 'lib/couchbase/options.rb', line 2208

def export_named_parameters
  @named_parameters&.each_with_object({}) { |(n, v), o| o[n.to_s] = JSON.dump(v) }
end

#export_positional_parameters ⇒ Array<String>?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Array<String>, nil) 


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

def export_positional_parameters
  @positional_parameters&.map { |p| JSON.dump(p) }
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



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

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



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

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) —

    the parameter name (key of the JSON property)

  • value (Object) —

    the parameter value (value of the JSON property)



2154
2155
2156
 
# File 'lib/couchbase/options.rb', line 2154

def raw(key, value)
  @raw_parameters[key] = 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



2169
2170
2171
2172
 
# File 'lib/couchbase/options.rb', line 2169

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

#to_backend(scope_name: nil, bucket_name: nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
 
# File 'lib/couchbase/options.rb', line 2221

def to_backend(scope_name: nil, bucket_name: nil)
  if scope_name && bucket_name
    default_query_context = format("default:`%<bucket>s`.`%<scope>s`", bucket: bucket_name, scope: scope_name)
  end
  {
    timeout: Utils::Time.extract_duration(@timeout),
    adhoc: @adhoc,
    client_context_id: @client_context_id,
    max_parallelism: @max_parallelism,
    readonly: @readonly,
    flex_index: @flex_index,
    preserve_expiry: @preserve_expiry,
    use_replica: @use_replica,
    scan_wait: Utils::Time.extract_duration(@scan_wait),
    scan_cap: @scan_cap,
    pipeline_batch: @pipeline_batch,
    pipeline_cap: @pipeline_cap,
    metrics: @metrics,
    profile: @profile,
    positional_parameters: export_positional_parameters,
    named_parameters: export_named_parameters,
    raw_parameters: @raw_parameters,
    scan_consistency: @scan_consistency,
    mutation_state: @mutation_state&.to_a,
    query_context: @scope_qualifier || default_query_context,
  }
end