Skip to content

Most visited

Recently visited

navigation
Added in API level 1

SQLiteQueryBuilder

public class SQLiteQueryBuilder
extends Object

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


This is a convience class that helps build SQL queries to be sent to SQLiteDatabase objects.

Summary

Public constructors

SQLiteQueryBuilder()

Public methods

static void appendColumns(StringBuilder s, String[] columns)

Add the names that are non-null in columns to s, separating them with commas.

void appendWhere(CharSequence inWhere)

Append a chunk to the WHERE clause of the query.

void appendWhereEscapeString(String inWhere)

Append a chunk to the WHERE clause of the query.

String buildQuery(String[] projectionIn, String selection, String groupBy, String having, String sortOrder, String limit)

Construct a SELECT statement suitable for use in a group of SELECT statements that will be joined through UNION operators in buildUnionQuery.

String buildQuery(String[] projectionIn, String selection, String[] selectionArgs, String groupBy, String having, String sortOrder, String limit)

This method was deprecated in API level 11. This method's signature is misleading since no SQL parameter substitution is carried out. The selection arguments parameter does not get used at all. To avoid confusion, call buildQuery(String[], String, String, String, String, String) instead.

static String buildQueryString(boolean distinct, String tables, String[] columns, String where, String groupBy, String having, String orderBy, String limit)

Build an SQL query string from the given clauses.

String buildUnionQuery(String[] subQueries, String sortOrder, String limit)

Given a set of subqueries, all of which are SELECT statements, construct a query that returns the union of what those subqueries return.

String buildUnionSubQuery(String typeDiscriminatorColumn, String[] unionColumns, Set<String> columnsPresentInTable, int computedColumnsOffset, String typeDiscriminatorValue, String selection, String[] selectionArgs, String groupBy, String having)

This method was deprecated in API level 11. This method's signature is misleading since no SQL parameter substitution is carried out. The selection arguments parameter does not get used at all. To avoid confusion, call buildUnionSubQuery(String, String[], Set, int, String, String, String, String) instead.

String buildUnionSubQuery(String typeDiscriminatorColumn, String[] unionColumns, Set<String> columnsPresentInTable, int computedColumnsOffset, String typeDiscriminatorValue, String selection, String groupBy, String having)

Construct a SELECT statement suitable for use in a group of SELECT statements that will be joined through UNION operators in buildUnionQuery.

String getTables()

Returns the list of tables being queried

Cursor query(SQLiteDatabase db, String[] projectionIn, String selection, String[] selectionArgs, String groupBy, String having, String sortOrder)

Perform a query by combining all current settings and the information passed into this method.

Cursor query(SQLiteDatabase db, String[] projectionIn, String selection, String[] selectionArgs, String groupBy, String having, String sortOrder, String limit)

Perform a query by combining all current settings and the information passed into this method.

Cursor query(SQLiteDatabase db, String[] projectionIn, String selection, String[] selectionArgs, String groupBy, String having, String sortOrder, String limit, CancellationSignal cancellationSignal)

Perform a query by combining all current settings and the information passed into this method.

void setCursorFactory(SQLiteDatabase.CursorFactory factory)

Sets the cursor factory to be used for the query.

void setDistinct(boolean distinct)

Mark the query as DISTINCT.

void setProjectionMap(Map<StringString> columnMap)

Sets the projection map for the query.

void setStrict(boolean flag)

When set, the selection is verified against malicious arguments.

void setTables(String inTables)

Sets the list of tables to query.

Inherited methods

From class java.lang.Object

Public constructors

SQLiteQueryBuilder

Added in API level 1
SQLiteQueryBuilder ()

Public methods

appendColumns

Added in API level 1
void appendColumns (StringBuilder s, 
                String[] columns)

Add the names that are non-null in columns to s, separating them with commas.

Parameters
s StringBuilder
columns String

appendWhere

Added in API level 1
void appendWhere (CharSequence inWhere)

Append a chunk to the WHERE clause of the query. All chunks appended are surrounded by parenthesis and ANDed with the selection passed to query(SQLiteDatabase, String[], String, String[], String, String, String). The final WHERE clause looks like: WHERE (<append chunk 1><append chunk2>) AND (<query() selection parameter>)

Parameters
inWhere CharSequence: the chunk of text to append to the WHERE clause.

appendWhereEscapeString

Added in API level 1
void appendWhereEscapeString (String inWhere)

Append a chunk to the WHERE clause of the query. All chunks appended are surrounded by parenthesis and ANDed with the selection passed to query(SQLiteDatabase, String[], String, String[], String, String, String). The final WHERE clause looks like: WHERE (<append chunk 1><append chunk2>) AND (<query() selection parameter>)

Parameters
inWhere String: the chunk of text to append to the WHERE clause. it will be escaped to avoid SQL injection attacks

buildQuery

Added in API level 11
String buildQuery (String[] projectionIn, 
                String selection, 
                String groupBy, 
                String having, 
                String sortOrder, 
                String limit)

Construct a SELECT statement suitable for use in a group of SELECT statements that will be joined through UNION operators in buildUnionQuery.

Parameters
projectionIn String: A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.
selection String: A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given URL.
groupBy String: A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.
having String: A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.
sortOrder String: How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.
limit String: Limits the number of rows returned by the query, formatted as LIMIT clause. Passing null denotes no LIMIT clause.
Returns
String the resulting SQL SELECT statement

buildQuery

Added in API level 1
String buildQuery (String[] projectionIn, 
                String selection, 
                String[] selectionArgs, 
                String groupBy, 
                String having, 
                String sortOrder, 
                String limit)

This method was deprecated in API level 11.
This method's signature is misleading since no SQL parameter substitution is carried out. The selection arguments parameter does not get used at all. To avoid confusion, call buildQuery(String[], String, String, String, String, String) instead.

Parameters
projectionIn String
selection String
selectionArgs String
groupBy String
having String
sortOrder String
limit String
Returns
String

buildQueryString

Added in API level 1
String buildQueryString (boolean distinct, 
                String tables, 
                String[] columns, 
                String where, 
                String groupBy, 
                String having, 
                String orderBy, 
                String limit)

Build an SQL query string from the given clauses.

Parameters
distinct boolean: true if you want each row to be unique, false otherwise.
tables String: The table names to compile the query against.
columns String: A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.
where String: A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given URL.
groupBy String: A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.
having String: A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.
orderBy String: How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.
limit String: Limits the number of rows returned by the query, formatted as LIMIT clause. Passing null denotes no LIMIT clause.
Returns
String the SQL query string

buildUnionQuery

Added in API level 1
String buildUnionQuery (String[] subQueries, 
                String sortOrder, 
                String limit)

Given a set of subqueries, all of which are SELECT statements, construct a query that returns the union of what those subqueries return.

Parameters
subQueries String: an array of SQL SELECT statements, all of which must have the same columns as the same positions in their results
sortOrder String: How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.
limit String: The limit clause, which applies to the entire union result set
Returns
String the resulting SQL SELECT statement

buildUnionSubQuery

Added in API level 1
String buildUnionSubQuery (String typeDiscriminatorColumn, 
                String[] unionColumns, 
                Set<String> columnsPresentInTable, 
                int computedColumnsOffset, 
                String typeDiscriminatorValue, 
                String selection, 
                String[] selectionArgs, 
                String groupBy, 
                String having)

This method was deprecated in API level 11.
This method's signature is misleading since no SQL parameter substitution is carried out. The selection arguments parameter does not get used at all. To avoid confusion, call buildUnionSubQuery(String, String[], Set, int, String, String, String, String) instead.

Parameters
typeDiscriminatorColumn String
unionColumns String
columnsPresentInTable Set
computedColumnsOffset int
typeDiscriminatorValue String
selection String
selectionArgs String
groupBy String
having String
Returns
String

buildUnionSubQuery

Added in API level 11
String buildUnionSubQuery (String typeDiscriminatorColumn, 
                String[] unionColumns, 
                Set<String> columnsPresentInTable, 
                int computedColumnsOffset, 
                String typeDiscriminatorValue, 
                String selection, 
                String groupBy, 
                String having)

Construct a SELECT statement suitable for use in a group of SELECT statements that will be joined through UNION operators in buildUnionQuery.

Parameters
typeDiscriminatorColumn String: the name of the result column whose cells will contain the name of the table from which each row was drawn.
unionColumns String: the names of the columns to appear in the result. This may include columns that do not appear in the table this SELECT is querying (i.e. mTables), but that do appear in one of the other tables in the UNION query that we are constructing.
columnsPresentInTable Set: a Set of the names of the columns that appear in this table (i.e. in the table whose name is mTables). Since columns in unionColumns include columns that appear only in other tables, we use this array to distinguish which ones actually are present. Other columns will have NULL values for results from this subquery.
computedColumnsOffset int: all columns in unionColumns before this index are included under the assumption that they're computed and therefore won't appear in columnsPresentInTable, e.g. "date * 1000 as normalized_date"
typeDiscriminatorValue String: the value used for the type-discriminator column in this subquery
selection String: A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given URL.
groupBy String: A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.
having String: A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.
Returns
String the resulting SQL SELECT statement

getTables

Added in API level 1
String getTables ()

Returns the list of tables being queried

Returns
String the list of tables being queried

query

Added in API level 1
Cursor query (SQLiteDatabase db, 
                String[] projectionIn, 
                String selection, 
                String[] selectionArgs, 
                String groupBy, 
                String having, 
                String sortOrder)

Perform a query by combining all current settings and the information passed into this method.

Parameters
db SQLiteDatabase: the database to query on
projectionIn String: A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.
selection String: A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given URL.
selectionArgs String: You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings.
groupBy String: A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.
having String: A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.
sortOrder String: How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.
Returns
Cursor a cursor over the result set

See also:

query

Added in API level 1
Cursor query (SQLiteDatabase db, 
                String[] projectionIn, 
                String selection, 
                String[] selectionArgs, 
                String groupBy, 
                String having, 
                String sortOrder, 
                String limit)

Perform a query by combining all current settings and the information passed into this method.

Parameters
db SQLiteDatabase: the database to query on
projectionIn String: A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.
selection String: A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given URL.
selectionArgs String: You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings.
groupBy String: A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.
having String: A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.
sortOrder String: How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.
limit String: Limits the number of rows returned by the query, formatted as LIMIT clause. Passing null denotes no LIMIT clause.
Returns
Cursor a cursor over the result set

See also:

query

Added in API level 16
Cursor query (SQLiteDatabase db, 
                String[] projectionIn, 
                String selection, 
                String[] selectionArgs, 
                String groupBy, 
                String having, 
                String sortOrder, 
                String limit, 
                CancellationSignal cancellationSignal)

Perform a query by combining all current settings and the information passed into this method.

Parameters
db SQLiteDatabase: the database to query on
projectionIn String: A list of which columns to return. Passing null will return all columns, which is discouraged to prevent reading data from storage that isn't going to be used.
selection String: A filter declaring which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). Passing null will return all rows for the given URL.
selectionArgs String: You may include ?s in selection, which will be replaced by the values from selectionArgs, in order that they appear in the selection. The values will be bound as Strings.
groupBy String: A filter declaring how to group rows, formatted as an SQL GROUP BY clause (excluding the GROUP BY itself). Passing null will cause the rows to not be grouped.
having String: A filter declare which row groups to include in the cursor, if row grouping is being used, formatted as an SQL HAVING clause (excluding the HAVING itself). Passing null will cause all row groups to be included, and is required when row grouping is not being used.
sortOrder String: How to order the rows, formatted as an SQL ORDER BY clause (excluding the ORDER BY itself). Passing null will use the default sort order, which may be unordered.
limit String: Limits the number of rows returned by the query, formatted as LIMIT clause. Passing null denotes no LIMIT clause.
cancellationSignal CancellationSignal: A signal to cancel the operation in progress, or null if none. If the operation is canceled, then OperationCanceledException will be thrown when the query is executed.
Returns
Cursor a cursor over the result set

See also:

setCursorFactory

Added in API level 1
void setCursorFactory (SQLiteDatabase.CursorFactory factory)

Sets the cursor factory to be used for the query. You can use one factory for all queries on a database but it is normally easier to specify the factory when doing this query.

Parameters
factory SQLiteDatabase.CursorFactory: the factory to use.

setDistinct

Added in API level 1
void setDistinct (boolean distinct)

Mark the query as DISTINCT.

Parameters
distinct boolean: if true the query is DISTINCT, otherwise it isn't

setProjectionMap

Added in API level 1
void setProjectionMap (Map<StringString> columnMap)

Sets the projection map for the query. The projection map maps from column names that the caller passes into query to database column names. This is useful for renaming columns as well as disambiguating column names when doing joins. For example you could map "name" to "people.name". If a projection map is set it must contain all column names the user may request, even if the key and value are the same.

Parameters
columnMap Map: maps from the user column names to the database column names

setStrict

Added in API level 14
void setStrict (boolean flag)

When set, the selection is verified against malicious arguments. When using this class to create a statement using buildQueryString(boolean, String, String[], String, String, String, String, String), non-numeric limits will raise an exception. If a projection map is specified, fields not in that map will be ignored. If this class is used to execute the statement directly using query(SQLiteDatabase, String[], String, String[], String, String, String) or query(SQLiteDatabase, String[], String, String[], String, String, String, String), additionally also parenthesis escaping selection are caught. To summarize: To get maximum protection against malicious third party apps (for example content provider consumers), make sure to do the following:

  • Set this value to true
  • Use a projection map
  • Use one of the query overloads instead of getting the statement as a sql string
By default, this value is false.

Parameters
flag boolean

setTables

Added in API level 1
void setTables (String inTables)

Sets the list of tables to query. Multiple tables can be specified to perform a join. For example: setTables("foo, bar") setTables("foo LEFT OUTER JOIN bar ON (foo.id = bar.foo_id)")

Parameters
inTables String: the list of tables to query on
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.