Class QueryOptions

Options to control execution of a N1QL query.

Inheritance
Object
QueryOptions
Namespace: Couchbase.Query
Assembly: Couchbase.NetClient.dll
Syntax
public class QueryOptions : object

Constructors

| Improve this Doc View Source

QueryOptions()

Creates a new QueryOptions object.

Declaration
public QueryOptions()
| Improve this Doc View Source

QueryOptions(QueryPlan, String)

Creates a new QueryOptions object with an existing Couchbase.Query.QueryOptions.QueryPlan(Couchbase.Query.QueryPlan).

Declaration
public QueryOptions(QueryPlan plan, string originalStatement)
Parameters
Type Name Description
QueryPlan plan

The Couchbase.Query.QueryOptions.QueryPlan(Couchbase.Query.QueryPlan).
String originalStatement

The original N1QL query statement used to generate the plan.
| Improve this Doc View Source

QueryOptions(String)

Creates a new QueryOptions object with a N1QL query statement.

Declaration
public QueryOptions(string statement)
Parameters
Type Name Description
String statement

A N1QL query statement.

Properties

| Improve this Doc View Source

CurrentContextId

Gets the context identifier for the N1QL query request/response. Useful for debugging.

Declaration
public string? CurrentContextId { get; }
Property Value
Type Description
Nullable<String>

The context identifier.
Remarks

This value changes for every request./>

| Improve this Doc View Source

IsAdHoc

Gets a value indicating whether this query statement is to executed in an ad-hoc manner.

Declaration
public bool IsAdHoc { get; }
Property Value
Type Description
Boolean

true if this instance is ad-hoc; otherwise, false.
| Improve this Doc View Source

IsPrepared

Returns true if the request is a prepared statement

Declaration
public bool IsPrepared { get; }
Property Value
Type Description
Boolean
| Improve this Doc View Source

LastDispatchedNode

Declaration
public Uri? LastDispatchedNode { get; set; }
Property Value
Type Description
Nullable<Uri>
| Improve this Doc View Source

Serializer

Custom ITypeSerializer to use when deserializing query results.

Declaration
public ITypeSerializer Serializer { get; set; }
Property Value
Type Description
ITypeSerializer
Remarks

Null will use the default ITypeSerializer.

Methods

| Improve this Doc View Source

AdHoc(Boolean)

If set to false, the client will try to perform optimizations transparently based on the server capabilities, like preparing the statement and then executing a query plan instead of the raw query.

Declaration
public QueryOptions AdHoc(bool adHoc)
Parameters
Type Name Description
Boolean adHoc

if set to false the query will be optimized if possible.
Returns
Type Description
QueryOptions
Remarks

The default is true; the query will executed in an ad-hoc manner, without special optimizations.

| Improve this Doc View Source

CancellationToken(CancellationToken)

Set the CancellationToken(CancellationToken) which will cancel the query if it is incomplete.

Declaration
public QueryOptions CancellationToken(CancellationToken cancellationToken)
Parameters
Type Name Description
CancellationToken cancellationToken

The CancellationToken(CancellationToken).
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
| Improve this Doc View Source

ClientContextId(String)

Client Context ID. If no client context ID is provided on this option, a UUID is generated and sent automatically so by default it is always possible to identify a query when debugging.

Declaration
public QueryOptions ClientContextId(string clientContextId)
Parameters
Type Name Description
String clientContextId

The client context identifier.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
| Improve this Doc View Source

ConsistentWith(MutationState)

Provides a means of ensuring "read your own writes" or RYOW consistency on the current query.

Declaration
public QueryOptions ConsistentWith(MutationState mutationState)
Parameters
Type Name Description
MutationState mutationState

State of the mutation.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Note: ScanConsistency(QueryScanConsistency) will be overwritten to Couchbase.Query.QueryScanConsistencyInternal.AtPlus.

| Improve this Doc View Source

Create()

Creates a new QueryOptions object.

Declaration
public static QueryOptions Create()
Returns
Type Description
QueryOptions
| Improve this Doc View Source

Create(QueryPlan, String)

Creates a query using the given plan as an optimization for the originalStatement.

Declaration
public static QueryOptions Create(QueryPlan plan, string originalStatement)
Parameters
Type Name Description
QueryPlan plan

The plan.
String originalStatement

The original statement, unoptimized.
Returns
Type Description
QueryOptions
| Improve this Doc View Source

Create(String)

Creates a new QueryOptions object with the specified statement.

Declaration
public static QueryOptions Create(string statement)
Parameters
Type Name Description
String statement

The statement.
Returns
Type Description
QueryOptions
| Improve this Doc View Source

FlexIndex(Boolean)

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

Declaration
public QueryOptions FlexIndex(bool flexIndex)
Parameters
Type Name Description
Boolean flexIndex

true if a flex index should be used, false is the default
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

This feature is Uncommitted and may change in the future.

| Improve this Doc View Source

GetFormValues()

Gets a of the name/value pairs to be POSTed to the service.

Declaration
public IDictionary<string, object?> GetFormValues()
Returns
Type Description
IDictionary<String, Nullable<Object>>

The of the name/value pairs to be POSTed to the service.
Remarks

Since values will be POSTed as JSON, here we deal with unencoded typed values (like ints, Lists, etc...) rather than only strings.

| Improve this Doc View Source

GetFormValuesAsJson()

Gets the JSON representation of this query for execution in a POST.

Declaration
public string GetFormValuesAsJson()
Returns
Type Description
String

The form values as a JSON object.
| Improve this Doc View Source

MaxServerParallelism(Int32)

Specifies the maximum parallelism for the query. A zero or negative value means the number of logical cpus will be used as the parallelism for the query. There is also a server wide max_parallelism parameter which defaults to 1. If a request includes max_parallelism, it will be capped by the server max_parallelism. If a request does not include max_parallelism, the server wide max_parallelism will be used.

Declaration
public QueryOptions MaxServerParallelism(int parallelism)
Parameters
Type Name Description
Int32 parallelism
Returns
Type Description
QueryOptions
| Improve this Doc View Source

Metrics(Boolean)

Specifies that metrics should be returned with query results.

Declaration
public QueryOptions Metrics(bool includeMetrics)
Parameters
Type Name Description
Boolean includeMetrics

True to return query metrics.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Optional.

| Improve this Doc View Source

Parameter(KeyValuePair<String, Object>[])

Adds a collection of named parameters to the parameters to the statement or prepared statement.

Declaration
public QueryOptions Parameter(params KeyValuePair<string, object>[] parameters)
Parameters
Type Name Description
KeyValuePair<String, Object>[] parameters

A list of to be sent.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Optional.

| Improve this Doc View Source

Parameter(Nullable<Object>)

Adds a positional parameter to the parameters to the statement or prepared statement.

Declaration
public QueryOptions Parameter(object? value)
Parameters
Type Name Description
Nullable<Object> value

The value of the positional parameter.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Optional.

| Improve this Doc View Source

Parameter(Object[])

Adds a list of positional parameters to the statement or prepared statement.

Declaration
public QueryOptions Parameter(params object[] parameters)
Parameters
Type Name Description
Object[] parameters

A list of positional parameters.
Returns
Type Description
QueryOptions
| Improve this Doc View Source

Parameter(String, Object)

Adds a named parameter to the parameters to the statement or prepared statement.

Declaration
public QueryOptions Parameter(string name, object value)
Parameters
Type Name Description
String name

The name of the parameter.
Object value

The value of the parameter.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Optional.

| Improve this Doc View Source

PipelineBatch(Int32)

Sets the number of items execution operators can batch for fetch from the KV.

Declaration
public QueryOptions PipelineBatch(int batchSize)
Parameters
Type Name Description
Int32 batchSize

The maximum number of items.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
| Improve this Doc View Source

PipelineCap(Int32)

Sets maximum number of items each execution operator can buffer between various operators.

Declaration
public QueryOptions PipelineCap(int capacity)
Parameters
Type Name Description
Int32 capacity

The maximum number of items.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
| Improve this Doc View Source

Prepared(QueryPlan, String)

Sets a N1QL statement to be executed in an optimized way using the given queryPlan.

Declaration
public QueryOptions Prepared(QueryPlan preparedPlan, string originalStatement)
Parameters
Type Name Description
QueryPlan preparedPlan

The QueryPlan that was prepared beforehand.
String originalStatement

The original statement (eg. SELECT * FROM default) that the user attempted to optimize
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Required if statement not provided, will erase a previously set Statement.

| Improve this Doc View Source

PreserveExpiry(Boolean)

(v.7.1.0 and onwards) Tells the query engine to preserve expiration values set on any documents modified by this query.

Declaration
public QueryOptions PreserveExpiry(bool preserveExpiry)
Parameters
Type Name Description
Boolean preserveExpiry

If expiration values should be preserved, the default is false.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
| Improve this Doc View Source

Profile(QueryProfile)

Set the QueryProfile information to be returned along with the query results.

Declaration
public QueryOptions Profile(QueryProfile profile)
Parameters
Type Name Description
QueryProfile profile

The QueryProfile.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
| Improve this Doc View Source

Raw(String, Object)

Adds a raw query parameter and value to the query. NOTE: This is uncommitted and may change in the future.

Declaration
public QueryOptions Raw(string name, object value)
Parameters
Type Name Description
String name

The paramter name.
Object value

The parameter value.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
| Improve this Doc View Source

Readonly(Boolean)

If a GET request, this will always be true otherwise false.

Declaration
public QueryOptions Readonly(bool readOnly)
Parameters
Type Name Description
Boolean readOnly

True for get requests.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Any value set here will be overridden by the type of request sent.

| Improve this Doc View Source

ReadOnly(Boolean)

If a GET request, this will always be true otherwise false.

Declaration
public QueryOptions ReadOnly(bool readOnly)
Parameters
Type Name Description
Boolean readOnly

True for get requests.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Any value set here will be overridden by the type of request sent.

| Improve this Doc View Source

RequestSpan(IRequestSpan)

Declaration
public QueryOptions RequestSpan(IRequestSpan span)
Parameters
Type Name Description
IRequestSpan span
Returns
Type Description
QueryOptions
| Improve this Doc View Source

RetryStrategy(IRetryStrategy)

Overrides the global IRetryStrategy defined in ClusterOptions for a request.

Declaration
public QueryOptions RetryStrategy(IRetryStrategy retryStrategy)
Parameters
Type Name Description
IRetryStrategy retryStrategy

The IRetryStrategy to use for a single request.
Returns
Type Description
QueryOptions

The options.
| Improve this Doc View Source

ScanCap(Int32)

Sets maximum buffered channel size between the indexer client and the query service for index scans. This parameter controls when to use scan backfill. Use 0 or a negative number to disable.

Declaration
public QueryOptions ScanCap(int capacity)
Parameters
Type Name Description
Int32 capacity

The maximum number of channels.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
| Improve this Doc View Source

ScanConsistency(QueryScanConsistency)

Specifies the consistency guarantee/constraint for index scanning.

Declaration
public QueryOptions ScanConsistency(QueryScanConsistency scanConsistency)
Parameters
Type Name Description
QueryScanConsistency scanConsistency

Specify the consistency guarantee/constraint for index scanning.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Optional.

| Improve this Doc View Source

ScanWait(TimeSpan)

Specifies the maximum time the client is willing to wait for an index to catch up to the vector timestamp in the request. If an index has to catch up, and the ScanWait(TimeSpan) time is exceed doing so, an error is returned.

Declaration
public QueryOptions ScanWait(TimeSpan scanWait)
Parameters
Type Name Description
TimeSpan scanWait

The maximum time the client is willing to wait for index to catch up to the vector timestamp.
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Optional.

| Improve this Doc View Source

Timeout(TimeSpan)

Sets the maximum time to spend on the request.

Declaration
public QueryOptions Timeout(TimeSpan timeOut)
Parameters
Type Name Description
TimeSpan timeOut

Maximum time to spend on the request
Returns
Type Description
QueryOptions

A reference to the current QueryOptions for method chaining.
Remarks

Optional - the default is 0ms, which means the request runs for as long as it takes.

| Improve this Doc View Source

ToString()

Returns a that represents this instance.

Declaration
public override string ToString()
Returns
Type Description
String

A that represents this instance.