Added in API level 35

Summary: Constants | Methods | Inherited Methods

SQLiteRawStatement

Kotlin |Java

public final class SQLiteRawStatement
extends Object implements Closeable

java.lang.Object
↳	android.database.sqlite.SQLiteRawStatement

A SQLiteRawStatement represents a SQLite prepared statement. The methods correspond very closely to SQLite APIs that operate on a sqlite_stmt object. In general, each API in this class corresponds to a single SQLite API.

A SQLiteRawStatement must be created through a database, and there must be a transaction open at the time. Statements are implicitly closed when the outermost transaction ends, or if the current transaction is marked successful. Statements may be explicitly closed at any time with close(). The close() operation is idempotent and may be called multiple times without harm.

Multiple SQLiteRawStatements may be open simultaneously. They are independent of each other. Closing one statement does not affect any other statement nor does it have any effect on the enclosing transaction.

Once a SQLiteRawStatement has been closed, no further database operations are permitted on that statement. An IllegalStateException will be thrown if a database operation is attempted on a closed statement.

All operations on a SQLiteRawStatement must be invoked from the thread that created it. A IllegalStateException will be thrown if cross-thread use is detected.

A common pattern for statements is try-with-resources.

 // Begin a transaction.
 database.beginTransaction();
 try (SQLiteRawStatement statement = database.createRawStatement("SELECT * FROM ...")) {
     while (statement.step()) {
         // Fetch columns from the result rows.
     }
     database.setTransactionSuccessful();
 } finally {
     database.endTransaction();
 }

Note that SQLiteRawStatement is unrelated to SQLiteStatement.

See also:

sqlite3_stmt

Summary

Constants
`int`	`SQLITE_DATA_TYPE_BLOB` The constant returned by `getColumnType(int)` when the column value is SQLITE_BLOB.
`int`	`SQLITE_DATA_TYPE_FLOAT` The constant returned by `getColumnType(int)` when the column value is SQLITE_FLOAT.
`int`	`SQLITE_DATA_TYPE_INTEGER` The constant returned by `getColumnType(int)` when the column value is SQLITE_INTEGER.
`int`	`SQLITE_DATA_TYPE_NULL` The constant returned by `getColumnType(int)` when the column value is SQLITE_NULL.
`int`	`SQLITE_DATA_TYPE_TEXT` The constant returned by `getColumnType(int)` when the column value is SQLITE_TEXT.

Public methods
`void`	`bindBlob(int parameterIndex, byte[] value)` Bind a blob to a parameter.
`void`	`bindBlob(int parameterIndex, byte[] value, int offset, int length)` Bind a blob to a parameter.
`void`	`bindDouble(int parameterIndex, double value)` Bind a double to a parameter.
`void`	`bindInt(int parameterIndex, int value)` Bind an int to a parameter.
`void`	`bindLong(int parameterIndex, long value)` Bind a long to the parameter.
`void`	`bindNull(int parameterIndex)` Bind a null to the parameter.
`void`	`bindText(int parameterIndex, String value)` Bind a string to the parameter.
`void`	`clearBindings()` Clear all parameter bindings.
`void`	`close()` Close the object and release any native resources.
`byte[]`	`getColumnBlob(int columnIndex)` Return the column value of the result row as a blob.
`double`	`getColumnDouble(int columnIndex)` Return the column value as a double.
`int`	`getColumnInt(int columnIndex)` Return the column value as a int.
`int`	`getColumnLength(int columnIndex)` Return the length of the column value in the result row.
`long`	`getColumnLong(int columnIndex)` Return the column value as a long.
`String`	`getColumnName(int columnIndex)` Return the name of the column in the result row.
`String`	`getColumnText(int columnIndex)` Return the column value as a text.
`int`	`getColumnType(int columnIndex)` Return the type of the column in the result row.
`int`	`getParameterCount()` Return the number of parameters in the statement.
`int`	`getParameterIndex(String name)` Return the index of the parameter with specified name.
`String`	`getParameterName(int parameterIndex)` Return the name of the parameter at the specified index.
`int`	`getResultColumnCount()` Return the number of columns in the current result row.
`boolean`	`isOpen()` Return true if the statement is still open and false otherwise.
`int`	`readColumnBlob(int columnIndex, byte[] buffer, int offset, int length, int srcOffset)` Copy the column value of the result row, interpreted as a blob, into the buffer.
`void`	`reset()` Reset the statement.
`boolean`	`step()` Step to the next result row.
`String`	`toString()` Returns a string representation of the object.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

From interface


        
          java.io.Closeable


      close()

Closes this stream and releases any system resources associated with it.

From interface


        
          java.lang.AutoCloseable


      close()

Closes this resource, relinquishing any underlying resources.

Constants

SQLITE_DATA_TYPE_BLOB

Added in API level 35

public static final int SQLITE_DATA_TYPE_BLOB

The constant returned by getColumnType(int) when the column value is SQLITE_BLOB.

Constant Value: 4 (0x00000004)

SQLITE_DATA_TYPE_FLOAT

Added in API level 35

public static final int SQLITE_DATA_TYPE_FLOAT

The constant returned by getColumnType(int) when the column value is SQLITE_FLOAT.

Constant Value: 2 (0x00000002)

SQLITE_DATA_TYPE_INTEGER

Added in API level 35

public static final int SQLITE_DATA_TYPE_INTEGER

The constant returned by getColumnType(int) when the column value is SQLITE_INTEGER.

Constant Value: 1 (0x00000001)

SQLITE_DATA_TYPE_NULL

Added in API level 35

public static final int SQLITE_DATA_TYPE_NULL

The constant returned by getColumnType(int) when the column value is SQLITE_NULL.

Constant Value: 5 (0x00000005)

SQLITE_DATA_TYPE_TEXT

Added in API level 35

public static final int SQLITE_DATA_TYPE_TEXT

The constant returned by getColumnType(int) when the column value is SQLITE_TEXT.

Constant Value: 3 (0x00000003)

Public methods

bindBlob

Added in API level 35

public void bindBlob (int parameterIndex, 
                byte[] value)

Bind a blob to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
`parameterIndex`	`int`: The index of the parameter in the query. It is one-based.
`value`	`byte`: The value to be bound to the parameter. This value cannot be `null`.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the parameter is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_bind_blob

bindBlob

Added in API level 35

public void bindBlob (int parameterIndex, 
                byte[] value, 
                int offset, 
                int length)

Bind a blob to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds. The sub-array value[offset] to value[offset+length-1] is bound.

Parameters
`parameterIndex`	`int`: The index of the parameter in the query. It is one-based.
`value`	`byte`: The value to be bound to the parameter. This value cannot be `null`.
`offset`	`int`: An offset into the value array
`length`	`int`: The number of bytes to bind from the value array.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`IllegalArgumentException`	if the sub-array exceeds the bounds of the value array.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the parameter is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_bind_blob

bindDouble

Added in API level 35

public void bindDouble (int parameterIndex, 
                double value)

Bind a double to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
`parameterIndex`	`int`: The index of the parameter in the query. It is one-based.
`value`	`double`: The value to be bound to the parameter.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the parameter is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_bind_double

bindInt

Added in API level 35

public void bindInt (int parameterIndex, 
                int value)

Bind an int to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
`parameterIndex`	`int`: The index of the parameter in the query. It is one-based.
`value`	`int`

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the parameter is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_bind_int

bindLong

Added in API level 35

public void bindLong (int parameterIndex, 
                long value)

Bind a long to the parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
`parameterIndex`	`int`
`value`	`long`: The value to be bound to the parameter.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the parameter is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_bind_int64

bindNull

Added in API level 35

public void bindNull (int parameterIndex)

Bind a null to the parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
`parameterIndex`	`int`: The index of the parameter in the query. It is one-based.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the parameter is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_bind_null

bindText

Added in API level 35

public void bindText (int parameterIndex, 
                String value)

Bind a string to the parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds. The string may not be null.

Parameters
`parameterIndex`	`int`: The index of the parameter in the query. It is one-based.
`value`	`String`: The value to be bound to the parameter. This value cannot be `null`.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the parameter is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_bind_text16

clearBindings

Added in API level 35

public void clearBindings ()

Clear all parameter bindings.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_clear_bindings

close

Added in API level 35

public void close ()

Close the object and release any native resources. It is not an error to call this on an already-closed object.

getColumnBlob

Added in API level 35

public byte[] getColumnBlob (int columnIndex)

Return the column value of the result row as a blob. Column indices start at 0. This throws an exception if column is not in the result. This returns null if the column value is null. The column value will be converted if it is not of type SQLITE_DATA_TYPE_BLOB; see the sqlite documentation for details.

Parameters
`columnIndex`	`int`: The index of a column in the result row. It is zero-based.

Returns
`byte[]`	The value of the column as a blob, or null if the column is NULL.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the column is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_column_blob

getColumnDouble

Added in API level 35

public double getColumnDouble (int columnIndex)

Return the column value as a double. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_FLOAT; see the sqlite documentation for details.

Parameters
`columnIndex`	`int`: The index of a column in the result row. It is zero-based.

Returns
`double`	The value of a column as a double.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the column is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_column_double

getColumnInt

Added in API level 35

public int getColumnInt (int columnIndex)

Return the column value as a int. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_INTEGER; see the sqlite documentation for details.

Parameters
`columnIndex`	`int`: The index of a column in the result row. It is zero-based.

Returns
`int`	The value of the column as an int.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the column is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_column_int

getColumnLength

Added in API level 35

public int getColumnLength (int columnIndex)

Return the length of the column value in the result row. Column indices start at 0. This returns 0 for a null and number of bytes for text or blob. Numeric values are converted to a string and the length of the string is returned. See the sqlite documentation for details. Note that this cannot be used to distinguish a null value from an empty text or blob. Note that this returns the number of bytes in the text value, not the number of characters.

Parameters
`columnIndex`	`int`: The index of a column in the result row. It is zero-based.

Returns
`int`	The length, in bytes, of the value in the column.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the column is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_column_bytes

getColumnLong

Added in API level 35

public long getColumnLong (int columnIndex)

Return the column value as a long. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_INTEGER; see the sqlite documentation for details.

Parameters
`columnIndex`	`int`: The index of a column in the result row. It is zero-based.

Returns
`long`	The value of the column as an long.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the column is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_column_long

getColumnName

Added in API level 35

public String getColumnName (int columnIndex)

Return the name of the column in the result row. Column indices start at 0. This throws an exception if column is not in the result.

Parameters
`columnIndex`	`int`: The index of a column in the result row. It is zero-based.

Returns
`String`	The name of the column in the result row. This value cannot be `null`.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the column is out of range.
`SQLiteOutOfMemoryException`	if the database cannot allocate memory for the name.

See also:

sqlite3_column_name

getColumnText

Added in API level 35

public String getColumnText (int columnIndex)

Return the column value as a text. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_TEXT; see the sqlite documentation for details.

Parameters
`columnIndex`	`int`: The index of a column in the result row. It is zero-based.

Returns
`String`	The value of the column as a string. This value cannot be `null`.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the column is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_column_text16

getColumnType

Added in API level 35

public int getColumnType (int columnIndex)

Return the type of the column in the result row. Column indices start at 0.

Parameters
`columnIndex`	`int`: The index of a column in the result row. It is zero-based.

Returns
`int`	The type of the value in the column of the result row. Value is `SQLITE_DATA_TYPE_INTEGER`, `SQLITE_DATA_TYPE_FLOAT`, `SQLITE_DATA_TYPE_TEXT`, `SQLITE_DATA_TYPE_BLOB`, or `SQLITE_DATA_TYPE_NULL`

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the column is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_column_type

getParameterCount

Added in API level 35

public int getParameterCount ()

Return the number of parameters in the statement.

Returns
`int`	The number of parameters in the statement.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.

See also:

sqlite3_bind_parameter_count

getParameterIndex

Added in API level 35

public int getParameterIndex (String name)

Return the index of the parameter with specified name. If the name does not match any parameter, 0 is returned.

Parameters
`name`	`String`: The name of a parameter. This value cannot be `null`.

Returns
`int`	The index of the parameter or 0 if the name does not identify a parameter.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.

See also:

sqlite3_bind_parameter_index

getParameterName

Added in API level 35

public String getParameterName (int parameterIndex)

Return the name of the parameter at the specified index. Null is returned if there is no such parameter or if the parameter does not have a name.

Parameters
`parameterIndex`	`int`: The index of the parameter.

Returns
`String`	The name of the parameter. This value may be `null`.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.

See also:

sqlite3_bind_parameter_name

getResultColumnCount

Added in API level 35

public int getResultColumnCount ()

Return the number of columns in the current result row.

Returns
`int`	The number of columns in the result row.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.

See also:

sqlite3_column_count

isOpen

Added in API level 35

public boolean isOpen ()

Return true if the statement is still open and false otherwise.

Returns
`boolean`	True if the statement is open.

readColumnBlob

Added in API level 35

public int readColumnBlob (int columnIndex, 
                byte[] buffer, 
                int offset, 
                int length, 
                int srcOffset)

Copy the column value of the result row, interpreted as a blob, into the buffer. Column indices start at 0. This throws an exception if column is not in the result row. Bytes are copied into the buffer starting at the offset. Bytes are copied from the blob starting at srcOffset. Length bytes are copied unless the column value has fewer bytes available. The function returns the number of bytes copied. The column value will be converted if it is not of type SQLITE_DATA_TYPE_BLOB; see the sqlite documentation for details.

Parameters
`columnIndex`	`int`: The index of a column in the result row. It is zero-based.
`buffer`	`byte`: A pre-allocated array to be filled with the value of the column. This value cannot be `null`.
`offset`	`int`: An offset into the buffer: copying starts here.
`length`	`int`: The number of bytes to copy.
`srcOffset`	`int`: The offset into the blob from which to start copying.

Returns
`int`	the number of bytes that were copied.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`IllegalArgumentException`	if the buffer is too small for offset+length.
`SQLiteBindOrColumnIndexOutOfRangeException`	if the column is out of range.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_column_blob

reset

Added in API level 35

public void reset ()

Reset the statement.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_reset

step

Added in API level 35

public boolean step ()

Step to the next result row. This returns true if the statement stepped to a new row, and false if the statement is done. The method throws on any other result, including a busy or locked database. If WAL is enabled then the database should never be locked or busy.

Returns
`boolean`	True if a row is available and false otherwise.

Throws
`IllegalStateException`	if the statement is closed or this is a foreign thread.
`SQLiteDatabaseLockedException`	if the database is locked or busy.
`SQLiteException`	if a native error occurs.

See also:

sqlite3_step

toString

Added in API level 35

public String toString ()

Returns a string representation of the object.

Returns
`String`	a string representation of the object.