com.parse
Class ParseQuery

Object
  extended by com.parse.ParseQuery

public class ParseQuery
extends Object

The ParseQuery class defines a query that is used to fetch ParseObjects. The most common use case is finding all objects that match a query through the 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 query = new ParseQuery("MyClass");
 query.findInBackground(new FindCallback() {
     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 getInBackground 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 query = new ParseQuery("MyClass");
 query.getInBackground(myId, new GetCallback() {
     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 query = new ParseQuery("MyClass");
 query.countInBackground(new FindCallback() {
     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 find, get or 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.


Nested Class Summary
static class ParseQuery.CachePolicy
           
 
Constructor Summary
ParseQuery(String theClassName)
          Constructs a query.
 
Method Summary
 ParseQuery addAscendingOrder(String key)
          Also sorts the results in ascending order by the given key.
 ParseQuery 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.
protected  int count(boolean needsLock)
           
 void countInBackground(CountCallback callback)
          Counts the number of objects that match this query in a background thread.
 List<ParseObject> find()
          Retrieves a list of ParseObjects that satisfy this query.
 List<ParseObject> find(boolean needsLock)
           
 void findInBackground(FindCallback callback)
          Retrieves a list of ParseObjects that satisfy this query from the server in a background thread.
 ParseObject get(String theObjectId)
          Constructs a ParseObject whose id is already known by fetching data from the server.
protected  ParseObject get(String theObjectId, boolean needsLock)
           
 ParseQuery.CachePolicy getCachePolicy()
          Accessor for the caching policy.
 String getClassName()
          Accessor for the class name.
 ParseObject getFirst()
          Retrieves at most one ParseObject that satisfies this query.
protected  ParseObject getFirst(boolean needsLock)
           
 void getFirstInBackground(GetCallback callback)
          Retrieves at most one ParseObject that satisfies this query from the server in a background thread.
 void getInBackground(String objectId, GetCallback callback)
          Constructs a ParseObject whose id is already known by fetching data from the server 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.
 int getSkip()
          Accessor for the skip value.
static ParseQuery getUserQuery()
          Deprecated. Please use ParseUser.getQuery() instead.
 boolean hasCachedResult()
          Returns whether or not this query has a cached result.
 void include(String key)
          Include nested ParseObjects for the provided key.
static ParseQuery or(List<ParseQuery> queries)
          Constructs a query that is the or of the given queries.
 ParseQuery orderByAscending(String key)
          Sorts the results in ascending order by the given key.
 ParseQuery orderByDescending(String key)
          Sorts the results in descending order by the given key.
 void setCachePolicy(ParseQuery.CachePolicy newCachePolicy)
          Change the caching policy of this query.
 void setLimit(int newLimit)
          Controls the maximum number of results that are returned.
 void setMaxCacheAge(long maxAgeInMilliseconds)
          Sets the maximum age of cached data that will be considered in this query.
 void setSkip(int newSkip)
          Controls the number of results to skip before returning any results.
 void setTrace(boolean shouldTrace)
          Turn on performance tracing of finds.
 ParseQuery 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 whereContains(String key, String substring)
          Add a constraint for finding string values that contain a provided string.
 ParseQuery whereContainsAll(String key, Collection<?> values)
          Add a constraint to the query that requires a particular key's value to contain every one of the provided list of values.
 ParseQuery whereDoesNotExist(String key)
          Add a constraint for finding objects that do not contain a given key.
 ParseQuery 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 whereDoesNotMatchQuery(String key, ParseQuery query)
          Add a constraint to the query that requires a particular key's value does not match another ParseQuery.
 ParseQuery whereEndsWith(String key, String suffix)
          Add a constraint for finding string values that end with a provided string.
 ParseQuery 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 whereExists(String key)
          Add a constraint for finding objects that contain the given key.
 ParseQuery 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 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 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 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 whereMatches(String key, String regex)
          Add a regular expression constraint for finding string values that match the provided regular expression.
 ParseQuery whereMatches(String key, String regex, String modifiers)
          Add a regular expression constraint for finding string values that match the provided regular expression.
 ParseQuery 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 whereMatchesQuery(String key, ParseQuery query)
          Add a constraint to the query that requires a particular key's value match another ParseQuery.
 ParseQuery whereNear(String key, ParseGeoPoint point)
          Add a proximity based constraint for finding objects with key point values near the point given.
 ParseQuery 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 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 whereStartsWith(String key, String prefix)
          Add a constraint for finding string values that start with a provided string.
 ParseQuery 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 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 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 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.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ParseQuery

public ParseQuery(String theClassName)
Constructs a query. A default query with no further parameters will retrieve all ParseObjects of the provided class.

Parameters:
theClassName - The name of the class to retrieve ParseObjects for.
Method Detail

or

public static ParseQuery or(List<ParseQuery> queries)
Constructs a query that is the or of the given queries.

Parameters:
queries - The list of ParseQuerys to 'or' together
Returns:
A ParseQuery that is the 'or' of the passed in queries

getUserQuery

@Deprecated
public static ParseQuery getUserQuery()
Deprecated. Please use ParseUser.getQuery() instead.

Constructs a query for ParseUsers


cancel

public void cancel()
Cancels the current network request (if one is running).


find

public List<ParseObject> find()
                       throws ParseException
Retrieves a list of ParseObjects that satisfy this query. Uses the network and/or the cache, depending on the cache policy.

Returns:
A list of all ParseObjects obeying the conditions set in this query.
Throws:
ParseException

find

public List<ParseObject> find(boolean needsLock)
                       throws ParseException
Throws:
ParseException

getFirst

public ParseObject getFirst()
                     throws ParseException
Retrieves at most one ParseObject that satisfies this query. Uses the network and/or the cache, depending on the cache policy. This mutates the ParseQuery.

Returns:
A ParseObject obeying the conditions set in this query, or null if none found.
Throws:
ParseException - Throws a ParseException if no object is found.

getFirst

protected ParseObject getFirst(boolean needsLock)
                        throws ParseException
Throws:
ParseException

setCachePolicy

public void setCachePolicy(ParseQuery.CachePolicy newCachePolicy)
Change the caching policy of this query.


getCachePolicy

public ParseQuery.CachePolicy getCachePolicy()
Accessor for the caching policy.


setMaxCacheAge

public void setMaxCacheAge(long maxAgeInMilliseconds)
Sets the maximum age of cached data that will be considered in this query.


getMaxCacheAge

public long getMaxCacheAge()
Gets the maximum age of cached data that will be considered in this query. The returned value is in milliseconds


findInBackground

public void findInBackground(FindCallback callback)
Retrieves a list of ParseObjects that satisfy this query from the server in a background thread. This is preferable to using find(), unless your code is already running in a background thread.

Parameters:
callback - callback.done(objectList, e) is called when the find completes.

getFirstInBackground

public void getFirstInBackground(GetCallback callback)
Retrieves at most one ParseObject that satisfies this query from the server in a background thread. This is preferable to using getFirst(), unless your code is already running in a background thread. This mutates the ParseQuery.

Parameters:
callback - callback.done(object, e) is called when the find completes.

count

public int count()
          throws ParseException
Counts the number of objects that match this query. This does not use caching.

Throws:
ParseException - Throws an exception when the network connection fails or when the query is invalid.

count

protected int count(boolean needsLock)
             throws ParseException
Throws:
ParseException

countInBackground

public void countInBackground(CountCallback callback)
Counts the number of objects that match this query in a background thread. This does not use caching.

Parameters:
callback - callback.done(count, e) will be called when the count completes.

get

public ParseObject get(String theObjectId)
                throws ParseException
Constructs a ParseObject whose id is already known by fetching data from the server. This mutates the ParseQuery.

Parameters:
theObjectId - Object id of the ParseObject to fetch.
Throws:
ParseException - Throws an exception when there is no such object or when the network connection fails.

get

protected ParseObject get(String theObjectId,
                          boolean needsLock)
                   throws ParseException
Throws:
ParseException

hasCachedResult

public boolean hasCachedResult()
Returns whether or not this query has a cached result.


clearCachedResult

public void clearCachedResult()
Removes the previously cached result for this query, forcing the next find() to hit the network. If there is no cached result for this query, then this is a no-op.


clearAllCachedResults

public static void clearAllCachedResults()
Clears the cached result for all queries.


getInBackground

public void getInBackground(String objectId,
                            GetCallback callback)
Constructs a ParseObject whose id is already known by fetching data from the server in a background thread. This does not use caching. This is preferable to using the ParseObject(className, objectId) constructor, unless your code is already running in a background thread.

Parameters:
objectId - Object id of the ParseObject to fetch.
callback - callback.done(object, e) will be called when the fetch completes.

whereEqualTo

public ParseQuery 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.

Parameters:
key - The key to check.
value - The value that the ParseObject must contain.
Returns:
Returns the query, so you can chain this call.

whereLessThan

public ParseQuery 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.

Parameters:
key - The key to check.
value - The value that provides an upper bound.
Returns:
Returns the query, so you can chain this call.

whereNotEqualTo

public ParseQuery 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.

Parameters:
key - The key to check.
value - The value that must not be equalled.
Returns:
Returns the query, so you can chain this call.

whereGreaterThan

public ParseQuery 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.

Parameters:
key - The key to check.
value - The value that provides an lower bound.
Returns:
Returns the query, so you can chain this call.

whereLessThanOrEqualTo

public ParseQuery 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.

Parameters:
key - The key to check.
value - The value that provides an upper bound.
Returns:
Returns the query, so you can chain this call.

whereGreaterThanOrEqualTo

public ParseQuery 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.

Parameters:
key - The key to check.
value - The value that provides an lower bound.
Returns:
Returns the query, so you can chain this call.

whereContainedIn

public ParseQuery 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.

Parameters:
key - The key to check.
values - The values that will match.
Returns:
Returns the query, so you can chain this call.

whereContainsAll

public ParseQuery whereContainsAll(String key,
                                   Collection<?> values)
Add a constraint to the query that requires a particular key's value to contain every one of the provided list of values.

Parameters:
key - The key to check. This key's value must be an array.
values - The values that will match.
Returns:
Returns the query, so you can chain this call.

whereMatchesQuery

public ParseQuery whereMatchesQuery(String key,
                                    ParseQuery query)
Add a constraint to the query that requires a particular key's value match another ParseQuery. This only works on keys whose values are ParseObjects or lists of ParseObjects.

Parameters:
key - The key to check.
query - The query that the value should match
Returns:
Returns the query so you can chain this call.

whereDoesNotMatchQuery

public ParseQuery whereDoesNotMatchQuery(String key,
                                         ParseQuery query)
Add a constraint to the query that requires a particular key's value does not match another ParseQuery. This only works on keys whose values are ParseObjects or lists of ParseObjects.

Parameters:
key - The key to check.
query - The query that the value should not match
Returns:
Returns the query so you can chain this call.

whereMatchesKeyInQuery

public ParseQuery 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

Parameters:
key - The key whose value is being checked
keyInQuery - The key in the objects from the sub query to look in
query - The sub query to run
Returns:
Returns the query so you can chain this call.

whereDoesNotMatchKeyInQuery

public ParseQuery 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.

Parameters:
key - The key whose value is being checked and excluded
keyInQuery - The key in the objects from the sub query to look in
query - The sub query to run
Returns:
Returns the query so you can chain this call.

whereNotContainedIn

public ParseQuery 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.

Parameters:
key - The key to check.
values - The values that will not match.
Returns:
Returns the query, so you can chain this call.

whereNear

public ParseQuery whereNear(String key,
                            ParseGeoPoint point)
Add a proximity based constraint for finding objects with key point values near the point given.

Parameters:
key - The key that the ParseGeoPoint is stored in.
point - The reference ParseGeoPoint that is used.
Returns:
Returns the query, so you can chain this call.

whereWithinMiles

public ParseQuery 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. Radius of earth used is 3958.8 miles.

Parameters:
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.
Returns:
Returns the query, so you can chain this call.

whereWithinKilometers

public ParseQuery 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. Radius of earth used is 6371.0 kilometers.

Parameters:
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.
Returns:
Returns the query, so you can chain this call.

whereWithinRadians

public ParseQuery 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.

Parameters:
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.
Returns:
Returns the query, so you can chain this call.

whereWithinGeoBox

public ParseQuery 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.

Parameters:
key - The key to be constrained.
southwest - The lower-left inclusive corner of the box.
northeast - The upper-right inclusive corner of the box.
Returns:
Returns the query, so you can chain this call.

whereMatches

public ParseQuery whereMatches(String key,
                               String regex)
Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large datasets.

Parameters:
key - The key that the string to match is stored in.
regex - The regular expression pattern to match.
Returns:
Returns the query, so you can chain this call.

whereMatches

public ParseQuery whereMatches(String key,
                               String regex,
                               String modifiers)
Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large datasets.

Parameters:
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 search
m - Search across multiple lines of input
Returns:
Returns the query, so you can chain this call.

whereContains

public ParseQuery whereContains(String key,
                                String substring)
Add a constraint for finding string values that contain a provided string. This will be slow for large datasets.

Parameters:
key - The key that the string to match is stored in.
substring - The substring that the value must contain.
Returns:
Returns the query, so you can chain this call.

whereStartsWith

public ParseQuery whereStartsWith(String key,
                                  String prefix)
Add a constraint for finding string values that start with a provided string. This query will use the backend index, so it will be fast even for large datasets.

Parameters:
key - The key that the string to match is stored in.
prefix - The substring that the value must start with.
Returns:
Returns the query, so you can chain this call.

whereEndsWith

public ParseQuery whereEndsWith(String key,
                                String suffix)
Add a constraint for finding string values that end with a provided string. This will be slow for large datasets.

Parameters:
key - The key that the string to match is stored in.
suffix - The substring that the value must end with.
Returns:
Returns the query, so you can chain this call.

include

public void include(String key)
Include nested ParseObjects for the provided key. You can use dot notation to specify which fields in the included object that are also fetched.

Parameters:
key - The key that should be included.

whereExists

public ParseQuery whereExists(String key)
Add a constraint for finding objects that contain the given key.

Parameters:
key - The key that should exist.

whereDoesNotExist

public ParseQuery whereDoesNotExist(String key)
Add a constraint for finding objects that do not contain a given key.

Parameters:
key - The key that should not exist

orderByAscending

public ParseQuery orderByAscending(String key)
Sorts the results in ascending order by the given key.

Parameters:
key - The key to order by.
Returns:
Returns the query, so you can chain this call.

addAscendingOrder

public ParseQuery addAscendingOrder(String key)
Also sorts the results in ascending order by the given key. The previous sort keys have precedence over this key.

Parameters:
key - The key to order by
Returns:
Returns the query so you can chain this call.

orderByDescending

public ParseQuery orderByDescending(String key)
Sorts the results in descending order by the given key.

Parameters:
key - The key to order by.
Returns:
Returns the query, so you can chain this call.

addDescendingOrder

public ParseQuery addDescendingOrder(String key)
Also sorts the results in descending order by the given key. The previous sort keys have precedence over this key.

Parameters:
key - The key to order by
Returns:
Returns the query so you can chain this call.

setLimit

public void setLimit(int newLimit)
Controls the maximum number of results that are returned. Setting a negative limit denotes retrieval without a limit.

Parameters:
newLimit -

setTrace

public void setTrace(boolean shouldTrace)
Turn on performance tracing of finds. If performance tracing is already turned on this does nothing. In general you don't need to call trace.


getLimit

public int getLimit()
Accessor for the limit.


setSkip

public void setSkip(int newSkip)
Controls the number of results to skip before returning any results. This is useful for pagination. Default is to skip zero results.

Parameters:
newSkip -

getSkip

public int getSkip()
Accessor for the skip value.


getClassName

public String getClassName()
Accessor for the class name.