ContentProvider.Query Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Overloads
| Query(Uri, String[], String, String[], String) |
Implement this to handle query requests from clients. |
| Query(Uri, String[], String, String[], String, CancellationSignal) |
Implement this to handle query requests from clients with support for cancellation. |
| Query(Uri, String[], Bundle, CancellationSignal) |
Implement this to handle query requests where the arguments are packed into a |
Query(Uri, String[], String, String[], String)
Implement this to handle query requests from clients.
[Android.Runtime.Register("query", "(Landroid/net/Uri;[Ljava/lang/String;Ljava/lang/String;[Ljava/lang/String;Ljava/lang/String;)Landroid/database/Cursor;", "GetQuery_Landroid_net_Uri_arrayLjava_lang_String_Ljava_lang_String_arrayLjava_lang_String_Ljava_lang_String_Handler")]
public abstract Android.Database.ICursor? Query (Android.Net.Uri uri, string[]? projection, string? selection, string[]? selectionArgs, string? sortOrder);[<Android.Runtime.Register("query", "(Landroid/net/Uri;[Ljava/lang/String;Ljava/lang/String;[Ljava/lang/String;Ljava/lang/String;)Landroid/database/Cursor;", "GetQuery_Landroid_net_Uri_arrayLjava_lang_String_Ljava_lang_String_arrayLjava_lang_String_Ljava_lang_String_Handler")>]
abstract member Query : Android.Net.Uri * string[] * string * string[] * string -> Android.Database.ICursorParameters
- uri
- Uri
The URI to query. This will be the full URI sent by the client; if the client is requesting a specific record, the URI will end in a record number that the implementation should parse and add to a WHERE or HAVING clause, specifying that _id value.
- projection
- String[]
The list of columns to put into the cursor. If
null all columns are included.
- selection
- String
A selection criteria to apply when filtering rows.
If null then all rows are included.
- 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.
- sortOrder
- String
How the rows in the cursor should be sorted.
If null then the provider is free to define the sort order.
Returns
a Cursor or null.
- Attributes
Remarks
Implement this to handle query requests from clients.
Apps targeting android.os.Build.VERSION_CODES#O or higher should override #query(Uri, String[], Bundle, CancellationSignal) and provide a stub implementation of this method.
This method can be called from multiple threads, as described in Processes and Threads.
Example client call:
// Request a specific record.
Cursor managedCursor = managedQuery(
ContentUris.withAppendedId(Contacts.People.CONTENT_URI, 2),
projection, // Which columns to return.
null, // WHERE clause.
null, // WHERE clause value substitution
People.NAME + " ASC"); // Sort order.
Example implementation:
// SQLiteQueryBuilder is a helper class that creates the
// proper SQL syntax for us.
SQLiteQueryBuilder qBuilder = new SQLiteQueryBuilder();
// Set the table we're querying.
qBuilder.setTables(DATABASE_TABLE_NAME);
// If the query ends in a specific record number, we're
// being asked for a specific record, so set the
// WHERE clause in our query.
if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE){
qBuilder.appendWhere("_id=" + uri.getPathLeafId());
}
// Make the query.
Cursor c = qBuilder.query(mDb,
projection,
selection,
selectionArgs,
groupBy,
having,
sortOrder);
c.setNotificationUri(getContext().getContentResolver(), uri);
return c;
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Applies to
Query(Uri, String[], String, String[], String, CancellationSignal)
Implement this to handle query requests from clients with support for cancellation.
[Android.Runtime.Register("query", "(Landroid/net/Uri;[Ljava/lang/String;Ljava/lang/String;[Ljava/lang/String;Ljava/lang/String;Landroid/os/CancellationSignal;)Landroid/database/Cursor;", "GetQuery_Landroid_net_Uri_arrayLjava_lang_String_Ljava_lang_String_arrayLjava_lang_String_Ljava_lang_String_Landroid_os_CancellationSignal_Handler")]
public virtual Android.Database.ICursor? Query (Android.Net.Uri uri, string[]? projection, string? selection, string[]? selectionArgs, string? sortOrder, Android.OS.CancellationSignal? cancellationSignal);[<Android.Runtime.Register("query", "(Landroid/net/Uri;[Ljava/lang/String;Ljava/lang/String;[Ljava/lang/String;Ljava/lang/String;Landroid/os/CancellationSignal;)Landroid/database/Cursor;", "GetQuery_Landroid_net_Uri_arrayLjava_lang_String_Ljava_lang_String_arrayLjava_lang_String_Ljava_lang_String_Landroid_os_CancellationSignal_Handler")>]
abstract member Query : Android.Net.Uri * string[] * string * string[] * string * Android.OS.CancellationSignal -> Android.Database.ICursor
override this.Query : Android.Net.Uri * string[] * string * string[] * string * Android.OS.CancellationSignal -> Android.Database.ICursorParameters
- uri
- Uri
The URI to query. This will be the full URI sent by the client; if the client is requesting a specific record, the URI will end in a record number that the implementation should parse and add to a WHERE or HAVING clause, specifying that _id value.
- projection
- String[]
The list of columns to put into the cursor. If
null all columns are included.
- selection
- String
A selection criteria to apply when filtering rows.
If null then all rows are included.
- 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.
- sortOrder
- String
How the rows in the cursor should be sorted.
If null then the provider is free to define the sort order.
- cancellationSignal
- CancellationSignal
A signal to cancel the operation in progress, or null if none.
If the operation is canceled, then android.os.OperationCanceledException will be thrown
when the query is executed.
Returns
a Cursor or null.
- Attributes
Remarks
Implement this to handle query requests from clients with support for cancellation.
Apps targeting android.os.Build.VERSION_CODES#O or higher should override #query(Uri, String[], Bundle, CancellationSignal) instead of this method.
This method can be called from multiple threads, as described in Processes and Threads.
Example client call:
// Request a specific record.
Cursor managedCursor = managedQuery(
ContentUris.withAppendedId(Contacts.People.CONTENT_URI, 2),
projection, // Which columns to return.
null, // WHERE clause.
null, // WHERE clause value substitution
People.NAME + " ASC"); // Sort order.
Example implementation:
// SQLiteQueryBuilder is a helper class that creates the
// proper SQL syntax for us.
SQLiteQueryBuilder qBuilder = new SQLiteQueryBuilder();
// Set the table we're querying.
qBuilder.setTables(DATABASE_TABLE_NAME);
// If the query ends in a specific record number, we're
// being asked for a specific record, so set the
// WHERE clause in our query.
if((URI_MATCHER.match(uri)) == SPECIFIC_MESSAGE){
qBuilder.appendWhere("_id=" + uri.getPathLeafId());
}
// Make the query.
Cursor c = qBuilder.query(mDb,
projection,
selection,
selectionArgs,
groupBy,
having,
sortOrder);
c.setNotificationUri(getContext().getContentResolver(), uri);
return c;
If you implement this method then you must also implement the version of #query(Uri, String[], String, String[], String) that does not take a cancellation signal to ensure correct operation on older versions of the Android Framework in which the cancellation signal overload was not available.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Applies to
Query(Uri, String[], Bundle, CancellationSignal)
Implement this to handle query requests where the arguments are packed into a Bundle.
[Android.Runtime.Register("query", "(Landroid/net/Uri;[Ljava/lang/String;Landroid/os/Bundle;Landroid/os/CancellationSignal;)Landroid/database/Cursor;", "GetQuery_Landroid_net_Uri_arrayLjava_lang_String_Landroid_os_Bundle_Landroid_os_CancellationSignal_Handler", ApiSince=26)]
public virtual Android.Database.ICursor? Query (Android.Net.Uri uri, string[]? projection, Android.OS.Bundle? queryArgs, Android.OS.CancellationSignal? cancellationSignal);[<Android.Runtime.Register("query", "(Landroid/net/Uri;[Ljava/lang/String;Landroid/os/Bundle;Landroid/os/CancellationSignal;)Landroid/database/Cursor;", "GetQuery_Landroid_net_Uri_arrayLjava_lang_String_Landroid_os_Bundle_Landroid_os_CancellationSignal_Handler", ApiSince=26)>]
abstract member Query : Android.Net.Uri * string[] * Android.OS.Bundle * Android.OS.CancellationSignal -> Android.Database.ICursor
override this.Query : Android.Net.Uri * string[] * Android.OS.Bundle * Android.OS.CancellationSignal -> Android.Database.ICursorParameters
- uri
- Uri
The URI to query. This will be the full URI sent by the client.
- projection
- String[]
The list of columns to put into the cursor.
If null provide a default set of columns.
- queryArgs
- Bundle
A Bundle containing additional information necessary for
the operation. Arguments may include SQL style arguments, such
as ContentResolver#QUERY_ARG_SQL_LIMIT, but note that
the documentation for each individual provider will indicate
which arguments they support.
- cancellationSignal
- CancellationSignal
A signal to cancel the operation in progress,
or null.
Returns
a Cursor or null.
- Attributes
Remarks
Implement this to handle query requests where the arguments are packed into a Bundle. Arguments may include traditional SQL style query arguments. When present these should be handled according to the contract established in #query(Uri, String[], String, String[], String, CancellationSignal).
Traditional SQL arguments can be found in the bundle using the following keys: <li>android.content.ContentResolver#QUERY_ARG_SQL_SELECTION<li>android.content.ContentResolver#QUERY_ARG_SQL_SELECTION_ARGS<li>android.content.ContentResolver#QUERY_ARG_SQL_SORT_ORDER
This method can be called from multiple threads, as described in Processes and Threads.
Example client call:
// Request 20 records starting at row index 30.
Bundle queryArgs = new Bundle();
queryArgs.putInt(ContentResolver.QUERY_ARG_OFFSET, 30);
queryArgs.putInt(ContentResolver.QUERY_ARG_LIMIT, 20);
Cursor cursor = getContentResolver().query(
contentUri, // Content Uri is specific to individual content providers.
projection, // String[] describing which columns to return.
queryArgs, // Query arguments.
null); // Cancellation signal.
Example implementation:
int recordsetSize = 0x1000; // Actual value is implementation specific.
queryArgs = queryArgs != null ? queryArgs : Bundle.EMPTY; // ensure queryArgs is non-null
int offset = queryArgs.getInt(ContentResolver.QUERY_ARG_OFFSET, 0);
int limit = queryArgs.getInt(ContentResolver.QUERY_ARG_LIMIT, Integer.MIN_VALUE);
MatrixCursor c = new MatrixCursor(PROJECTION, limit);
// Calculate the number of items to include in the cursor.
int numItems = MathUtils.constrain(recordsetSize - offset, 0, limit);
// Build the paged result set....
for (int i = offset; i < offset + numItems; i++) {
// populate row from your data.
}
Bundle extras = new Bundle();
c.setExtras(extras);
// Any QUERY_ARG_* key may be included if honored.
// In an actual implementation, include only keys that are both present in queryArgs
// and reflected in the Cursor output. For example, if QUERY_ARG_OFFSET were included
// in queryArgs, but was ignored because it contained an invalid value (like –273),
// then QUERY_ARG_OFFSET should be omitted.
extras.putStringArray(ContentResolver.EXTRA_HONORED_ARGS, new String[] {
ContentResolver.QUERY_ARG_OFFSET,
ContentResolver.QUERY_ARG_LIMIT
});
extras.putInt(ContentResolver.EXTRA_TOTAL_COUNT, recordsetSize);
cursor.setNotificationUri(getContext().getContentResolver(), uri);
return cursor;
See #query(Uri, String[], String, String[], String, CancellationSignal) for implementation details.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.