Getting Started

The easiest way to integrate the Parse SDK into your iOS, iPadOS, macOS, watchOS, tvOS app is via Swift Package Manager (SPM).

1. Open Xcode > File > Add packages…
2. Add the following package URL:

https://github.com/parse-community/Parse-SDK-iOS-OSX

Note: You may have to add submodules under Link Binary with Libraries

To initialize the Parse client, add the following to your AppDelegate.swift file (AppDelegate.m for Objective-C), in the application:didFinishLaunchingWithOptions: method.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
 [Parse initializeWithConfiguration:[ParseClientConfiguration configurationWithBlock:^(id<ParseMutableClientConfiguration> configuration) {
        configuration.applicationId = @"parseAppId";
        configuration.clientKey = @"parseClientKey";
        configuration.server = @"parseServerUrlString";
    }]];
	return YES;
}

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        let parseConfig = ParseClientConfiguration {
            $0.applicationId = "parseAppId"
            $0.clientKey = "parseClientKey"
            $0.server = "parseServerUrlString"
        }
        Parse.initialize(with: parseConfig)
        return true
}

Make sure to import the Parse module at the top of any file in which you want to use the Parse SDK by including the follwing.

@import ParseCore;

import ParseCore

Objects

The PFObject

Storing data on Parse is built around the PFObject. Each PFObject contains key-value pairs of JSON-compatible data. This data is schemaless, which means that you don’t need to specify ahead of time what keys exist on each PFObject. You simply set whatever key-value pairs you want, and our backend will store it.

For example, let’s say you’re tracking high scores for a game. A single PFObject could contain:

score: 1337, playerName: "Sean Plott", cheatMode: false

Keys must be alphanumeric strings. Values can be strings, numbers, booleans, or even arrays and dictionaries - anything that can be JSON-encoded.

Each PFObject has a class name that you can use to distinguish different sorts of data. For example, we could call the high score object a GameScore. We recommend that you NameYourClassesLikeThis and nameYourKeysLikeThis, just to keep your code looking pretty.

Saving Objects

Let’s say you want to save the GameScore described above to a Parse Server. The interface is similar to a NSMutableDictionary. The saveInBackgroundWithBlock function:

PFObject *gameScore = [PFObject objectWithClassName:@"GameScore"];
gameScore[@"score"] = @1337;
gameScore[@"playerName"] = @"Sean Plott";
gameScore[@"cheatMode"] = @NO;
[gameScore saveInBackgroundWithBlock:^(BOOL succeeded, NSError * _Nullable error) {
  if (succeeded) {
    // The object has been saved.
  } else {
    // There was a problem, check error.description
  }
}];

let gameScore = PFObject(className:"GameScore")
gameScore["score"] = 1337
gameScore["playerName"] = "Sean Plott"
gameScore["cheatMode"] = false
gameScore.saveInBackground { (succeeded, error)  in
    if (succeeded) {
        // The object has been saved.
    } else {
        // There was a problem, check error.description
    }
}

After this code runs, you will probably be wondering if anything really happened. If Parse Dashboard is implemented for your server, you can verify the data was saved in the data browser. You should see something like this:

{
  "objectId": "xWMyZ4YEGZ",
  "score": 1337,
  "playerName": "Sean Plott",
  "cheatMode": false,
  "createdAt":"2022-01-01T12:23:45.678Z",
  "updatedAt":"2022-01-01T12:23:45.678Z"
}

There are two things to note here. You didn’t have to configure or set up a new Class called GameScore before running this code. Your Parse app lazily creates this Class for you when it first encounters it.

There are also a few fields you don’t need to specify that are provided and set by the system as a convenience. objectId is a unique identifier for each saved object. createdAt and updatedAt represent the time that each object was created or last modified and saved to the Parse Server. Each of these fields is filled in by Parse Server, so they don’t exist on a PFObject until the first save operation has been completed.

Retrieving Objects

Saving data to the cloud is fun, but it’s even more fun to get that data out again. If the PFObject has been uploaded to the server, you can retrieve it with its objectId by using a PFQuery. This is an asynchronous method, with variations for using either blocks or callback methods:

PFQuery *query = [PFQuery queryWithClassName:@"GameScore"];
[query getObjectInBackgroundWithId:@"xWMyZ4YEGZ" block:^(PFObject *gameScore, NSError *error) {
    if (!error) {
        // Success!
    } else {
        // Failure!
    }
}];

let query = PFQuery(className:"GameScore")
query.getObjectInBackground(withId: "xWMyZEGZ") { (gameScore, error) in
    if error == nil {
        // Success!
    } else {
        // Fail!
    }
}

To get the values out of the PFObject, you can use either the objectForKey: method or the [] subscripting operator:

int score = [[gameScore objectForKey:@"score"] intValue];
NSString *playerName = gameScore[@"playerName"];
BOOL cheatMode = [gameScore[@"cheatMode"] boolValue];

let score = gameScore["score"] as? Int
let playerName = gameScore["playerName"] as? String
let cheatMode = gameScore["cheatMode"] as? Bool

The four special values are provided as properties:

NSString *objectId = gameScore.objectId;
NSDate *updatedAt = gameScore.updatedAt;
NSDate *createdAt = gameScore.createdAt;
PFACL *ACL = gameScore.ACL;

let objectId = gameScore.objectId
let updatedAt = gameScore.updatedAt
let createdAt = gameScore.createdAt
let acl = gameScore.acl

If you need to refresh an object you already have with the latest data that is in the database, you can use the fetchInBackgroundWithBlock: or fetchInBackgroundWithTarget:selector: methods.

[myObject fetchInBackgroundWithBlock:^(PFObject * _Nullable object, NSError * _Nullable error) {
    if (!error) {
        // Success!
    } else {
        // Failure!
    }
}];

myObject.fetchInBackground { (object, error) in
    if error == nil {
        // Success!
    } else {
        // Failure!
    }
}

Note: In a similar way to the save methods, you can use the throwable fetch or fetchIfNeeded methods, or asyncronous task without completion. fetchInBackground

The Local Datastore

Parse also lets you store objects in a local datastore on the device itself. You can use this for data that doesn’t need to be saved to the cloud, but this is especially useful for temporarily storing data so that it can be synced later. To enable the datastore, add isLocalDatastoreEnabled = true to the ParseClientConfiguration block in your AppDelegate application:didFinishLaunchWithOptions:, or call Parse.enableLocalDatastore() before calling Parse.initialize(). Once the local datastore is enabled, you can store an object by pinning it.

PFObject *gameScore = [PFObject objectWithClassName:@"GameScore"];
gameScore[@"score"] = 1337;
gameScore[@"playerName"] = @"Sean Plott";
gameScore[@"cheatMode"] = @NO;
[gameScore pinInBackground];

let gameScore = PFObject(className:"GameScore")
gameScore["score"] = 1337
gameScore["playerName"] = "Sean Plott"
gameScore["cheatMode"] = false
gameScore.pinInBackground()

As with saving, this recursively stores every object and file that gameScore points to, if it has been fetched from the cloud. Whenever you save changes to the object, or fetch new changes from Parse, the copy in the datastore will be automatically updated, so you don’t have to worry about it.

Retrieving Objects from the Local Datastore

Storing an object is only useful if you can get it back out. To get the data for a specific object, you can use a PFQuery just like you would while on the network, but using the fromLocalDatastore: method to tell it where to get the data.

PFQuery *query = [PFQuery queryWithClassName:@"GameScore"];
[query fromLocalDatastore];
[[query getObjectInBackgroundWithId:@"xWMyZ4YEGZ"] continueWithBlock:^id(BFTask *task) {
  if (task.error) {
    // something went wrong;
    return task;
  }

  // task.result will be your game score
  return task;
}];

let query = PFQuery(className:"GameScore")
query.fromLocalDatastore()
query.getObjectInBackground(withId: "xWMyZEGZ").continueWith { (task: BFTask<PFObject>!) -> Any? in
    if task.error != nil {
        // There was an error.
        return task
    }

    // task.result will be your game score
    return task
}

If you already have an instance of the object, you can instead use the fetchFromLocalDatastoreInBackground: method.

PFObject *object = [PFObject objectWithoutDataWithClassName:@"GameScore" objectId:@"xWMyZ4YEGZ"];
[[object fetchFromLocalDatastoreInBackground] continueWithBlock:^id(BFTask *task) {
  if (task.error) {
    // something went wrong
    return task;
  }

  // task.result will be your game score
  return task;
}];

let object = PFObject(withoutDataWithClassName:"GameScore", objectId:"xWMyZ4YEGZ")
object.fetchFromLocalDatastoreInBackground().continueWith { (task: BFTask<PFObject>!) -> Any? in
    if task.error != nil {
        // There was an error.
        return task
    }

    // task.result will be your game score
    return task
}

Unpinning Objects

When you are done with the object and no longer need to keep it on the device, you can release it with unpinInBackground:.

[gameScore unpinInBackground];

gameScore.unpinInBackground()

Saving Objects Offline

Most save functions execute immediately, and inform your app when the save is complete. For a network consious soltion on non-priority save requests use saveEventually. Not only does it retry saving upon regaining network connection, but If your app is closed prior to save completion Parse will try the next time the app is opened. Additionally, all calls to saveEventually (and deleteEventually) are executed in the order they are called, making it safe to call saveEventually on an object multiple times.

// Create the object.
PFObject *gameScore = [PFObject objectWithClassName:@"GameScore"];
gameScore[@"score"] = @1337;
gameScore[@"playerName"] = @"Sean Plott";
gameScore[@"cheatMode"] = @NO;
[gameScore saveEventually];

let gameScore = PFObject(className:"GameScore")
gameScore["score"] = 1337
gameScore["playerName"] = "Sean Plott"
gameScore["cheatMode"] = false
gameScore.saveEventually()

Updating Objects

Updating an object is simple. Just set some new data on it and call one of the save methods. Assuming you have saved the object and have the objectId, you can retrieve the PFObject using a PFQuery and update its data:

PFQuery *query = [PFQuery queryWithClassName:@"GameScore"];

// Retrieve the object by id
[query getObjectInBackgroundWithId:@"xWMyZ4YEGZ"
                             block:^(PFObject *gameScore, NSError *error) {
    // Now let's update it with some new data. In this case, only cheatMode and score
    // will get sent to the cloud. playerName hasn't changed.
    gameScore[@"cheatMode"] = @YES;
    gameScore[@"score"] = @1338;
    [gameScore saveInBackground];
}];

let query = PFQuery(className:"GameScore")
query.getObjectInBackground(withId: "xWMyZEGZ") { (gameScore: PFObject?, error: Error?) in
    if let error = error {
        print(error.localizedDescription)
    } else if let gameScore = gameScore {
        gameScore["cheatMode"] = true
        gameScore["score"] = 1338
        gameScore.saveInBackground()
    }
}

The client automatically figures out which data has changed so only “dirty” fields will be sent to Parse. You don’t need to worry about squashing data that you didn’t intend to update.

Counters

The above example contains a common use case. The “score” field is a counter that we’ll need to continually update with the player’s latest score. Using the above method works but it’s cumbersome and can lead to problems if you have multiple clients trying to update the same counter.

To help with storing counter-type data, Parse provides methods that atomically increment (or decrement) any number field. So, the same update can be rewritten as:

[gameScore incrementKey:@"score"];
[gameScore saveInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
  if (succeeded) {
    // The score key has been incremented
  } else {
    // There was a problem, check error.description
  }
}];

let gameScore = PFObject(className:"GameScore")
gameScore.incrementKey("score")
gameScore.saveInBackground {
  (success: Bool, error: Error?) in
  if (success) {
    // The score key has been incremented
  } else {
    // There was a problem, check error.description
  }
}

You can also increment by any amount using incrementKey:byAmount:.

Arrays

To help with storing array data, there are three operations that can be used to atomically change an array field:

• addObject:forKey: and addObjectsFromArray:forKey: append the given objects to the end of an array field.
• addUniqueObject:forKey: and addUniqueObjectsFromArray:forKey: add only the given objects which aren’t already contained in an array field to that field. The position of the insert is not guaranteed.
• removeObject:forKey: and removeObjectsInArray:forKey: remove all instances of each given object from an array field.

For example, we can add items to the set-like “skills” field like so:

[gameScore addUniqueObjectsFromArray:@[@"flying", @"kungfu"] forKey:@"skills"];
[gameScore saveInBackground];

gameScore.addUniqueObjects(from: ["flying", "kungfu"], forKey:"skills")
gameScore.saveInBackground()

Note that it is not currently possible to atomically add and remove items from an array in the same save using. You will have to call save in between every different kind of array operation.

Deleting Objects

There are a few ways to delete a PFObject. For basic asynchronous deletion of a single object call the objects deleteInBackground function. If you prefer to recieve a callback you can use the deleteInBackgroundWithBlock: or deleteInBackgroundWithTarget:selector: methods. If you want to block the calling thread, you can use the delete method. Lastly, deleteEventually is a network conscious option that deletes when possible but does not guarantee a timeframe for the tasks completion.

For deleting multiple objects use the PFObject static function deleteAllInBackground to delete an array of objects asynchronously. The same can be done while blocking the calling thread using deleteAll. Lastly, to recieve a callback after deleting objects asyncronously use deleteAllInBackground:block: as demonstrated below.

[PFObject deleteAllInBackground:objectArray block:^(BOOL succeeded, NSError * _Nullable error) {
    if (succeeded) {
        // The array of objects was successfully deleted.
    } else {
        // There was an error. Check the errors localizedDescription.
    }
}];

PFObject.deleteAll(inBackground: objectArray) { (succeeded, error) in
    if (succeeded) {
        // The array of objects was successfully deleted.
    } else {
        // There was an error. Check the errors localizedDescription.
    }
}

Note: Deleting an object from the server that contains a PFFileObject does NOT delete the file from storage. Instead, an objects deletion only deletes the data referencing the stored file. To delete the data from storage you must use the REST API. For more info about PFFileObject, please see the Files section.

Relational Data

Objects can have relationships with other objects. To model this behavior, any PFObject can be used as a value in other PFObjects. Internally, the Parse framework will store the referred-to object in just one place, to maintain consistency.

For example, each Comment in a blogging app might correspond to one Post. To create a new Post with a single Comment, you could write:

// Create the post
PFObject *myPost = [PFObject objectWithClassName:@"Post"];
myPost[@"title"] = @"I'm Hungry";
myPost[@"content"] = @"Where should we go for lunch?";

// Create the comment
PFObject *myComment = [PFObject objectWithClassName:@"Comment"];
myComment[@"content"] = @"Let's do Sushirrito.";

// Add a relation between the Post and Comment
myComment[@"post"] = myPost;

// This will save both myPost and myComment
[myComment saveInBackground];

// Create the post
let myPost = PFObject(className:"Post")
myPost["title"] = "I'm Hungry"
myPost["content"] = "Where should we go for lunch?"

// Create the comment
let myComment = PFObject(className:"Comment")
myComment["content"] = "Let's do Sushirrito."

// Add a relation between the Post and Comment
myComment["post"] = myPost

// This will save both myPost and myComment
myComment.saveInBackground()

Note: Saving an object with a relational pointer to another object will save both objects. However, two new objects with pointers to each other will cause a error for having a circular dependency.

Object Relationships With Minimal Data

You can link objects without even fetching data by initializing PFObjects with only the class name and the objects objectId like so:

myComment[@"post"] = [PFObject objectWithoutDataWithClassName:@"Post" objectId:@"1zEcyElZ80"];

// Add a relation between the Post with objectId "1zEcyElZ80" and the comment
myComment["post"] = PFObject(withoutDataWithClassName: "Post", objectId: "1zEcyElZ80")

By default, when fetching an object, related PFObjects are not fetched. These objects’ values cannot be retrieved until they have been fetched like so:

PFObject *post = myComment[@"post"];
[post fetchInBackgroundWithBlock:^(PFObject * _Nullable object, NSError * _Nullable error) {
    NSString *title = post[@"title"];
    if (title) {  // do something with title }
}];

let post = myComment["post"] as! PFObject
post.fetchIfNeededInBackground { (object, error) in
    if let title = post["title"] as? String {
        // do something with your title variable
    } else if let errorString = error?.localizedDescription {
        print(errorString)
    }
}

You can also model a many-to-many relation using the PFRelation object. This works similar to an NSArray of PFObjects, except that you don’t need to download all the Objects in a relation at once. This allows PFRelation to scale to many more objects than the NSArray of PFObject approach. For example, a User may have many Posts that they might like. In this case, you can store the set of Posts that a User likes using relationForKey:. In order to add a post to the list, the code would look something like:

PFUser *user = [PFUser currentUser];
PFRelation *relation = [user relationForKey:@"likes"];
[relation addObject:post];
[user saveInBackgroundWithBlock:^(BOOL succeeded, NSError * _Nullable error) {
    if (succeeded) {
        // The post has been added to the user's likes relation.
    } else {
        // There was a problem, check error.description
    }
}];

guard let user = PFUser.current() else { return }
let relation = user.relation(forKey: "likes")
relation.add(post)
user.saveInBackground { (succeeded, error) in
    if (succeeded) {
        // The post has been added to the user's likes relation.
    } else {
        // There was a problem, check error.description
    }
}

You can remove a post from the PFRelation similarly using the removeObject: function followed by saving the parent object.

By default, the list of objects in this relation are not downloaded. You can get the list of Posts by using calling findObjectsInBackgroundWithBlock: on the PFQuery returned by query. The code would look like:

[[relation query] findObjectsInBackgroundWithBlock:^(NSArray * _Nullable objects, NSError * _Nullable error) {
    if (error) {
        // There was an error
    } else {
        // objects has all the Posts the current user liked.
    }
}];

relation.query().findObjectsInBackground { (object, error) in
    if error == nil {
        // Success
    } else {
        // Failure!
    }
})

You can add constraints to a PFRelation’s query by adding constraints to the PFQuery returned by its query parameter as demonstrated below:

PFQuery *query = [relation query];
[query whereKey:"category" equalTo:@"development"];
PFObject *object = [query getFirstObject]; // Query first object found
if (object) {
    // Do something with object
}

var query = relation.query()
query.whereKey("category", equalTo: "development") 

// Query first object found
if let object = try? query.getFirstObject() {
    // Do something with object
} ```
</div>

You can learn more about queries by visiting the [PFQuery](#queries) section. A `PFRelation` behaves similarly to an array of  `PFObject` yet has a built in query that's capable of everything a standard `PFQuery` is other than `includeKey:`.

## Data Types

So far we've used values with type `NSString`, `NSNumber`, and `PFObject`. Parse also supports `NSDate`, `NSObject`, `NSArray`, and `NSNull`. You can nest `NSObject` and `NSArray` objects to store more structured data within a single `PFObject`. Overall, the following types are allowed for each field in your object:

* String => `NSString`
* Number => `NSNumber`
* Bool => `NSNumber`
* Array => `NSArray`
* Object => `NSObject`
* Date => `NSDate`
* File => `PFFileObject`
* Pointer => other `PFObject`
* Relation => `PFRelation`
* Null => `NSNull`

Some examples:

<div class="language-toggle" markdown="1">
```objective_c
NSNumber *number = @42;
NSNumber *bool = @NO;
NSString *string = [NSString stringWithFormat:@"the number is %@", number];
NSDate *date = [NSDate date];
NSArray *array = @[string, number];
NSDictionary *dictionary = @{@"number": number, @"string": string};
NSNull *null = [NSNull null];
PFObject *pointer = [PFObject objectWithoutDataWithClassName:@"MyClassName" objectId:@"xyz"];

PFObject *bigObject = [PFObject objectWithClassName:@"BigObject"];
bigObject[@"myNumberKey"] = number;
bigObject[@"myBoolKey"] = bool;
bigObject[@"myStringKey"] = string;
bigObject[@"myDateKey"] = date;
bigObject[@"myArrayKey"] = array;
bigObject[@"myObjectKey"] = dictionary; // shows up as 'object' in the Data Browser
bigObject[@"anyKey"] = null; // this value can only be saved to an existing key
bigObject[@"myPointerKey"] = pointer; // shows up as Pointer MyClassName in the Data Browser
[bigObject saveInBackground];

let number = 42
let bool = false
let string = "the number is \(number)"
let date = NSDate()
let array = [string, number]
let dictionary = ["number": number, "string": string]
let null = NSNull()
let pointer = PFObject(objectWithoutDataWithClassName:"MyClassName", objectId: "xyz")

var bigObject = PFObject(className:"BigObject")
bigObject["myNumberKey"] = number
bigObject["myBooleanKey"] = bool
bigObject["myStringKey"] = string
bigObject["myDateKey"] = date
bigObject["myArrayKey"] = array
bigObject["myObjectKey"] = dictionary // shows up as 'object' in the Data Browser
bigObject["anyKey"] = null // this value can only be saved to an existing key
bigObject["myPointerKey"] = pointer // shows up as Pointer MyClassName in the Data Browser
bigObject.saveInBackground()

We do not recommend storing large pieces of binary data like images or documents on PFObject. We recommend you use PFFileObjects to store images, documents, and other types of files. You can do so by instantiating a PFFileObject object and setting it on a field. See Files for more details.

For more information about how Parse handles data, check out our documentation on Data.

Subclasses

Parse is designed to get you up and running as quickly as possible. You can access all of your data using the PFObject class and access any field with objectForKey: or the [] subscripting operator. In mature codebases, subclasses have many advantages, including terseness, extensibility, and support for autocomplete. Subclassing is completely optional, but can transform this code:

PFObject *shield = [PFObject objectWithClassName:@"Armor"];
shield[@"displayName"] = @"Wooden Shield";
shield[@"fireProof"] = @NO;
shield[@"rupees"] = @50;

var shield = PFObject(className: "Armor")
shield["displayName"] = "Wooden Shield"
shield["fireProof"] = false
shield["rupees"] = 50

Into this:

Armor *shield = [Armor object];
shield.displayName = @"Wooden Shield";
shield.fireProof = NO;
shield.rupees = 50;

var shield = Armor()
shield.displayName = "Wooden Shield"
shield.fireProof = false
shield.rupees = 50

Subclassing PFObject

To create a subclass:

1. Declare a subclass of PFObject which conforms to the PFSubclassing protocol.
2. Implement the static method parseClassName and return the string you would pass to initWithClassName:. This makes all future class name references unnecessary.

Note: Objective-C developers should Import PFObject+Subclass in your .m file. This implements all methods in PFSubclassing beyond parseClassName.

Properties & Methods

Adding custom properties and methods to your PFObject subclass helps encapsulate logic about the class. With PFSubclassing, you can keep all your logic about a subject in one place rather than using separate classes for business logic and storage/transmission logic.

PFObject supports dynamic synthesizers just like NSManagedObject. Declare a property as you normally would, but use @dynamic rather than @synthesize in your .m file. The following example creates a displayName property in the Armor class:

You can access the displayName property using armor.displayName or [armor displayName] and assign to it using armor.displayName = @"Wooden Shield" or [armor setDisplayName:@"Wooden Sword"]. Dynamic properties allow Xcode to provide autocomplete and catch typos.

NSNumber properties can be implemented either as NSNumbers or as their primitive counterparts. Consider the following example:

@property BOOL fireProof;
@property int rupees;

@NSManaged var fireProof: Boolean
@NSManaged var rupees: Int

In this case, game[@"fireProof"] will return an NSNumber which is accessed using boolValue and game[@"rupees"] will return an NSNumber which is accessed using intValue, but the fireProof property is an actual BOOL and the rupees property is an actual int. The dynamic getter will automatically extract the BOOL or int value and the dynamic setter will automatically wrap the value in an NSNumber. You are free to use either format. Primitive property types are easier to use but NSNumber property types support nil values more clearly.

If you need more complicated logic than simple property access, you can declare your own methods as well:

@dynamic iconFile;

- (UIImageView *)iconView {
  PFImageView *view = [[PFImageView alloc] initWithImage:kPlaceholderImage];
  view.file = self.iconFile;
  [view loadInBackground];
  
  return view;
}

@NSManaged var iconFile: PFFileObject!

func iconView() -> UIImageView {
  let view = PFImageView(imageView: PlaceholderImage)
  view.file = iconFile
  view.loadInBackground()
  
  return view
}

Initializing Subclasses

You should initialize new instances of subclassses with standard initialization methods. To create a new instance of an existing Parse object, use the inherited PFObject class function objectWithoutDataWithObjectId:, or create a new object and set the objectId property manually.

Queries

We’ve already seen how a PFQuery with getObjectInBackgroundWithId:block: can retrieve a single PFObject from Parse. There are many other ways to retrieve data with PFQuery - you can retrieve many objects at once, put conditions on the objects you wish to retrieve, cache queries automatically to avoid writing that code yourself, and more.

Basic Queries

In many cases, getObjectInBackgroundWithId:block: isn’t powerful enough to specify which objects you want to retrieve. The PFQuery offers different ways to retrieve a list of objects rather than just a single object.

The general pattern is to create a PFQuery, put conditions on it, and then retrieve a NSArray of matching PFObjects using either findObjectsInBackgroundWithBlock: or findObjectsInBackgroundWithTarget:selector:. For example, to retrieve scores with a particular playerName, use the whereKey:equalTo: method to constrain the value for a key.

PFQuery *query = [PFQuery queryWithClassName:@"GameScore"];
[query whereKey:@"playerName" equalTo:@"Dan Stemkoski"];
[query findObjectsInBackgroundWithBlock:^(NSArray *objects, NSError *error) {
  if (!error) {
    // The find succeeded.
    NSLog(@"Successfully retrieved %d scores.", objects.count);
    // Do something with the found objects
    for (PFObject *object in objects) {
        NSLog(@"%@", object.objectId);
    }
  } else {
    // Log details of the failure
    NSLog(@"Error: %@ %@", error, [error userInfo]);
  }
}];

let query = PFQuery(className:"GameScore")
query.whereKey("playerName", equalTo:"Sean Plott")
query.findObjectsInBackground { (objects: [PFObject]?, error: Error?) in
    if let error = error {
        // Log details of the failure
        print(error.localizedDescription)
    } else if let objects = objects {
        // The find succeeded.
        print("Successfully retrieved \(objects.count) scores.")
        // Do something with the found objects
        for object in objects {
            print(object.objectId as Any)
        }
    }
}

Both findObjectsInBackgroundWithBlock: and findObjectsInBackgroundWithTarget:selector: work similarly in that they assure the network request is done without blocking, and run the block/callback in the main thread. There is a corresponding findObjects method that blocks the calling thread, if you are already in a background thread:

// Only use this code if you are already running it in a background
// thread, or for testing purposes!

// Using PFQuery
PFQuery *query = [PFQuery queryWithClassName:@"GameScore"];
[query whereKey:@"playerName" equalTo:@"Dan Stemkoski"];
NSArray* scoreArray = [query findObjects];

// Using NSPredicate
NSPredicate *predicate = [NSPredicate predicateWithFormat:@"playerName = 'Dan Stemkosk'"];
PFQuery *query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate];
NSArray* scoreArray = [query findObjects];

// Only use this code if you are already running it in a background
// thread, or for testing purposes!

// Using PFQuery
let query = PFQuery(className: "GameScore")
query.whereKey("playerName", equalTo: "Dan Stemkoski")
let scoreArray = query.findObjects()

// Using NSPredicate
let predicate = NSPredicate(format:"playerName = 'Dan Stemkosk'")
let query = PFQuery(className: "GameScore", predicate: predicate)
let scoreArray = query.findObjects()

Specifying Constraints with NSPredicate

To get the most out of PFQuery we recommend using its methods listed below to add constraints. However, if you prefer using NSPredicate, a subset of the constraints can be specified by providing an NSPredicate when creating your PFQuery.

NSPredicate *predicate = [NSPredicate predicateWithFormat:@"playerName = 'Dan Stemkosk'"];
PFQuery *query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate];

let predicate = NSPredicate(format: "playerName = 'Dan Stemkosk'")
let query = PFQuery(className: "GameScore", predicate: predicate)

These features 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.
• Sub-queries 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.

Query Constraints

There are several ways to put constraints on the objects found by a PFQuery. You can filter out objects with a particular key-value pair with whereKey:notEqualTo:

// Using PFQuery
[query whereKey:@"playerName" notEqualTo:@"Michael Yabuti"];

// Using NSPredicate
NSPredicate *predicate = [NSPredicate predicateWithFormat:   @"playerName != 'Michael Yabuti'"];
PFQuery *query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate];

// Using PFQuery
query.whereKey("playerName", notEqualTo: "Michael Yabuti")

// Using NSPredicate
let predicate = NSPredicate(format:"playerName != 'Michael Yabuti'")
let query = PFQuery(className: "GameScore", predicate: predicate)

You can give multiple constraints, and objects will only be in the results if they match all of the constraints. In other words, it’s like an AND of constraints.

// Using PFQuery
[query whereKey:@"playerName" notEqualTo:@"Michael Yabuti"];
[query whereKey:@"playerAge" greaterThan:@18];

// Using NSPredicate
NSPredicate *predicate = [NSPredicate predicateWithFormat:   @"playerName != 'Michael Yabuti' AND playerAge > 18"];
PFQuery *query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate];

// Using PFQuery
query.whereKey("playerName", notEqualTo: "Michael Yabuti")
query.whereKey("playerAge", greaterThan: 18)

// Using NSPredicate
let predicate = NSPredicate(format:"playerName != 'Michael Yabuti' AND playerAge > 18")
let query = PFQuery(className: "GameScore", predicate: predicate)

You can limit the number of results by setting limit. By default, results are limited to 100. In the old Parse hosted backend, the maximum limit was 1,000, but Parse Server removed that constraint:

query.limit = 10; // limit to at most 10 results

query.limit = 10 // limit to at most 10 results

If you want exactly one result, a more convenient alternative may be to use getFirstObject or getFirstObjectInBackground instead of using findObject.

PFQuery *query = [PFQuery queryWithClassName:@"GameScore"];
[query whereKey:@"playerEmail" equalTo:@"[email protected]"];
[query getFirstObjectInBackgroundWithBlock:^(PFObject *object, NSError *error) {
  if (!object) {
    NSLog(@"The getFirstObject request failed.");
  } else {
    // The find succeeded.
    NSLog(@"Successfully retrieved the object.");
  }
}];

let query = PFQuery(className: "GameScore")
query.whereKey("playerEmail", equalTo: "[email protected]")
query.getFirstObjectInBackground { (object: PFObject?, error: Error?) in
    if let error = error {
        // The query failed
        print(error.localizedDescription)
    } else if let object = object {
        // The query succeeded with a matching result
        print(object)
    } else {
        // The query succeeded but no matching result was found
    }
}

You can skip the first results by setting skip. In the old Parse hosted backend, the maximum skip value was 10,000, but Parse Server removed that constraint. This can be useful for pagination:

query.skip = 10; // skip the first 10 results

query.skip = 10

For sortable types like numbers and strings, you can control the order in which results are returned:

// Sorts the results in ascending order by the score field
[query orderByAscending:@"score"];

// Sorts the results in descending order by the score field
[query orderByDescending:@"score"];

// Sorts the results in ascending order by the score field
query.order(byAscending: "score")

// Sorts the results in descending order by the score field
query.order(byDescending: "score")

You can add more sort keys to the query as follows:

// Sorts the results in ascending order by the score field if the previous sort keys are equal.
[query addAscendingOrder:@"score"];

// Sorts the results in descending order by the score field if the previous sort keys are equal.
[query addDescendingOrder:@"score"];

// Sorts the results in ascending order by the score field if the previous sort keys are equal.
query.addAscendingOrder("score")

// Sorts the results in descending order by the score field if the previous sort keys are equal.
query.addDescendingOrder("score")

For sortable types, you can also use comparisons in queries:

// Restricts to wins < 50
[query whereKey:@"wins" lessThan:@50];
// Or with NSPredicate
NSPredicate *predicate = [NSPredicate predicateWithFormat:@"wins < 50"];
PFQuery *query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate];

// Restricts to wins <= 50
[query whereKey:@"wins" lessThanOrEqualTo:@50];
// Or with NSPredicate
predicate = [NSPredicate predicateWithFormat:@"wins <= 50"];
query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate]

// Restricts to wins > 50
[query whereKey:@"wins" greaterThan:@50];
// Or with NSPredicate
predicate = [NSPredicate predicateWithFormat:@"wins > 50"];
query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate];

// Restricts to wins >= 50
[query whereKey:@"wins" greaterThanOrEqualTo:@50];
// Or with NSPredicate
predicate = [NSPredicate predicateWithFormat:@"wins >= 50"];
query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate];

// Restricts to wins < 50
query.whereKey("wins", lessThan: 50)
// Or with NSPredicate
let predicate = NSPredicate(format: "wins < 50")
let query = PFQuery(className: "GameScore", predicate: predicate)

// Restricts to wins <= 50
query.whereKey("wins", lessThanOrEqualTo: 50)
// Or with NSPredicate
let predicate = NSPredicate(format: "wins <= 50")
let query = PFQuery(className: "GameScore", predicate: predicate)

// Restricts to wins > 50
query.whereKey("wins", greaterThan: 50)
// Or with NSPredicate
let predicate = NSPredicate(format: "wins > 50")
let query = PFQuery(className: "GameScore", predicate: predicate)

// Restricts to wins >= 50
query.whereKey("wins", greaterThanOrEqualTo: 50)
// Or with NSPredicate
let predicate = NSPredicate(format: "wins >= 50")
let query = PFQuery(className: "GameScore", predicate: predicate)

If you want to retrieve objects matching several different values, you can use whereKey:containedIn:, providing an array of acceptable values. This is often useful to replace multiple queries with a single query. For example, if you want to retrieve scores made by any player in a particular list:

// Finds scores from any of Jonathan, Dario, or Shawn
// Using PFQuery
NSArray *names = @[@"Jonathan Walsh", @"Dario Wunsch", @"Shawn Simon"];
[query whereKey:@"playerName" containedIn:names];

// Using NSPredicate
NSArray *names = @[@"Jonathan Walsh", @"Dario Wunsch", @"Shawn Simon"];
NSPredicate *pred = [NSPredicate predicateWithFormat: @"playerName IN %@", names];
PFQuery *query = [PFQuery queryWithClassName:@"GameScore" predicate:pred];

// Finds scores from any of Jonathan, Dario, or Shawn
// Using PFQuery
let names = ["Jonathan Walsh", "Dario Wunsch", "Shawn Simon"]
query.whereKey("playerName", containedIn: names)

// Using NSPredicate
let names = ["Jonathan Walsh", "Dario Wunsch", "Shawn Simon"]
let predicate = NSPredicate(format: "playerName IN %@", names)
let query = PFQuery(className: "GameScore", predicate: predicate)

If you want to retrieve objects that do not match any of several values you can use whereKey:notContainedIn:, providing an array of acceptable values. For example, if you want to retrieve scores from players besides those in a list:

// Finds scores from anyone who is neither Jonathan, Dario, nor Shawn
// Using PFQuery
NSArray *names = @[@"Jonathan Walsh", @"Dario Wunsch", @"Shawn Simon"];
[query whereKey:@"playerName" notContainedIn:names];

// Using NSPredicate
NSArray *names = @[@"Jonathan Walsh", @"Dario Wunsch", @"Shawn Simon"];
NSPredicate *pred = [NSPredicate predicateWithFormat: @"NOT (playerName IN %@)", names];
PFQuery *query = [PFQuery queryWithClassName:@"GameScore" predicate:pred];

// Finds scores from anyone who is neither Jonathan, Dario, nor Shawn
// Using PFQuery
let names = ["Jonathan Walsh", "Dario Wunsch", "Shawn Simon"]
query.whereKey("playerName", notContainedIn: names)

// Using NSPredicate
let names = ["Jonathan Walsh", "Dario Wunsch", "Shawn Simon"]
let predicate = NSPredicate(format: "NOT (playerName IN %@)", names)
let query = PFQuery(className: "GameScore", predicate: predicate)

If you want to retrieve objects that have a particular key set, you can use whereKeyExists. Conversely, if you want to retrieve objects without a particular key set, you can use whereKeyDoesNotExist.

// Finds objects that have the score set
[query whereKeyExists:@"score"];
// Or using NSPredicate
NSPredicate *predicate = [NSPredicate predicateWithFormat:@"score IN SELF"];
PFQuery *query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate];

// Finds objects that don't have the score set
[query whereKeyDoesNotExist:@"score"];
// Or using NSPredicate
NSPredicate *predicate = [NSPredicate predicateWithFormat:@"NOT (score IN SELF)"];
PFQuery *query = [PFQuery queryWithClassName:@"GameScore" predicate:predicate];

// Finds objects that have the score set
query.whereKeyExists("score")
// Or using NSPredicate
let predicate = NSPredicate(format: "score IN SELF")
let query = PFQuery(className: "GameScore", predicate: predicate)

// Finds objects that don't have the score set
query.whereKeyDoesNotExist("score")
// Or using NSPredicate
let predicate = NSPredicate(format: "NOT (score IN SELF)")
let query = PFQuery(className: "GameScore", predicate: predicate)

You can use the whereKey:matchesKey:inQuery: method to get objects where a key matches the value of a key in a set of objects resulting from another query. For example, if you have a class containing sports teams and you store a user’s hometown in the user class, you can issue one query to find the list of users whose hometown teams have winning records. The query would look like:

PFQuery *teamQuery = [PFQuery queryWithClassName:@"Team"];
[teamQuery whereKey:@"winPct" greaterThan:@(0.5)];
PFQuery *userQuery = [PFQuery queryForUser];
[userQuery whereKey:@"hometown" matchesKey:@"city" inQuery:teamQuery];
[userQuery findObjectsInBackgroundWithBlock:^(NSArray *results, NSError *error) {
    // results will contain users with a hometown team with a winning record
}];

let teamQuery = PFQuery(className:"Team")
teamQuery.whereKey("winPct", greaterThan:0.5)
let userQuery = PFUser.query()
userQuery?.whereKey("hometown", matchesKey: "city", in: teamQuery)
userQuery?.findObjectsInBackground(block: { (results: [PFObject]?, error: Error?) in
    if let error = error {
        // The query failed
        print(error.localizedDescription)
    } else {
        // results will contain users with a hometown team with a winning record
    }
})

Conversely, to get objects where a key does not match the value of a key in a set of objects resulting from another query, use whereKey:doesNotMatchKey:inQuery:. For example, to find users whose hometown teams have losing records:

PFQuery *losingUserQuery = [PFQuery queryForUser];
[losingUserQuery whereKey:@"hometown" doesNotMatchKey:@"city" inQuery:teamQuery];
[losingUserQuery findObjectsInBackgroundWithBlock:^(NSArray *results, NSError *error) {
    // results will contain users with a hometown team with a losing record
}];

let teamQuery = PFQuery(className:"Team")
teamQuery.whereKey("winPct", greaterThan:0.5)
let losingUserQuery = PFUser.query()
losingUserQuery?.whereKey("hometown", doesNotMatchKey:"city", in: teamQuery)
losingUserQuery?.findObjectsInBackground(block: { (results: [PFObject]?, error: Error?) in
    if let error = error {
        // The query failed
        print(error.localizedDescription)
    } else {
        // results will contain users with a hometown team with a losing records
    }
})

You can restrict the fields returned by calling selectKeys: with an NSArray of keys. To retrieve documents that contain only the score and playerName fields (and also special built-in fields such as objectId, createdAt, and updatedAt):

PFQuery *query = [PFQuery queryWithClassName:@"GameScore"];
[query selectKeys:@[@"playerName", @"score"]];
[query findObjectsInBackgroundWithBlock:^(NSArray *results, NSError *error) {
    // objects in results will only contain the playerName and score fields
}];

let query = PFQuery(className:"GameScore")
query.selectKeys(["playerName", "score"])
query.findObjectsInBackground { (objects: [PFObject]?, error: Error?) in
    if let error = error {
        // The query failed
        print(error.localizedDescription)
    } else {
        // objects in results will only contain the playerName and score fields
    }
}

The remaining fields can be fetched later by calling one of the fetchIfNeeded variants on the returned objects:

PFObject *object = (PFObject*)results[0];
[object fetchIfNeededInBackgroundWithBlock:^(PFObject *object, NSError *error) {
  // all fields of the object will now be available here.
}];

// Use array of PFObjects from earlier query
var object = objects?[0] as! PFObject
object.fetchInBackground(block: { (object: PFObject?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else {
        // all fields of the object will now be available here.
    }
})

Queries on Array Values

For keys with an array type, you can find objects where the key’s array value contains 2 by:

// Find objects where the array in arrayKey contains 2.
// Using PFQuery
[query whereKey:@"arrayKey" equalTo:@2];

// Or using NSPredicate
NSPredicate *predicate = [NSPredicate predicateWithFormat:@"2 IN arrayKey"];
PFQuery *query = [PFQuery queryWithClassName:@"MyClass" predicate:predicate];

// Find objects where the array in arrayKey contains 2.
// Using PFQuery
query.whereKey("arrayKey", equalTo: 2)

// Or using NSPredicate
let predicate = NSPredicate(format: "2 IN arrayKey")
let query = PFQuery(className: "MyClass", predicate: predicate)

You can also find objects where the key’s array value contains each of the values 2, 3, and 4 with the following:

// Find objects where the array in arrayKey contains each of the
// elements 2, 3, and 4.
[query whereKey:@"arrayKey" containsAllObjectsInArray:@[@2, @3, @4]];

// Find objects where the array in arrayKey contains each of the
// elements 2, 3, and 4.
query.whereKey("arrayKey", containsAllObjectsIn:[2, 3, 4])

Queries on String Values

Use whereKey:hasPrefix: to restrict to string values that start with a particular string. Similar to a MySQL LIKE operator, this is indexed so it is efficient for large datasets:

// Finds barbecue sauces that start with "Big Daddy".
// Using PFQuery
PFQuery *query = [PFQuery queryWithClassName:@"BarbecueSauce"];
[query whereKey:@"name" hasPrefix:@"Big Daddy's"];

// Using NSPredicate
NSPredicate *pred = [NSPredicate predicateWithFormat:@"name BEGINSWITH 'Big Daddy"];
PFQuery *query = [PFQuery queryWithClassName:@"BarbecueSauce" predicate:pred];

// Finds barbecue sauces that start with "Big Daddy".
// Using PFQuery
let query = PFQuery(className: "BarbecueSauce")
query.whereKey("name", hasPrefix: "Big Daddy's")

// Using NSPredicate
let pred = NSPredicate(format: "name BEGINSWITH 'Big Daddy")
let query = PFQuery(className: "BarbecueSauce", predicate: predicate)

The above example will match any BarbecueSauce objects where the value in the “name” String key starts with “Big Daddy’s”. For example, both “Big Daddy’s” and “Big Daddy’s BBQ” will match, but “big daddy’s” or “BBQ Sauce: Big Daddy’s” will not.

Queries that have regular expression constraints are very expensive. Refer to the Performance Guide for more details.

Full Text Search

You can use whereKey:matchesText for efficient search capabilities. Text indexes are automatically created for you. Your strings are turned into tokens for fast searching.

• Note: Full Text Search can be resource intensive. Ensure the cost of using indexes is worth the benefit, see storage requirements & performance costs of text indexes..

• Requires Parse Server 2.5.0+

PFQuery *query = [PFQuery queryWithClassName:@"BarbecueSauce"];
[query whereKey:@"name" matchesText:@"bbq"];

let query = PFQuery(className: "BarbecueSauce")
query.whereKey("name", matchesText: "bbq")

The above example will match any BarbecueSauce objects where the value in the “name” String key contains “bbq”. For example, both “Big Daddy’s BBQ”, “Big Daddy’s bbq” and “Big BBQ Daddy” will match.

// You can sort by weight / rank. orderByAscending and selectKeys
PFQuery *query = [PFQuery queryWithClassName:@"BarbecueSauce"];
[query whereKey:@"name" matchesText:@"bbq"];
[query orderByAscending:@"$score"];
[query selectKeys:@[@"$score"]];
[query findObjectsInBackgroundWithBlock:^(NSArray *objects, NSError *error) {
  if (!error) {
    // The find succeeded.
    for (PFObject *object in objects) {
      NSLog(@"Successfully retrieved %d weight / rank.", object[@"$score"]);
    }
  } else {
    // Log details of the failure
    NSLog(@"Error: %@ %@", error, [error userInfo]);
  }
}];

let query = PFQuery(className: "BarbecueSauce")
query.whereKey("name", matchesText: "bbq")
query.order(byAscending: "$score")
query.selectKeys(["$score"])
query.findObjectsInBackground { (objects: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else if let objects = objects {
        objects.forEach { (object) in
            print("Successfully retrieved \(String(describing: object["$score"])) weight / rank.");
        }
    }
}

For Case or Diacritic Sensitive search, please use the REST API.

Relational Queries

There are several ways to issue queries for relational data. If you want to retrieve objects where a field matches a particular PFObject, you can use whereKey:equalTo: just like for other data types. For example, if each Comment has a Post object in its post field, you can fetch comments for a particular Post:

// Assume PFObject *myPost was previously created.
// Using PFQuery
PFQuery *query = [PFQuery queryWithClassName:@"Comment"];
[query whereKey:@"post" equalTo:myPost];

[query findObjectsInBackgroundWithBlock:^(NSArray *comments, NSError *error) {
    // comments now contains the comments for myPost
}];

// Using NSPredicate
NSPredicate *predicate = [NSPredicate predicateWithFormat:@"post = %@", myPost];
PFQuery *query = [PFQuery queryWithClassName:@"Comment" predicate:predicate];

[query findObjectsInBackgroundWithBlock:^(NSArray *comments, NSError *error) {
    // comments now contains the comments for myPost
}];

// Assume PFObject *myPost was previously created.
// Using PFQuery
let query = PFQuery(className: "Comment")
query.whereKey("post", equalTo: myPost)
query.findObjectsInBackground { (comments: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else {
        // comments now contains the comments for myPost
    }
}

// Using NSPredicate
let predicate = NSPredicate(format: "post = %@", myPost)
let query = PFQuery(className: "Comment", predicate: predicate)

query.findObjectsInBackground { (comments: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else {
        // comments now contains the comments for myPost
    }
}

You can also do relational queries by objectId:

// Using PFQuery
[query whereKey:@"post" equalTo:[PFObject objectWithoutDataWithClassName:@"Post" objectId:@"1zEcyElZ80"]];

// Using NSPredicate
[NSPredicate predicateWithFormat:@"post = %@",
    [PFObject objectWithoutDataWithClassName:@"Post" objectId:@"1zEcyElZ80"]];

// Using PFQuery
query.whereKey("post", equalTo: PFObject(withoutDataWithClassName: "Post", objectId: "1zEcyElZ80"))

// Using NSPredicate
NSPredicate(format: "post = %@", PFObject(withoutDataWithClassName: "Post", objectId: "1zEcyElZ80"))

If you want to retrieve objects where a field contains a PFObject that match a different query, you can use whereKey:matchesQuery. In order to find comments for posts with images, you can do:

// Using PFQuery
PFQuery *innerQuery = [PFQuery queryWithClassName:@"Post"];
[innerQuery whereKeyExists:@"image"];
PFQuery *query = [PFQuery queryWithClassName:@"Comment"];
[query whereKey:@"post" matchesQuery:innerQuery];
[query findObjectsInBackgroundWithBlock:^(NSArray *comments, NSError *error) {
    // comments now contains the comments for posts with images
}];

// Using NSPredicate
NSPredicate *innerPred = [NSPredicate predicateWithFormat:@"image IN SELF"];
PFQuery *innerQuery = [PFQuery queryWithClassName:@"Post" predicate:innerPred];

NSPredicate *pred = [NSPredicate predicateWithFormat:@"post IN %@", innerQuery];
PFQuery *query = [PFQuery queryWithClassName:@"Comment" predicate:pred];

[query findObjectsInBackgroundWithBlock:^(NSArray *comments, NSError *error) {
    // comments now contains the comments for posts with images
}];

// Using PFQuery
let innerQuery = PFQuery(className: "Post")
innerQuery.whereKeyExists("image")
let query = PFQuery(className: "Comment")
query.whereKey("post", matchesQuery: innerQuery)
query.findObjectsInBackground { (comments: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else {
        // comments now contains the comments for posts with images

    }
}

// Using NSPredicate
let innerPred = NSPredicate(format: "image IN SELF")
let innerQuery = PFQuery(className: "Post", predicate: innerPred)

let pred = NSPredicate(format: "post IN %@", innerQuery)
let query = PFQuery(className: "Comment", predicate: pred)

query.findObjectsInBackground { (comments: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else {
        // comments now contains the comments for posts with images

    }
}

If you want to retrieve objects where a field contains a PFObject that does not match a different query, you can use whereKey:doesNotMatchQuery. In order to find comments for posts without images, you can do:

// Using PFQuery
PFQuery *innerQuery = [PFQuery queryWithClassName:@"Post"];
[innerQuery whereKeyExists:@"image"];
PFQuery *query = [PFQuery queryWithClassName:@"Comment"];
[query whereKey:@"post" doesNotMatchQuery:innerQuery];
[query findObjectsInBackgroundWithBlock:^(NSArray *comments, NSError *error) {
    // comments now contains the comments for posts without images
}];

// Using NSPredicate
NSPredicate *innerPred = [NSPredicate predicateWithFormat:@"image IN SELF"];
PFQuery *innerQuery = [PFQuery queryWithClassName:@"Post" predicate:innerPred];

NSPredicate *pred = [NSPredicate predicateWithFormat:@"NOT (post IN %@)", innerQuery];
PFQuery *query = [PFQuery queryWithClassName:@"Comment" predicate:pred];

[query findObjectsInBackgroundWithBlock:^(NSArray *comments, NSError *error) {
    // comments now contains the comments for posts without images
}];

// Using PFQuery
let innerQuery = PFQuery(className: "Post")
innerQuery.whereKeyExists("image")
let query = PFQuery(className: "Comment")
query.whereKey("post", doesNotMatch: innerQuery)
query.findObjectsInBackground { (comments: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else {
        // comments now contains the comments for posts without images

    }
}

// Using NSPredicate
let innerPred = NSPredicate(format: "image IN SELF")
let innerQuery = PFQuery(className: "Post", predicate: innerPred)

let pred = NSPredicate(format: "NOT (post IN %@)", innerQuery)
let query = PFQuery(className: "Comment", predicate: pred)

query.findObjectsInBackground { (comments: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else {
        // comments now contains the comments for posts without images

    }
}

In some situations, you want to return multiple types of related objects in one query. You can do this with the includeKey: method. For example, let’s say you are retrieving the last ten comments, and you want to retrieve their related posts at the same time:

PFQuery *query = [PFQuery queryWithClassName:@"Comment"];

// Retrieve the most recent ones
[query orderByDescending:@"createdAt"];

// Only retrieve the last ten
query.limit = 10;

// Include the post data with each comment
[query includeKey:@"post"];

[query findObjectsInBackgroundWithBlock:^(NSArray *comments, NSError *error) {
    // Comments now contains the last ten comments, and the "post" field
    // has been populated. For example:
    for (PFObject *comment in comments) {
         // This does not require a network access.
         PFObject *post = comment[@"post"];
         NSLog(@"retrieved related post: %@", post);
    }
}];

let query = PFQuery(className:"Comment")

// Retrieve the most recent ones
query.order(byDescending: "createdAt")

// Only retrieve the last ten
query.limit = 10

// Include the post data with each comment
query.includeKey("post")

query.findObjectsInBackground { (comments: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else if let comments = comments {
        // Comments now contains the last ten comments, and the "post" field
        // has been populated. For example:
        for comment in comments {
            // This does not require a network access.
            let post = comment["post"] as? PFObject
            print("retrieved related post: \(String(describing: post))")
        }

    }
}

You can also do multi level includes using dot notation. If you wanted to include the post for a comment and the post’s author as well you can do:

[query includeKey:@"post.author"];

query.includeKey("post.author")

You can issue a query with multiple fields included by calling includeKey: multiple times. This functionality also works with PFQuery helpers like getFirstObject and getObjectInBackground

Using the Local Datastore

If you have enabled the local datastore by calling [Parse enableLocalDatastore] before your call to [Parse setApplicationId:clientKey:], then you can also query against the objects stored locally on the device. To do this, call the fromLocalDatastore method on the query.

[query fromLocalDatastore];
[[query findObjectsInBackground] continueWithBlock:^id(BFTask *task) {
  if (!task.error) {
    // There was an error.
    return task;
  }

  // Results were successfully found from the local datastore.
  return task;
}];

let query = PFQuery(className:"Comment")
query.fromLocalDatastore()
query.findObjectsInBackground().continueWith { (task: BFTask<NSArray>) -> Any? in
    if task.error != nil {
        // There was an error.
        return task
    }

    // Results were successfully found from the local datastore.

    return task
}

You can query from the local datastore using exactly the same kinds of queries you use over the network. The results will include every object that matches the query that’s been pinned to your device. The query even takes into account any changes you’ve made to the object that haven’t yet been saved to the cloud. For example, if you call deleteEventually, on an object, it will no longer be returned from these queries.

Caching Queries

It’s often useful to cache the result of a query on disk. This lets you show data when the user’s device is offline, or when the app has just started and network requests have not yet had time to complete. Parse takes care of automatically flushing the cache when it takes up too much space.

The default query behavior doesn’t use the cache, but you can enable caching by setting query.cachePolicy. For example, to try the network and then fall back to cached data if the network is not available:

PFQuery *query = [PFQuery queryWithClassName:@"GameScore"];
query.cachePolicy = kPFCachePolicyNetworkElseCache;
[query findObjectsInBackgroundWithBlock:^(NSArray *objects, NSError *error) {
  if (!error) {
    // Results were successfully found, looking first on the
    // network and then on disk.
  } else {
    // The network was inaccessible and we have no cached data for
    // this query.
  }
}];

let query = PFQuery(className:"GameScore")
query.cachePolicy = .cacheElseNetwork
query.findObjectsInBackground { (objects: [PFObject]?, error: Error?) in
    if let error = error {
        // The network was inaccessible and we have no cached data for
        // this query.
        print(error.localizedDescription)
    } else {
        // Results were successfully found, looking first on the
        // network and then on disk.
    }
}

Parse provides several different cache policies:

• IgnoreCache: The query does not load from the cache or save results to the cache. IgnoreCache is the default cache policy.
• CacheOnly: The query only loads from the cache, ignoring the network. If there are no cached results, that causes a PFError.
• NetworkOnly: The query does not load from the cache, but it will save results to the cache.
• CacheElseNetwork: The query first tries to load from the cache, but if that fails, it loads results from the network. If neither cache nor network succeed, there is a PFError.
• NetworkElseCache: The query first tries to load from the network, but if that fails, it loads results from the cache. If neither network nor cache succeed, there is a PFError.
• CacheThenNetwork: The query first loads from the cache, then loads from the network. In this case, the callback will actually be called twice - first with the cached results, then with the network results. Since it returns two results at different times, this cache policy cannot be used synchronously with findObjects.

If you need to control the cache’s behavior, you can use methods provided in PFQuery to interact with the cache. You can do the following operations on the cache:

• Check to see if there is a cached result for the query with:

BOOL isInCache = [query hasCachedResult];

let isInCache = query.hasCachedResult

[query clearCachedResult];

query.clearCachedResult()

[PFQuery clearAllCachedResults];

PFQuery.clearAllCachedResults()

PFQuery *query = [PFQuery queryWithClassName:@"GameScore"];
[query whereKey:@"playername" equalTo:@"Sean Plott"];
[query countObjectsInBackgroundWithBlock:^(int count, NSError *error) {
  if (!error) {
    // The count request succeeded. Log the count
    NSLog(@"Sean has played %d games", count);
  } else {
    // The request failed
  }
}];

let query = PFQuery(className:"GameScore")
query.whereKey("playerName", equalTo:"Sean Plott")
query.countObjectsInBackground { (count: Int32, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else {
        print("Sean has played \(count) games")
    }
}

PFQuery *lotsOfWins = [PFQuery queryWithClassName:@"Player"];
[lotsOfWins whereKey:@"wins" greaterThan:@150];

PFQuery *fewWins = [PFQuery queryWithClassName:@"Player"];
[fewWins whereKey:@"wins" lessThan:@5];
PFQuery *query = [PFQuery orQueryWithSubqueries:@[fewWins,lotsOfWins]];
[query findObjectsInBackgroundWithBlock:^(NSArray *results, NSError *error) {
  // results contains players with lots of wins or only a few wins.
}];

let lotsOfWins = PFQuery(className:"Player")
lotsOfWins.whereKey("wins", greaterThan:150)

let fewWins = PFQuery(className:"Player")
fewWins.whereKey("wins", lessThan:5)

let query = PFQuery.orQuery(withSubqueries: [lotsOfWins, fewWins])
query.findObjectsInBackground { (results: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else {
        // results contains players with lots of wins or only a few wins.
    }
}

PFQuery *query = [Armor query];
[query whereKey:@"rupees" lessThanOrEqualTo:[PFUser currentUser][@"rupees"]];
[query findObjectsInBackgroundWithBlock:^(NSArray *objects, NSError *error) {
  if (!error) {
    Armor *firstArmor = [objects firstObject];
    // ...
  }
}];

let query = Armor.query()
query.whereKey("rupees", lessThanOrEqualTo: PFUser.current()?["rupees"] as Any)
query.findObjectsInBackground { (objects: [PFObject]?, error: Error?) in
    if let error = error {
        // The request failed
        print(error.localizedDescription)
    } else if let objects = objects as? [Armor], let firstArmor = objects.first {
       //...
    }
}

Users

At the core of many apps, there is a notion of user accounts that lets users access their information in a secure manner. We provide a specialized user class called PFUser that automatically handles much of the functionality required for user account management.

With this class, you’ll be able to add user account functionality in your app.

PFUser is a subclass of PFObject and has all the same features, such as flexible schema, automatic persistence, and a key value interface. All the methods that are on PFObject also exist in PFUser. The difference is that PFUser has some special additions specific to user accounts.

PFUser Properties

PFUser has several properties that set it apart from PFObject:

• username: The username for the user (required).
• password: The password for the user (required on signup).
• email: The email address for the user (optional).

We’ll go through each of these in detail as we run through the various use cases for users. Keep in mind that if you set username and email through these properties, you do not need to set it using the setObject:forKey: method — this is set for you automatically.

Signing Up

The first thing your app will do is probably ask the user to sign up. The following code illustrates a typical sign up:

- (void)myMethod {
    PFUser *user = [PFUser user];
    user.username = @"my name";
    user.password = @"my pass";
    user.email = @"[email protected]";

    // other fields can be set just like with PFObject
    user[@"phone"] = @"415-392-0202";

    [user signUpInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
      if (!error) {   // Hooray! Let them use the app now.
      } else {   NSString *errorString = [error userInfo][@"error"];   // Show the errorString somewhere and let the user try again.
      }
    }];
}

func myMethod() {
  var user = PFUser()
  user.username = "myUsername"
  user.password = "myPassword"
  user.email = "[email protected]"
  // other fields can be set just like with PFObject
  user["phone"] = "415-392-0202"

  user.signUpInBackground {
    (succeeded: Bool, error: Error?) -> Void in
    if let error = error {
      let errorString = error.localizedDescription
      // Show the errorString somewhere and let the user try again.
    } else {
      // Hooray! Let them use the app now.
    }
  }
}

This call will asynchronously create a new user in your Parse App. Before it does this, it also checks to make sure that both the username and email are unique. Also, it securely hashes the password in the cloud using bcrypt. We never store passwords in plaintext, nor will we ever transmit passwords back to the client in plaintext.

Note that we used the signUp method, not the save method. New PFUsers should always be created using the signUp method. Subsequent updates to a user can be done by calling save.

The signUp method comes in various flavors, with the ability to pass back errors, and also synchronous versions. As usual, we highly recommend using the asynchronous versions when possible, so as not to block the UI in your app. You can read more about these specific methods in our API docs.

If a signup isn’t successful, you should read the error object that is returned. The most likely case is that the username or email has already been taken by another user. You should clearly communicate this to your users, and ask them try a different username.

You are free to use an email address as the username. Simply ask your users to enter their email, but fill it in the username property — PFUser will work as normal. We’ll go over how this is handled in the reset password section.

Logging In

Of course, after you allow users to sign up, you need to let them log in to their account in the future. To do this, you can use the class method logInWithUsernameInBackground:password:.

[PFUser logInWithUsernameInBackground:@"myname" password:@"mypass"
  block:^(PFUser *user, NSError *error) {
    if (user) {
      // Do stuff after successful login.
    } else {
      // The login failed. Check error to see why.
    }
}];

PFUser.logInWithUsername(inBackground:"myname", password:"mypass") {
  (user: PFUser?, error: Error?) -> Void in
  if user != nil {
    // Do stuff after successful login.
  } else {
    // The login failed. Check error to see why.
  }
}

Verifying Emails

Enabling email verification in an application’s settings allows the application to reserve part of its experience for users with confirmed email addresses. Email verification adds the emailVerified key to the PFUser object. When a PFUser’s email is set or modified, emailVerified is set to false. Parse then emails the user a link which will set emailVerified to true.

There are three emailVerified states to consider:

1. true - the user confirmed his or her email address by clicking on the link Parse emailed them. PFUsers can never have a true value when the user account is first created.
2. false - at the time the PFUser object was last refreshed, the user had not confirmed his or her email address. If emailVerified is false, consider calling refresh: on the PFUser.
3. missing - the PFUser was created when email verification was off or the PFUser does not have an email.

Current User

It would be bothersome if the user had to log in every time they open your app. You can avoid this by using the cached currentUser object.

Whenever you use any signup or login methods, the user is cached on disk. You can treat this cache as a session, and automatically assume the user is logged in:

PFUser *currentUser = [PFUser currentUser];
if (currentUser) {
    // do stuff with the user
} else {
    // show the signup or login screen
}

var currentUser = PFUser.current()
if currentUser != nil {
  // Do stuff with the user
} else {
  // Show the signup or login screen
}

You can clear the current user by logging them out:

[PFUser logOut];
PFUser *currentUser = [PFUser currentUser]; // this will now be nil

PFUser.logOut()
var currentUser = PFUser.current() // this will now be nil

Anonymous Users

Being able to associate data and objects with individual users is highly valuable, but sometimes you want to be able to do this without forcing a user to specify a username and password.

An anonymous user is a user that can be created without a username and password but still has all of the same capabilities as any other PFUser. After logging out, an anonymous user is abandoned, and its data is no longer accessible.

You can create an anonymous user using PFAnonymousUtils:

[PFAnonymousUtils logInWithBlock:^(PFUser *user, NSError *error) {
    if (error) {
      NSLog(@"Anonymous login failed.");
    } else {
      NSLog(@"Anonymous user logged in.");
    }
}];

PFAnonymousUtils.logInWithBlock {
  (user: PFUser?, error: NSError?) -> Void in
  if error != nil || user == nil {
    print("Anonymous login failed.")
  } else {
    print("Anonymous user logged in.")
  }
}

You can convert an anonymous user into a regular user by setting the username and password, then calling signUp, or by logging in or linking with a service like Facebook or Twitter. The converted user will retain all of its data. To determine whether the current user is an anonymous user, you can check PFAnonymousUtils isLinkedWithUser: