PFQuery

@interface PFQuery < PFGenericObject : PFObject * >  : NSObject<NSCopying> 

The PFQuery class defines a query that is used to query for PFObjects.

  • Initializes the query with a class name.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithClassName:(nonnull NSString *)className;

    Parameters

    className

    The class name.

  • Returns a PFQuery for a given class.

    Declaration

    Objective-C

    + (nonnull instancetype)queryWithClassName:(nonnull NSString *)className;

    Parameters

    className

    The class to query on.

    Return Value

    A PFQuery object.

  • Creates a PFQuery with the constraints given by predicate.

    The following types of predicates are supported:

    • Simple comparisons such as =, !=, <, >, <=, >=, and BETWEEN with a key and a constant.
    • 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.
    • Regular expressions, such as LIKE, MATCHES, CONTAINS, or ENDSWITH.
    • Predicates comparing one key to another.
    • Complex predicates with many ORed clauses.

    Declaration

    Objective-C

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

    Parameters

    className

    The class to query on.

    predicate

    The predicate to create conditions from.

  • The class name to query for.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) NSString *_Nonnull parseClassName;
  • Make the query include PFObjects 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.

    Declaration

    Objective-C

    - (nonnull instancetype)includeKey:(nonnull NSString *)key;

    Parameters

    key

    The key to load child PFObjects for.

    Return Value

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

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

    Declaration

    Objective-C

    - (nonnull instancetype)selectKeys:(nonnull NSArray<NSString *> *)keys;

    Parameters

    keys

    The keys to include in the result.

    Return Value

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

  • Add a constraint that requires a particular key exists.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKeyExists:(nonnull NSString *)key;

    Parameters

    key

    The key that should exist.

    Return Value

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

  • Add a constraint that requires a key not exist.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKeyDoesNotExist:(nonnull NSString *)key;

    Parameters

    key

    The key that should not exist.

    Return Value

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

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

    Declaration

    Objective-C

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

    Parameters

    key

    The key to be constrained.

    object

    The object that must be equalled.

    Return Value

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

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

    Declaration

    Objective-C

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

    Parameters

    key

    The key to be constrained.

    object

    The object that provides an upper bound.

    Return Value

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

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

    Declaration

    Objective-C

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

    Parameters

    key

    The key to be constrained.

    object

    The object that must be equalled.

    Return Value

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

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

    Declaration

    Objective-C

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

    Parameters

    key

    The key to be constrained.

    object

    The object that must be equalled.

    Return Value

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

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

    Declaration

    Objective-C

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

    Parameters

    key

    The key to be constrained.

    object

    The object that must be equalled.

    Return Value

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

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

    Declaration

    Objective-C

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

    Parameters

    key

    The key to be constrained.

    object

    The object that must not be equalled.

    Return Value

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

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

    Declaration

    Objective-C

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

    Parameters

    key

    The key to be constrained.

    array

    The possible values for the key’s object.

    Return Value

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

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

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                      notContainedIn:(nonnull 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 PFQuery as the receiver. This allows method chaining.

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

    Declaration

    Objective-C

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

    Parameters

    key

    The key to be constrained.

    array

    The array of values to search for.

    Return Value

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

  • Add a constraint to the query that requires a particular key’s coordinates (specified via PFGeoPoint) be near a reference point.

    Distance is calculated based on angular distance on a sphere. Results will be sorted by distance from reference point.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                        nearGeoPoint:(nonnull PFGeoPoint *)geopoint;

    Parameters

    key

    The key to be constrained.

    geopoint

    The reference point represented as a PFGeoPoint.

    Return Value

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

  • Add a constraint to the query that requires a particular key’s coordinates (specified via PFGeoPoint) 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.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                        nearGeoPoint:(nonnull PFGeoPoint *)geopoint
                         withinMiles:(double)maxDistance;

    Parameters

    key

    The key to be constrained.

    geopoint

    The reference point represented as a PFGeoPoint.

    maxDistance

    Maximum distance in miles.

    Return Value

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

  • Add a constraint to the query that requires a particular key’s coordinates (specified via PFGeoPoint) 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.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                        nearGeoPoint:(nonnull PFGeoPoint *)geopoint
                    withinKilometers:(double)maxDistance;

    Parameters

    key

    The key to be constrained.

    geopoint

    The reference point represented as a PFGeoPoint.

    maxDistance

    Maximum distance in kilometers.

    Return Value

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

  • Add a constraint to the query that requires a particular key’s coordinates (specified via PFGeoPoint) 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.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                        nearGeoPoint:(nonnull PFGeoPoint *)geopoint
                       withinRadians:(double)maxDistance;

    Parameters

    key

    The key to be constrained.

    geopoint

    The reference point as a PFGeoPoint.

    maxDistance

    Maximum distance in radians.

    Return Value

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

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

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
           withinGeoBoxFromSouthwest:(nonnull PFGeoPoint *)southwest
                         toNortheast:(nonnull PFGeoPoint *)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 PFQuery as the receiver. This allows method chaining.

  • Add a regular expression constraint for finding string values that match the provided regular expression.

    Warning

    This may be slow for large datasets.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                        matchesRegex:(nonnull 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 PFQuery as the receiver. This allows method chaining.

  • Add a regular expression constraint for finding string values that match the provided regular expression.

    Warning

    This may be slow for large datasets.

  • i - Case insensitive search

  • m - Search across multiple lines of input

  • Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                        matchesRegex:(nonnull 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 PFQuery as the receiver. This allows method chaining.

  • Add a constraint for finding string values that contain a provided substring.

    Warning

    This will be slow for large datasets.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull 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 PFQuery as the receiver. This allows method chaining.

  • 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.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull 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 PFQuery as the receiver. This allows method chaining.

  • Add a constraint for finding string values that end with a provided suffix.

    Warning

    This will be slow for large datasets.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull 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 PFQuery as the receiver. This allows method chaining.

  • Returns a PFQuery that is the or of the passed in queries.

    Declaration

    Objective-C

    + (nonnull instancetype)orQueryWithSubqueries:
            (nonnull NSArray<PFQuery *> *)queries;

    Parameters

    queries

    The list of queries to or together.

    Return Value

    An instance of PFQuery that is the or of the passed in queries.

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

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                          matchesKey:(nonnull NSString *)otherKey
                             inQuery:(nonnull PFQuery *)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 PFQuery as the receiver. This allows method chaining.

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

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                     doesNotMatchKey:(nonnull NSString *)otherKey
                             inQuery:(nonnull PFQuery *)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 PFQuery as the receiver. This allows method chaining.

  • Add a constraint that requires that a key’s value matches a PFQuery constraint.

    Warning

    This only works where the key’s values are PFObjects or arrays of PFObjects.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                        matchesQuery:(nonnull PFQuery *)query;

    Parameters

    key

    The key that the value is stored in

    query

    The query the value should match

    Return Value

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

  • Add a constraint that requires that a key’s value to not match a PFQuery constraint.

    Warning

    This only works where the key’s values are PFObjects or arrays of PFObjects.

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                   doesNotMatchQuery:(nonnull PFQuery *)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 PFQuery as the receiver. This allows method chaining.

  • Sort the results in ascending order with the given key.

    Declaration

    Objective-C

    - (nonnull instancetype)orderByAscending:(nonnull NSString *)key;

    Parameters

    key

    The key to order by.

    Return Value

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

  • Additionally sort in ascending order by the given key.

    The previous keys provided will precedence over this key.

    Declaration

    Objective-C

    - (nonnull instancetype)addAscendingOrder:(nonnull NSString *)key;

    Parameters

    key

    The key to order by.

  • Sort the results in descending order with the given key.

    Declaration

    Objective-C

    - (nonnull instancetype)orderByDescending:(nonnull NSString *)key;

    Parameters

    key

    The key to order by.

    Return Value

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

  • Additionally sort in descending order by the given key.

    The previous keys provided will precedence over this key.

    Declaration

    Objective-C

    - (nonnull instancetype)addDescendingOrder:(nonnull NSString *)key;

    Parameters

    key

    The key to order by.

  • Sort the results using a given sort descriptor.

    Warning

    If a sortDescriptor has custom selector or comparator - they aren’t going to be used.

    Declaration

    Objective-C

    - (nonnull instancetype)orderBySortDescriptor:
            (nonnull NSSortDescriptor *)sortDescriptor;

    Parameters

    sortDescriptor

    The NSSortDescriptor to use to sort the results of the query.

    Return Value

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

  • Sort the results using a given array of sort descriptors.

    Warning

    If a sortDescriptor has custom selector or comparator - they aren’t going to be used.

    Declaration

    Objective-C

    - (nonnull instancetype)orderBySortDescriptors:
            (nullable NSArray<NSSortDescriptor *> *)sortDescriptors;

    Parameters

    sortDescriptors

    An array of NSSortDescriptor objects to use to sort the results of the query.

    Return Value

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

  • Gets a PFObject asynchronously and calls the given block with the result.

    Warning

    This method mutates the query. It will reset limit to 1, skip to 0 and remove all conditions, leaving only objectId.

    Declaration

    Objective-C

    - (id)getObjectInBackgroundWithId:(nonnull NSString *)objectId;

    Parameters

    objectId

    The id of the object that is being requested.

    Return Value

    The task, that encapsulates the work being done.

  • Gets a PFObject asynchronously and calls the given block with the result.

    Warning

    This method mutates the query. It will reset limit to 1, skip to 0 and remove all conditions, leaving only objectId.

    Declaration

    Objective-C

    - (void)getObjectInBackgroundWithId:(nonnull NSString *)objectId
                                  block:
                                      (nullable void (^)(PFGenericObject _Nullable,
                                                         NSError *_Nullable))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)

  • @deprecated Please use [PFUser query] instead.

    Declaration

    Objective-C

    + (nonnull instancetype)queryForUser;
  • Finds objects asynchronously and sets the NSArray of PFObject objects as a result of the task.

    Declaration

    Objective-C

    - (id)findObjectsInBackground;

    Return Value

    The task, that encapsulates the work being done.

  • Finds objects asynchronously and calls the given block with the results.

    Declaration

    Objective-C

    - (void)findObjectsInBackgroundWithBlock:
            (nullable PFQueryArrayResultBlock)block;

    Parameters

    block

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

  • Gets an object asynchronously and sets it as a result of the task.

    Warning

    This method mutates the query. It will reset the limit to 1.

    Declaration

    Objective-C

    - (id)getFirstObjectInBackground;

    Return Value

    The task, that encapsulates the work being done.

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

    Warning

    This method mutates the query. It will reset the limit to 1.

    Declaration

    Objective-C

    - (void)getFirstObjectInBackgroundWithBlock:
            (nullable void (^)(PFGenericObject _Nullable, NSError *_Nullable))block;

    Parameters

    block

    The block to execute. It should have the following argument signature: ^(PFObject *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.

  • Counts objects asynchronously and sets NSNumber with count as a result of the task.

    Declaration

    Objective-C

    - (id)countObjectsInBackground;

    Return Value

    The task, that encapsulates the work being done.

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

    Declaration

    Objective-C

    - (void)countObjectsInBackgroundWithBlock:(nullable PFIntegerResultBlock)block;

    Parameters

    block

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

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

    Declaration

    Objective-C

    - (void)cancel;
  • 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.

    Warning

    If you are calling findObjects with limit = 1, you may find it easier to use getFirst instead.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSInteger limit;
  • The number of objects to skip before returning any.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSInteger skip;
  • The cache policy to use for requests.

    Not allowed when Pinning is enabled.

    See

    fromLocalDatastore

    See

    fromPin

    See

    fromPinWithName:

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) PFCachePolicy cachePolicy;
  • The age after which a cached value will be ignored

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSTimeInterval maxCacheAge;
  • Returns whether there is a cached result for this query.

    @result YES if there is a cached result for this query, otherwise NO.

    Declaration

    Objective-C

    @property (readonly, assign, nonatomic) BOOL hasCachedResult;
  • Clears the cached result for this query. If there is no cached result, this is a noop.

    Declaration

    Objective-C

    - (void)clearCachedResult;
  • Clears the cached results for all queries.

    Declaration

    Objective-C

    + (void)clearAllCachedResults;
  • Change the source of this query to all pinned objects.

    Warning

    Requires Local Datastore to be enabled.

    See

    cachePolicy

    Declaration

    Objective-C

    - (nonnull instancetype)fromLocalDatastore;

    Return Value

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

  • Change the source of this query to the default group of pinned objects.

    Warning

    Requires Local Datastore to be enabled.

    See

    PFObjectDefaultPin

    See

    cachePolicy

    Declaration

    Objective-C

    - (nonnull instancetype)fromPin;

    Return Value

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

  • Change the source of this query to a specific group of pinned objects.

    Warning

    Requires Local Datastore to be enabled.

    See

    PFObjectDefaultPin

    See

    cachePolicy

    Declaration

    Objective-C

    - (nonnull instancetype)fromPinWithName:(nullable NSString *)name;

    Parameters

    name

    The pinned group.

    Return Value

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

  • Ignore ACLs when querying from the Local Datastore.

    This is particularly useful when querying for objects with Role based ACLs set on them.

    Warning

    Requires Local Datastore to be enabled.

    Declaration

    Objective-C

    - (nonnull instancetype)ignoreACLs;

    Return Value

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

  • Whether or not performance tracing should be done on the query.

    Warning

    This should not be set to YES in most cases.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL trace;