Class QueryOptions

Options to control execution of a N1QL query.

Inheritance

object

QueryOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Couchbase.Query

Assembly: Couchbase.NetClient.dll

Syntax

public class QueryOptions

Constructors

QueryOptions()

Creates a new QueryOptions object.

Declaration

public QueryOptions()

QueryOptions(QueryPlan, string)

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

Declaration

public QueryOptions(QueryPlan plan, string originalStatement)

Parameters

Type	Name	Description
QueryPlan	plan	The QueryPlan(QueryPlan).
string	originalStatement	The original N1QL query statement used to generate the plan.

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.

Fields

DefaultReadOnly

Declaration

public static readonly QueryOptions.ReadOnlyRecord DefaultReadOnly

Field Value

Type	Description
QueryOptions.ReadOnlyRecord

Properties

CurrentContextId

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

Declaration

public string? CurrentContextId { get; }

Property Value

Type	Description
string	The context identifier.

Remarks

This value changes for every request./>

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
bool	true if this instance is ad-hoc; otherwise, false.

IsPrepared

Returns true if the request is a prepared statement

Declaration

public bool IsPrepared { get; }

Property Value

Type	Description
bool

LastDispatchedNode

Declaration

[InterfaceStability(Level.Volatile)]
public Uri? LastDispatchedNode { get; set; }

Property Value

Type	Description
Uri

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

AdHoc(bool)

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
bool	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.

AsReadOnly()

Declaration

public QueryOptions.ReadOnlyRecord AsReadOnly()

Returns

Type	Description
QueryOptions.ReadOnlyRecord

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.

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.

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 AtPlus.

Create()

Creates a new QueryOptions object.

Declaration

public static QueryOptions Create()

Returns

Type	Description
QueryOptions

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

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

Deconstruct(out IReadOnlyList<object?>, out IReadOnlyDictionary<string, object>, out IReadOnlyDictionary<string, object>, out bool, out bool?, out int?, out int?, out int?, out QueryPlan?, out QueryProfile, out bool?, out int?, out QueryScanConsistency, out TimeSpan?, out string?, out TimeSpan?, out bool, out bool, out bool, out string?, out string?, out IRequestSpan?, out IRetryStrategy?, out CancellationToken, out Uri?, out bool, out bool, out string?, out ITypeSerializer?, out string?, out bool?)

Declaration

public void Deconstruct(out IReadOnlyList<object?> arguments, out IReadOnlyDictionary<string, object> parameters, out IReadOnlyDictionary<string, object> rawParameters, out bool autoExecute, out bool? includeMetrics, out int? maxServerParallelism, out int? pipelineBatch, out int? pipelineCapacity, out QueryPlan? preparedPayload, out QueryProfile profile, out bool? readOnly, out int? scanCapacity, out QueryScanConsistency scanConsistency, out TimeSpan? scanWait, out string? statement, out TimeSpan? timeOut, out bool flexIndex, out bool isUsed, out bool preserveExpiry, out string? bucketName, out string? scopeName, out IRequestSpan? requestSpanValue, out IRetryStrategy? retryStrategyValue, out CancellationToken token, out Uri? lastDispatchedNode, out bool isPrepared, out bool isAdHoc, out string? currentContextId, out ITypeSerializer? serializer, out string? queryContext, out bool? useReplica)

Parameters

Type	Name	Description
IReadOnlyList<object>	arguments
IReadOnlyDictionary<string, object>	parameters
IReadOnlyDictionary<string, object>	rawParameters
bool	autoExecute
bool?	includeMetrics
int?	maxServerParallelism
int?	pipelineBatch
int?	pipelineCapacity
QueryPlan	preparedPayload
QueryProfile	profile
bool?	readOnly
int?	scanCapacity
QueryScanConsistency	scanConsistency
TimeSpan?	scanWait
string	statement
TimeSpan?	timeOut
bool	flexIndex
bool	isUsed
bool	preserveExpiry
string	bucketName
string	scopeName
IRequestSpan	requestSpanValue
IRetryStrategy	retryStrategyValue
CancellationToken	token
Uri	lastDispatchedNode
bool	isPrepared
bool	isAdHoc
string	currentContextId
ITypeSerializer	serializer
string	queryContext
bool?	useReplica

FlexIndex(bool)

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

Declaration

public QueryOptions FlexIndex(bool flexIndex)

Parameters

Type	Name	Description
bool	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.

GetFormValues()

Gets a IDictionary<TKey, TValue> of the name/value pairs to be POSTed to the service.

Declaration

public IDictionary<string, object?> GetFormValues()

Returns

Type	Description
IDictionary<string, object>	The IDictionary<TKey, TValue> 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.

Exceptions

Type	Condition
ArgumentException	A statement or prepared plan must be provided.

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.

MaxServerParallelism(int)

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
int	parallelism

Returns

Type	Description
QueryOptions

Metrics(bool)

Specifies that metrics should be returned with query results.

Declaration

public QueryOptions Metrics(bool includeMetrics)

Parameters

Type	Name	Description
bool	includeMetrics	True to return query metrics.

Returns

Type	Description
QueryOptions	A reference to the current QueryOptions for method chaining.

Remarks

Optional.

Parameter(params 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 KeyValuePair<TKey, TValue> to be sent.

Returns

Type	Description
QueryOptions	A reference to the current QueryOptions for method chaining.

Remarks

Optional.

Parameter(object?)

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

Declaration

public QueryOptions Parameter(object? value)

Parameters

Type	Name	Description
object	value	The value of the positional parameter.

Returns

Type	Description
QueryOptions	A reference to the current QueryOptions for method chaining.

Remarks

Optional.

Parameter(params 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

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.

PipelineBatch(int)

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

Declaration

public QueryOptions PipelineBatch(int batchSize)

Parameters

Type	Name	Description
int	batchSize	The maximum number of items.

Returns

Type	Description
QueryOptions	A reference to the current QueryOptions for method chaining.

PipelineCap(int)

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

Declaration

public QueryOptions PipelineCap(int capacity)

Parameters

Type	Name	Description
int	capacity	The maximum number of items.

Returns

Type	Description
QueryOptions	A reference to the current QueryOptions for method chaining.

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.

Exceptions

Type	Condition
ArgumentNullException	preparedPlan is null.

PreserveExpiry(bool)

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

Declaration

[InterfaceStability(Level.Uncommitted)]
public QueryOptions PreserveExpiry(bool preserveExpiry)

Parameters

Type	Name	Description
bool	preserveExpiry	If expiration values should be preserved, the default is false.

Returns

Type	Description
QueryOptions	A reference to the current QueryOptions for method chaining.

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.

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.

ReadOnly(bool)

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

Declaration

[Obsolete("Use QueryOptions.Readonly property instead.")]
public QueryOptions ReadOnly(bool readOnly)

Parameters

Type	Name	Description
bool	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.

Readonly(bool)

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

Declaration

public QueryOptions Readonly(bool readOnly)

Parameters

Type	Name	Description
bool	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.

RequestSpan(IRequestSpan)

Declaration

public QueryOptions RequestSpan(IRequestSpan span)

Parameters

Type	Name	Description
IRequestSpan	span

Returns

Type	Description
QueryOptions

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.

ScanCap(int)

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
int	capacity	The maximum number of channels.

Returns

Type	Description
QueryOptions	A reference to the current QueryOptions for method chaining.

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.

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.

StreamResults(bool)

If .NET5 or greater, this has no effect, we always stream the results. However in older .NET, we default to false, limiting the size of the results to 2Gb. If you are using .NET Framework 4.8, for instance, and need to return result sets of >2Gb, set this to true. However, you must Dispose of the returned QueryResult, or you will leak HTTP connections.

Declaration

public QueryOptions StreamResults(bool streamResults)

Parameters

Type	Name	Description
bool	streamResults

Returns

Type	Description
QueryOptions

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.

UseReplica(bool?)

Allows querying data from replicas. True: Allows the server to read potentially stale data from replica vBuckets. False: The server must use up-to-date data from primaries (nodes which own the vBucket containing the data).

Declaration

public QueryOptions UseReplica(bool? useReplica)

Parameters

Type	Name	Description
bool?	useReplica

Returns

Type	Description
QueryOptions