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.

aggregate(pipeline, options) → {Parse.Promise}

Executes an aggregate query and returns aggregate results

Parameters:
Name Type Description
pipeline Mixed

Array or Object of stages to process query
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.
  • 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 query completes.

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.

distinct(key, options) → {Parse.Promise}

Executes a distinct query and returns unique values

Parameters:
Name Type Description
key String

A field to find distinct values
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.
  • 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 query completes.

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.

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

Adds a constraint for finding string values that contain a provided string. This may be slow for large datasets. Requires Parse-Server > 2.5.0

In order to sort you must use select and ascending ($score is required) 

  query.fullText('term');
  query.ascending('$score');
  query.select('$score');

To retrieve the weight / rank 

  object->get('score');

Parameters:
Name Type Description
key String

The key that the string to match is stored in.
value String

The string to search
Returns:
Type:
Parse.Query

Returns the query, so you can chain this call.

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.