public class ParseQuery<T extends ParseObject> extends Object
ParseQuery
class defines a query that is used to fetch ParseObject
s. The most
common use case is finding all objects that match a query through the ParseQuery.findInBackground()
method, using a FindCallback
. For example, this sample code fetches all objects of class
"MyClass"
. It calls a different function depending on whether the fetch succeeded or not.
ParseQuery<ParseObject> query = ParseQuery.getQuery("MyClass"); query.findInBackground(new FindCallback<ParseObject>() { public void done(List<ParseObject> objects, ParseException e) { if (e == null) { objectsWereRetrievedSuccessfully(objects); } else { objectRetrievalFailed(); } } }A
ParseQuery
can also be used to retrieve a single object whose id is known, through the
ParseQuery.getInBackground(String)
method, using a GetCallback
. For example, this
sample code fetches an object of class "MyClass"
and id myId
. It calls
a different function depending on whether the fetch succeeded or not.
ParseQuery<ParseObject> query = ParseQuery.getQuery("MyClass"); query.getInBackground(myId, new GetCallback<ParseObject>() { public void done(ParseObject object, ParseException e) { if (e == null) { objectWasRetrievedSuccessfully(object); } else { objectRetrievalFailed(); } } }A
ParseQuery
can also be used to count the number of objects that match the query without
retrieving all of those objects. For example, this sample code counts the number of objects of
the class "MyClass"
.
ParseQuery<ParseObject> query = ParseQuery.getQuery("MyClass"); query.countInBackground(new CountCallback() { public void done(int count, ParseException e) { if (e == null) { objectsWereCounted(count); } else { objectCountFailed(); } } }Using the callback methods is usually preferred because the network operation will not block the calling thread. However, in some cases it may be easier to use the
ParseQuery.find()
,
ParseQuery.get(String)
or ParseQuery.count()
calls, which do block the calling thread. For example,
if your application has already spawned a background task to perform work, that background task
could use the blocking calls and avoid the code complexity of callbacks.Modifier and Type | Class and Description |
---|---|
static class |
ParseQuery.CachePolicy
CachePolicy specifies different caching policies that could be used with
ParseQuery . |
Constructor and Description |
---|
ParseQuery(Class<T> subclass)
Constructs a query for a
ParseObject subclass type. |
ParseQuery(String theClassName)
Constructs a query.
|
Modifier and Type | Method and Description |
---|---|
ParseQuery<T> |
addAscendingOrder(String key)
Also sorts the results in ascending order by the given key.
|
ParseQuery<T> |
addDescendingOrder(String key)
Also sorts the results in descending order by the given key.
|
void |
cancel()
Cancels the current network request (if one is running).
|
static void |
clearAllCachedResults()
Clears the cached result for all queries.
|
void |
clearCachedResult()
Removes the previously cached result for this query, forcing the next find() to hit the
network.
|
int |
count()
Counts the number of objects that match this query.
|
Task<Integer> |
countInBackground()
Counts the number of objects that match this query in a background thread.
|
void |
countInBackground(CountCallback callback)
Counts the number of objects that match this query in a background thread.
|
List<T> |
find()
Retrieves a list of
ParseObject s that satisfy this query. |
Task<List<T>> |
findInBackground()
Retrieves a list of
ParseObject s that satisfy this query from the source in a
background thread. |
void |
findInBackground(FindCallback<T> callback)
Retrieves a list of
ParseObject s that satisfy this query from the source in a
background thread. |
ParseQuery<T> |
fromLocalDatastore()
Change the source of this query to all pinned objects.
|
ParseQuery<T> |
fromPin()
Change the source of this query to the default group of pinned objects.
|
ParseQuery<T> |
fromPin(String name)
Change the source of this query to a specific group of pinned objects.
|
T |
get(String objectId)
Constructs a
ParseObject whose id is already known by fetching data from the source. |
ParseQuery.CachePolicy |
getCachePolicy() |
String |
getClassName()
Accessor for the class name.
|
T |
getFirst()
Retrieves at most one
ParseObject that satisfies this query. |
Task<T> |
getFirstInBackground()
Retrieves at most one
ParseObject that satisfies this query from the source in a
background thread. |
void |
getFirstInBackground(GetCallback<T> callback)
Retrieves at most one
ParseObject that satisfies this query from the source in a
background thread. |
Task<T> |
getInBackground(String objectId)
Constructs a
ParseObject whose id is already known by fetching data from the source in a
background thread. |
void |
getInBackground(String objectId,
GetCallback<T> callback)
Constructs a
ParseObject whose id is already known by fetching data from the source in
a background thread. |
int |
getLimit()
Accessor for the limit.
|
long |
getMaxCacheAge()
Gets the maximum age of cached data that will be considered in this query.
|
static <T extends ParseObject> |
getQuery(Class<T> subclass)
Creates a new query for the given
ParseObject subclass type. |
static <T extends ParseObject> |
getQuery(String className)
Creates a new query for the given class name.
|
int |
getSkip()
Accessor for the skip value.
|
static ParseQuery<ParseUser> |
getUserQuery()
Deprecated.
Please use
ParseUser.getQuery() instead. |
boolean |
hasCachedResult()
Returns whether or not this query has a cached result.
|
ParseQuery<T> |
ignoreACLs()
Ignore ACLs when querying from the Local Datastore.
|
ParseQuery<T> |
include(String key)
Include nested
ParseObject s for the provided key. |
static <T extends ParseObject> |
or(List<ParseQuery<T>> queries)
Constructs a query that is the
or of the given queries. |
ParseQuery<T> |
orderByAscending(String key)
Sorts the results in ascending order by the given key.
|
ParseQuery<T> |
orderByDescending(String key)
Sorts the results in descending order by the given key.
|
ParseQuery<T> |
selectKeys(Collection<String> keys)
Restrict the fields of returned
ParseObject s to only include the provided keys. |
ParseQuery<T> |
setCachePolicy(ParseQuery.CachePolicy newCachePolicy)
Change the caching policy of this query.
|
ParseQuery<T> |
setLimit(int newLimit)
Controls the maximum number of results that are returned.
|
ParseQuery<T> |
setMaxCacheAge(long maxAgeInMilliseconds)
Sets the maximum age of cached data that will be considered in this query.
|
ParseQuery<T> |
setSkip(int newSkip)
Controls the number of results to skip before returning any results.
|
ParseQuery<T> |
setTrace(boolean shouldTrace)
Turn on performance tracing of finds.
|
ParseQuery<T> |
whereContainedIn(String key,
Collection<? extends Object> values)
Add a constraint to the query that requires a particular key's value to be contained in the
provided list of values.
|
ParseQuery<T> |
whereContains(String key,
String substring)
Add a constraint for finding string values that contain a provided string.
|
ParseQuery<T> |
whereContainsAll(String key,
Collection<?> values)
Add a constraint to the query that requires a particular key's value match another
ParseQuery . |
ParseQuery<T> |
whereDoesNotExist(String key)
Add a constraint for finding objects that do not contain a given key.
|
ParseQuery<T> |
whereDoesNotMatchKeyInQuery(String key,
String keyInQuery,
ParseQuery<?> query)
Add a constraint to the query that requires a particular key's value does not match any value
for a key in the results of another
ParseQuery . |
ParseQuery<T> |
whereDoesNotMatchQuery(String key,
ParseQuery<?> query)
Add a constraint to the query that requires a particular key's value does not match another
ParseQuery . |
ParseQuery<T> |
whereEndsWith(String key,
String suffix)
Add a constraint for finding string values that end with a provided string.
|
ParseQuery<T> |
whereEqualTo(String key,
Object value)
Add a constraint to the query that requires a particular key's value to be equal to the
provided value.
|
ParseQuery<T> |
whereExists(String key)
Add a constraint for finding objects that contain the given key.
|
ParseQuery<T> |
whereGreaterThan(String key,
Object value)
Add a constraint to the query that requires a particular key's value to be greater than the
provided value.
|
ParseQuery<T> |
whereGreaterThanOrEqualTo(String key,
Object value)
Add a constraint to the query that requires a particular key's value to be greater than or
equal to the provided value.
|
ParseQuery<T> |
whereLessThan(String key,
Object value)
Add a constraint to the query that requires a particular key's value to be less than the
provided value.
|
ParseQuery<T> |
whereLessThanOrEqualTo(String key,
Object value)
Add a constraint to the query that requires a particular key's value to be less than or equal
to the provided value.
|
ParseQuery<T> |
whereMatches(String key,
String regex)
Add a regular expression constraint for finding string values that match the provided regular
expression.
|
ParseQuery<T> |
whereMatches(String key,
String regex,
String modifiers)
Add a regular expression constraint for finding string values that match the provided regular
expression.
|
ParseQuery<T> |
whereMatchesKeyInQuery(String key,
String keyInQuery,
ParseQuery<?> query)
Add a constraint to the query that requires a particular key's value matches a value for a key
in the results of another
ParseQuery . |
ParseQuery<T> |
whereMatchesQuery(String key,
ParseQuery<?> query)
Add a constraint to the query that requires a particular key's value match another
ParseQuery . |
ParseQuery<T> |
whereNear(String key,
ParseGeoPoint point)
Add a proximity based constraint for finding objects with key point values near the point
given.
|
ParseQuery<T> |
whereNotContainedIn(String key,
Collection<? extends Object> values)
Add a constraint to the query that requires a particular key's value not be contained in the
provided list of values.
|
ParseQuery<T> |
whereNotEqualTo(String key,
Object value)
Add a constraint to the query that requires a particular key's value to be not equal to the
provided value.
|
ParseQuery<T> |
whereStartsWith(String key,
String prefix)
Add a constraint for finding string values that start with a provided string.
|
ParseQuery<T> |
whereWithinGeoBox(String key,
ParseGeoPoint southwest,
ParseGeoPoint northeast)
Add a constraint to the query that requires a particular key's coordinates be contained within
a given rectangular geographic bounding box.
|
ParseQuery<T> |
whereWithinKilometers(String key,
ParseGeoPoint point,
double maxDistance)
Add a proximity based constraint for finding objects with key point values near the point given
and within the maximum distance given.
|
ParseQuery<T> |
whereWithinMiles(String key,
ParseGeoPoint point,
double maxDistance)
Add a proximity based constraint for finding objects with key point values near the point given
and within the maximum distance given.
|
ParseQuery<T> |
whereWithinRadians(String key,
ParseGeoPoint point,
double maxDistance)
Add a proximity based constraint for finding objects with key point values near the point given
and within the maximum distance given.
|
public ParseQuery(Class<T> subclass)
ParseObject
subclass type. A default query with no further
parameters will retrieve all ParseObject
s of the provided class.subclass
- The ParseObject
subclass type to retrieve.public ParseQuery(String theClassName)
ParseObject
s of the provided class.theClassName
- The name of the class to retrieve ParseObject
s for.public static <T extends ParseObject> ParseQuery<T> or(List<ParseQuery<T>> queries)
or
of the given queries.queries
- The list of ParseQuery
s to 'or' togetherParseQuery
that is the 'or' of the passed in queriespublic static <T extends ParseObject> ParseQuery<T> getQuery(Class<T> subclass)
ParseObject
subclass type. A default query with no
further parameters will retrieve all ParseObject
s of the provided class.subclass
- The ParseObject
subclass type to retrieve.ParseQuery
.public static <T extends ParseObject> ParseQuery<T> getQuery(String className)
ParseObject
s of the provided class name.className
- The name of the class to retrieve ParseObject
s for.ParseQuery
.@Deprecated public static ParseQuery<ParseUser> getUserQuery()
ParseUser.getQuery()
instead.ParseUser
s.public void cancel()
public List<T> find() throws ParseException
ParseObject
s that satisfy this query.
ParseObject
s obeying the conditions set in this query.ParseException
- Throws a ParseException
if no object is found.ParseException.OBJECT_NOT_FOUND
public T getFirst() throws ParseException
ParseObject
that satisfies this query.
Note:This mutates the ParseQuery
.ParseObject
obeying the conditions set in this query.ParseException
- Throws a ParseException
if no object is found.ParseException.OBJECT_NOT_FOUND
public ParseQuery<T> setCachePolicy(ParseQuery.CachePolicy newCachePolicy)
ParseQuery.fromLocalDatastore()
,
ParseQuery.fromPin()
,
ParseQuery.fromPin(String)
public ParseQuery.CachePolicy getCachePolicy()
public ParseQuery<T> fromLocalDatastore()
ParseQuery.setCachePolicy(CachePolicy)
public ParseQuery<T> fromPin()
ParseObject.DEFAULT_PIN
,
ParseQuery.setCachePolicy(CachePolicy)
public ParseQuery<T> fromPin(String name)
name
- the pinned groupParseQuery.setCachePolicy(CachePolicy)
public ParseQuery<T> ignoreACLs()
public ParseQuery<T> setMaxCacheAge(long maxAgeInMilliseconds)
public long getMaxCacheAge()
public Task<List<T>> findInBackground()
ParseObject
s that satisfy this query from the source in a
background thread.
This is preferable to using ParseQuery.find()
, unless your code is already running in a
background thread.Task
that will be resolved when the find has completed.public void findInBackground(FindCallback<T> callback)
ParseObject
s that satisfy this query from the source in a
background thread.
This is preferable to using ParseQuery.find()
, unless your code is already running in a
background thread.callback
- callback.done(objectList, e) is called when the find completes.public Task<T> getFirstInBackground()
ParseObject
that satisfies this query from the source in a
background thread.
This is preferable to using ParseQuery.getFirst()
, unless your code is already running in a
background thread.
Note:This mutates the ParseQuery
.Task
that will be resolved when the get has completed.public void getFirstInBackground(GetCallback<T> callback)
ParseObject
that satisfies this query from the source in a
background thread.
This is preferable to using ParseQuery.getFirst()
, unless your code is already running in a
background thread.
Note:This mutates the ParseQuery
.callback
- callback.done(object, e) is called when the find completes.public int count() throws ParseException
ParseException
- Throws an exception when the network connection fails or when the query is invalid.public Task<Integer> countInBackground()
Task
that will be resolved when the count has completed.public void countInBackground(CountCallback callback)
callback
- callback.done(count, e) will be called when the count completes.public T get(String objectId) throws ParseException
ParseObject
whose id is already known by fetching data from the source.
Note:This mutates the ParseQuery
.objectId
- Object id of the ParseObject
to fetch.ParseException
- Throws an exception when there is no such object or when the network connection
fails.ParseException.OBJECT_NOT_FOUND
public boolean hasCachedResult()
public void clearCachedResult()
public static void clearAllCachedResults()
public Task<T> getInBackground(String objectId)
ParseObject
whose id is already known by fetching data from the source in a
background thread. This does not use caching.
This is preferable to using the ParseObject.createWithoutData(String, String)
, unless
your code is already running in a background thread.objectId
- Object id of the ParseObject
to fetch.Task
that is resolved when the fetch completes.public void getInBackground(String objectId, GetCallback<T> callback)
ParseObject
whose id is already known by fetching data from the source in
a background thread. This does not use caching.
This is preferable to using the ParseObject.createWithoutData(String, String)
, unless
your code is already running in a background thread.objectId
- Object id of the ParseObject
to fetch.callback
- callback.done(object, e) will be called when the fetch completes.public ParseQuery<T> whereEqualTo(String key, Object value)
key
- The key to check.value
- The value that the ParseObject
must contain.public ParseQuery<T> whereLessThan(String key, Object value)
key
- The key to check.value
- The value that provides an upper bound.public ParseQuery<T> whereNotEqualTo(String key, Object value)
key
- The key to check.value
- The value that must not be equalled.public ParseQuery<T> whereGreaterThan(String key, Object value)
key
- The key to check.value
- The value that provides an lower bound.public ParseQuery<T> whereLessThanOrEqualTo(String key, Object value)
key
- The key to check.value
- The value that provides an upper bound.public ParseQuery<T> whereGreaterThanOrEqualTo(String key, Object value)
key
- The key to check.value
- The value that provides an lower bound.public ParseQuery<T> whereContainedIn(String key, Collection<? extends Object> values)
key
- The key to check.values
- The values that will match.public ParseQuery<T> whereContainsAll(String key, Collection<?> values)
ParseQuery
.
This only works on keys whose values are ParseObject
s or lists of ParseObject
s.
Add a constraint to the query that requires a particular key's value to contain every one of
the provided list of values.key
- The key to check. This key's value must be an array.values
- The values that will match.public ParseQuery<T> whereMatchesQuery(String key, ParseQuery<?> query)
ParseQuery
.
This only works on keys whose values are ParseObject
s or lists of ParseObject
s.key
- The key to check.query
- The query that the value should matchpublic ParseQuery<T> whereDoesNotMatchQuery(String key, ParseQuery<?> query)
ParseQuery
.
This only works on keys whose values are ParseObject
s or lists of ParseObject
s.key
- The key to check.query
- The query that the value should not matchpublic ParseQuery<T> whereMatchesKeyInQuery(String key, String keyInQuery, ParseQuery<?> query)
ParseQuery
.key
- The key whose value is being checkedkeyInQuery
- The key in the objects from the sub query to look inquery
- The sub query to runpublic ParseQuery<T> whereDoesNotMatchKeyInQuery(String key, String keyInQuery, ParseQuery<?> query)
ParseQuery
.key
- The key whose value is being checked and excludedkeyInQuery
- The key in the objects from the sub query to look inquery
- The sub query to runpublic ParseQuery<T> whereNotContainedIn(String key, Collection<? extends Object> values)
key
- The key to check.values
- The values that will not match.public ParseQuery<T> whereNear(String key, ParseGeoPoint point)
key
- The key that the ParseGeoPoint
is stored in.point
- The reference ParseGeoPoint
that is used.public ParseQuery<T> whereWithinMiles(String key, ParseGeoPoint point, double maxDistance)
3958.8
miles.key
- The key that the ParseGeoPoint
is stored in.point
- The reference ParseGeoPoint
that is used.maxDistance
- Maximum distance (in miles) of results to return.public ParseQuery<T> whereWithinKilometers(String key, ParseGeoPoint point, double maxDistance)
6371.0
kilometers.key
- The key that the ParseGeoPoint
is stored in.point
- The reference ParseGeoPoint
that is used.maxDistance
- Maximum distance (in kilometers) of results to return.public ParseQuery<T> whereWithinRadians(String key, ParseGeoPoint point, double maxDistance)
key
- The key that the ParseGeoPoint
is stored in.point
- The reference ParseGeoPoint
that is used.maxDistance
- Maximum distance (in radians) of results to return.public ParseQuery<T> whereWithinGeoBox(String key, ParseGeoPoint southwest, ParseGeoPoint northeast)
key
- The key to be constrained.southwest
- The lower-left inclusive corner of the box.northeast
- The upper-right inclusive corner of the box.public ParseQuery<T> whereMatches(String key, String regex)
key
- The key that the string to match is stored in.regex
- The regular expression pattern to match.public ParseQuery<T> whereMatches(String key, String regex, String modifiers)
key
- The key that the string to match is stored in.regex
- The regular expression pattern to match.modifiers
- Any of the following supported PCRE modifiers:i
- Case insensitive searchm
- Search across multiple lines of inputpublic ParseQuery<T> whereContains(String key, String substring)
key
- The key that the string to match is stored in.substring
- The substring that the value must contain.public ParseQuery<T> whereStartsWith(String key, String prefix)
key
- The key that the string to match is stored in.prefix
- The substring that the value must start with.public ParseQuery<T> whereEndsWith(String key, String suffix)
key
- The key that the string to match is stored in.suffix
- The substring that the value must end with.public ParseQuery<T> include(String key)
ParseObject
s for the provided key.
You can use dot notation to specify which fields in the included object that are also fetched.key
- The key that should be included.public ParseQuery<T> selectKeys(Collection<String> keys)
ParseObject
s to only include the provided keys.
If this is called multiple times, then all of the keys specified in each of the calls will be
included.
Note: This option will be ignored when querying from the local datastore. This
is done since all the keys will be in memory anyway and there will be no performance gain from
removing them.keys
- The set of keys to include in the result.public ParseQuery<T> whereExists(String key)
key
- The key that should exist.public ParseQuery<T> whereDoesNotExist(String key)
key
- The key that should not existpublic ParseQuery<T> orderByAscending(String key)
key
- The key to order by.public ParseQuery<T> addAscendingOrder(String key)
key
- The key to order bypublic ParseQuery<T> orderByDescending(String key)
key
- The key to order by.public ParseQuery<T> addDescendingOrder(String key)
key
- The key to order bypublic ParseQuery<T> setLimit(int newLimit)
100
,
with a maximum of 1000
results being returned at a time.newLimit
- The new limit.public int getLimit()
public ParseQuery<T> setSkip(int newSkip)
newSkip
- The new skippublic int getSkip()
public String getClassName()
public ParseQuery<T> setTrace(boolean shouldTrace)