Package com.datastax.oss.driver.api.core.cql

Interface Statement<SelfT extends Statement<SelfT>>

    • Method Detail

      • setExecutionProfileName

        @NonNull
@CheckReturnValue
SelfT setExecutionProfileName​(@Nullable
                              String newConfigProfileName)
        Sets the name of the execution profile that will be used for this statement.

        For all the driver's built-in implementations, calling this method with a non-null argument automatically resets Request.getExecutionProfile() to null.

        All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

      • setExecutionProfile

        @NonNull
@CheckReturnValue
SelfT setExecutionProfile​(@Nullable
                          DriverExecutionProfile newProfile)
        Sets the execution profile to use for this statement.

        For all the driver's built-in implementations, calling this method with a non-null argument automatically resets Request.getExecutionProfileName() to null.

        All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

      • setRoutingKeyspace

        @NonNull
@CheckReturnValue
SelfT setRoutingKeyspace​(@Nullable
                         CqlIdentifier newRoutingKeyspace)
        Sets the keyspace to use for token-aware routing.

        See Request.getRoutingKey() for a description of the token-aware routing algorithm.

        Parameters:
        newRoutingKeyspace - The keyspace to use, or null to disable token-aware routing.

      • setNode

        @NonNull
@CheckReturnValue
SelfT setNode​(@Nullable
              Node node)
        Sets the Node that should handle this query.

        In the general case, use of this method is heavily discouraged and should only be used in the following cases:

        1. Querying node-local tables, such as tables in the system and system_views keyspaces.
        2. Applying a series of schema changes, where it may be advantageous to execute schema changes in sequence on the same node.

        Configuring a specific node causes the configured LoadBalancingPolicy to be completely bypassed. However, if the load balancing policy dictates that the node is at distance NodeDistance.IGNORED or there is no active connectivity to the node, the request will fail with a NoNodeAvailableException.

        Parameters:
        node - The node that should be used to handle executions of this statement or null to delegate to the configured load balancing policy.

      • setRoutingKey

        @NonNull
@CheckReturnValue
SelfT setRoutingKey​(@Nullable
                    ByteBuffer newRoutingKey)
        Sets the key to use for token-aware routing.

        See Request.getRoutingKey() for a description of the token-aware routing algorithm.

        Parameters:
        newRoutingKey - The routing key to use, or null to disable token-aware routing.

      • setRoutingKey

        @NonNull
@CheckReturnValue
default SelfT setRoutingKey​(@NonNull
                            ByteBuffer... newRoutingKeyComponents)
        Sets the key to use for token-aware routing, when the partition key has multiple components.

        This method assembles the components into a single byte buffer and passes it to setRoutingKey(ByteBuffer). Neither the individual components, nor the vararg array itself, can be null.

      • setRoutingToken

        @NonNull
@CheckReturnValue
SelfT setRoutingToken​(@Nullable
                      Token newRoutingToken)
        Sets the token to use for token-aware routing.

        See Request.getRoutingKey() for a description of the token-aware routing algorithm.

        Parameters:
        newRoutingToken - The routing token to use, or null to disable token-aware routing.

      • setCustomPayload

        @NonNull
@CheckReturnValue
SelfT setCustomPayload​(@NonNull
                       Map<String,​ByteBuffer> newCustomPayload)
        Sets the custom payload to use for execution.

        All the driver's built-in statement implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

        Note that it's your responsibility to provide a thread-safe map. This can be achieved with a concurrent or immutable implementation, or by making it effectively immutable (meaning that it's never modified after being set on the statement).

      • setIdempotent

        @NonNull
@CheckReturnValue
SelfT setIdempotent​(@Nullable
                    Boolean newIdempotence)
        Sets the idempotence to use for execution.

        All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

        Parameters:
        newIdempotence - a boolean instance to set a statement-specific value, or null to use the default idempotence defined in the configuration.

      • setTracing

        @NonNull
@CheckReturnValue
SelfT setTracing​(boolean newTracing)
        Sets tracing for execution.

        All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

      • enableTracing

        @Deprecated
@NonNull
@CheckReturnValue
default SelfT enableTracing()
        Deprecated.
        this method only exists to ease the transition from driver 3, it is an alias for setTracing(true).

      • disableTracing

        @Deprecated
@NonNull
@CheckReturnValue
default SelfT disableTracing()
        Deprecated.
        this method only exists to ease the transition from driver 3, it is an alias for setTracing(false).

      • getDefaultTimestamp

        @Deprecated
default long getDefaultTimestamp()
        Deprecated.
        this method only exists to ease the transition from driver 3, it is an alias for getQueryTimestamp().

      • setQueryTimestamp

        @NonNull
@CheckReturnValue
SelfT setQueryTimestamp​(long newTimestamp)
        Sets the query timestamp, in microseconds, to send with the statement.

        This is an alternative to appending a USING TIMESTAMP clause in the statement's query string, and has the advantage of sending the timestamp separately from the query string itself, which doesn't have to be modified when executing the same statement with different timestamps. Note that, if both a USING TIMESTAMP clause and a query timestamp are set for a given statement, the timestamp from the USING TIMESTAMP clause wins.

        This method can be used on any instance of SimpleStatement, BoundStatement or BatchStatement. For a BatchStatement, the timestamp will apply to all its child statements; it is not possible to define per-child timestamps using this method, and consequently, if this method is called on a batch child statement, the provided timestamp will be silently ignored. If different timestamps are required for individual child statements, this can only be achieved with a custom USING TIMESTAMP clause in each child query.

        If this is equal to NO_DEFAULT_TIMESTAMP, the TimestampGenerator configured for this driver instance will be used to generate a timestamp.

        All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

        See Also:
        NO_DEFAULT_TIMESTAMP, TimestampGenerator

      • setDefaultTimestamp

        @Deprecated
@NonNull
@CheckReturnValue
default SelfT setDefaultTimestamp​(long newTimestamp)
        Deprecated.
        this method only exists to ease the transition from driver 3, it is an alias for setQueryTimestamp(long).

      • setTimeout

        @NonNull
@CheckReturnValue
SelfT setTimeout​(@Nullable
                 Duration newTimeout)
        Sets how long to wait for this request to complete. This is a global limit on the duration of a session.execute() call, including any retries the driver might do.
        Parameters:
        newTimeout - the timeout to use, or null to use the default value defined in the configuration.
        See Also:
        DefaultDriverOption.REQUEST_TIMEOUT

      • getPagingState

        @Nullable
ByteBuffer getPagingState()
        Returns the paging state to send with the statement, or null if this statement has no paging state.

        Paging states are used in scenarios where a paged result is interrupted then resumed later. The paging state can only be reused with the exact same statement (same query string, same parameters). It is an opaque value that is only meant to be collected, stored and re-used. If you try to modify its contents or reuse it with a different statement, the results are unpredictable.

      • setPagingState

        @NonNull
@CheckReturnValue
SelfT setPagingState​(@Nullable
                     ByteBuffer newPagingState)
        Sets the paging state to send with the statement, or null if this statement has no paging state.

        Paging states are used in scenarios where a paged result is interrupted then resumed later. The paging state can only be reused with the exact same statement (same query string, same parameters). It is an opaque value that is only meant to be collected, stored and re-used. If you try to modify its contents or reuse it with a different statement, the results are unpredictable.

        All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance; if you do so, you must override copy(ByteBuffer).

      • setPagingState

        @NonNull
@CheckReturnValue
default SelfT setPagingState​(@Nullable
                             PagingState newPagingState)
        Sets the paging state to send with the statement, or null if this statement has no paging state.

        This variant uses the "safe" paging state wrapper, it will throw immediately if the statement doesn't match the one that the state was initially extracted from (same query string, same parameters). The advantage is that it fails fast, instead of waiting for an error response from the server.

        Note that, if this statement is a SimpleStatement with bound values, those values must be encoded in order to perform the check. This method uses the default codec registry and default protocol version. This might fail if you use custom codecs; in that case, use setPagingState(PagingState, Session) instead.

        Throws:
        IllegalArgumentException - if the given state does not match this statement.
        See Also:
        setPagingState(ByteBuffer), ExecutionInfo.getSafePagingState()

      • setPagingState

        @NonNull
@CheckReturnValue
default SelfT setPagingState​(@Nullable
                             PagingState newPagingState,
                             @Nullable
                             Session session)
        Alternative to setPagingState(PagingState) that specifies the session the statement will be executed with. You only need this for simple statements, and if you use custom codecs. Bound statements already know which session they are attached to.

      • getPageSize

        int getPageSize()
        Returns the page size to use for the statement.
        Returns:
        the set page size, otherwise 0 or a negative value to use the default value defined in the configuration.
        See Also:
        DefaultDriverOption.REQUEST_PAGE_SIZE

      • getFetchSize

        @Deprecated
default int getFetchSize()
        Deprecated.
        this method only exists to ease the transition from driver 3, it is an alias for getPageSize().

      • setPageSize

        @NonNull
@CheckReturnValue
SelfT setPageSize​(int newPageSize)
        Configures how many rows will be retrieved simultaneously in a single network roundtrip (the goal being to avoid loading too many results in memory at the same time).
        Parameters:
        newPageSize - the page size to use, set to 0 or a negative value to use the default value defined in the configuration.
        See Also:
        DefaultDriverOption.REQUEST_PAGE_SIZE

      • setFetchSize

        @Deprecated
@NonNull
@CheckReturnValue
default SelfT setFetchSize​(int newPageSize)
        Deprecated.
        this method only exists to ease the transition from driver 3, it is an alias for setPageSize(int).

      • isTracing

        boolean isTracing()
        Whether tracing information should be recorded for this statement.

      • getNowInSeconds

        default int getNowInSeconds()
        A custom "now in seconds" to use when applying the request (for testing purposes).

        This method's default implementation returns NO_NOW_IN_SECONDS. The only reason it exists is to preserve binary compatibility. Internally, the driver overrides it to return the value that was set programmatically (if any).

        See Also:
        NO_NOW_IN_SECONDS

      • setNowInSeconds

        @NonNull
@CheckReturnValue
default SelfT setNowInSeconds​(int nowInSeconds)
        Sets the "now in seconds" to use when applying the request (for testing purposes).

        This method's default implementation returns the statement unchanged. The only reason it exists is to preserve binary compatibility. Internally, the driver overrides it to record the new value.

        See Also:
        NO_NOW_IN_SECONDS

      • setRequestRoutingType

        @NonNull
@CheckReturnValue
default SelfT setRequestRoutingType​(@Nullable
                                    RequestRoutingType requestRoutingType)
        Sets the request routing type to use when applying the request (for testing purposes).

        This method's default implementation returns the statement unchanged. The only reason it exists is to preserve binary compatibility. Internally, the driver overrides it to record the new value.

      • isLWT

        default boolean isLWT()
        Informs if this is a prepared LWT query.

        Not guaranteed to return true for prepared LWT queries (but guaranteed to return false for non-LWT ones). It can happen for several reasons, for example: using Cassandra instead of Scylla, using too old Scylla version, future changes in driver allowing channels to be created without sending OPTIONS request.

        Provided implementations of BatchStatements will be considered by driver as LWT if any of the statements in a batch is LWT on its own.

        More information about LWT:

        See Also:
        Docs about LWT

      • computeSizeInBytes

        int computeSizeInBytes​(@NonNull
                       DriverContext context)
        Calculates the approximate size in bytes that the statement will have when encoded.

        The size might be over-estimated by a few bytes due to global options that may be defined on a Session but not explicitly set on the statement itself.

        The result of this method is not cached, calling it will cause some encoding to be done in order to determine some of the statement's attributes sizes. Therefore, use this method sparingly in order to avoid unnecessary computation.

        Returns:
        the approximate number of bytes this statement will take when encoded.

      • copy

        @NonNull
@CheckReturnValue
default SelfT copy​(@Nullable
                   ByteBuffer newPagingState)
        Creates a new instance with a different paging state.

        Since all the built-in statement implementations in the driver are immutable, this method's default implementation delegates to setPagingState(ByteBuffer). However, if you write your own mutable implementation, make sure it returns a different instance.