com.couchbase.client.java.query

Class N1qlParams

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

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.
N1qlParams	consistency(ScanConsistency consistency) Sets scan consistency.
N1qlParams	consistentWith(Document... documents) Sets the Documents resulting of a mutation this query should be consistent with.
N1qlParams	consistentWith(DocumentFragment... fragments) Sets the DocumentFragments 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.
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	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	rawParam(String name, Object value) Allows to specify an arbitrary, raw N1QL param.
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

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.

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.

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