Class N1qlParams

java.lang.Object
com.couchbase.client.java.query.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 Details

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

      @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​(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

      @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

      @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

      @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