Query

Parse. Query

Creates a new parse Parse.Query for the given Parse.Object subclass.

Parse.Query defines a query that is used to fetch Parse.Objects. The most common use case is finding all objects that match a query through the find method. for example, this sample code fetches all objects of class myclass. it calls a different function depending on whether the fetch succeeded or not. 

var query = new parse.query(myclass);
query.find({
  success: function(results) {
    // results is an array of parse.object.
  },

  error: function(error) {
    // error is an instance of parse.error.
  }
});

a parse.query can also be used to retrieve a single object whose id is known, through the get method. 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. 

var query = new parse.query(myclass);
query.get(myid, {
  success: function(object) {
    // object is an instance of parse.object.
  },

  error: function(object, error) {
    // error is an instance of parse.error.
  }
});

a parse.query 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 

var query = new parse.query(myclass);
query.count({
  success: function(number) {
    // there are number instances of myclass.
  },

  error: function(error) {
    // error is an instance of Parse.Error.
  }
});

Constructor

new Query()

Methods

(static) fromJSON(className, json) → {Parse.Query}

Static method to restore Parse.Query by json representation Internally calling Parse.Query.withJSON
Parameters:
Name Type Description
className String
json QueryJSON from Parse.Query.toJSON() method
Returns:
Type:
Parse.Query
new created query

(static) or(…var_args) → {Parse.Query}

Constructs a Parse.Query that is the OR of the passed in queries. For example: 
var compoundQuery = Parse.Query.or(query1, query2, query3);
will create a compoundQuery that is an or of the query1, query2, and query3.
Parameters:
Name Type Attributes Description
var_args Parse.Query <repeatable>
 The list of queries to OR.
Returns:
Type:
Parse.Query
The query that is the OR of the passed in queries.

_addCondition()

Helper for condition queries

_orQuery(queries) → {Parse.Query}

Adds constraint that at least one of the passed in queries matches.
Parameters:
Name Type Description
queries Array
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

addAscending(key) → {Parse.Query}

Sorts the results in ascending order by the given key, but can also add secondary sort descriptors without overwriting _order.
Parameters:
Name Type Description
key String | Array.<String> | String The key to order by, which is a string of comma separated values, or an Array of keys, or multiple keys.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

addDescending(key) → {Parse.Query}

Sorts the results in descending order by the given key, but can also add secondary sort descriptors without overwriting _order.
Parameters:
Name Type Description
key String | Array.<String> | String The key to order by, which is a string of comma separated values, or an Array of keys, or multiple keys.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

ascending(key) → {Parse.Query}

Sorts the results in ascending order by the given key.
Parameters:
Name Type Description
key String | Array.<String> | String The key to order by, which is a string of comma separated values, or an Array of keys, or multiple keys.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

containedIn(key, values) → {Parse.Query}

Adds a constraint to the query that requires a particular key's value to be contained in the provided list of values.
Parameters:
Name Type Description
key String The key to check.
values Array The values that will match.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

contains(key, substring) → {Parse.Query}

Adds a constraint for finding string values that contain a provided string. This may be slow for large datasets.
Parameters:
Name Type Description
key String The key that the string to match is stored in.
substring String The substring that the value must contain.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

containsAll(key, values) → {Parse.Query}

Adds a constraint to the query that requires a particular key's value to contain each one of the provided list of values.
Parameters:
Name Type Description
key String The key to check. This key's value must be an array.
values Array The values that will match.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

count(options) → {Parse.Promise}

Counts the number of objects that match this query. Either options.success or options.error is called when the count completes.
Parameters:
Name Type Description
options Object A Backbone-style options object. Valid options are:
  • success: Function to call when the count completes successfully.
  • error: Function to call when the find fails.
  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
Returns:
Type:
Parse.Promise
A promise that is resolved with the count when the query completes.

descending(key) → {Parse.Query}

Sorts the results in descending order by the given key.
Parameters:
Name Type Description
key String | Array.<String> | String The key to order by, which is a string of comma separated values, or an Array of keys, or multiple keys.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

doesNotExist(key) → {Parse.Query}

Adds a constraint for finding objects that do not contain a given key.
Parameters:
Name Type Description
key String The key that should not exist
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

doesNotMatchKeyInQuery(key, queryKey, query) → {Parse.Query}

Adds a constraint that requires that a key's value not match a value in an object returned by a different Parse.Query.
Parameters:
Name Type Description
key String The key that contains the value that is being excluded.
queryKey String The key in the objects returned by the query to match against.
query Parse.Query The query to run.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

doesNotMatchQuery(key, query) → {Parse.Query}

Adds a constraint that requires that a key's value not matches a Parse.Query constraint.
Parameters:
Name Type Description
key String The key that the contains the object to match the query.
query Parse.Query The query that should not match.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

each(callback, options) → {Parse.Promise}

Iterates over each result of a query, calling a callback for each one. If the callback returns a promise, the iteration will not continue until that promise has been fulfilled. If the callback returns a rejected promise, then iteration will stop with that error. The items are processed in an unspecified order. The query may not have any sort order, and may not use limit or skip.
Parameters:
Name Type Description
callback function Callback that will be called with each result of the query.
options Object A Backbone-style options object. Valid options are:
  • success: Function to call when the iteration completes successfully.
  • error: Function to call when the iteration fails.
  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
Returns:
Type:
Parse.Promise
A promise that will be fulfilled once the iteration has completed.

endsWith(key, suffix) → {Parse.Query}

Adds a constraint for finding string values that end with a provided string. This will be slow for large datasets.
Parameters:
Name Type Description
key String The key that the string to match is stored in.
suffix String The substring that the value must end with.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

equalTo(key, value) → {Parse.Query}

Adds a constraint to the query that requires a particular key's value to be equal to the provided value.
Parameters:
Name Type Description
key String The key to check.
value The value that the Parse.Object must contain.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

exists(key) → {Parse.Query}

Adds a constraint for finding objects that contain the given key.
Parameters:
Name Type Description
key String The key that should exist.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

find(options) → {Parse.Promise}

Retrieves a list of ParseObjects that satisfy this query. Either options.success or options.error is called when the find completes.
Parameters:
Name Type Description
options Object A Backbone-style options object. Valid options are:
  • success: Function to call when the find completes successfully.
  • error: Function to call when the find fails.
  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
Returns:
Type:
Parse.Promise
A promise that is resolved with the results when the query completes.

first(options) → {Parse.Promise}

Retrieves at most one Parse.Object that satisfies this query. Either options.success or options.error is called when it completes. success is passed the object if there is one. otherwise, undefined.
Parameters:
Name Type Description
options Object A Backbone-style options object. Valid options are:
  • success: Function to call when the find completes successfully.
  • error: Function to call when the find fails.
  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
Returns:
Type:
Parse.Promise
A promise that is resolved with the object when the query completes.

get(objectId, options) → {Parse.Promise}

Constructs a Parse.Object whose id is already known by fetching data from the server. Either options.success or options.error is called when the find completes.
Parameters:
Name Type Description
objectId String The id of the object to be fetched.
options Object A Backbone-style options object. Valid options are:
  • success: A Backbone-style success callback
  • error: An Backbone-style error callback.
  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
Returns:
Type:
Parse.Promise
A promise that is resolved with the result when the query completes.

greaterThan(key, value) → {Parse.Query}

Adds a constraint to the query that requires a particular key's value to be greater than the provided value.
Parameters:
Name Type Description
key String The key to check.
value The value that provides an lower bound.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

greaterThanOrEqualTo(key, value) → {Parse.Query}

Adds a constraint to the query that requires a particular key's value to be greater than or equal to the provided value.
Parameters:
Name Type Description
key String The key to check.
value The value that provides an lower bound.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

include(key) → {Parse.Query}

Includes nested Parse.Objects for the provided key. You can use dot notation to specify which fields in the included object are also fetched.
Parameters:
Name Type Description
key String The name of the key to include.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

lessThan(key, value) → {Parse.Query}

Adds a constraint to the query that requires a particular key's value to be less than the provided value.
Parameters:
Name Type Description
key String The key to check.
value The value that provides an upper bound.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

lessThanOrEqualTo(key, value) → {Parse.Query}

Adds a constraint to the query that requires a particular key's value to be less than or equal to the provided value.
Parameters:
Name Type Description
key String The key to check.
value The value that provides an upper bound.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

limit(n) → {Parse.Query}

Sets the limit of the number of results to return. The default limit is 100, with a maximum of 1000 results being returned at a time.
Parameters:
Name Type Description
n Number the number of results to limit to.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

matches(key, regex) → {Parse.Query}

Adds a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large datasets.
Parameters:
Name Type Description
key String The key that the string to match is stored in.
regex RegExp The regular expression pattern to match.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

matchesKeyInQuery(key, queryKey, query) → {Parse.Query}

Adds a constraint that requires that a key's value matches a value in an object returned by a different Parse.Query.
Parameters:
Name Type Description
key String The key that contains the value that is being matched.
queryKey String The key in the objects returned by the query to match against.
query Parse.Query The query to run.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

matchesQuery(key, query) → {Parse.Query}

Adds a constraint that requires that a key's value matches a Parse.Query constraint.
Parameters:
Name Type Description
key String The key that the contains the object to match the query.
query Parse.Query The query that should match.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

near(key, point) → {Parse.Query}

Adds a proximity based constraint for finding objects with key point values near the point given.
Parameters:
Name Type Description
key String The key that the Parse.GeoPoint is stored in.
point Parse.GeoPoint The reference Parse.GeoPoint that is used.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

notContainedIn(key, values) → {Parse.Query}

Adds a constraint to the query that requires a particular key's value to not be contained in the provided list of values.
Parameters:
Name Type Description
key String The key to check.
values Array The values that will not match.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

notEqualTo(key, value) → {Parse.Query}

Adds a constraint to the query that requires a particular key's value to be not equal to the provided value.
Parameters:
Name Type Description
key String The key to check.
value The value that must not be equalled.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

polygonContains(key, GeoPoint) → {Parse.Query}

Add a constraint to the query that requires a particular key's coordinates that contains a ParseGeoPoint
Parameters:
Name Type Description
key String The key to be constrained.
GeoPoint Parse.GeoPoint
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

select(…keys) → {Parse.Query}

Restricts the fields of the returned Parse.Objects to include only the provided keys. If this is called multiple times, then all of the keys specified in each of the calls will be included.
Parameters:
Name Type Attributes Description
keys Array <repeatable>
 The names of the keys to include.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

skip(n) → {Parse.Query}

Sets the number of results to skip before returning any results. This is useful for pagination. Default is to skip zero results.
Parameters:
Name Type Description
n Number the number of results to skip.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

startsWith(key, prefix) → {Parse.Query}

Adds 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:
Name Type Description
key String The key that the string to match is stored in.
prefix String The substring that the value must start with.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

subscribe() → {LiveQuerySubscription}

Subscribe this query to get liveQuery updates
Returns:
Type:
LiveQuerySubscription
Returns the liveQuerySubscription, it's an event emitter which can be used to get liveQuery updates.

toJSON() → {Object}

Returns a JSON representation of this query.
Returns:
Type:
Object
The JSON representation of the query.

withinGeoBox(key, southwest, northeast) → {Parse.Query}

Adds a constraint to the query that requires a particular key's coordinates be contained within a given rectangular geographic bounding box.
Parameters:
Name Type Description
key String The key to be constrained.
southwest Parse.GeoPoint The lower-left inclusive corner of the box.
northeast Parse.GeoPoint The upper-right inclusive corner of the box.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

withinKilometers(key, point, maxDistance) → {Parse.Query}

Adds 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:
Name Type Description
key String The key that the Parse.GeoPoint is stored in.
point Parse.GeoPoint The reference Parse.GeoPoint that is used.
maxDistance Number Maximum distance (in kilometers) of results to return.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

withinMiles(key, point, maxDistance) → {Parse.Query}

Adds 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:
Name Type Description
key String The key that the Parse.GeoPoint is stored in.
point Parse.GeoPoint The reference Parse.GeoPoint that is used.
maxDistance Number Maximum distance (in miles) of results to return.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

withinPolygon(key, array) → {Parse.Query}

Adds a constraint to the query that requires a particular key's coordinates be contained within and on the bounds of a given polygon. Supports closed and open (last point is connected to first) paths Polygon must have at least 3 points
Parameters:
Name Type Description
key String The key to be constrained.
array Array of geopoints
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

withinRadians(key, point, maxDistance) → {Parse.Query}

Adds a proximity based constraint for finding objects with key point values near the point given and within the maximum distance given.
Parameters:
Name Type Description
key String The key that the Parse.GeoPoint is stored in.
point Parse.GeoPoint The reference Parse.GeoPoint that is used.
maxDistance Number Maximum distance (in radians) of results to return.
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.

withJSON(json) → {Parse.Query}

Return a query with conditions from json, can be useful to send query from server side to client Not static, all query conditions was set before calling this method will be deleted. For example on the server side we have var query = new Parse.Query("className"); query.equalTo(key: value); query.limit(100); ... (others queries) Create JSON representation of Query Object var jsonFromServer = query.fromJSON(); On client side getting query: var query = new Parse.Query("className"); query.fromJSON(jsonFromServer); and continue to query... query.skip(100).find().then(...);
Parameters:
Name Type Description
json QueryJSON from Parse.Query.toJSON() method
Returns:
Type:
Parse.Query
Returns the query, so you can chain this call.