MLQuery Class Reference

Inherits from NSObject
Conforms to NSCopying
NSSecureCoding
Declared in MLQuery.h

Overview

A class that defines a query that is used to query for MLObjects.

Creating a Query for a Class

+ queryWithClassName:

Returns a MLQuery for a given class.

+ (instancetype)queryWithClassName:(NSString *)className

Parameters

className

The class to query on.

Return Value

A MLQuery object.

Declared In

MLQuery.h

+ queryWithClassName:predicate:

Creates a MLQuery with the constraints given by predicate.

+ (instancetype)queryWithClassName:(NSString *)className predicate:(nullable NSPredicate *)predicate

Parameters

className

The class to query on.

predicate

The predicate used to construct a query.

Return Value

A MLQuery object.

Discussion

The following types of predicates are supported:
* Simple comparisons such as =, !=, <, >, <=, >=, and BETWEEN with a key and a constant.
* Regular expressions, such as LIKE, MATCHES, CONTAINS, or ENDSWITH.
* Containment predicates, such as “x IN {1, 2, 3}”.
* Key-existence predicates, such as “x IN SELF”.
* BEGINSWITH expressions.
* Compound predicates with AND, OR, and NOT.
* SubQueries with “key IN %@”, subquery.

The following types of predicates are NOT supported:
* Aggregate operations, such as ANY, SOME, ALL, or NONE.
* Predicates comparing one key to another.
* Complex predicates with many ORed clauses.

Declared In

MLQuery.h

– initWithClassName:

Initializes the query with a class name.

- (instancetype)initWithClassName:(NSString *)className

Parameters

className

The class name.

Declared In

MLQuery.h

  leapClassName

The class name to query for

@property (nonatomic, strong) NSString *leapClassName

Declared In

MLQuery.h

Adding Basic Constraints

– includeKey:

Make the query include MLObjects that have a reference stored at the provided key. This has an effect similar to a join. You can use dot notation to specify which fields in the included object are also fetch.

- (instancetype)includeKey:(NSString *)key

Parameters

key

The key to load child MLObjects for.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– selectKeys:

Make the query restrict the fields of the returned MLObjects 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.

- (instancetype)selectKeys:(NSArray ML_GENERIC ( NSString *) *)keys

Parameters

keys

The keys to include in the result.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKeyExists:

Add a constraint that requires a particular key exists.

- (instancetype)whereKeyExists:(NSString *)key

Parameters

key

The key that should exist.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKeyDoesNotExist:

Add a constraint that requires a key not exist.

- (instancetype)whereKeyDoesNotExist:(NSString *)key

Parameters

key

The key that should not exist.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:equalTo:

Add a constraint to the query that requires a particular key’s object to be equal to the provided object.

- (instancetype)whereKey:(NSString *)key equalTo:(id)object

Parameters

key

The key to be constrained.

object

The object that must be equalled.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Discussion

Object cannot be nil. If you try to match objects that do not exist key %@, use whereKeyDoesNotExist: instead.

Declared In

MLQuery.h

– whereKey:lessThan:

Add a constraint to the query that requires a particular key’s object to be less than the provided object.

- (instancetype)whereKey:(NSString *)key lessThan:(id)object

Parameters

key

The key to be constrained.

object

The object that provides an upper bound.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:lessThanOrEqualTo:

Add a constraint to the query that requires a particular key’s object to be less than or equal to the provided object.

- (instancetype)whereKey:(NSString *)key lessThanOrEqualTo:(id)object

Parameters

key

The key to be constrained.

object

The object that must be equalled.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:greaterThan:

Add a constraint to the query that requires a particular key’s object to be greater than the provided object.

- (instancetype)whereKey:(NSString *)key greaterThan:(id)object

Parameters

key

The key to be constrained.

object

The object that must be equalled.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:greaterThanOrEqualTo:

Add a constraint to the query that requires a particular key’s object to be greater than or equal to the provided object.

- (instancetype)whereKey:(NSString *)key greaterThanOrEqualTo:(id)object

Parameters

key

The key to be constrained.

object

The object that must be equalled.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:notEqualTo:

Add a constraint to the query that requires a particular key’s object to be not equal to the provided object.

- (instancetype)whereKey:(NSString *)key notEqualTo:(id)object

Parameters

key

The key to be constrained.

object

The object that must not be equalled.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Discussion

Object cannot be nil. If you try to match objects that do exist key %@, use whereKeyExists: instead.

Declared In

MLQuery.h

– whereKey:containedIn:

Add a constraint to the query that requires a particular key’s object to be contained in the provided array.

- (instancetype)whereKey:(NSString *)key containedIn:(NSArray *)array

Parameters

key

The key to be constrained.

array

The possible values for the key’s object.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:notContainedIn:

Add a constraint to the query that requires a particular key’s object not be contained in the provided array.

- (instancetype)whereKey:(NSString *)key notContainedIn:(NSArray *)array

Parameters

key

The key to be constrained.

array

The list of values the key’s object should not be.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:containsAllObjectsInArray:

Add a constraint to the query that requires a particular key’s array contains every element of the provided array.

- (instancetype)whereKey:(NSString *)key containsAllObjectsInArray:(NSArray *)array

Parameters

key

The key to be constrained.

array

The array of values to search for.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

Adding Location Constraints

– whereKey:nearGeoPoint:

Add a constraint to the query that requires a particular key’s coordinates (specified via MLGeoPoint) be near a reference point. Distance is calculated based on angular distance on a sphere. Results will be sorted by distance from reference point.

- (instancetype)whereKey:(NSString *)key nearGeoPoint:(MLGeoPoint *)geopoint

Parameters

key

The key to be constrained.

geopoint

The reference point. A MLGeoPoint.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:nearGeoPoint:withinMiles:

Add a constraint to the query that requires a particular key’s coordinates (specified via MLGeoPoint) be near a reference point and within the maximum distance specified (in miles). Distance is calculated based on a spherical coordinate system. Results will be sorted by distance (nearest to farthest) from the reference point.

- (instancetype)whereKey:(NSString *)key nearGeoPoint:(MLGeoPoint *)geopoint withinMiles:(double)maxDistance

Parameters

key

The key to be constrained.

geopoint

The reference point. A MLGeoPoint.

maxDistance

Maximum distance in miles.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:nearGeoPoint:withinKilometers:

Add a constraint to the query that requires a particular key’s coordinates (specified via MLGeoPoint) be near a reference point and within the maximum distance specified (in kilometers). Distance is calculated based on a spherical coordinate system. Results will be sorted by distance (nearest to farthest) from the reference point.

- (instancetype)whereKey:(NSString *)key nearGeoPoint:(MLGeoPoint *)geopoint withinKilometers:(double)maxDistance

Parameters

key

The key to be constrained.

geopoint

The reference point. A MLGeoPoint.

maxDistance

Maximum distance in kilometers.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:nearGeoPoint:withinRadians:

Add a constraint to the query that requires a particular key’s coordinates (specified via MLGeoPoint) be near a reference point and within the maximum distance specified (in radians). Distance is calculated based on angular distance on a sphere. Results will be sorted by distance (nearest to farthest) from the reference point.

- (instancetype)whereKey:(NSString *)key nearGeoPoint:(MLGeoPoint *)geopoint withinRadians:(double)maxDistance

Parameters

key

The key to be constrained.

geopoint

The reference point. A MLGeoPoint.

maxDistance

Maximum distance in radians.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:withinGeoBoxFromSouthwest:toNortheast:

Add a constraint to the query that requires a particular key’s coordinates (specified via MLGeoPoint) be contained within a given rectangular geographic bounding box.

- (instancetype)whereKey:(NSString *)key withinGeoBoxFromSouthwest:(MLGeoPoint *)southwest toNortheast:(MLGeoPoint *)northeast

Parameters

key

The key to be constrained.

southwest

The lower-left inclusive corner of the box.

northeast

The upper-right inclusive corner of the box.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

Adding String Constraints

– whereKey:matchesRegex:

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

- (instancetype)whereKey:(NSString *)key matchesRegex:(NSString *)regex

Parameters

key

The key that the string to match is stored in.

regex

The regular expression pattern to match.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:matchesRegex:modifiers:

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

- (instancetype)whereKey:(NSString *)key matchesRegex:(NSString *)regex modifiers:(nullable NSString *)modifiers

Parameters

key

The key that the string to match is stored in.

regex

The regular expression pattern to match.

modifiers

Any of the following supported PCRE modifiers:
i - Case insensitive search
m - Search across multiple lines of input

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:containsString:

Add a constraint for finding string values that contain a provided substring. This will be slow for large datasets.

- (instancetype)whereKey:(NSString *)key containsString:(nullable NSString *)substring

Parameters

key

The key that the string to match is stored in.

substring

The substring that the value must contain.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:hasPrefix:

Add a constraint for finding string values that start with a provided prefix. This will use smart indexing, so it will be fast for large datasets.

- (instancetype)whereKey:(NSString *)key hasPrefix:(nullable NSString *)prefix

Parameters

key

The key that the string to match is stored in.

prefix

The substring that the value must start with.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:hasSuffix:

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

- (instancetype)whereKey:(NSString *)key hasSuffix:(nullable NSString *)suffix

Parameters

key

The key that the string to match is stored in.

suffix

The substring that the value must end with.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

Adding Subqueries

+ orQueryWithSubqueries:

Returns a MLQuery that is the OR of the passed in MLQuerys.

+ (nullable MLQuery *)orQueryWithSubqueries:(nullable NSArray ML_GENERIC ( MLQuery *) *)queries

Parameters

queries

The list of queries to or together.

Return Value

a MLQuery that is the OR of the passed in MLQuerys.

Declared In

MLQuery.h

+ andQueryWithSubqueries:

Returns a MLQuery that is the AND of the passed in MLQuerys.

+ (nullable MLQuery *)andQueryWithSubqueries:(nullable NSArray ML_GENERIC ( MLQuery *) *)queries

Parameters

queries

The list of queries to or together.

Return Value

a MLQuery that is the AND of the passed in MLQuerys.

Declared In

MLQuery.h

– notQuery

Return a query with negated conditions of the receiver.

- (MLQuery *)notQuery

Declared In

MLQuery.h

– whereKey:matchesKey:inQuery:

Adds a constraint that requires that a key’s value matches a value in another key in objects returned by a sub query.

- (instancetype)whereKey:(NSString *)key matchesKey:(NSString *)otherKey inQuery:(MLQuery *)query

Parameters

key

The key that the value is stored

otherKey

The key in objects in the returned by the sub query whose value should match

query

The query to run.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:doesNotMatchKey:inQuery:

Adds a constraint that requires that a key’s value NOT match a value in another key in objects returned by a sub query.

- (instancetype)whereKey:(NSString *)key doesNotMatchKey:(NSString *)otherKey inQuery:(MLQuery *)query

Parameters

key

The key that the value is stored

otherKey

The key in objects in the returned by the sub query whose value should match

query

The query to run.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:matchesQuery:

Add a constraint that requires that a key’s value matches a MLQuery constraint. This only works where the key’s values are MLObjects or arrays of MLObjects.

- (instancetype)whereKey:(NSString *)key matchesQuery:(MLQuery *)query

Parameters

key

The key that the value is stored in

query

The query the value should match

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– whereKey:doesNotMatchQuery:

Add a constraint that requires that a key’s value to not match a MLQuery constraint. This only works where the key’s values are MLObjects or arrays of MLObjects.

- (instancetype)whereKey:(NSString *)key doesNotMatchQuery:(MLQuery *)query

Parameters

key

The key that the value is stored in

query

The query the value should not match

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

Sorting

– orderByAscending:

Sort the results in ascending order with the given key.

- (instancetype)orderByAscending:(NSString *)key

Parameters

key

The key to order by.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– addAscendingOrder:

Also sort in ascending order by the given key. The previous keys provided will precedence over this key.

- (instancetype)addAscendingOrder:(NSString *)key

Parameters

key

The key to order by.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– orderByDescending:

Sort the results in descending order with the given key.

- (instancetype)orderByDescending:(NSString *)key

Parameters

key

The key to order by.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– addDescendingOrder:

Also sort in descending order by the given key. The previous keys provided will precedence over this key.

- (instancetype)addDescendingOrder:(NSString *)key

Parameters

key

The key to order by.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– orderBySortDescriptor:

Sort the results in descending order with the given descriptor.

- (instancetype)orderBySortDescriptor:(NSSortDescriptor *)sortDescriptor

Parameters

sortDescriptor

The NSSortDescriptor to order by.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

– orderBySortDescriptors:

Sort the results in descending order with the given descriptors.

- (instancetype)orderBySortDescriptors:(nullable NSArray ML_GENERIC ( NSSortDescriptor *) *)sortDescriptors

Parameters

sortDescriptors

An NSArray of NSSortDescriptor instances to order by.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.d

Declared In

MLQuery.h

Paginating Results

  limit

A limit on the number of objects to return. The default limit is 100, with a maximum of 1000 results being returned at a time.

@property (nonatomic) NSInteger limit

Discussion

Note: If you are calling findObject with limit=1, you may find it easier to use getFirstObjectInBackgroundWithBlock: instead.

Declared In

MLQuery.h

– limit:

Set limit on the number of objects to return. The default limit is 100, with a maximum of 1000 results being returned at a time.

- (instancetype)limit:(NSInteger)limit

Parameters

limit

A limit on the number of objects to return.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Discussion

Note: If you are calling findObject with limit=1, you may find it easier to use getFirstObjectInBackgroundWithBlock: instead.

Declared In

MLQuery.h

  skip

The number of objects to skip before returning any.

@property (nonatomic) NSInteger skip

Declared In

MLQuery.h

– skip:

Set the skip number.

- (instancetype)skip:(NSInteger)skip

Parameters

skip

The number of objects to skip before returning any.

Return Value

The same instance of MLQuery as the receiver. This allows method chaining.

Declared In

MLQuery.h

  cachePolicy

The cache policy to use for requests.

@property (nonatomic) MLCachePolicy cachePolicy

Declared In

MLQuery.h

  maxCacheAge

The age after which a cached value is ignored. Defaults to 0.0, meaning no practical limit.

@property (nonatomic) NSTimeInterval maxCacheAge

Declared In

MLQuery.h

  hasCachedResult

Returns whether there is a cached result for this query.

@property (nonatomic, readonly) BOOL hasCachedResult

Declared In

MLQuery.h

– clearCachedResult

Clears the cached result for this query. If there is no cached result, this does nothing.

- (void)clearCachedResult

Declared In

MLQuery.h

+ clearAllCachedResults

Clears the cached results for all queries.

+ (void)clearAllCachedResults

Declared In

MLQuery.h

Getting Objects by ID

– getObjectInBackgroundWithId:block:

Gets a MLObject asynchronously and calls the given block with the result.

- (void)getObjectInBackgroundWithId:(NSString *)objectId block:(nullable MLObjectResultBlock)block

Parameters

objectId

The id of the object that is being requested.

block

The block to execute. The block should have the following argument signature: ^(NSArray *object, NSError *error)

Discussion

Warning: This method mutates the query.

Declared In

MLQuery.h

Getting all Matches for a Query

– findObjectsInBackgroundWithBlock:

Finds objects with the provided query asynchronously and calls the given block with the results.

- (void)findObjectsInBackgroundWithBlock:(nullable MLArrayResultBlock)block

Parameters

block

The block to execute. The block should have the following argument signature:(NSArray objects, NSError error)

Declared In

MLQuery.h

Getting the First Match in a Query

– getFirstObjectInBackgroundWithBlock:

Gets an object asynchronously and calls the given block with the result.

- (void)getFirstObjectInBackgroundWithBlock:(nullable MLObjectResultBlock)block

Parameters

block

The block to execute. The block should have the following argument signature:(MLObject object, NSError error) result will be nil if error is set OR no object was found matching the query. error will be nil if result is set OR if the query succeeded, but found no results.

Discussion

Warning: This method mutates the query.

Declared In

MLQuery.h

Counting the Matches in a Query

– countObjectsInBackgroundWithBlock:

Counts objects asynchronously and calls the given block with the counts.

- (void)countObjectsInBackgroundWithBlock:(nullable MLIntegerResultBlock)block

Parameters

block

The block to execute. The block should have the following argument signature: (int count, NSError *error)

Discussion

Warning: This method mutates the query.

Declared In

MLQuery.h

Cancelling a Query

– cancel

Cancels the current network request (if any). Ensures that callbacks won’t be called.

- (void)cancel

Declared In

MLQuery.h