Couchbase .NET SDK | 3.7.2
Search Results for

    Show / Hide Table of Contents

    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

    | Edit this page View Source

    QueryOptions()

    Creates a new QueryOptions object.

    Declaration
    public QueryOptions()
    | Edit this page View Source

    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.

    | Edit this page 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

    | Edit this page View Source

    DefaultReadOnly

    Declaration
    public static readonly QueryOptions.ReadOnlyRecord DefaultReadOnly
    Field Value
    Type Description
    QueryOptions.ReadOnlyRecord

    Properties

    | Edit this page 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./>

    | Edit this page 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.

    | Edit this page View Source

    IsPrepared

    Returns true if the request is a prepared statement

    Declaration
    public bool IsPrepared { get; }
    Property Value
    Type Description
    bool
    | Edit this page View Source

    LastDispatchedNode

    Declaration
    [InterfaceStability(Level.Volatile)]
    public Uri? LastDispatchedNode { get; set; }
    Property Value
    Type Description
    Uri
    | Edit this page 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

    | Edit this page 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.

    | Edit this page View Source

    AsReadOnly()

    Declaration
    public QueryOptions.ReadOnlyRecord AsReadOnly()
    Returns
    Type Description
    QueryOptions.ReadOnlyRecord
    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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 AtPlus.

    | Edit this page View Source

    Create()

    Creates a new QueryOptions object.

    Declaration
    public static QueryOptions Create()
    Returns
    Type Description
    QueryOptions
    | Edit this page 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
    | Edit this page 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
    | Edit this page 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
    | Edit this page 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.

    | Edit this page View Source

    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.

    | Edit this page 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.

    | Edit this page 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
    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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
    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page View Source

    RequestSpan(IRequestSpan)

    Declaration
    public QueryOptions RequestSpan(IRequestSpan span)
    Parameters
    Type Name Description
    IRequestSpan span
    Returns
    Type Description
    QueryOptions
    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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.

    | Edit this page 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
    | Edit this page 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.

    | Edit this page 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
    • Edit this page
    • View Source
    In this article
    Back to top © 2025 Couchbase, Inc.