Package com.datastax.driver.core

Class QueryOptions

  • public class QueryOptions
extends Object
    Options related to defaults for individual queries.

    • Field Detail

      • DEFAULT_FETCH_SIZE

        public static final int DEFAULT_FETCH_SIZE
        The default fetch size for SELECT queries: 5000.
        See Also:
        Constant Field Values

      • DEFAULT_MAX_PENDING_REFRESH_NODE_LIST_REQUESTS

        public static final int DEFAULT_MAX_PENDING_REFRESH_NODE_LIST_REQUESTS
        See Also:
        Constant Field Values

      • DEFAULT_MAX_PENDING_REFRESH_NODE_REQUESTS

        public static final int DEFAULT_MAX_PENDING_REFRESH_NODE_REQUESTS
        See Also:
        Constant Field Values

      • DEFAULT_MAX_PENDING_REFRESH_SCHEMA_REQUESTS

        public static final int DEFAULT_MAX_PENDING_REFRESH_SCHEMA_REQUESTS
        See Also:
        Constant Field Values

      • DEFAULT_REFRESH_NODE_LIST_INTERVAL_MILLIS

        public static final int DEFAULT_REFRESH_NODE_LIST_INTERVAL_MILLIS
        See Also:
        Constant Field Values

      • DEFAULT_REFRESH_NODE_INTERVAL_MILLIS

        public static final int DEFAULT_REFRESH_NODE_INTERVAL_MILLIS
        See Also:
        Constant Field Values

      • DEFAULT_REFRESH_SCHEMA_INTERVAL_MILLIS

        public static final int DEFAULT_REFRESH_SCHEMA_INTERVAL_MILLIS
        See Also:
        Constant Field Values

    • Method Detail

      • setConsistencyLevel

        public QueryOptions setConsistencyLevel​(ConsistencyLevel consistencyLevel)
        Sets the default consistency level to use for queries.

        The consistency level set through this method will be use for queries that don't explicitly have a consistency level, i.e. when Statement.getConsistencyLevel() returns null.

        Parameters:
        consistencyLevel - the new consistency level to set as default. It must not be null: every query needs a consistency level, so a null default would fail any statement that does not set one of its own.
        Returns:
        this QueryOptions instance.
        Throws:
        NullPointerException - if consistencyLevel is null.

      • getConsistencyLevel

        public ConsistencyLevel getConsistencyLevel()
        The default consistency level used by queries.
        Returns:
        the default consistency level used by queries.

      • setSerialConsistencyLevel

        public QueryOptions setSerialConsistencyLevel​(ConsistencyLevel serialConsistencyLevel)
        Sets the default serial consistency level to use for queries.

        The serial consistency level set through this method will be use for queries that don't explicitly have a serial consistency level, i.e. when Statement.getSerialConsistencyLevel() returns null.

        Parameters:
        serialConsistencyLevel - the new serial consistency level to set as default.
        Returns:
        this QueryOptions instance.

      • getSerialConsistencyLevel

        public ConsistencyLevel getSerialConsistencyLevel()
        The default serial consistency level used by queries.
        Returns:
        the default serial consistency level used by queries.

      • getFetchSize

        public int getFetchSize()
        The default fetch size used by queries.
        Returns:
        the default fetch size used by queries.

      • setDefaultIdempotence

        public QueryOptions setDefaultIdempotence​(boolean defaultIdempotence)
        Sets the default idempotence for queries.

        This will be used for statements for which Statement.isIdempotent() returns null.

        Parameters:
        defaultIdempotence - the new value to set as default idempotence.
        Returns:
        this QueryOptions instance.

      • getDefaultIdempotence

        public boolean getDefaultIdempotence()
        The default idempotence for queries.

        It defaults to DEFAULT_IDEMPOTENCE.

        Returns:
        the default idempotence for queries.

      • setSkipCQL4MetadataResolveMethod

        public QueryOptions setSkipCQL4MetadataResolveMethod​(QueryOptions.CQL4SkipMetadataResolveMethod method)
        There is known problem in CQL 4.x when prepared statement invalidation could be voided: more info When it happens metadata on client side does not match data and deserialization can go wrong in many ways To avoid driver can disable skip metadata flag to make server respond with metadata on every query. Unfortunately it causes excessive network traffic and CPU overhead on both server and driver side. This option controls how driver resolves skip metadata flag for CQL4 prepared statements. **SMART** - disable flag only for wildcard selects (select * from) and selects that return UDTs, including collections of UDTs and maps that contain UDTs **ENABLED** - flag is always set **DISABLED** - flag is always disabled Default is SMART Required: yes Modifiable at runtime: yes, the new value will be used for requests issued after the change. Overridable in a profile: yes
        Parameters:
        method - the new value to set as skip metadata resolve method.
        Returns:
        this QueryOptions instance.

      • setPrepareOnAllHosts

        public QueryOptions setPrepareOnAllHosts​(boolean prepareOnAllHosts)
        Set whether the driver should prepare statements on all hosts in the cluster.

        A statement is normally prepared in two steps:

        1. prepare the query on a single host in the cluster;
        2. if that succeeds, prepare on all other hosts.
        This option controls whether step 2 is executed. It is enabled by default.

        The reason why you might want to disable it is to optimize network usage if you have a large number of clients preparing the same set of statements at startup. If your load balancing policy distributes queries randomly, each client will pick a different host to prepare its statements, and on the whole each host has a good chance of having been hit by at least one client for each statement.

        On the other hand, if that assumption turns out to be wrong and one host hasn't prepared a given statement, it needs to be re-prepared on the fly the first time it gets executed; this causes a performance penalty (one extra roundtrip to resend the query to prepare, and another to retry the execution).

        Parameters:
        prepareOnAllHosts - the new value to set to indicate whether to prepare statements once or on all nodes.
        Returns:
        this QueryOptions instance.

      • isPrepareOnAllHosts

        public boolean isPrepareOnAllHosts()
        Returns whether the driver should prepare statements on all hosts in the cluster.
        Returns:
        the value.
        See Also:
        setPrepareOnAllHosts(boolean)

      • setReprepareOnUp

        public QueryOptions setReprepareOnUp​(boolean reprepareOnUp)
        Set whether the driver should re-prepare all cached prepared statements on a host when it marks it back up.

        This option is enabled by default.

        The reason why you might want to disable it is to optimize reconnection time when you believe hosts often get marked down because of temporary network issues, rather than the host really crashing. In that case, the host still has prepared statements in its cache when the driver reconnects, so re-preparing is redundant.

        On the other hand, if that assumption turns out to be wrong and the host had really restarted, its prepared statement cache is empty, and statements need to be re-prepared on the fly the first time they get executed; this causes a performance penalty (one extra roundtrip to resend the query to prepare, and another to retry the execution).

        Parameters:
        reprepareOnUp - whether the driver should re-prepare when marking a node up.
        Returns:
        this QueryOptions instance.

      • isReprepareOnUp

        public boolean isReprepareOnUp()
        Whether the driver should re-prepare all cached prepared statements on a host when its marks that host back up.
        Returns:
        the value.
        See Also:
        setReprepareOnUp(boolean)

      • setMetadataEnabled

        public QueryOptions setMetadataEnabled​(boolean enabled)
        Toggle client-side token and schema metadata.

        This feature is enabled by default. Some applications might wish to disable it in order to eliminate the overhead of querying the metadata and building its client-side representation. However, take note that doing so will have important consequences:

        • most schema- or token-related methods in Metadata will return stale or null/empty results (see the javadoc of each method for details);
        • Metadata.newToken(String) and Metadata.newTokenRange(Token, Token) will throw an exception if metadata was disabled before startup;
        • token-aware routing will not work properly: if metadata was never initialized, TokenAwarePolicy will always delegate to its child policy. Otherwise, it might not pick the best coordinator (i.e. chose a host that is not a replica for the statement's routing key). In addition, statements prepared while the metadata was disabled might also be sent to a non-optimal coordinator, even if metadata was re-enabled later.
        Parameters:
        enabled - whether metadata is enabled.
        Returns:
        this QueryOptions instance.

      • isMetadataEnabled

        public boolean isMetadataEnabled()
        Whether client-side token and schema metadata is enabled.
        Returns:
        the value.
        See Also:
        setMetadataEnabled(boolean)

      • setSchemaQueriesPaged

        public QueryOptions setSchemaQueriesPaged​(boolean enabled)
        Toggle schema queries paging.
        Parameters:
        enabled - whether paging is enabled in schema queries.
        Returns:
        this QueryOptions instance.

      • isSchemaQueriesPaged

        public boolean isSchemaQueriesPaged()
        Whether schema queries are using paging.
        Returns:
        the value.

      • setRefreshSchemaIntervalMillis

        public QueryOptions setRefreshSchemaIntervalMillis​(int refreshSchemaIntervalMillis)
        Sets the default window size in milliseconds used to debounce node list refresh requests.

        When the control connection receives a new schema refresh request, it puts it on hold and starts a timer, cancelling any previous running timer; when a timer expires, then the pending requests are coalesced and executed as a single request.

        Parameters:
        refreshSchemaIntervalMillis - The default window size in milliseconds used to debounce schema refresh requests.

      • getRefreshSchemaIntervalMillis

        public int getRefreshSchemaIntervalMillis()
        The default window size in milliseconds used to debounce schema refresh requests.
        Returns:
        The default window size in milliseconds used to debounce schema refresh requests.

      • setMaxPendingRefreshSchemaRequests

        public QueryOptions setMaxPendingRefreshSchemaRequests​(int maxPendingRefreshSchemaRequests)
        Sets the maximum number of schema refresh requests that the control connection can accumulate before executing them.

        When the control connection receives a new schema refresh request, it puts it on hold and starts a timer, cancelling any previous running timer; if the control connection receives too many events, is parameter allows to trigger execution of pending requests, event if the last timer is still running.

        Parameters:
        maxPendingRefreshSchemaRequests - The maximum number of schema refresh requests that the control connection can accumulate before executing them.

      • getMaxPendingRefreshSchemaRequests

        public int getMaxPendingRefreshSchemaRequests()
        The maximum number of schema refresh requests that the control connection can accumulate before executing them.
        Returns:
        The maximum number of schema refresh requests that the control connection can accumulate before executing them.

      • setRefreshNodeListIntervalMillis

        public QueryOptions setRefreshNodeListIntervalMillis​(int refreshNodeListIntervalMillis)
        Sets the default window size in milliseconds used to debounce node list refresh requests.

        When the control connection receives a new node list refresh request, it puts it on hold and starts a timer, cancelling any previous running timer; when a timer expires, then the pending requests are coalesced and executed as a single request.

        Parameters:
        refreshNodeListIntervalMillis - The default window size in milliseconds used to debounce node list refresh requests.

      • getRefreshNodeListIntervalMillis

        public int getRefreshNodeListIntervalMillis()
        The default window size in milliseconds used to debounce node list refresh requests.
        Returns:
        The default window size in milliseconds used to debounce node list refresh requests.

      • setMaxPendingRefreshNodeListRequests

        public QueryOptions setMaxPendingRefreshNodeListRequests​(int maxPendingRefreshNodeListRequests)
        Sets the maximum number of node list refresh requests that the control connection can accumulate before executing them.

        When the control connection receives a new node list refresh request, it puts it on hold and starts a timer, cancelling any previous running timer; if the control connection receives too many events, is parameter allows to trigger execution of pending requests, event if the last timer is still running.

        Parameters:
        maxPendingRefreshNodeListRequests - The maximum number of node list refresh requests that the control connection can accumulate before executing them.

      • getMaxPendingRefreshNodeListRequests

        public int getMaxPendingRefreshNodeListRequests()
        Sets the maximum number of node list refresh requests that the control connection can accumulate before executing them.
        Returns:
        The maximum number of node list refresh requests that the control connection can accumulate before executing them.

      • setRefreshNodeIntervalMillis

        public QueryOptions setRefreshNodeIntervalMillis​(int refreshNodeIntervalMillis)
        Sets the default window size in milliseconds used to debounce node refresh requests.

        When the control connection receives a new node refresh request, it puts it on hold and starts a timer, cancelling any previous running timer; when a timer expires, then the pending requests are coalesced and executed as a single request.

        Parameters:
        refreshNodeIntervalMillis - The default window size in milliseconds used to debounce node refresh requests.

      • getRefreshNodeIntervalMillis

        public int getRefreshNodeIntervalMillis()
        The default window size in milliseconds used to debounce node refresh requests.
        Returns:
        The default window size in milliseconds used to debounce node refresh requests.

      • setMaxPendingRefreshNodeRequests

        public QueryOptions setMaxPendingRefreshNodeRequests​(int maxPendingRefreshNodeRequests)
        Sets the maximum number of node refresh requests that the control connection can accumulate before executing them.

        When the control connection receives a new node refresh request, it puts it on hold and starts a timer, cancelling any previous running timer; if the control connection receives too many events, is parameter allows to trigger execution of pending requests, event if the last timer is still running.

        Parameters:
        maxPendingRefreshNodeRequests - The maximum number of node refresh requests that the control connection can accumulate before executing them.

      • getMaxPendingRefreshNodeRequests

        public int getMaxPendingRefreshNodeRequests()
        The maximum number of node refresh requests that the control connection can accumulate before executing them.
        Returns:
        The maximum number of node refresh requests that the control connection can accumulate before executing them.

      • setAddOriginalContactsToReconnectionPlan

        public QueryOptions setAddOriginalContactsToReconnectionPlan​(boolean enabled)
        Whether the driver should use original contact points when reconnecting to a control node. In practice this forces driver to manually add original contact points to the end of the query plan. It is possible that it may introduce duplicates (but under differnet Host class instances) in the query plan. If this is set to false it does not mean that original contact points will be excluded.

        One use case of this feature is that if the original contact point is defined by hostname and its IP address changes then setting this to true allows trying reconnecting to the new IP if all connection was lost.

      • shouldAddOriginalContactsToReconnectionPlan

        public boolean shouldAddOriginalContactsToReconnectionPlan()

      • setConsiderZeroTokenNodesValidPeers

        public QueryOptions setConsiderZeroTokenNodesValidPeers​(boolean enabled)
        Recently introduced in Scylla zero-token nodes have null value in "tokens" column in their system.peers rows. By default extended peer check considers such rows as invalid. Enabling this option will exclude this field from the check, and allow such rows from system.peers queries to be used when refreshing metadata.

      • shouldConsiderZeroTokenNodesValidPeers

        public boolean shouldConsiderZeroTokenNodesValidPeers()

      • getLoadBalancingLwtRequestRoutingMethod

        public QueryOptions.RequestRoutingMethod getLoadBalancingLwtRequestRoutingMethod()
        The default request routing method used by LWT queries.
        Returns:
        the default request routing method used by LWT queries.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • isConsistencySet

        public boolean isConsistencySet()