Class: Couchbase::Options::Query

Inherits:
Base
  • Object
show all
Defined in:
lib/couchbase/options.rb,
/Users/sergey.auseyau/code/couchbase-ruby-client/lib/couchbase/options.rb more...

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

  • 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)
[View source]

1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
 
# File 'lib/couchbase/options.rb', line 1379

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,
               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
  @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) 

1306
1307
1308
 
# File 'lib/couchbase/options.rb', line 1306

def adhoc
  @adhoc
end

#client_context_id ⇒ String

Returns:

  • (String) 

1307
1308
1309
 
# File 'lib/couchbase/options.rb', line 1307

def client_context_id
  @client_context_id
end

#flex_index ⇒ Boolean

Returns:

  • (Boolean) 

1316
1317
1318
 
# File 'lib/couchbase/options.rb', line 1316

def flex_index
  @flex_index
end

#max_parallelism ⇒ Integer

Returns:

  • (Integer) 

1308
1309
1310
 
# File 'lib/couchbase/options.rb', line 1308

def max_parallelism
  @max_parallelism
end

#metrics ⇒ Boolean

Returns:

  • (Boolean) 

1314
1315
1316
 
# File 'lib/couchbase/options.rb', line 1314

def metrics
  @metrics
end

#pipeline_batch ⇒ Integer

Returns:

  • (Integer) 

1312
1313
1314
 
# File 'lib/couchbase/options.rb', line 1312

def pipeline_batch
  @pipeline_batch
end

#pipeline_cap ⇒ Integer

Returns:

  • (Integer) 

1313
1314
1315
 
# File 'lib/couchbase/options.rb', line 1313

def pipeline_cap
  @pipeline_cap
end

#profile ⇒ Symbol

Returns:

  • (Symbol) 

1315
1316
1317
 
# File 'lib/couchbase/options.rb', line 1315

def profile
  @profile
end

#readonly ⇒ Boolean

Returns:

  • (Boolean) 

1309
1310
1311
 
# File 'lib/couchbase/options.rb', line 1309

def readonly
  @readonly
end

#scan_cap ⇒ Integer

Returns:

  • (Integer) 

1311
1312
1313
 
# File 'lib/couchbase/options.rb', line 1311

def scan_cap
  @scan_cap
end

#scan_wait ⇒ Integer, #in_milliseconds

Returns:

  • (Integer, #in_milliseconds) 

1310
1311
1312
 
# File 'lib/couchbase/options.rb', line 1310

def scan_wait
  @scan_wait
end

#scope_qualifier ⇒ String

Returns:

  • (String) 

1317
1318
1319
 
# File 'lib/couchbase/options.rb', line 1317

def scope_qualifier
  @scope_qualifier
end

#transcoder ⇒ JsonTranscoder, #decode(String)

Returns:


1318
1319
1320
 
# File 'lib/couchbase/options.rb', line 1318

def transcoder
  @transcoder
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

[View source]

1453
1454
1455
1456
 
# File 'lib/couchbase/options.rb', line 1453

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

[View source]

1475
1476
1477
1478
 
# File 'lib/couchbase/options.rb', line 1475

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

[View source]

1461
1462
1463
1464
 
# File 'lib/couchbase/options.rb', line 1461

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)

[View source]

1428
1429
1430
 
# File 'lib/couchbase/options.rb', line 1428

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

[View source]

1443
1444
1445
1446
 
# File 'lib/couchbase/options.rb', line 1443

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