Class QueryOptions

Options to control execution of a N1QL query.

Inheritance

object

QueryOptions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Namespace: Couchbase.Query

Assembly: Couchbase.NetClient.dll

Syntax

public class QueryOptions

Constructors

View Source

QueryOptions()

Creates a new QueryOptions object.

Declaration

public QueryOptions()

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.

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.

Fields

View Source

DefaultReadOnly

Declaration

public static readonly QueryOptions.ReadOnlyRecord DefaultReadOnly

Field Value

Type	Description
QueryOptions.ReadOnlyRecord

Properties

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
string	The context identifier.

Remarks

This value changes for every request./>

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

View Source

IsPrepared

Returns true if the request is a prepared statement

Declaration

[MemberNotNullWhen(true, "_preparedPayload")]
public bool IsPrepared { get; }

Property Value

Type	Description
bool

View Source

LastDispatchedNode

Declaration

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

Property Value

Type	Description
Uri

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

View Source

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.

View Source

AsReadOnly()

Declaration

public QueryOptions.ReadOnlyRecord AsReadOnly()

Returns

Type	Description
QueryOptions.ReadOnlyRecord

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.

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.

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.

View Source

Create()

Creates a new QueryOptions object.

Declaration

public static QueryOptions Create()

Returns

Type	Description
QueryOptions

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

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

View Source

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

View Source

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.

View Source

GetFormValues()

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

Declaration

[RequiresUnreferencedCode("GetFormValuesAsJson uses Newtonsoft.Json which requires unreferenced code and is incompatible with trimming.")]
[RequiresDynamicCode("GetFormValuesAsJson uses Newtonsoft.Json which may required dynamic code.")]
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.

View Source

GetFormValuesAsJson()

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

Declaration

[RequiresUnreferencedCode("GetFormValuesAsJson uses Newtonsoft.Json which requires unreferenced code and is incompatible with trimming.")]
[RequiresDynamicCode("GetFormValuesAsJson uses Newtonsoft.Json which may required dynamic code.")]
public string GetFormValuesAsJson()

Returns

Type	Description
string	The form values as a JSON object.

View Source

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

View Source

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.

View Source

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.

View Source

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.

View Source

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

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.

View Source

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.

View Source

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.

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.

Exceptions

Type	Condition
ArgumentNullException	`preparedPlan` is null.

View Source

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.

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.

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.

View Source

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.

View Source

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.

View Source

RequestSpan(IRequestSpan)

Declaration

public QueryOptions RequestSpan(IRequestSpan span)

Parameters

Type	Name	Description
IRequestSpan	span

Returns

Type	Description
QueryOptions

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.

View Source

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.

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.

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.

View Source

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

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.

View Source

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