# Query

## AV. Query

AV.Query defines a query that is used to fetch AV.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 AV.Query(MyClass);
    query.find().then(function(results) {
      // results is an array of AV.Object.
    }, function(error) {
      // error is an instance of AVError.
    });

An AV.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 AV.Query(MyClass);
    query.get(myId).then(function(object) {
      // object is an instance of AV.Object.
    }, function(error) {
      // error is an instance of AVError.
    });

An AV.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 AV.Query(MyClass);
    query.count().then(function(number) {
      // There are number instances of MyClass.
    }, function(error) {
      // error is an instance of AVError.
    });

## Constructor

#### new Query(objectClass)

Source:
  - query.js, line 59

Creates a new AV.Query for the given AV.Object subclass.

##### Parameters:

Name | Type | Description
--- | --- | ---
`objectClass` | Class | String | An instance of a subclass of AV.Object, or a AV className string.

### Methods

#### (static) and(…var_args) → {AV.Query}

Source:
  - query.js, line 113

Constructs a AV.Query that is the AND of the passed in queries. For example:

    var compoundQuery = AV.Query.and(query1, query2, query3);

will create a compoundQuery that is an 'and' of the query1, query2, and query3.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`var_args` | AV.Query | <repeatable> | The list of queries to AND.

##### Returns:

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

Type
  AV.Query

#### (static) doCloudQuery(cql, pvalues, options) → {Promise}

Source:
  - query.js, line 140

Retrieves a list of AVObjects that satisfy the CQL. CQL syntax please see CQL Guide.

##### Parameters:

Name | Type | Description
--- | --- | ---
`cql` | String | A CQL string, see CQL Guide.
`pvalues` | Array | An array contains placeholder values.
`options` | AuthOptions |

##### Returns:

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

Type
  Promise

#### (static) or(…var_args) → {AV.Query}

Source:
  - query.js, line 86

Constructs a AV.Query that is the OR of the passed in queries. For example:

    var compoundQuery = AV.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` | AV.Query | <repeatable> | The list of queries to OR.

##### Returns:

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

Type
  AV.Query

#### addAscending(key) → {AV.Query}

Source:
  - query.js, line 846

Also sorts the results in ascending order by the given key. The previous sort keys have precedence over this key.

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The key to order by

##### Returns:

Returns the query so you can chain this call.

Type
  AV.Query

#### addDescending(key) → {AV.Query}

Source:
  - query.js, line 872

Also sorts the results in descending order by the given key. The previous sort keys have precedence over this key.

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The key to order by

##### Returns:

Returns the query so you can chain this call.

Type
  AV.Query

#### ascending(key) → {AV.Query}

Source:
  - query.js, line 833

Sorts the results in ascending order by the given key.

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The key to order by.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### containedIn(key, values) → {AV.Query}

Source:
  - query.js, line 605

Add 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
  AV.Query

#### contains(key, substring) → {AV.Query}

Source:
  - query.js, line 797

Add 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
  AV.Query

#### containsAll(key, values) → {AV.Query}

Source:
  - query.js, line 629

Add 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
  AV.Query

#### count(options) → {Promise}

Source:
  - query.js, line 435

Counts the number of objects that match this query.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | AuthOptions |

##### Returns:

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

Type
  Promise

#### descending(key) → {AV.Query}

Source:
  - query.js, line 859

Sorts the results in descending order by the given key.

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The key to order by.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### destroyAll(options) → {Promise}

Source:
  - query.js, line 421

Delete objects retrieved by this query.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | AuthOptions |

##### Returns:

A promise that is fulfilled when the save completes.

Type
  Promise

#### doesNotExist(key) → {AV.Query}

Source:
  - query.js, line 649

Add 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
  AV.Query

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

Source:
  - query.js, line 740

Add a constraint that requires that a key's value not match a value in an object returned by a different AV.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` | AV.Query | The query to run.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### doesNotMatchQuery(key, query) → {AV.Query}

Source:
  - query.js, line 706

Add a constraint that requires that a key's value not matches a AV.Query constraint.

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The key that the contains the object to match the query.
`query` | AV.Query | The query that should not match.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### each(callback) → {Promise}

Source:
  - query.js, line 1010

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.

##### Returns:

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

Type
  Promise

#### endsWith(key, suffix) → {AV.Query}

Source:
  - query.js, line 822

Add 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
  AV.Query

#### equalTo(key, value) → {AV.Query}

Source:
  - query.js, line 503

Add 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 AV.Object must contain.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### exists(key) → {AV.Query}

Source:
  - query.js, line 639

Add 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
  AV.Query

#### find(options) → {Promise}

Source:
  - query.js, line 321

Retrieves a list of AVObjects that satisfy this query.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | AuthOptions |

##### Returns:

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

Type
  Promise

#### first(options) → {Promise}

Source:
  - query.js, line 453

Retrieves at most one AV.Object that satisfies this query.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | AuthOptions |

##### Returns:

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

Type
  Promise

#### get(objectId, options) → {Promise.<AV.Object>}

Source:
  - query.js, line 185

Constructs an AV.Object whose id is already known by fetching data from the server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`objectId` | String | The id of the object to be fetched.
`options` | AuthOptions |

##### Returns:

Type
  Promise.<AV.Object>

#### greaterThan(key, value) → {AV.Query}

Source:
  - query.js, line 569

Add 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
  AV.Query

#### greaterThanOrEqualTo(key, value) → {AV.Query}

Source:
  - query.js, line 593

Add 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
  AV.Query

#### include(keys) → {AV.Query}

Source:
  - query.js, line 965

Include nested AV.Objects for the provided key. You can use dot notation to specify which fields in the included object are also fetch.

##### Parameters:

Name | Type | Description
--- | --- | ---
`keys` | Array.<String> | The name of the key to include.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### includeACL(valueopt) → {AV.Query}

Source:
  - query.js, line 978

Include the ACL.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`value` | Boolean | <optional> | `true` | Whether to include the ACL

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### lessThan(key, value) → {AV.Query}

Source:
  - query.js, line 557

Add 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
  AV.Query

#### lessThanOrEqualTo(key, value) → {AV.Query}

Source:
  - query.js, line 581

Add 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
  AV.Query

#### limit(n) → {AV.Query}

Source:
  - query.js, line 490

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
  AV.Query

#### matches(key, regex) → {AV.Query}

Source:
  - query.js, line 662

Add 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
  AV.Query

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

Source:
  - query.js, line 723

Add a constraint that requires that a key's value matches a value in an object returned by a different AV.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` | AV.Query | The query to run.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### matchesQuery(key, query) → {AV.Query}

Source:
  - query.js, line 691

Add a constraint that requires that a key's value matches a AV.Query constraint.

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The key that the contains the object to match the query.
`query` | AV.Query | The query that should match.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### near(key, point) → {AV.Query}

Source:
  - query.js, line 886

Add 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 AV.GeoPoint is stored in.
`point` | AV.GeoPoint | The reference AV.GeoPoint that is used.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### notContainedIn(key, values) → {AV.Query}

Source:
  - query.js, line 617

Add 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
  AV.Query

#### notEqualTo(key, value) → {AV.Query}

Source:
  - query.js, line 545

Add 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
  AV.Query

#### scan(optionsopt, authOptionsopt) → {AsyncIterator.<AV.Object>}

Source:
  - query.js, line 349
Since:
  - 2.1.0

scan a Query. masterKey required.

##### Example

    const scan = new AV.Query(TestClass).scan({
      orderedBy: 'objectId',
      batchSize: 10,
    }, {
      useMasterKey: true,
    });
    const getTen = () => Promise.all(new Array(10).fill(0).map(() => scan.next()));
    getTen().then(results => {
      // results are fisrt 10 instances of TestClass
      return getTen();
    }).then(results => {
      // 11 - 20
    });

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`options` | object | <optional> | ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`orderedBy` | string | <optional> | specify the key to sort
`batchSize` | number | <optional> | specify the batch size for each request
`authOptions` | AuthOptions | <optional> |

##### Returns:

Type
  AsyncIterator.<AV.Object>

#### select(keys) → {AV.Query}

Source:
  - query.js, line 990

Restrict the fields of the returned AV.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 | Description
--- | --- | ---
`keys` | Array.<String> | The names of the keys to include.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### sizeEqualTo(key, value) → {AV.Query}

Source:
  - query.js, line 534

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

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | String | The array key to check.
`value` |  | The length value.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

#### skip(n) → {AV.Query}

Source:
  - query.js, line 478

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
  AV.Query

#### startsWith(key, prefix) → {AV.Query}

Source:
  - query.js, line 810

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:

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
  AV.Query

#### subscribe() → {AV.LiveQuery}

Source:
  - query.js, line 1061
Since:
  - 3.0.0

Subscribe the changes of this query. LiveQuery is not included in the default bundle: https://url.leanapp.cn/enable-live-query.

##### Returns:

An eventemitter which can be used to get LiveQuery updates;

Type
  AV.LiveQuery

#### toJSON() → {Object}

Source:
  - query.js, line 224

Returns a JSON representation of this query.

##### Returns:

Type
  Object

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

Source:
  - query.js, line 948

Add 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` | AV.GeoPoint | The lower-left inclusive corner of the box.
`northeast` | AV.GeoPoint | The upper-right inclusive corner of the box.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query

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

Source:
  - query.js, line 933

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:

Name | Type | Description
--- | --- | ---
`key` | String | The key that the AV.GeoPoint is stored in.
`point` | AV.GeoPoint | The reference AV.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
  AV.Query

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

Source:
  - query.js, line 919

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:

Name | Type | Description
--- | --- | ---
`key` | String | The key that the AV.GeoPoint is stored in.
`point` | AV.GeoPoint | The reference AV.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
  AV.Query

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

Source:
  - query.js, line 903

Add 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 AV.GeoPoint is stored in.
`point` | AV.GeoPoint | The reference AV.GeoPoint that is used.
`maxDistance` |  | Maximum distance (in radians) of results to return.

##### Returns:

Returns the query, so you can chain this call.

Type
  AV.Query