Class: 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:
new created query
Type
Parse.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:
The query that is the OR of the passed in queries.
Type
Parse.Query

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

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

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

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

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

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

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

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:
A promise that is resolved with the count when the query completes.
Type
Parse.Promise

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

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

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

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

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:
A promise that will be fulfilled once the iteration has completed.
Type
Parse.Promise

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

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

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

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:
A promise that is resolved with the results when the query completes.
Type
Parse.Promise

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:
A promise that is resolved with the object when the query completes.
Type
Parse.Promise

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:
A promise that is resolved with the result when the query completes.
Type
Parse.Promise

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

subscribe() → {LiveQuerySubscription}

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

toJSON() → {Object}

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

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

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

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

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

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

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