PFQuery

Objective-C

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

Swift

class PFQuery<PFGenericObject> : NSObject, NSCopying where PFGenericObject : PFObject

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

Creating a Query for a Class

  • Initializes the query with a class name.

    Declaration

    Objective-C

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

    Swift

    init(className: String)

    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;

    Swift

    convenience init(className: String, predicate: NSPredicate?)

    Parameters

    className

    The class to query on.
    predicate

    The predicate to create conditions from.

  • The class name to query for.

    Declaration

    Objective-C

    @property (nonatomic, strong) NSString *_Nonnull parseClassName;

    Swift

    var parseClassName: String { get set }

Adding Basic Constraints

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

    Swift

    func includeKey(_ key: String) -> Self

    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 include PFObjects that have a reference stored at the provided keys.

    Declaration

    Objective-C

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

    Swift

    func includeKeys(_ keys: [String]) -> Self

    Parameters

    keys

    The keys to load child PFObjects for.

    Return Value

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

  • Make the query include all PFObjects that have a reference.

    Declaration

    Objective-C

    - (nonnull instancetype)includeAll;

    Swift

    func includeAll() -> Self

    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 exclude the provided key.

    If this is called multiple times, then all of the keys specified in each of the calls will be excluded.

    Declaration

    Objective-C

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

    Swift

    func excludeKey(_ key: String) -> Self

    Parameters

    key

    The key to exclude in the result.

    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 exclude the provided keys.

    If this is called multiple times, then all of the keys specified in each of the calls will be excluded.

    Declaration

    Objective-C

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

    Swift

    func excludeKeys(_ keys: [String]) -> Self

    Parameters

    keys

    The keys to exclude in the result.

    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;

    Swift

    func selectKeys(_ keys: [String]) -> Self

    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;

    Swift

    func whereKeyExists(_ key: String) -> Self

    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;

    Swift

    func whereKeyDoesNotExist(_ key: String) -> Self

    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;

    Swift

    func whereKey(_ key: String, equalTo object: Any) -> Self

    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;

    Swift

    func whereKey(_ key: String, lessThan object: Any) -> Self

    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;

    Swift

    func whereKey(_ key: String, lessThanOrEqualTo object: Any) -> Self

    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;

    Swift

    func whereKey(_ key: String, greaterThan object: Any) -> Self

    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;

    Swift

    func whereKey(_ key: String, greaterThanOrEqualTo object: Any) -> Self

    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;

    Swift

    func whereKey(_ key: String, notEqualTo object: Any) -> Self

    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 for finding string values that contain a provided string using Full Text Search

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                     matchesText:(nonnull NSString *)text;

    Swift

    func whereKey(_ key: String, matchesText text: String) -> Self

    Parameters

    key

    The key to be constrained.
    text

    the substring that the value must contain.

    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;

    Swift

    func whereKey(_ key: String, containedIn array: [Any]) -> Self

    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;

    Swift

    func whereKey(_ key: String, notContainedIn array: [Any]) -> Self

    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;

    Swift

    func whereKey(_ key: String, containsAllObjectsIn array: [Any]) -> Self

    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.

  • Adds a constraint to the query that requires a particular key’s value to be contained by the provided list of values. Get objects where all array elements match

    Declaration

    Objective-C

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

    Swift

    func whereKey(_ key: String, containedBy array: [Any]) -> Self

    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.

Adding Location Constraints

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

    Swift

    func whereKey(_ key: String, nearGeoPoint geopoint: PFGeoPoint) -> Self

    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;

    Swift

    func whereKey(_ key: String, nearGeoPoint geopoint: PFGeoPoint, withinMiles maxDistance: Double) -> Self

    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;

    Swift

    func whereKey(_ key: String, nearGeoPoint geopoint: PFGeoPoint, withinKilometers maxDistance: Double) -> Self

    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;

    Swift

    func whereKey(_ key: String, nearGeoPoint geopoint: PFGeoPoint, withinRadians maxDistance: Double) -> Self

    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;

    Swift

    func whereKey(_ key: String, withinGeoBoxFromSouthwest southwest: PFGeoPoint, toNortheast northeast: PFGeoPoint) -> Self

    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 constraint to the query that requires a particular key’s coordinates be contained within and on the bounds of a given polygon Supports closed and open (last point is connected to first) paths. (Requires [email protected])

    Polygon must have at least 3 points

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                   withinPolygon:(nonnull NSArray<PFGeoPoint *> *)points;

    Swift

    func whereKey(_ key: String, withinPolygon points: [PFGeoPoint]) -> Self

    Parameters

    key

    The key to be constrained.
    points

    The polygon points as an Array of PFGeoPoint‘s.

    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 that contains a PFGeoPoint (Requires [email protected])

    Declaration

    Objective-C

    - (nonnull instancetype)whereKey:(nonnull NSString *)key
                 polygonContains:(nonnull PFGeoPoint *)point;

    Swift

    func whereKey(_ key: String, polygonContains point: PFGeoPoint) -> Self

    Parameters

    key

    The key to be constrained.
    point

    Return Value

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

Adding String Constraints

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

    Swift

    func whereKey(_ key: String, matchesRegex regex: String) -> Self

    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;

    Swift

    func whereKey(_ key: String, matchesRegex regex: String, modifiers: String?) -> Self

    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:

    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;

    Swift

    func whereKey(_ key: String, contains substring: String?) -> Self

    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;

    Swift

    func whereKey(_ key: String, hasPrefix prefix: String?) -> Self

    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;

    Swift

    func whereKey(_ key: String, hasSuffix suffix: String?) -> Self

    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.

Adding Subqueries

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

    Declaration

    Objective-C

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

    Swift

    class func orQuery(withSubqueries queries: [PFQuery<PFObject>]) -> Self

    Parameters

    queries

    The list of queries to or together.

    Return Value

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

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

    Declaration

    Objective-C

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

    Swift

    class func andQuery(withSubqueries queries: [PFQuery<PFObject>]) -> Self

    Parameters

    queries

    The list of queries to and together.

    Return Value

    An instance of PFQuery that is the and 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;

    Swift

    func whereKey(_ key: String, matchesKey otherKey: String, in query: PFQuery<PFObject>) -> Self

    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;

    Swift

    func whereKey(_ key: String, doesNotMatchKey otherKey: String, in query: PFQuery<PFObject>) -> Self

    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;

    Swift

    func whereKey(_ key: String, matchesQuery query: PFQuery<PFObject>) -> Self

    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;

    Swift

    func whereKey(_ key: String, doesNotMatch query: PFQuery<PFObject>) -> Self

    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.

Sorting

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

    Declaration

    Objective-C

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

    Swift

    func order(byAscending key: String) -> Self

    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;

    Swift

    func addAscendingOrder(_ key: String) -> Self

    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;

    Swift

    func order(byDescending key: String) -> Self

    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;

    Swift

    func addDescendingOrder(_ key: String) -> Self

    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;

    Swift

    func order(by sortDescriptor: NSSortDescriptor) -> Self

    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;

    Swift

    func order(by sortDescriptors: [NSSortDescriptor]?) -> Self

    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.

Getting Objects by ID

  • 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

    - (nonnull BFTask<PFGenericObject> *)getObjectInBackgroundWithId:
    (nonnull NSString *)objectId;

    Swift

    func getObjectInBackground(withId objectId: String) -> Any!

    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;

    Swift

    func getObjectInBackground(withId objectId: String, block: ((PFGenericObject?, (any Error)?) -> Void)? = nil)

    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)

Getting User Objects

  • Deprecated

    Use [PFUser query] instead.

    @deprecated Please use [PFUser query] instead.

    Declaration

    Objective-C

    + (nonnull instancetype)queryForUser;

    Swift

    class func forUser() -> Self

Getting all Matches for a Query

  • Finds objects asynchronously and sets the NSArray of PFObject objects as a result of the task.

    Declaration

    Objective-C

    - (nonnull BFTask<NSArray<PFGenericObject> *> *)findObjectsInBackground;

    Swift

    func findObjectsInBackground() -> Any!

    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;

    Swift

    func findObjectsInBackground() async throws -> [PFGenericObject]

    Parameters

    block

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

Getting the First Match in a Query

  • 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

    - (nonnull BFTask<PFGenericObject> *)getFirstObjectInBackground;

    Swift

    func getFirstObjectInBackground() -> Any!

    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;

    Swift

    func firstObjectInBackground() async throws -> PFGenericObject

    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.

Counting the Matches in a Query

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

    Declaration

    Objective-C

    - (nonnull BFTask<NSNumber *> *)countObjectsInBackground;

    Swift

    func countObjectsInBackground() -> Any!

    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;

    Swift

    func countObjectsInBackground() async throws -> Int32

    Parameters

    block

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

Cancelling a Query

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

    Declaration

    Objective-C

    - (void)cancel;

    Swift

    func cancel()

Paginating Results

  • 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 (nonatomic) NSInteger limit;

    Swift

    var limit: Int { get set }

  • The number of objects to skip before returning any.

    Declaration

    Objective-C

    @property (nonatomic) NSInteger skip;

    Swift

    var skip: Int { get set }

Controlling Caching Behavior

  • The cache policy to use for requests.

    Not allowed when Pinning is enabled.

    See

    fromLocalDatastore

    See

    fromPin

    See

    fromPinWithName:

    Declaration

    Objective-C

    @property (nonatomic) PFCachePolicy cachePolicy;

    Swift

    var cachePolicy: PFCachePolicy { get set }

  • The age after which a cached value will be ignored

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval maxCacheAge;

    Swift

    var maxCacheAge: TimeInterval { get set }

  • 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 (nonatomic, readonly) BOOL hasCachedResult;

    Swift

    var hasCachedResult: Bool { get }

  • Clears the cached result for this query. If there is no cached result, this is a noop.

    Declaration

    Objective-C

    - (void)clearCachedResult;

    Swift

    func clearCachedResult()

  • Clears the cached results for all queries.

    Declaration

    Objective-C

    + (void)clearAllCachedResults;

    Swift

    class func clearAllCachedResults()

Query Source

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

    Swift

    func fromLocalDatastore() -> Self

    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;

    Swift

    func fromPin() -> Self

    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;

    Swift

    func fromPin(withName name: String?) -> Self

    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;

    Swift

    func ignoreACLs() -> Self

    Return Value

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

Advanced Settings

  • 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 (nonatomic) BOOL trace;

    Swift

    var trace: Bool { get set }

Getting Objects by ID

  • Deprecated

    Please use PFQuery.-getObjectInBackgroundWithId:block: instead.

    Gets a PFObject asynchronously.

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

    @deprecated Please use PFQuery.-getObjectInBackgroundWithId:block: instead.

    Declaration

    Objective-C

    - (void)getObjectInBackgroundWithId:(nonnull NSString *)objectId
                             target:(nullable id)target
                           selector:(nullable SEL)selector;

    Swift

    func getObjectInBackground(withId objectId: String, target: Any?, selector: Selector?)

    Parameters

    objectId

    The id of the object being requested.
    target

    The target for the callback selector.
    selector

    The selector for the callback. It should have the following signature: (void)callbackWithResult:(id)result error:(NSError *)error. Result will be nil if error is set and vice versa.

Getting all Matches for a Query

  • Deprecated

    Please use PFQuery.-findObjectsInBackgroundWithBlock: instead.

    Finds objects asynchronously and calls the given callback with the results.

    @deprecated Please use PFQuery.-findObjectsInBackgroundWithBlock: instead.

    Declaration

    Objective-C

    - (void)findObjectsInBackgroundWithTarget:(nullable id)target
                                 selector:(nullable SEL)selector;

    Swift

    func findObjectsInBackground(withTarget target: Any?, selector: Selector?)

    Parameters

    target

    The object to call the selector on.
    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(id)result error:(NSError *)error. Result will be nil if error is set and vice versa.

Getting the First Match in a Query

  • Deprecated

    Please use PFQuery.-getFirstObjectInBackgroundWithBlock: instead.

    Gets an object asynchronously and calls the given callback with the results.

    Warning

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

    @deprecated Please use PFQuery.-getFirstObjectInBackgroundWithBlock: instead.

    Declaration

    Objective-C

    - (void)getFirstObjectInBackgroundWithTarget:(nullable id)target
                                    selector:(nullable SEL)selector;

    Swift

    func getFirstObjectInBackground(withTarget target: Any?, selector: Selector?)

    Parameters

    target

    The object to call the selector on.
    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(PFObject *)result error:(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.

Counting the Matches in a Query

  • Deprecated

    Please use PFQuery.-countObjectsInBackgroundWithBlock: instead.

    Counts objects asynchronously and calls the given callback with the count.

    @deprecated Please use PFQuery.-countObjectsInBackgroundWithBlock: instead.

    Declaration

    Objective-C

    - (void)countObjectsInBackgroundWithTarget:(nullable id)target
                                  selector:(nullable SEL)selector;

    Swift

    func countObjectsInBackground(withTarget target: Any?, selector: Selector?)

    Parameters

    target

    The object to call the selector on.
    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(NSNumber *)result error:(NSError *)error.

Getting Objects by ID

  • Returns a PFObject with a given class and id.

    Declaration

    Objective-C

    + (nullable PFGenericObject)getObjectOfClass:(nonnull NSString *)objectClass
                                    objectId:(nonnull NSString *)objectId;

    Parameters

    objectClass

    The class name for the object that is being requested.
    objectId

    The id of the object that is being requested.

    Return Value

    The PFObject if found. Returns nil if the object isn’t found, or if there was an error.

  • Returns a PFObject with a given class and id and sets an error if necessary.

    Declaration

    Objective-C

    + (nullable PFGenericObject)getObjectOfClass:(nonnull NSString *)objectClass
                                    objectId:(nonnull NSString *)objectId
                                       error:
                                           (NSError *_Nullable *_Nullable)error;

    Swift

    class func getObjectOfClass(_ objectClass: String, objectId: String) throws -> PFGenericObject

    Parameters

    objectClass

    The class name for the object that is being requested.
    objectId

    The id of the object that is being requested.
    error

    Pointer to an NSError that will be set if necessary.

    Return Value

    The PFObject if found. Returns nil if the object isn’t found, or if there was an error.

  • Returns a PFObject with the given id.

    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

    - (nullable PFGenericObject)getObjectWithId:(nonnull NSString *)objectId;

    Parameters

    objectId

    The id of the object that is being requested.

    Return Value

    The PFObject if found. Returns nil if the object isn’t found, or if there was an error.

  • Returns a PFObject with the given id and sets an error if necessary.

    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

    - (nullable PFGenericObject)getObjectWithId:(nonnull NSString *)objectId
                                      error:
                                          (NSError *_Nullable *_Nullable)error;

    Swift

    func getObjectWithId(_ objectId: String) throws -> PFGenericObject

    Parameters

    objectId

    The id of the object that is being requested.
    error

    Pointer to an NSError that will be set if necessary.

    Return Value

    The PFObject if found. Returns nil if the object isn’t found, or if there was an error.

Getting User Objects

  • Returns a PFUser with a given id.

    Declaration

    Objective-C

    + (nullable PFUser *)getUserObjectWithId:(nonnull NSString *)objectId;

    Parameters

    objectId

    The id of the object that is being requested.

    Return Value

    The PFUser if found. Returns nil if the object isn’t found, or if there was an error.

  • Returns a PFUser with a given class and id and sets an error if necessary.

    Declaration

    Objective-C

    + (nullable PFUser *)getUserObjectWithId:(nonnull NSString *)objectId
                                   error:(NSError *_Nullable *_Nullable)error;

    Swift

    class func getUserObject(withId objectId: String) throws -> PFUser

    Parameters

    objectId

    The id of the object that is being requested.
    error

    Pointer to an NSError that will be set if necessary. @result The PFUser if found. Returns nil if the object isn’t found, or if there was an error.

Getting all Matches for a Query

  • Finds objects synchronously based on the constructed query.

    Declaration

    Objective-C

    - (nullable NSArray<PFGenericObject> *)findObjects;

    Return Value

    Returns an array of PFObject objects that were found.

  • Finds objects synchronously based on the constructed query and sets an error if there was one.

    Declaration

    Objective-C

    - (nullable NSArray<PFGenericObject> *)findObjects:
    (NSError *_Nullable *_Nullable)error;

    Swift

    func findObjects() throws -> [PFGenericObject]

    Parameters

    error

    Pointer to an NSError that will be set if necessary.

    Return Value

    Returns an array of PFObject objects that were found.

Getting the First Match in a Query

  • Gets an object synchronously based on the constructed query.

    Warning

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

    Declaration

    Objective-C

    - (nullable PFGenericObject)getFirstObject;

    Return Value

    Returns a PFObject, or nil if none was found.

  • Gets an object synchronously based on the constructed query and sets an error if any occurred.

    Warning

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

    Declaration

    Objective-C

    - (nullable PFGenericObject)getFirstObject:(NSError *_Nullable *_Nullable)error;

    Swift

    func getFirstObject() throws -> PFGenericObject

    Parameters

    error

    Pointer to an NSError that will be set if necessary.

    Return Value

    Returns a PFObject, or nil if none was found.

Counting the Matches in a Query

  • Counts objects synchronously based on the constructed query.

    Declaration

    Objective-C

    - (NSInteger)countObjects;

    Return Value

    Returns the number of PFObject objects that match the query, or -1 if there is an error.

  • Counts objects synchronously based on the constructed query and sets an error if there was one.

    Declaration

    Objective-C

    - (NSInteger)countObjects:(NSError *_Nullable *_Nullable)error;

    Swift

    func countObjects(_ error: NSErrorPointer) -> Int

    Parameters

    error

    Pointer to an NSError that will be set if necessary.

    Return Value

    Returns the number of PFObject objects that match the query, or -1 if there is an error.