Package com.couchbase.client.java.query

Class N1qlParams

  • All Implemented Interfaces:
    Serializable
    @Committed
@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 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.

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

      • consistentWith

        @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

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

      • rawParam

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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object