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:
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:
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:
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) fromJSON(json) → {AV.Query}

Source:
Since:
  • 4.0.0
Return a query with conditions from json. This can be useful to send a query from server side to client side.
Parameters:
Name Type Description
json Object from AV.Query#toJSON
Returns:
Type
AV.Query

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

Source:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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

findAndCount(options) → {Promise}

Source:
Since:
  • 4.12.0
Retrieves both AVObjects and total count.
Parameters:
Name Type Description
options AuthOptions
Returns:
A tuple contains results and count.
Type
Promise

first(options) → {Promise}

Source:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
Since:
  • 2.1.0
scan a Query. masterKey required.
Example
const testIterator = {
  [Symbol.asyncIterator]() {
    return new Query('Test').scan(undefined, { useMasterKey: true });
  },
};
for await (const test of testIterator) {
  console.log(test.id);
}
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:
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:
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 number The length value.
Returns:
Returns the query, so you can chain this call.
Type
AV.Query

skip(n) → {AV.Query}

Source:
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:
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:
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:
Returns a JSON representation of this query.
Returns:
Type
Object

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

Source:
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:
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:
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:
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