N1qlParams (Couchbase Java SDK)

java.lang.Object
- com.couchbase.client.java.query.N1qlParams

All Implemented Interfaces:

Serializable
```
@InterfaceStability.Committed
 @InterfaceAudience.Public
public class N1qlParams
extends Object
implements Serializable
```
Parameter Object for queries that allows to fluently set most of the N1QL query parameters: - server side timeout - client context ID - scan consistency (with associated scan vector and/or scan wait if relevant) - max parallelism
Note that these are different from statement-related named parameters or positional parameters.

Since:

2.1

Author:

Simon Baslé

See Also:

Serialized Form

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`N1qlParams`	`adhoc(boolean adhoc)` Allows to specify if this query is adhoc or not.
`static N1qlParams`	`build()` Start building a `N1qlParams`, allowing to customize an N1QL request.
`String`	`clientContextId()` Helper method to check if a client context ID is set.
`N1qlParams`	`consistency(ScanConsistency consistency)` Sets scan consistency.
`N1qlParams`	`consistentWith(Document... documents)` Sets the `Document`s resulting of a mutation this query should be consistent with.
`N1qlParams`	`consistentWith(DocumentFragment... fragments)` Sets the `DocumentFragment`s resulting of a mutation this query should be consistent with.
`N1qlParams`	`consistentWith(MutationState mutationState)` Sets the `MutationState` this query should be consistent with.
`N1qlParams`	`disableMetrics(boolean disableMetrics)` If set to true (false being the default), the metrics object will not be returned from N1QL and as a result be more efficient.
`static String`	`durationToN1qlFormat(long duration, TimeUnit unit)` Helper method to convert a duration into the n1ql (golang) format.
`boolean`	`equals(Object o)`
`int`	`hashCode()`
`boolean`	`hasServerSideTimeout()` Helper method to check if a custom server side timeout has been applied on the params.
`void`	`injectParams(JsonObject queryJson)` Modifies the given N1QL query (as a `JsonObject`) to reflect these `N1qlParams`.
`boolean`	`isAdhoc()` True if this query is adhoc, false otherwise.
`N1qlParams`	`maxParallelism(int maxParallelism)` Allows to override the default maximum parallelism for the query execution on the server side.
`N1qlParams`	`pipelineBatch(int pipelineBatch)` Advanced: Controls the number of items execution operators can batch for Fetch from the KV.
`N1qlParams`	`pipelineCap(int pipelineCap)` Advanced: Maximum number of items each execution operator can buffer between various operators.
`N1qlParams`	`pretty(boolean pretty)` If set to false, the server will be instructed to remove extra whitespace from the JSON response in order to save bytes.
`N1qlParams`	`profile(N1qlProfile profile)` Specifies if there should be a profile section returned with the request results.
`N1qlParams`	`rawParam(String name, Object value)` Allows to specify an arbitrary, raw N1QL param.
`N1qlParams`	`readonly(boolean readonly)` If set to true, it will signal the query engine on the server that only non-data modifying requests are allowed.
`N1qlParams`	`scanCap(int scanCap)` Advanced: Maximum buffered channel size between the indexer client and the query service for index scans.
`N1qlParams`	`scanWait(long wait, TimeUnit unit)` If the `NOT_BOUNDED scan consistency` has been chosen, does nothing.
`N1qlParams`	`serverSideTimeout(long timeout, TimeUnit unit)` Sets a maximum timeout for processing on the server side.
`String`	`toString()`
`N1qlParams`	`withContextId(String clientContextId)` Adds a client context ID to the request, that will be sent back in the response, allowing clients to meaningfully trace requests/responses when many are exchanged.
`N1qlParams`	`withCredentials(List<Credential> credentials)` Allows to add a list of credentials (in the form of `Credential` objects) to this request.
`N1qlParams`	`withCredentials(String login, String password)` Allows to add a credential username/password pair to this request.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - injectParams
```
public void injectParams(JsonObject queryJson)
```
    Modifies the given N1QL query (as a JsonObject) to reflect these N1qlParams.
    
    Parameters:
    
    queryJson - the N1QL query
  - durationToN1qlFormat
```
public static String durationToN1qlFormat(long duration,
                                          TimeUnit unit)
```
    Helper method to convert a duration into the n1ql (golang) format.
    
    Returns:
  - build
```
public static N1qlParams build()
```
    Start building a N1qlParams, allowing to customize an N1QL request.
    
    Returns:
    
    a new N1qlParams
  - serverSideTimeout
```
public N1qlParams serverSideTimeout(long timeout,
                                    TimeUnit unit)
```
    Sets a maximum timeout for processing on the server side.
    
    Parameters:
    
    timeout - the duration of the timeout.
    
    unit - the unit of the timeout, from nanoseconds to hours.
    
    Returns:
    
    this N1qlParams for chaining.
  - withContextId
```
public N1qlParams withContextId(String clientContextId)
```
    Adds a client context ID to the request, that will be sent back in the response, allowing clients to meaningfully trace requests/responses when many are exchanged.
    
    Parameters:
    
    clientContextId - the client context ID (null to send none)
    
    Returns:
    
    this N1qlParams for chaining.
  - disableMetrics
```
public N1qlParams disableMetrics(boolean disableMetrics)
```
    If set to true (false being the default), the metrics object will not be returned from N1QL and as a result be more efficient. Note that if metrics are disabled you are loosing information to diagnose problems - so use with care!
    
    Parameters:
    
    disableMetrics - true if disabled, false otherwise (false = default).
    
    Returns:
    
    this N1qlParams for chaining.
  - consistency
```
public N1qlParams consistency(ScanConsistency consistency)
```
    Sets scan consistency.
    Note that NOT_BOUNDED will unset the scanWait if it was set.
    
    Returns:
    
    this N1qlParams for chaining.
  - consistentWith
```
@InterfaceStability.Committed
public N1qlParams consistentWith(Document... documents)
```
    Sets the Documents resulting of a mutation this query should be consistent with.
    
    Parameters:
    
    documents - the documents returned from a mutation.
    
    Returns:
    
    this N1qlParams for chaining.
  - consistentWith
```
@InterfaceStability.Committed
public N1qlParams consistentWith(DocumentFragment... fragments)
```
    Sets the DocumentFragments resulting of a mutation this query should be consistent with.
    
    Parameters:
    
    fragments - the fragments returned from a mutation.
    
    Returns:
    
    this N1qlParams for chaining.
  - consistentWith
```
@InterfaceStability.Committed
public N1qlParams consistentWith(MutationState mutationState)
```
    Sets the MutationState this query should be consistent with.
    
    Parameters:
    
    mutationState - the mutation state which accumulates tokens from one or more mutation results.
    
    Returns:
    
    this N1qlParams for chaining.
  - scanWait
```
public N1qlParams scanWait(long wait,
                           TimeUnit unit)
```
    If the NOT_BOUNDED scan consistency has been chosen, does nothing.
    Otherwise, sets the maximum time the client is willing to wait for an index to catch up to the vector timestamp in the request.
    
    Parameters:
    
    wait - the duration.
    
    unit - the unit for the duration.
    
    Returns:
    
    this N1qlParams for chaining.
  - maxParallelism
```
public N1qlParams maxParallelism(int maxParallelism)
```
    Allows to override the default maximum parallelism for the query execution on the server side.
    
    Parameters:
    
    maxParallelism - the maximum parallelism for this query, 0 or negative values disable it.
    
    Returns:
    
    this N1qlParams for chaining.
  - adhoc
```
public N1qlParams adhoc(boolean adhoc)
```
    Allows to specify if this query is adhoc or not.
    If it is not adhoc (so performed often), 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.
    
    Parameters:
    
    adhoc - if the query is adhoc, default is true (plain execution).
    
    Returns:
    
    this N1qlParams for chaining.
  - withCredentials
```
public N1qlParams withCredentials(List<Credential> credentials)
```
    Allows to add a list of credentials (in the form of Credential objects) to this request. Credentials for usernames that were previously set by a similar call are replaced.
    
    Parameters:
    
    credentials - the list of credentials to add to the request.
    
    Returns:
    
    this N1qlParams for chaining.
  - withCredentials
```
public N1qlParams withCredentials(String login,
                                  String password)
```
    Allows to add a credential username/password pair to this request. If a credential for that username was previously set by a similar call, it is replaced.
    
    Parameters:
    
    login - the username/bucketname to add a credential for.
    
    password - the associated password.
    
    Returns:
    
    this N1qlParams for chaining.
  - pretty
```
public N1qlParams pretty(boolean pretty)
```
    If set to false, the server will be instructed to remove extra whitespace from the JSON response in order to save bytes. In performance-critical environments as well as large responses this is recommended in order to cut down on network traffic.
    Note that this option is only supported in Couchbase Server 4.5.1 or later.
    
    Parameters:
    
    pretty - if set to false, pretty responses are disabled.
    
    Returns:
    
    this N1qlParams for chaining.
  - readonly
```
public N1qlParams readonly(boolean readonly)
```
    If set to true, it will signal the query engine on the server that only non-data modifying requests are allowed. Note that this rule is enforced on the server and not the SDK side.
    Controls whether a query can change a resulting record set.
    If readonly is true, then the following statements are not allowed: - CREATE INDEX - DROP INDEX - INSERT - MERGE - UPDATE - UPSERT - DELETE
    
    Parameters:
    
    readonly - true if readonly should be forced, false is the default and will use the server side default.
    
    Returns:
    
    this N1qlParams for chaining.
  - scanCap
```
public N1qlParams scanCap(int scanCap)
```
    Advanced: 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.
    
    Parameters:
    
    scanCap - the scan_cap param, use 0 or negative number to disable.
    
    Returns:
    
    this N1qlParams for chaining.
  - pipelineBatch
```
public N1qlParams pipelineBatch(int pipelineBatch)
```
    Advanced: Controls the number of items execution operators can batch for Fetch from the KV.
    
    Parameters:
    
    pipelineBatch - the pipeline_batch param.
    
    Returns:
    
    this N1qlParams for chaining.
  - pipelineCap
```
public N1qlParams pipelineCap(int pipelineCap)
```
    Advanced: Maximum number of items each execution operator can buffer between various operators.
    
    Parameters:
    
    pipelineCap - the pipeline_cap param.
    
    Returns:
    
    this N1qlParams for chaining.
  - profile
```
@InterfaceStability.Uncommitted
public N1qlParams profile(N1qlProfile profile)
```
    Specifies if there should be a profile section returned with the request results.
    
    Parameters:
    
    profile - the profile param N1qlProfile.
    
    Returns:
    
    this N1qlParams for chaining.
    
    See Also:
    
    Monitoring N1QL Queries
  - rawParam
```
@InterfaceStability.Uncommitted
public N1qlParams rawParam(String name,
                                                           Object value)
```
    Allows to specify an arbitrary, raw N1QL param.
    Use with care and only provide options that are supported by the server and are not exposed as part of the overall stable API in the N1qlParams class.
    
    Parameters:
    
    name - the name of the property.
    
    value - the value of the property, only JSON value types are supported.
    
    Returns:
    
    this N1qlParams for chaining.
  - hasServerSideTimeout
```
public boolean hasServerSideTimeout()
```
    Helper method to check if a custom server side timeout has been applied on the params.
    
    Returns:
    
    true if it has, false otherwise.
  - clientContextId
```
public String clientContextId()
```
    Helper method to check if a client context ID is set.
  - isAdhoc
```
public boolean isAdhoc()
```
    True if this query is adhoc, false otherwise.
    
    Returns:
    
    true if adhoc false otherwise.
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class N1qlParams

Method Summary

Methods inherited from class java.lang.Object

Method Detail

injectParams

durationToN1qlFormat

build

serverSideTimeout

withContextId

disableMetrics

consistency

consistentWith

consistentWith

consistentWith

scanWait

maxParallelism

adhoc

withCredentials

withCredentials

pretty

readonly

scanCap

pipelineBatch

pipelineCap

profile

rawParam

hasServerSideTimeout

clientContextId

isAdhoc

equals

hashCode

toString