API Docs for:

Class Parse.Query

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

Parse.Query( objectClass )
Parameters:
  • objectClass <Object>

    An instance of a subclass of Parse.Object, or a Parse className string.

    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. } });

Parse.Query _orQuery( queries )

Adds constraint that at least one of the passed in queries matches.

Parameters:
  • queries <Array>

Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query addAscending( key )

Sorts the results in ascending order by the given key, but can also add secondary sort descriptors without overwriting _order.

Parameters:
  • key <(String | String | ...String>

    The key to order by, which is a string of comma separated values, or an Array of keys, or multiple keys.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query addDescending( key )

Sorts the results in descending order by the given key, but can also add secondary sort descriptors without overwriting _order.

Parameters:
  • key <(String | String | ...String>

    The key to order by, which is a string of comma separated values, or an Array of keys, or multiple keys.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query ascending( key )

Sorts the results in ascending order by the given key.

Parameters:
  • key <(String | String | ...String>

    The key to order by, which is a string of comma separated values, or an Array of keys, or multiple keys.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query containedIn( key, values )

Adds a constraint to the query that requires a particular key's value to be contained in the provided list of values.

Parameters:
  • key <String>

    The key to check.

  • values <Array>

    The values that will match.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query contains( key, substring )

Adds a constraint for finding string values that contain a provided string. This may be slow for large datasets.

Parameters:
  • key <String>

    The key that the string to match is stored in.

  • substring <String>

    The substring that the value must contain.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query containsAll( key, values )

Adds a constraint to the query that requires a particular key's value to contain each one of the provided list of values.

Parameters:
  • key <String>

    The key to check. This key's value must be an array.

  • values <Array>

    The values that will match.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Promise count( options )

Counts the number of objects that match this query. Either options.success or options.error is called when the count completes.

Parameters:
  • 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: <Parse.Promise>

A promise that is resolved with the count when the query completes.

Parse.Query descending( key )

Sorts the results in descending order by the given key.

Parameters:
  • key <(String | String | ...String>

    The key to order by, which is a string of comma separated values, or an Array of keys, or multiple keys.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query doesNotExist( key )

Adds a constraint for finding objects that do not contain a given key.

Parameters:
  • key <String>

    The key that should not exist


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query doesNotMatchKeyInQuery( key, queryKey, 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:
  • 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: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query doesNotMatchQuery( key, query )

Adds a constraint that requires that a key's value not matches a Parse.Query constraint.

Parameters:
  • key <String>

    The key that the contains the object to match the query.

  • query <Parse.Query>

    The query that should not match.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Promise each( callback, options )

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:
  • callback <Function>

    Callback that will be called with each result of the query.

  • options <Object>

    An optional Backbone-like options object with success and error callbacks that will be invoked once the iteration has finished.


Returns: <Parse.Promise>

A promise that will be fulfilled once the iteration has completed.

Parse.Query endsWith( key, suffix )

Adds a constraint for finding string values that end with a provided string. This will be slow for large datasets.

Parameters:
  • key <String>

    The key that the string to match is stored in.

  • suffix <String>

    The substring that the value must end with.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query equalTo( key, value )

Adds a constraint to the query that requires a particular key's value to be equal to the provided value.

Parameters:
  • key <String>

    The key to check.

  • value <Object>

    The value that the Parse.Object must contain.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query exists( key )

Adds a constraint for finding objects that contain the given key.

Parameters:
  • key <String>

    The key that should exist.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Promise find( options )

Retrieves a list of ParseObjects that satisfy this query. Either options.success or options.error is called when the find completes.

Parameters:
  • 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: <Parse.Promise>

A promise that is resolved with the results when the query completes.

Parse.Promise first( options )

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:
  • 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: <Parse.Promise>

A promise that is resolved with the object when the query completes.

Parse.Promise get( objectId, options )

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:
  • 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: <Parse.Promise>

A promise that is resolved with the result when the query completes.

Parse.Query greaterThan( key, value )

Adds a constraint to the query that requires a particular key's value to be greater than the provided value.

Parameters:
  • key <String>

    The key to check.

  • value <Object>

    The value that provides an lower bound.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query greaterThanOrEqualTo( key, value )

Adds a constraint to the query that requires a particular key's value to be greater than or equal to the provided value.

Parameters:
  • key <String>

    The key to check.

  • value <Object>

    The value that provides an lower bound.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query include( key )

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:
  • key <String>

    The name of the key to include.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query lessThan( key, value )

Adds a constraint to the query that requires a particular key's value to be less than the provided value.

Parameters:
  • key <String>

    The key to check.

  • value <Object>

    The value that provides an upper bound.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query lessThanOrEqualTo( key, value )

Adds a constraint to the query that requires a particular key's value to be less than or equal to the provided value.

Parameters:
  • key <String>

    The key to check.

  • value <Object>

    The value that provides an upper bound.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query limit( n )

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:
  • n <Number>

    the number of results to limit to.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query matches( key, regex )

Adds a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large datasets.

Parameters:
  • key <String>

    The key that the string to match is stored in.

  • regex <RegExp>

    The regular expression pattern to match.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query matchesKeyInQuery( key, queryKey, query )

Adds a constraint that requires that a key's value matches a value in an object returned by a different Parse.Query.

Parameters:
  • 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: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query matchesQuery( key, query )

Adds a constraint that requires that a key's value matches a Parse.Query constraint.

Parameters:
  • key <String>

    The key that the contains the object to match the query.

  • query <Parse.Query>

    The query that should match.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query near( key, point )

Adds a proximity based constraint for finding objects with key point values near the point given.

Parameters:
  • key <String>

    The key that the Parse.GeoPoint is stored in.

  • point <Parse.GeoPoint>

    The reference Parse.GeoPoint that is used.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query notContainedIn( key, values )

Adds a constraint to the query that requires a particular key's value to not be contained in the provided list of values.

Parameters:
  • key <String>

    The key to check.

  • values <Array>

    The values that will not match.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query notEqualTo( key, value )

Adds a constraint to the query that requires a particular key's value to be not equal to the provided value.

Parameters:
  • key <String>

    The key to check.

  • value <Object>

    The value that must not be equalled.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query or( var_args )

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:
  • var_args <...Parse.Query>

    The list of queries to OR.


Returns: <Parse.Query>

The query that is the OR of the passed in queries.

Parse.Query select( keys )

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:
  • keys <Array>

    The names of the keys to include.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query skip( n )

Sets the number of results to skip before returning any results. This is useful for pagination. Default is to skip zero results.

Parameters:
  • n <Number>

    the number of results to skip.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query startsWith( key, prefix )

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:
  • key <String>

    The key that the string to match is stored in.

  • prefix <String>

    The substring that the value must start with.


Returns: <Parse.Query>

Returns the query, so you can chain this call.

Object toJSON( )

Returns a JSON representation of this query.


Returns: <Object>

The JSON representation of the query.

Parse.Query withinGeoBox( key, southwest, northeast )

Adds a constraint to the query that requires a particular key's coordinates be contained within a given rectangular geographic bounding box.

Parameters:
  • 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: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query withinKilometers( key, point, maxDistance )

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:
  • 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: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query withinMiles( key, point, maxDistance )

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:
  • 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: <Parse.Query>

Returns the query, so you can chain this call.

Parse.Query withinRadians( key, point, maxDistance )

Adds a proximity based constraint for finding objects with key point values near the point given and within the maximum distance given.

Parameters:
  • 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: <Parse.Query>

Returns the query, so you can chain this call.