Class SqlStatement


  • public final class SqlStatement
    extends java.lang.Object
    Definition of an SQL statement.

    This object is mutable. Properties are read once before the execution is started. Changes to properties do not affect the behavior of already running statements.

    • Constructor Detail

      • SqlStatement

        public SqlStatement​(@Nonnull
                            java.lang.String sql)
    • Method Detail

      • getSql

        @Nonnull
        public java.lang.String getSql()
        Gets the SQL string to be executed.
        Returns:
        SQL string
      • setSql

        @Nonnull
        public SqlStatement setSql​(@Nonnull
                                   java.lang.String sql)
        Sets the SQL string to be executed.

        The SQL string cannot be null or empty.

        Parameters:
        sql - SQL string
        Returns:
        this instance for chaining
        Throws:
        java.lang.NullPointerException - if passed SQL string is null
        java.lang.IllegalArgumentException - if passed SQL string is empty
      • getSchema

        @Nullable
        public java.lang.String getSchema()
        Gets the schema name.
        Returns:
        the schema name or null if there is none
        Since:
        4.2
      • setSchema

        @Nonnull
        public SqlStatement setSchema​(@Nullable
                                      java.lang.String schema)
        Sets the schema name. The engine will try to resolve the non-qualified object identifiers from the statement in the given schema. If not found, the default search path will be used, which looks for objects in the predefined schemas "partitioned" and "public".

        The schema name is case sensitive. For example, "foo" and "Foo" are different schemas.

        The default value is null meaning only the default search path is used.

        Parameters:
        schema - the current schema name
        Returns:
        this instance for chaining
        Since:
        4.2
      • getParameters

        @Nonnull
        public java.util.List<java.lang.Object> getParameters()
        Gets the statement parameter values.
      • setParameters

        @Nonnull
        public SqlStatement setParameters​(java.util.List<java.lang.Object> parameters)
        Sets the values for statement parameters.

        You may define parameter placeholders in the statement with the "?" character. For every placeholder, a value must be provided.

        When the method is called, the contents of the list are copied. Subsequent changes to the original list don't change the statement parameters.

        Parameters:
        parameters - statement parameters
        Returns:
        this instance for chaining
        See Also:
        addParameter(Object), clearParameters()
      • addParameter

        @Nonnull
        public SqlStatement addParameter​(java.lang.Object value)
        Adds a single parameter value to the end of the parameter values list.
        Parameters:
        value - parameter value
        Returns:
        this instance for chaining
        See Also:
        setParameters(List), clearParameters()
      • getTimeoutMillis

        public long getTimeoutMillis()
        Gets the execution timeout in milliseconds.
        Returns:
        execution timeout in milliseconds
      • setTimeoutMillis

        @Nonnull
        public SqlStatement setTimeoutMillis​(long timeout)
        Sets the execution timeout in milliseconds.

        If the timeout is reached for a running statement, it will be cancelled forcefully.

        Zero value means no timeout. -1L means that the value from SqlConfig.getStatementTimeoutMillis() will be used. Other negative values are prohibited.

        Defaults to -1L.

        Parameters:
        timeout - execution timeout in milliseconds, 0 for no timeout, -1 to user member's default timeout
        Returns:
        this instance for chaining
        See Also:
        SqlConfig.getStatementTimeoutMillis()
      • getCursorBufferSize

        public int getCursorBufferSize()
        Gets the cursor buffer size (measured in the number of rows).
        Returns:
        cursor buffer size (measured in the number of rows)
      • setCursorBufferSize

        @Nonnull
        public SqlStatement setCursorBufferSize​(int cursorBufferSize)
        Sets the cursor buffer size (measured in the number of rows).

        When a statement is submitted for execution, a SqlResult is returned as a result. When rows are ready to be consumed, they are put into an internal buffer of the cursor. This parameter defines the maximum number of rows in that buffer. When the threshold is reached, the backpressure mechanism will slow down the execution, possibly to a complete halt, to prevent out-of-memory.

        Only positive values are allowed.

        The default value is expected to work well for most workloads. A bigger buffer size may give you a slight performance boost for queries with large result sets at the cost of increased memory consumption.

        Defaults to 4096.

        Parameters:
        cursorBufferSize - cursor buffer size (measured in the number of rows)
        Returns:
        this instance for chaining
        See Also:
        SqlService.execute(SqlStatement), SqlResult
      • getExpectedResultType

        @Nonnull
        public SqlExpectedResultType getExpectedResultType()
        Gets the expected result type.
        Returns:
        expected result type
        Since:
        4.2
      • setExpectedResultType

        @Nonnull
        public SqlStatement setExpectedResultType​(@Nonnull
                                                  SqlExpectedResultType expectedResultType)
        Sets the expected result type.
        Parameters:
        expectedResultType - expected result type
        Returns:
        this instance for chaining
        Since:
        4.2
      • getPartitionArgumentIndex

        @PrivateApi
        public int getPartitionArgumentIndex()
        Get the partition argument index value
        Returns:
        partitionArgumentIndex, -1 if not set.
      • setPartitionArgumentIndex

        @PrivateApi
        public void setPartitionArgumentIndex​(int partitionArgumentIndex)
        Set the partition argument index. If there's no such argument, use -1.

        Setting a wrong argument index will not cause incorrect query results, but might cause performance degradation due to more network communication. Setting a value higher than the actual number of arguments will have no effect.

        Parameters:
        partitionArgumentIndex - index of the partition-determining argument of the statement
      • copy

        @Nonnull
        public SqlStatement copy()
        Creates a copy of this instance
        Returns:
        Copy of this instance
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object