Getting Started

The easiest way to integrate the Parse SDK into your JavaScript project is through the npm module. However, if you want to use a pre-compiled file, you can fetch it from npmcdn. The development version is available at https://npmcdn.com/parse/dist/parse.js, and the minified production version is at https://npmcdn.com/parse/dist/parse.min.js.

The JavaScript ecosystem is wide and incorporates a large number of platforms and execution environments. To handle this, the Parse npm module contains special versions of the SDK tailored to use in Node.js and React Native environments. Not all features make sense in all environments, so using the appropriate package will ensure that items like local storage, user sessions, and HTTP requests use appropriate dependencies.

To use the npm modules for a browser based application, include it as you normally would:

const Parse = require('parse');

For server-side applications or Node.js command line tools, include 'parse/node':

// In a node.js environment
const Parse = require('parse/node');
// ES6 Minimized
import Parse from 'parse/dist/parse.min.js';

For React Native applications, include 'parse/react-native.js':

// In a React Native application
const Parse = require('parse/react-native.js');

Additionally on React-Native / Expo environments, make sure to add the piece of code below :

//Get your favorite AsyncStorage handler with import (ES6) or require
import { AsyncStorage } from 'react-native'; 

//Before using the SDK...
Parse.setAsyncStorage(AsyncStorage);

To initialize your own Parse-Server with Javascript, you should replace your current initialization code with this

Parse.initialize("YOUR_APP_ID", "YOUR_JAVASCRIPT_KEY");
//javascriptKey is required only if you have it on server.

Parse.serverURL = 'http://YOUR_PARSE_SERVER:1337/parse'

⚠️ If the Masterkey needs to be provided, use the following. Please note that the master key should only be used in safe environments and never on client side ‼️

Parse.initialize("YOUR_APP_ID", "YOUR_JAVASCRIPT_KEY", "YOUR_MASTERKEY");
//javascriptKey is required only if you have it on server.

Parse.serverURL = 'http://YOUR_PARSE_SERVER:1337/parse'

Our JavaScript SDK is originally based on the popular Backbone.js framework, but it provides flexible APIs that allow it to be paired with your favorite JS libraries. Our goal is to minimize configuration and let you quickly start building your JavaScript and HTML5 app on Parse.

Our SDK supports Firefox 23+, Chrome 17+, Safari 5+, and IE 10. IE 9 is supported only for apps that are hosted with HTTPS.

Objects

Parse.Object

Storing data on Parse is built around Parse.Object. Each Parse.Object 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 Parse.Object. 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 Parse.Object 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 Parse.Object is an instance of a specific subclass with 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.

To create a new subclass, use the Parse.Object.extend method. Any Parse.Query will return instances of the new class for any Parse.Object with the same classname. If you’re familiar with Backbone.Model, then you already know how to use Parse.Object. It’s designed to be created and modified in the same ways.

// Simple syntax to create a new subclass of Parse.Object.
const GameScore = Parse.Object.extend("GameScore");

// Create a new instance of that class.
const gameScore = new GameScore();

// Alternatively, you can use the typical Backbone syntax.
const Achievement = Parse.Object.extend({
  className: "Achievement"
});

You can add additional methods and properties to your subclasses of Parse.Object.

// A complex subclass of Parse.Object
const Monster = Parse.Object.extend("Monster", {
  // Instance methods
  hasSuperHumanStrength: function () {
    return this.get("strength") > 18;
  },
  // Instance properties go in an initialize method
  initialize: function (attrs, options) {
    this.sound = "Rawr"
  }
}, {
  // Class methods
  spawn: function(strength) {
    const monster = new Monster();
    monster.set("strength", strength);
    return monster;
  }
});

const monster = Monster.spawn(200);
alert(monster.get('strength'));  // Displays 200.
alert(monster.sound); // Displays Rawr.

To create a single instance of any Parse Object class, you can also use the Parse.Object constructor directly. new Parse.Object(className) will create a single Parse Object with that class name.

If you’re already using ES6 in your codebase, good news! From version 1.6.0 onwards, the JavaScript SDK is compatible with ES6 classes. You can subclass Parse.Object with the extends keyword:

class Monster extends Parse.Object {
  constructor() {
    // Pass the ClassName to the Parse.Object constructor
    super('Monster');
    // All other initialization
    this.sound = 'Rawr';
  }

  hasSuperHumanStrength() {
    return this.get('strength') > 18;
  }

  static spawn(strength) {
    const monster = new Monster();
    monster.set('strength', strength);
    return monster;
  }
}

However, when using extends, the SDK is not automatically aware of your subclass. If you want objects returned from queries to use your subclass of Parse.Object, you will need to register the subclass, similar to what we do on other platforms.

// After specifying the Monster subclass...
Parse.Object.registerSubclass('Monster', Monster);

Similarly, you can use extends with Parse.User.

class CustomUser extends Parse.User {
  constructor(attributes) {
    super(attributes);
  }

  doSomething() {
    return 5;
  }
}
Parse.Object.registerSubclass('_User', CustomUser);

In addition to queries, logIn and signUp will return the subclass CustomUser.

const customUser = new CustomUser({ foo: 'bar' });
customUser.setUsername('username');
customUser.setPassword('password');
customUser.signUp().then((user) => {
  // user is an instance of CustomUser
  user.doSomething(); // return 5
  user.get('foo');    // return 'bar'
});

CustomUser.logIn and CustomUser.signUp will return the subclass CustomUser (SDK v2.3.0).

Saving Objects

Let’s say you want to save the GameScore described above to the Parse Cloud. The interface is similar to a Backbone.Model, including the save method:

const GameScore = Parse.Object.extend("GameScore");
const gameScore = new GameScore();

gameScore.set("score", 1337);
gameScore.set("playerName", "Sean Plott");
gameScore.set("cheatMode", false);

gameScore.save()
.then((gameScore) => {
  // Execute any logic that should take place after the object is saved.
  alert('New object created with objectId: ' + gameScore.id);
}, (error) => {
  // Execute any logic that should take place if the save fails.
  // error is a Parse.Error with an error code and message.
  alert('Failed to create new object, with error code: ' + error.message);
});

After this code runs, you will probably be wondering if anything really happened. To make sure the data was saved, you can look at the Data Browser in your app on Parse. 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 as a convenience. objectId is a unique identifier for each saved object. createdAt and updatedAt represent the time that each object was created and last modified in the cloud. Each of these fields is filled in by Parse, so they don’t exist on a Parse.Object until a save operation has completed.

If you prefer, you can set attributes directly in your call to save instead.

const GameScore = Parse.Object.extend("GameScore");
const gameScore = new GameScore();

gameScore.save({
  score: 1337,
  playerName: "Sean Plott",
  cheatMode: false
})
.then((gameScore) => {
  // The object was saved successfully.
}, (error) => {
  // The save failed.
  // error is a Parse.Error with an error code and message.
});

Saving Nested Objects

You may add a Parse.Object as the value of a property in another Parse.Object. By default, when you call save() on the parent object, all nested objects will be created and/or saved as well in a batch operation. This feature makes it really easy to manage relational data as you don’t have to take care of creating the objects in any specific order.

const Child = Parse.Object.extend("Child");
const child = new Child();

const Parent = Parse.Object.extend("Parent");
const parent = new Parent();

parent.save({ child: child });
// Automatically the object Child is created on the server
// just before saving the Parent

In some scenarios, you may want to prevent this default chain save. For example, when saving a team member’s profile that points to an account owned by another user to which you don’t have write access. In this case, setting the option cascadeSave to false may be useful:

const TeamMember = Parse.Object.extend("TeamMember");
const teamMember = new TeamMember();
teamMember.set('ownerAccount', ownerAccount);   // Suppose `ownerAccount` has been created earlier.

teamMember.save(null, { cascadeSave: false });
// Will save `teamMember` wihout attempting to save or modify `ownerAccount`

Saving Objects Offline

Most save functions execute immediately, and inform your app when the save is complete. If you don’t need to know when the save has finished, you can use saveEventually instead. The advantage is that if the user currently doesn’t have a network connection, saveEventually will store the update on the device until a network connection is re-established. If your app is closed before the connection is back, Parse will try again the next time the app is opened. All calls to saveEventually (and destroyEventually) are executed in the order they are called, so it is safe to call saveEventually on an object multiple times. If you have the local datastore enabled, then any object you saveEventually will be pinned as long as that save is in progress. That makes it easy to retrieve your local changes while waiting for the network to be available. If an error occurs while saving or deleting an object the data will be lost. Parse.enableLocalDatastore() must be called to use this feature.

const TeamMember = Parse.Object.extend("TeamMember");
const teamMember = new TeamMember();

teamMember.set('ownerAccount', ownerAccount); 

await teamMember.saveEventually();

Saving Objects Offline Advanced API

The SDK provides utility functions to queue objects that will be saved to the server at a later date with Parse.EventuallyQueue. See EventuallyQueue API for full documentation.

Add Object to Queue

Adding unique hashes to your objects is highly recommended

const object = new Parse.Object('TestObject');
object.save({ hash: 'unique' });

await Parse.EventuallyQueue.save(object, options);
await Parse.EventuallyQueue.destroy(object, options);

Send Queue to Parse Server

await Parse.EventuallyQueue.sendQueue();

You can send the queue either right after adding an object or on connect (or other events).

Clear Queue

await Parse.EventuallyQueue.clear();

Polling

This will call sendQueue when a connection to the server is established. Uses the serverURL used to initialize sdk

Parse.EventuallyQueue.poll();

Cloud Code context

Requires Parse Server 4.3.0+

You may pass a context dictionary that is accessible in Cloud Code beforeSave and afterSave triggers for that Parse.Object. This is useful if you want to condition certain operations in Cloud Code triggers on ephemeral information that should not be saved with the Parse.Object in the database. The context is ephemeral in the sense that it vanishes after the Cloud Code triggers for that particular Parse.Object have executed. For example:

const TeamMember = Parse.Object.extend("TeamMember");
const teamMember = new TeamMember();
teamMember.set("team", "A");

const context = { notifyTeam: false };
await teamMember.save(null, { context: context });

The context is then accessible in Cloud Code:

Parse.Cloud.afterSave("TeamMember", async (req) => {
  const notifyTeam = req.context.notifyTeam;
  if (notifyTeam) {
    // Notify team about new member.
  }
});

Retrieving Objects

Saving data to the cloud is fun, but it’s even more fun to get that data out again. If the Parse.Object has been uploaded to the server, you can use the objectId to get it using a Parse.Query:

const GameScore = Parse.Object.extend("GameScore");
const query = new Parse.Query(GameScore);
query.get("xWMyZ4YEGZ")
.then((gameScore) => {
  // The object was retrieved successfully.
}, (error) => {
  // The object was not retrieved successfully.
  // error is a Parse.Error with an error code and message.
});

To get the values out of the Parse.Object, use the get method.

const score = gameScore.get("score");
const playerName = gameScore.get("playerName");
const cheatMode = gameScore.get("cheatMode");

Alternatively, the attributes property of the Parse.Object can be treated as a Javascript object, and even destructured.

const { score, playerName, cheatMode } = result.attributes;

The four special reserved values are provided as properties and cannot be retrieved using the ‘get’ method nor modified with the ‘set’ method:

const objectId = gameScore.id;
const updatedAt = gameScore.updatedAt;
const createdAt = gameScore.createdAt;
const acl = gameScore.getACL();

If you need to refresh an object you already have with the latest data that is in the Parse Cloud, you can call the fetch method like so:

myObject.fetch().then((myObject) => {
  // The object was refreshed successfully.
}, (error) => {
  // The object was not refreshed successfully.
  // error is a Parse.Error with an error code and message.
});

If you need to check if an object has been fetched, you can call the isDataAvailable() method:

if (!myObject.isDataAvailable()) {
  await myObject.fetch();
}

Updating Objects

Updating an object is simple. Just set some new data on it and call the save method. For example:

// Create the object.
const GameScore = Parse.Object.extend("GameScore");
const gameScore = new GameScore();

gameScore.set("score", 1337);
gameScore.set("playerName", "Sean Plott");
gameScore.set("cheatMode", false);
gameScore.set("skills", ["pwnage", "flying"]);

gameScore.save().then((gameScore) => {
  // 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.set("cheatMode", true);
  gameScore.set("score", 1338);
  return gameScore.save();
});

Parse automatically figures out which data has changed so only “dirty” fields will be sent to the Parse Cloud. 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.increment("score");
gameScore.save();

You can also increment by any amount by passing in a second argument to increment. When no amount is specified, 1 is used by default.

Arrays

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

• add append the given object to the end of an array field.
• addUnique add the given object only if it isn’t already contained in an array field. The position of the insert is not guaranteed.
• remove remove all instances of the given object from an array field.

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

gameScore.addUnique("skills", "flying");
gameScore.addUnique("skills", "kungfu");
gameScore.save();

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

Destroying Objects

To delete an object from the cloud:

myObject.destroy().then((myObject) => {
  // The object was deleted from the Parse Cloud.
}, (error) => {
  // The delete failed.
  // error is a Parse.Error with an error code and message.
});

You can delete a single field from an object with the unset method:

// After this, the playerName field will be empty
myObject.unset("playerName");

// Saves the field deletion to the Parse Cloud.
// If the object's field is an array, call save() after every unset() operation.
myObject.save();

Please note that use of object.set(null) to remove a field from an object is not recommended and will result in unexpected functionality.

Relational Data

Objects may have relationships with other objects. For example, in a blogging application, a Post object may have many Comment objects. Parse supports all kind of relationships, including one-to-one, one-to-many, and many-to-many.

One-to-One and One-to-Many Relationships

One-to-one and one-to-many relationships are modeled by saving a Parse.Object as a value in the other object. 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:

// Declare the types.
const Post = Parse.Object.extend("Post");
const Comment = Parse.Object.extend("Comment");

// Create the post
const myPost = new Post();
myPost.set("title", "I'm Hungry");
myPost.set("content", "Where should we go for lunch?");

// Create the comment
const myComment = new Comment();
myComment.set("content", "Let's do Sushirrito.");

// Add the post as a value in the comment
myComment.set("parent", myPost);

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

Internally, the Parse framework will store the referred-to object in just one place, to maintain consistency. You can also link objects using just their objectIds like so:

const post = new Post();
post.id = "1zEcyElZ80";

myComment.set("parent", post);

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

const post = fetchedComment.get("parent");
await post.fetch();
const title = post.get("title");

Many-to-Many Relationships

Many-to-many relationships are modeled using Parse.Relation. This works similar to storing an array of Parse.Objects in a key, except that you don’t need to fetch all of the objects in a relation at once. In addition, this allows Parse.Relation to scale to many more objects than the array of Parse.Object approach. For example, a User may have many Posts that she might like. In this case, you can store the set of Posts that a User likes using relation. In order to add a Post to the “likes” list of the User, you can do:

const user = Parse.User.current();
const relation = user.relation("likes");
relation.add(post);
user.save();

You can remove a post from a Parse.Relation:

relation.remove(post);
user.save();

You can call add and remove multiple times before calling save:

relation.remove(post1);
relation.remove(post2);
user.save();

You can also pass in an array of Parse.Object to add and remove:

relation.add([post1, post2, post3]);
user.save();

By default, the list of objects in this relation are not downloaded. You can get a list of the posts that a user likes by using the Parse.Query returned by query. The code looks like:

relation.query().find({
  success: function(list) {
    // list contains the posts that the current user likes.
  }
});

If you want only a subset of the Posts, you can add extra constraints to the Parse.Query returned by query like this:

const query = relation.query();
query.equalTo("title", "I'm Hungry");
query.find({
  success:function(list) {
    // list contains post liked by the current user which have the title "I'm Hungry".
  }
});

For more details on Parse.Query, please look at the query portion of this guide. A Parse.Relation behaves similar to an array of Parse.Object for querying purposes, so any query you can do on an array of objects, you can do on a Parse.Relation.

Data Types

So far we’ve used values with type String, Number, and Parse.Object. Parse also supports Dates and null. You can nest JSON Objects and JSON Arrays to store more structured data within a single Parse.Object. Overall, the following types are allowed for each field in your object:

• String => String
• Number => Number
• Bool => bool
• Array => JSON Array
• Object => JSON Object
• Date => Date
• File => Parse.File
• Pointer => other Parse.Object
• Relation => Parse.Relation
• Null => null

Some examples:

const number = 42;
const bool = false;
const string = "the number is " + number;
const date = new Date();
const array = [string, number];
const object = { number: number, string: string };
const pointer = MyClassName.createWithoutData(objectId);

const BigObject = Parse.Object.extend("BigObject");
const bigObject = new BigObject();
bigObject.set("myNumber", number);
bigObject.set("myBool", bool);
bigObject.set("myString", string);
bigObject.set("myDate", date);
bigObject.set("myArray", array);
bigObject.set("myObject", object);
bigObject.set("anyKey", null); // this value can only be saved to an existing key
bigObject.set("myPointerKey", pointer); // shows up as Pointer <MyClassName> in the Data Browser
bigObject.save();

We do not recommend storing large pieces of binary data like images or documents on Parse.Object. We recommend you use Parse.Files to store images, documents, and other types of files. You can do so by instantiating a Parse.File 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.

Queries

We’ve already seen how a Parse.Query with get can retrieve a single Parse.Object from Parse. There are many other ways to retrieve data with Parse.Query - you can retrieve many objects at once, put conditions on the objects you wish to retrieve, and more.

Basic Queries

In many cases, get isn’t powerful enough to specify which objects you want to retrieve. Parse.Query offers different ways to retrieve a list of objects rather than just a single object.

The general pattern is to create a Parse.Query, put conditions on it, and then retrieve an Array of matching Parse.Objects using find. For example, to retrieve the scores that have a particular playerName, use the equalTo method to constrain the value for a key.

const GameScore = Parse.Object.extend("GameScore");
const query = new Parse.Query(GameScore);
query.equalTo("playerName", "Dan Stemkoski");
const results = await query.find();
alert("Successfully retrieved " + results.length + " scores.");
// Do something with the returned Parse.Object values
for (let i = 0; i < results.length; i++) {
  const object = results[i];
  alert(object.id + ' - ' + object.get('playerName'));
}

Query Constraints

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

query.notEqualTo("playerName", "Michael Yabuti");

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.

query.notEqualTo("playerName", "Michael Yabuti");
query.greaterThan("playerAge", 18);

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

If you want exactly one result, a more convenient alternative may be to use first instead of using find.

const GameScore = Parse.Object.extend("GameScore");
const query = new Parse.Query(GameScore);
query.equalTo("playerEmail", "[email protected]");
const object = await query.first();

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

If you want to know the total number of rows in a table satisfying your query, for e.g. pagination purposes - you can use withCount.

Note: Enabling this flag will change the structure of response, see the example below.

Let’s say you have 200 rows in a table called GameScore:

const GameScore = Parse.Object.extend("GameScore");
const query = new Parse.Query(GameScore);

query.limit(25);

const results = await query.find(); // [ GameScore, GameScore, ...]

// to include count:
query.withCount();
const response = await query.find(); // { results: [ GameScore, ... ], count: 200 }

⚠️ Сount operations can be slow and expensive.

If you only want to get the count without objects - use Counting Objects.

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.ascending("score");

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

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

// Restricts to wins < 50
query.lessThan("wins", 50);

// Restricts to wins <= 50
query.lessThanOrEqualTo("wins", 50);

// Restricts to wins > 50
query.greaterThan("wins", 50);

// Restricts to wins >= 50
query.greaterThanOrEqualTo("wins", 50);

If you want to retrieve objects matching any of the values in a list of values, you can use 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
query.containedIn("playerName",
                  ["Jonathan Walsh", "Dario Wunsch", "Shawn Simon"]);

If you want to retrieve objects that do not match any of several values you can use 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
query.notContainedIn("playerName",
                     ["Jonathan Walsh", "Dario Wunsch", "Shawn Simon"]);

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

// Finds objects that have the score set
query.exists("score");

// Finds objects that don't have the score set
query.doesNotExist("score");

You can use the matchesKeyInQuery 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:

const Team = Parse.Object.extend("Team");
const teamQuery = new Parse.Query(Team);
teamQuery.greaterThan("winPct", 0.5);
const userQuery = new Parse.Query(Parse.User);
userQuery.matchesKeyInQuery("hometown", "city", teamQuery);
// results has the list of users with a hometown team with a winning record
const results = await userQuery.find();

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 doesNotMatchKeyInQuery. For example, to find users whose hometown teams have losing records:

const losingUserQuery = new Parse.Query(Parse.User);
losingUserQuery.doesNotMatchKeyInQuery("hometown", "city", teamQuery);
// results has the list of users with a hometown team with a losing record
const results = await losingUserQuery.find();

To filter rows based on objectId’s from pointers in a second table, you can use dot notation:

const rolesOfTypeX = new Parse.Query('Role');
rolesOfTypeX.equalTo('type', 'x');

const groupsWithRoleX = new Parse.Query('Group');
groupsWithRoleX.matchesKeyInQuery('objectId', 'belongsTo.objectId', rolesOfTypeX);
groupsWithRoleX.find().then(function(results) {
   // results has the list of groups with role x
});

You can restrict the fields returned by calling select with a list 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):

const GameScore = Parse.Object.extend("GameScore");
const query = new Parse.Query(GameScore);
query.select("score", "playerName");
query.find().then(function(results) {
  // each of results will only have the selected fields available.
});

Similarly, use exclude to remove undesired fields while retrieving the rest:

const GameScore = Parse.Object.extend("GameScore");
const query = new Parse.Query(GameScore);
query.exclude("playerName");
query.find().then(function(results) {
  // Now each result will have all fields except `playerName`
});

The remaining fields can be fetched later by calling fetch on the returned objects:

query.first().then(function(result) {
  // only the selected fields of the object will now be available here.
  return result.fetch();
}).then(function(result) {
  // 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.
query.equalTo("arrayKey", 2);

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

// Find objects where the array in arrayKey contains all of the elements 2, 3, and 4.
query.containsAll("arrayKey", [2, 3, 4]);

Queries on String Values

Use startsWith 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's".
const query = new Parse.Query(BarbecueSauce);
query.startsWith("name", "Big Daddy's");

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, especially for classes with over 100,000 records. Parse restricts how many such operations can be run on a particular app at any given time.

Full Text Search

You can use fullText 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..

• Parse Server 2.5.0+

const query = new Parse.Query(BarbecueSauce);
query.fullText('name', '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. ascending() and select()
const query = new Parse.Query(BarbecueSauce);
query.fullText('name', 'bbq');
query.ascending('$score');
query.select('$score');
query.find()
  .then(function(results) {
    // results contains a weight / rank in result.get('score')
  })
  .catch(function(error) {
    // There was an error.
  });

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 Parse.Object, you can use 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 Parse.Object myPost was previously created.
const query = new Parse.Query(Comment);
query.equalTo("post", myPost);
// comments now contains the comments for myPost
const comments = await query.find();

If you want to retrieve objects where a field contains a Parse.Object that matches a different query, you can use matchesQuery. In order to find comments for posts containing images, you can do:

const Post = Parse.Object.extend("Post");
const Comment = Parse.Object.extend("Comment");
const innerQuery = new Parse.Query(Post);
innerQuery.exists("image");
const query = new Parse.Query(Comment);
query.matchesQuery("post", innerQuery);
// comments now contains the comments for posts with images.
const comments = await query.find();

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

const Post = Parse.Object.extend("Post");
const Comment = Parse.Object.extend("Comment");
const innerQuery = new Parse.Query(Post);
innerQuery.exists("image");
const query = new Parse.Query(Comment);
query.doesNotMatchQuery("post", innerQuery);
// comments now contains the comments for posts without images.
const comments = await query.find();

You can also do relational queries by objectId:

const post = new Post();
post.id = "1zEcyElZ80";
query.equalTo("post", post);

In some situations, you want to return multiple types of related objects in one query. You can do this with the include 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:

const query = new Parse.Query(Comment);

// Retrieve the most recent ones
query.descending("createdAt");

// Only retrieve the last ten
query.limit(10);

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

// Comments now contains the last ten comments, and the "post" field
const comments = await query.find();
// has been populated. For example:
for (let i = 0; i < comments.length; i++) {
  // This does not require a network access.
  const post = comments[i].get("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.include(["post.author"]);

You can issue a query with multiple fields included by calling include multiple times. This functionality also works with Parse.Query helpers like first and get.

Counting Objects

Note: In the old Parse hosted backend, count queries were rate limited to a maximum of 160 requests per minute. They also returned inaccurate results for classes with more than 1,000 objects. But, Parse Server has removed both constraints and can count objects well above 1,000.

If you just need to count how many objects match a query, but you do not need to retrieve all the objects that match, you can use count instead of find. For example, to count how many games have been played by a particular player:

const GameScore = Parse.Object.extend("GameScore");
const query = new Parse.Query(GameScore);
query.equalTo("playerName", "Sean Plott");
const count = await query.count();
alert("Sean has played " + count + " games");

Compound Queries

For more complex queries you might need compound queries. A compound query is a logical combination (e. g. “and” or “or”) of sub queries.

Note that we do not support GeoPoint or non-filtering constraints (e.g. near, withinGeoBox, limit, skip, ascending/descending, include) in the subqueries of the compound query.

OR-ed query constraints

If you want to find objects that match one of several queries, you can use Parse.Query.or method to construct a query that is an OR of the queries passed in. For instance if you want to find players who either have a lot of wins or a few wins, you can do:

const lotsOfWins = new Parse.Query("Player");
lotsOfWins.greaterThan("wins", 150);

const fewWins = new Parse.Query("Player");
fewWins.lessThan("wins", 5);

const mainQuery = Parse.Query.or(lotsOfWins, fewWins);
mainQuery.find()
  .then(function(results) {
    // results contains a list of players that either have won a lot of games or won only a few games.
  })
  .catch(function(error) {
    // There was an error.
  });

AND-ed query constraints

If you want to find objects that match all conditions, you normally would use just one query. You can add additional constraints to the newly created Parse.Query that act as an ‘and’ operator.

const query = new Parse.Query("User");
query.greaterThan("age", 18);
query.greaterThan("friends", 0);
query.find()
  .then(function(results) {
    // results contains a list of users both older than 18 and having friends.
  })
  .catch(function(error) {
    // There was an error.
  });

Sometimes the world is more complex than this simple example and you may need a compound query of sub queries. You can use Parse.Query.and method to construct a query that is an AND of the queries passed in. For instance if you want to find users in the age of 16 or 18 who have either no friends or at least 2 friends, you can do:

const age16Query = new Parse.Query("User");
age16Query.equalTo("age", 16);

const age18Query = new Parse.Query("User");
age18Query.equalTo("age", 18);

const friends0Query = new Parse.Query("User");
friends0Query.equalTo("friends", 0);

const friends2Query = new Parse.Query("User");
friends2Query.greaterThan("friends", 2);

const mainQuery = Parse.Query.and(
  Parse.Query.or(age16Query, age18Query),
  Parse.Query.or(friends0Query, friends2Query)
);
mainQuery.find()
  .then(function(results) {
    // results contains a list of users in the age of 16 or 18 who have either no friends or at least 2 friends
    // results: (age 16 or 18) and (0 or >2 friends)
  })
  .catch(function(error) {
    // There was an error.
  });

Aggregate

Queries can be made using aggregates, allowing you to retrieve objects over a set of input values. The results will not be Parse.Objects since you will be aggregating your own fields

• Parse Server 2.7.1+
• MasterKey is Required.

Aggregates use stages to filter results by piping results from one stage to the next.

You can create a pipeline using an Array or an Object.

The following example is a pipeline similar to distinct grouping by name field.

const pipelineObject = {
  $group: { _id: '$name' }
 };

const pipelineArray = [
  { $group: { _id: '$name' } }
];

For a list of available operators please refer to Mongo Aggregate Documentation.

Group pipeline is similar to distinct.

You can group by a field.

// score is the field. $ before score lets the database know this is a field
const pipeline = [
  { $group: { _id: '$score' } }
];
const query = new Parse.Query("User");
query.aggregate(pipeline)
  .then(function(results) {
    // results contains unique score values
  })
  .catch(function(error) {
    // There was an error.
  });

You can apply collective calculations like $sum, $avg, $max, $min.

// total will be a newly created field to hold the sum of score field
const pipeline = [
  { $group: { _id: null, total: { $sum: '$score' } } }
];
const query = new Parse.Query("User");
query.aggregate(pipeline)
  .then(function(results) {
    // results contains sum of score field and stores it in results[0].total
  })
  .catch(function(error) {
    // There was an error.
  });

Project pipeline is similar to keys or select, add or remove existing fields.

const pipeline = [
  { $project: { name: 1 } }
];
const query = new Parse.Query("User");
query.aggregate(pipeline)
  .then(function(results) {
    // results contains only name field
  })
  .catch(function(error) {
    // There was an error.
  });

Match pipeline is similar to equalTo.

const pipeline = [
  { $match: { name: 'BBQ' } }
];
const query = new Parse.Query("User");
query.aggregate(pipeline)
  .then(function(results) {
    // results contains name that matches 'BBQ'
  })
  .catch(function(error) {
    // There was an error.
  });

You can match by comparison.

const pipeline = [
  { $match: { score: { $gt: 15 } } }
];
const query = new Parse.Query("User");
query.aggregate(pipeline)
  .then(function(results) {
    // results contains score greater than 15
  })
  .catch(function(error) {
    // There was an error.
  });

Distinct

Queries can be made using distinct, allowing you find unique values for a specified field.

• Parse Server 2.7.1+
• MasterKey is required.

const query = new Parse.Query("User");
query.distinct("age")
  .then(function(results) {
    // results contains unique age
  })
  .catch(function(error) {
    // There was an error.
  });

You can also restrict results by using equalTo.

const query = new Parse.Query("User");
query.equalTo("name", "foo");
query.distinct("age")
  .then(function(results) {
    // results contains unique age where name is foo
  })
  .catch(function(error) {
    // There was an error.
  });

Local vs. Server Data

The value of a Parse Object field is determined from two data sources: the last-known value sent by the server, and any local changes made via .set() that have not been saved and sent to the server yet. When calling .get() on a field, the returned value will be the unsaved local value, or if no change has been made, the last-known value sent by the server.

If you called .set() on a field but did not save it, then calling .get() will always return the unsaved value, regardless of how the value changed on the server side.

If this is not a desired behavior, use .revert() to clear and unsaved local changes applied to the object.

// Save object
const GameScore = Parse.Object.extend("GameScore");
const localObject = new Parse.Object(GameScore);
localObject.set('field', 'a');
await localObject.save();

// Modify object locally without saving it
localObject.set('field', 'b');

// Fetch local object from server
const query = new Parse.Query(GameScore);
const fetchedObject = await query.first();

// Determine field value
fetchedObject.get('field'); // Returns value 'b'
fetchedObject.revert();
fetchedObject.get('field'); // Returns value 'a'

Read Preference

When using a MongoDB replica set, you can use the query.readPreference(readPreference, includeReadPreference, subqueryReadPreference) function to choose from which replica the objects will be retrieved. The includeReadPreference argument chooses from which replica the included pointers will be retrieved and the subqueryReadPreference argument chooses in which replica the subqueries will run. The possible values are PRIMARY (default), PRIMARY_PREFERRED, SECONDARY, SECONDARY_PREFERRED, or NEAREST. If the includeReadPreference argument is not passed, the same replica chosen for readPreference will be also used for the includes. The same rule applies for the subqueryReadPreference argument.

query.readPreference(
  'SECONDARY',
  'SECONDARY_PREFERRED',
  'NEAREST'
);

Live Queries

Standard API

As we discussed in our LiveQuery protocol, we maintain a WebSocket connection to communicate with the Parse LiveQuery server. When used server side we use the ws package and in the browser we use window.WebSocket. We think in most cases it isn’t necessary to deal with the WebSocket connection directly. Thus, we developed a simple API to let you focus on your own business logic.

Note: Live Queries is supported only in Parse Server with JS SDK ~1.8.

Create a subscription

let query = new Parse.Query('Game');
let subscription = await query.subscribe();

• Since release 2.3.0 of Parse JS SDK, the query.subscribe() function returns a Promise that resolves to the subscription object. Previous releases return the subscription object directly and require you to write let subscription = query.subscribe(); instead.

The subscription you get is actually an event emitter. For more information on event emitter, check here. You’ll get the LiveQuery events through this subscription. The first time you call subscribe, we’ll try to open the WebSocket connection to the LiveQuery server for you.

Event Handling

We define several types of events you’ll get through a subscription object:

Open event

subscription.on('open', () => {
 console.log('subscription opened');
});

When you call query.subscribe(), we send a subscribe request to the LiveQuery server. When we get the confirmation from the LiveQuery server, this event will be emitted.

When the client loses WebSocket connection to the LiveQuery server, we’ll try to auto reconnect the LiveQuery server. If we reconnect the LiveQuery server and successfully resubscribe the ParseQuery, you’ll also get this event.

Create event

subscription.on('create', (object) => {
  console.log('object created');
});

When a new ParseObject is created and it fulfills the ParseQuery you subscribe, you’ll get this event. The object is the ParseObject which was created.

Update event

subscription.on('update', (object) => {
  console.log('object updated');
});

When an existing ParseObject which fulfills the ParseQuery you subscribe is updated (The ParseObject fulfills the ParseQuery before and after changes), you’ll get this event. The object is the ParseObject which was updated. Its content is the latest value of the ParseObject.

Enter event

subscription.on('enter', (object) => {
  console.log('object entered');
});

When an existing ParseObject’s old value does not fulfill the ParseQuery but its new value fulfills the ParseQuery, you’ll get this event. The object is the ParseObject which enters the ParseQuery. Its content is the latest value of the ParseObject.

Leave event

subscription.on('leave', (object) => {
  console.log('object left');
});

When an existing ParseObject’s old value fulfills the ParseQuery but its new value doesn’t fulfill the ParseQuery, you’ll get this event. The object is the ParseObject which leaves the ParseQuery. Its content is the latest value of the ParseObject.

Delete event

subscription.on('delete', (object) => {
  console.log('object deleted');
});

When an existing ParseObject which fulfills the ParseQuery is deleted, you’ll get this event. The object is the ParseObject which is deleted.

Close event

subscription.on('close', () => {
  console.log('subscription closed');
});

When the client loses the WebSocket connection to the LiveQuery server and we can’t get anymore events, you’ll get this event.

Unsubscribe

subscription.unsubscribe();

If you would like to stop receiving events from a ParseQuery, you can just unsubscribe the subscription. After that, you won’t get any events from the subscription object.

Close

Parse.LiveQuery.close();

When you are done using LiveQuery, you can call Parse.LiveQuery.close(). This function will close the WebSocket connection to the LiveQuery server, cancel the auto reconnect, and unsubscribe all subscriptions based on it. If you call query.subscribe() after this, we will create a new WebSocket connection to the LiveQuery server.

Setup server URL

Parse.liveQueryServerURL = 'ws://XXXX'

Most of the time you do not need to manually set this. If you have setup your Parse.serverURL, we will try to extract the hostname and use ws://hostname as the default liveQueryServerURL. However, if you want to define your own liveQueryServerURL or use a different protocol such as wss, you should set it by yourself.

WebSocket Status

We expose three events to help you monitor the status of the WebSocket connection:

Open event

Parse.LiveQuery.on('open', () => {
  console.log('socket connection established');
});

When we establish the WebSocket connection to the LiveQuery server, you’ll get this event.

Close event

Parse.LiveQuery.on('close', () => {
  console.log('socket connection closed');
});

When we lose the WebSocket connection to the LiveQuery server, you’ll get this event.

Error event

Parse.LiveQuery.on('error', (error) => {
  console.log(error);
});

When some network error or LiveQuery server error happens, you’ll get this event.

Advanced API

In our standard API, we manage a global WebSocket connection for you, which is suitable for most cases. However, for some cases, like when you have multiple LiveQuery servers and want to connect to all of them, a single WebSocket connection isn’t enough. We’ve exposed the LiveQueryClient for these scenarios.

LiveQueryClient

A LiveQueryClient is a wrapper of a standard WebSocket client. We add several useful methods to help you connect/disconnect to LiveQueryServer and subscribe/unsubscribe a ParseQuery easily.

Initialize

let Parse = require('parse/node');
let LiveQueryClient = Parse.LiveQueryClient;
let client = new LiveQueryClient({
  applicationId: '',
  serverURL: '',
  javascriptKey: '',
  masterKey: ''
});

• applicationId is mandatory, it’s the applicationId of your Parse app
• serverURL is mandatory, it’s the URL of your LiveQuery server
• javascriptKey and masterKey are optional, they are used for verifying the LiveQueryClient when it tries to connect to the LiveQuery server. If you set them, they should match your Parse app. You can check LiveQuery protocol here for more details.

Open

client.open();

After you call this, the LiveQueryClient will try to send a connect request to the LiveQuery server.

Subscribe

let query = new Parse.Query('Game');
let subscription = client.subscribe(query, sessionToken); 

• query is mandatory, it is the ParseQuery you want to subscribe
• sessionToken is optional, if you provide the sessionToken, when the LiveQuery server gets ParseObject’s updates from parse server, it’ll try to check whether the sessionToken fulfills the ParseObject’s ACL. The LiveQuery server will only send updates to clients whose sessionToken is fit for the ParseObject’s ACL. You can check the LiveQuery protocol here for more details. The subscription you get is the same subscription you get from our Standard API. You can check our Standard API about how to use the subscription to get events.

Unsubscribe

client.unsubscribe(subscription); 

• subscription is mandatory, it’s the subscription you want to unsubscribe from. After you call this, you won’t get any events from the subscription object.

Close

client.close();

This function will close the WebSocket connection to this LiveQueryClient, cancel the auto reconnect, and unsubscribe all subscriptions based on it.

Event Handling

We expose three events to help you monitor the status of the LiveQueryClient.

Open event

client.on('open', () => {
  console.log('connection opened');
});

When we establish the WebSocket connection to the LiveQuery server, you’ll get this event.

Close event

client.on('close', () => {
  console.log('connection closed');
});

When we lose the WebSocket connection to the LiveQuery server, you’ll get this event.

Error event

client.on('error', (error) => {
  console.log('connection error');
});

When some network error or LiveQuery server error happens, you’ll get this event.

Reconnect

Since the whole LiveQuery feature relies on the WebSocket connection to the LiveQuery server, we always try to maintain an open WebSocket connection. Thus, when we find we lose the connection to the LiveQuery server, we will try to auto reconnect. We do exponential back off under the hood. However, if the WebSocket connection is closed due to Parse.LiveQuery.close() or client.close(), we’ll cancel the auto reconnect.

SessionToken

We send sessionToken to the LiveQuery server when you subscribe to a ParseQuery. For the standard API, we use the sessionToken of the current user by default. For the advanced API, you can use any sessionToken when you subscribe to a ParseQuery. An important thing to be aware of is when you log out or the sessionToken you are using is invalid, you should unsubscribe the subscription and subscribe to the ParseQuery again. Otherwise you may face a security issue since you’ll get events which shouldn’t be sent to you.

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 Parse.User 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.

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

Parse.User Properties

Parse.User has several values that set it apart from Parse.Object:

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

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:

const user = new Parse.User();
user.set("username", "my name");
user.set("password", "my pass");
user.set("email", "[email protected]");

// other fields can be set just like with Parse.Object
user.set("phone", "415-392-0202");
try {
  await user.signUp();
  // Hooray! Let them use the app now.
} catch (error) {
  // Show the error message somewhere and let the user try again.
  alert("Error: " + error.code + " " + error.message);
}

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 Parse.Users should always be created using the signUp method. Subsequent updates to a user can be done by calling save.

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 — Parse.User 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 logIn.

const user = await Parse.User.logIn("myname", "mypass");
// Do stuff after successful login.

By default, the SDK uses the POST HTTP method. If you would like to override this and use a GET HTTP method instead, you may pass an optional Boolean property in the options argument with the key usePost.

const user = await Parse.User.logIn("myname", "mypass", { usePost: false });
// Do stuff after successful login.

Available with SDK version 2.17.0 and later

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 Parse.User object. When a Parse.User’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. Parse.Users can never have a true value when the user account is first created.
2. false - at the time the Parse.User object was last refreshed, the user had not confirmed his or her email address. If emailVerified is false, consider calling fetch on the Parse.User.
3. missing - the Parse.User was created when email verification was off or the Parse.User 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 current Parse.User object.

Please note that this functionality is disabled by default on Node.js environments (such as React Native) to discourage stateful usages on server-side configurations. To bypass this behavior on this particular use case, call once Parse.User.enableUnsafeCurrentUser() right before using any cached-user related functionalities.

Whenever you use any signup or login methods, the user is cached in localStorage, or in any storage you configured via the Parse.setAsyncStorage method. You can treat this cache as a session, and automatically assume the user is logged in:

const currentUser = Parse.User.current();
if (currentUser) {
    // do stuff with the user
} else {
    // show the signup or login page
}

When using a platform with an async storage system you should call currentAsync() instead.

Parse.User.currentAsync().then(function(user) {
    // do stuff with your user
});

You can clear the current user by logging them out:

Parse.User.logOut().then(() => {
  const currentUser = Parse.User.current();  // this will now be null
});

Setting the Current User

If you’ve created your own authentication routines, or otherwise logged in a user on the server side, you can now pass the session token to the client and use the become method. This method will ensure the session token is valid before setting the current user.

Parse.User.become("session-token-here").then(function (user) {
  // The current user is now set to user.
}, function (error) {
  // The token could not be validated.
});

Security For User Objects

The Parse.User class is secured by default. Data stored in a Parse.User can only be modified by that user. By default, the data can still be read by any client. Thus, some Parse.User objects are authenticated and can be modified, whereas others are read-only.

Specifically, you are not able to invoke any of the save or delete methods unless the Parse.User was obtained using an authenticated method, like logIn or signUp. This ensures that only the user can alter their own data.

The following illustrates this security policy:

const user = await Parse.User.logIn("my_username", "my_password");
user.set("username", "my_new_username");
await user.save();
// This succeeds, since the user was authenticated on the device

// Get the user from a non-authenticated method
const query = new Parse.Query(Parse.User);
const userAgain = await query.get(user.objectId);
userAgain.set("username", "another_username");
await userAgain.save().catch(error => {
  // This will error, since the Parse.User is not authenticated
});

The Parse.User obtained from Parse.User.current() will always be authenticated.

If you need to check if a Parse.User is authenticated, you can invoke the authenticated method. You do not need to check authenticated with Parse.User objects that are obtained via an authenticated method.

Encrypting Current User

Often you may want to be more careful with user information stored in the browser, if this is the case you can encrypt the current user object:

Parse.enableEncryptedUser();
Parse.secret = 'my Secrey Key';

• It’s important to remember that this function will not work if Parse.secret is not set.
• Also note that this only works in the browser.

Now the record in Local Storage looks like a random string and only can be read using Parse.User.current() You can check if this feature is enabled with the function Parse.isEncryptedUserEnabled().

Security For Other Objects

The same security model that applies to the Parse.User can be applied to other objects. For any object, you can specify which users are allowed to read the object, and which users are allowed to modify an object. To support this type of security, each object has an access control list, implemented by the Parse.ACL class.

The simplest way to use a Parse.ACL is to specify that an object may only be read or written by a single user. This is done by initializing a Parse.ACL with a Parse.User: new Parse.ACL(user) generates a Parse.ACL that limits access to that user. An object’s ACL is updated when the object is saved, like any other property. Thus, to create a private note that can only be accessed by the current user:

const Note = Parse.Object.extend("Note");
const privateNote = new Note();
privateNote.set("content", "This note is private!");
privateNote.setACL(new Parse.ACL(Parse.User.current()));
privateNote.save();

This note will then only be accessible to the current user, although it will be accessible to any device where that user is signed in. This functionality is useful for applications where you want to enable access to user data across multiple devices, like a personal todo list.

Permissions can also be granted on a per-user basis. You can add permissions individually to a Parse.ACL using setReadAccess and setWriteAccess. For example, let’s say you have a message that will be sent to a group of several users, where each of them have the rights to read and delete that message:

const Message = Parse.Object.extend("Message");
const groupMessage = new Message();
const groupACL = new Parse.ACL();

// userList is an array with the users we are sending this message to.
for (let i = 0; i < userList.length; i++) {
  groupACL.setReadAccess(userList[i], true);
  groupACL.setWriteAccess(userList[i], true);
}

groupMessage.setACL(groupACL);
groupMessage.save();

You can also grant permissions to all users at once using setPublicReadAccess and setPublicWriteAccess. This allows patterns like posting comments on a message board. For example, to create a post that can only be edited by its author, but can be read by anyone:

const publicPost = new Post();
const postACL = new Parse.ACL(Parse.User.current());
postACL.setPublicReadAccess(true);
publicPost.setACL(postACL);
publicPost.save();

Operations that are forbidden, such as deleting an object that you do not have write access to, result in a Parse.Error.OBJECT_NOT_FOUND error code. For security purposes, this prevents clients from distinguishing which object ids exist but are secured, versus which object ids do not exist at all.

Resetting Passwords

It’s a fact that as soon as you introduce passwords into a system, users will forget them. In such cases, our library provides a way to let them securely reset their password.

To kick off the password reset flow, ask the user for their email address, and call:

Parse.User.requestPasswordReset("[email protected]")
.then(() => {
  // Password reset request was sent successfully
}).catch((error) => {
  // Show the error message somewhere
  alert("Error: " + error.code + " " + error.message);
});

This will attempt to match the given email with the user’s email or username field, and will send them a password reset email. By doing this, you can opt to have users use their email as their username, or you can collect it separately and store it in the email field.

The flow for password reset is as follows:

1. User requests that their password be reset by typing in their email.
2. Parse sends an email to their address, with a special password reset link.
3. User clicks on the reset link, and is directed to a special Parse page that will allow them type in a new password.
4. User types in a new password. Their password has now been reset to a value they specify.

Note that the messaging in this flow will reference your app by the name that you specified when you created this app on Parse.

Querying

To query for users, you can simple create a new Parse.Query for Parse.Users:

const query = new Parse.Query(Parse.User);
query.equalTo("gender", "female");  // find all the women
const women = await query.find();

Associations

Associations involving a Parse.User work right of the box. For example, let’s say you’re making a blogging app. To store a new post for a user and retrieve all their posts:

const user = Parse.User.current();

// Make a new post
const Post = Parse.Object.extend("Post");
const post = new Post();
post.set("title", "My New Post");
post.set("body", "This is some great content.");
post.set("user", user);
await post.save();
// Find all posts by the current user
const query = new Parse.Query(Post);
query.equalTo("user", user);
const userPosts = await query.find();
// userPosts contains all of the posts by the current user.
});

Facebook Users

Parse provides an easy way to integrate Facebook with your application. The Parse.FacebookUtils class integrates Parse.User and the Facebook Javascript SDK to make linking your users to their Facebook identities easy.

Using our Facebook integration, you can associate an authenticated Facebook user with a Parse.User. With just a few lines of code, you’ll be able to provide a “log in with Facebook” option in your app, and be able to save their data to Parse.

Setting up Facebook

To start using Facebook with Parse, you need to:

1. Create a Facebook Developer account.
2. Create an app.
3. In your app Dashboard, add a product -> Facebook Login.
4. Add appIds to Parse Server auth configuration or pass facebookAppIds into configuration

<script>
  // Initialize Parse
  Parse.initialize("$PARSE_APPLICATION_ID", "$PARSE_JAVASCRIPT_KEY");
  Parse.serverURL = 'http://YOUR_PARSE_SERVER:1337/parse';

  window.fbAsyncInit = function() {
    Parse.FacebookUtils.init({
      appId      : '{facebook-app-id}', // Facebook App ID
      status     : true,  // check Facebook Login status
      cookie     : true,  // enable cookies to allow Parse to access the session
      xfbml      : true,  // initialize Facebook social plugins on the page
      version    : 'v2.3' // point to the latest Facebook Graph API version
    });
    // Run code after the Facebook SDK is loaded.
    // ...
  };

  // Load Facebook SDK
  (function(d, s, id){
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) {return;}
    js = d.createElement(s); js.id = id;
    js.src = "//connect.facebook.net/en_US/sdk.js";
    fjs.parentNode.insertBefore(js, fjs);
  }(document, 'script', 'facebook-jssdk'));
</script>

The function assigned to fbAsyncInit is run as soon as the Facebook JavaScript SDK has completed loading. Any code that you want to run after the Facebook JavaScript SDK is loaded should be placed within this function and after the call to Parse.FacebookUtils.init().

If you encounter any issues that are Facebook-related, a good resource is the official getting started guide from Facebook.

There are two main ways to use Facebook with your Parse users: (1) logging in as a Facebook user and creating a Parse.User, or (2) linking Facebook to an existing Parse.User.

Login & Signup

Parse.FacebookUtils provides a way to allow your Parse.Users to log in or sign up through Facebook. This is accomplished using the logIn() method:

try {
  const users = await Parse.FacebookUtils.logIn();
  if (!user.existed()) {
    alert("User signed up and logged in through Facebook!");
  } else {
    alert("User logged in through Facebook!");
  }
} catch(error) {
  alert("User cancelled the Facebook login or did not fully authorize.");
}

When this code is run, the following happens:

1. The user is shown the Facebook login dialog.
2. The user authenticates via Facebook, and your app receives a callback.
3. Our SDK receives the Facebook data and saves it to a Parse.User. If it’s a new user based on the Facebook ID, then that user is created.

You may optionally provide a comma-delimited string that specifies what permissions your app requires from the Facebook user. For example:

const user = await Parse.FacebookUtils.logIn("user_likes,email");

Linking

If you want to associate an existing Parse.User to a Facebook account, you can link it like so:

if (!Parse.FacebookUtils.isLinked(user)) {
  try  {
    await Parse.FacebookUtils.link(user);
    alert("Woohoo, user logged in with Facebook!");
  } catch(error) {}
    alert("User cancelled the Facebook login or ddid not fully authorize.");
  });
}

The steps that happen when linking are very similar to log in. The difference is that on successful login, the existing Parse.User is updated with the Facebook information. Future logins via Facebook will now log the user into their existing account.

For advanced API: If you have a Facebook access_token, you can use linkWith().

If you want to unlink Facebook from a user, simply do this:

await Parse.FacebookUtils.unlink(user);
alert("The user is no longer associated with their Facebook account.");

Facebook SDK and Parse

The Facebook Javascript SDK provides a main FB object that is the starting point for many of the interactions with Facebook’s API. You can read more about their SDK here.

Facebook login using the Parse SDK requires that the Facebook SDK already be loaded before calling Parse.FacebookUtils.init().

Our library manages the FB object for you. The FB singleton is synchronized with the current user by default, so any methods you call on it will be acting on the Facebook user associated with the current Parse.User. Calling FB.login() or FB.logOut() explicitly will cause the Parse.User and FB object to fall out of synchronization, and is not recommended.

Linking Users

Parse allows you to link your users with 3rd party authentication, enabling your users to sign up or log into your application using their existing identities. This is accomplished through linkWith method by providing authentication data for the service you wish to link to a user in the authData field. Once your user is associated with a service, the authData for the service will be stored with the user and is retrievable by logging in.

authData is a JSON object with keys for each linked service containing the data below. The authData object is required to at least have a key named id, which is used to identify the user on subsequent login attempts with linked account data.

_linkWith has been deprecated since version 2.9.0, see _linkWith

Signing Up and Logging In

Signing a user up with a linked service and logging them in with that service uses the same linkWith() method, in which the authData for the user is specified.

const myAuthData = {
  id: '12345678'  // Required field. Used to uniquely identify the linked account.
};
const user = new Parse.User();
await user.linkWith('providerName', { authData: myAuthData });

Parse then verifies that the provided authData is valid and checks to see if a user is already associated with this data. If so, it returns a status code of 200 OK and the details (including a sessionToken for the user):

Status: 200 OK
Location: https://YOUR.PARSE-SERVER.HERE/parse/users/uMz0YZeAqc

With a response body like:

{
  "username": "Parse",
  "createdAt": "2022-01-01T12:23:45.678Z",
  "updatedAt": "2022-01-01T12:23:45.678Z",
  "objectId": "uMz0YZeAqc",
  "sessionToken": "r:samplei3l83eerhnln0ecxgy5",
  "authData": {
    "providerName": {
      "id": "12345678",
    }
  }
}

If the user has never been linked with this account, you will instead receive a status code of 201 Created, indicating that a new user was created:

Status: 201 Created
Location: https://YOUR.PARSE-SERVER.HERE/parse/users/uMz0YZeAqc

The body of the response will contain the objectId, createdAt, sessionToken, and an automatically-generated unique username. For example:

{
  "username": "iwz8sna7sug28v4eyu7t89fij",
  "createdAt": "2022-01-01T12:23:45.678Z",
  "objectId": "uMz0YZeAqc",
  "sessionToken": "r:samplei3l83eerhnln0ecxgy5"
}

Linking un-authenticated users

To create a link to an un-authenticated user (for example in cloud code), options can be passed to linkWith() to either use the masterKey or pass a sessionToken.

const myAuthData = {
  id: xzx5tt123,  // The id key is required in the authData-object. Otherwise Parse Server will throw the Error 252 'This authentication method is unsupported'.
  access: token
}

const user = await Parse.Query(Parse.User).get(userId);

await user.linkWith(
  'providerName',
  { authData: myAuthData },
  { useMasterKey: true }
);

On rest, web, mobile, or TV clients, users can then login using the CustomAdapter by passing myAuthData:

const loggedIn = await Parse.User.logInWith('CustomAdapter', { authData: myAuthData});

Custom Authentication Module

Parse Server supports many 3rd Party Authenications. It is possible to linkWith any 3rd Party Authentication by creating a custom authentication module. A custom authentication module normally consists of a client-side AuthProvider object and a back-end AuthAdapter. The client-side object should implement the AuthProvider interface. The backend AuthAdapter should implement the the functions validateAuthData and validateAppId, check out this AuthAdapter example. When calling the linkWith function without an authData object the client side authenticate-method from the provider object will be called. In the other case the authData object will be sent directly to Parse Server for authentication using the backend module.

Note: The following is a minimal example implementing AuthProvider client-side and AuthAdapter on the backend.

A minimal CustomAuth.js module in the backend:

// Don't require or import parse-server in this module.
// See this issue: https://github.com/parse-community/parse-server/issues/6467
function validateAuthData(authData, options) {
  return Promise.resolve({})
}

function validateAppId(appIds, authData, options) {
  return Promise.resolve({});
}

module.exports = {
  validateAppId,
  validateAuthData,
};

Configure the server to make the CustomAuth available:

const CustomAuth = require('./CustomAuth');

const api = new ParseServer({
  ...
  auth: {
    myAuth: {
      module: CustomAuth,
      option1: 'hello',
      option2: 'world',
    }
  }
  ...
});
...
await api.start();
app.use('/parse', api.app);

Use the CustomAuth:

const provider = {
  authenticate: (options) => {
    // Some code to get retrieve authData
    // If retrieved valid authData, call success function with the data
    options.success(this, {
      id: 1234
    });
    // You can also handle error
    // options.error(this, {});
  },
  restoreAuthentication() {
    return true;
  },

  getAuthType() {
    return 'myAuth';
  },

  getAuthData() {
    return {
      authData: {
        id: 1234,
      },
    };
  },
};
// Must register before linking
Parse.User._registerAuthenticationProvider(provider);
const user = new Parse.User();
user.setUsername('Alice');
user.setPassword('sekrit');
await user.signUp();
await user.linkWith(provider.getAuthType(), provider.getAuthData());
user._isLinked(provider); // true
// Unlink
await user._unlinkFrom(provider.getAuthType());

Sessions

Sessions represent an instance of a user logged into a device. Sessions are automatically created when users log in or sign up. They are automatically deleted when users log out. There is one distinct Session object for each user-installation pair; if a user issues a login request from a device they’re already logged into, that user’s previous Session object for that Installation is automatically deleted. Session objects are stored on Parse in the Session class, and you can view them on the Parse Dashboard Data Browser. We provide a set of APIs to manage Session objects in your app.

Session is a subclass of a Parse Object, so you can query, update, and delete sessions in the same way that you manipulate normal objects on Parse. Because Parse Server automatically creates sessions when you log in or sign up users, you should not manually create Session objects unless you are building an IoT app (e.g. Arduino or Embedded C). Deleting a Session will log the user out of the device that is currently using this session’s token.

Unlike other Parse objects, the Session class does not have Cloud Code triggers. So you cannot register a beforeSave or afterSave handler for the Session class.

Session Properties

The Session object has these special fields:

• sessionToken (readonly): String token for authentication on Parse API requests. In the response of Session queries, only your current Session object will contain a session token.
• user: (readonly) Pointer to the User object that this session is for.
• createdWith (readonly): Information about how this session was created (e.g. { "action": "login", "authProvider": "password"}).
  • action could have values: login, signup, create, or upgrade. The create action is when the developer manually creates the session by saving a Session object. The upgrade action is when the user is upgraded to revocable session from a legacy session token.
  • authProvider could have values: password, anonymous, facebook, or twitter.
• expiresAt (readonly): Approximate UTC date when this Session object will be automatically deleted. You can configure session expiration settings (either 1-year inactivity expiration or no expiration) in your app’s Parse Dashboard settings page.
• installationId (can be set only once): String referring to the Installation where the session is logged in from. For Parse SDKs, this field will be automatically set when users log in or sign up. All special fields except installationId can only be set automatically by Parse Server. You can add custom fields onto Session objects, but please keep in mind that any logged-in device (with session token) can read other sessions that belong to the same user (unless you disable Class-Level Permissions, see below).

Handling Invalid Session Token Error

With revocable sessions, your current session token could become invalid if its corresponding Session object is deleted from your Parse Server. This could happen if you implement a Session Manager UI that lets users log out of other devices, or if you manually delete the session via Cloud Code, REST API, or Data Browser. Sessions could also be deleted due to automatic expiration (if configured in app settings). When a device’s session token no longer corresponds to a Session object on your Parse Server, all API requests from that device will fail with “Error 209: invalid session token”.

To handle this error, we recommend writing a global utility function that is called by all of your Parse request error callbacks. You can then handle the “invalid session token” error in this global function. You should prompt the user to login again so that they can obtain a new session token. This code could look like this:

function handleParseError(err) {
  switch (err.code) {
    case Parse.Error.INVALID_SESSION_TOKEN:
      Parse.User.logOut();
      ... // If web browser, render a log in screen
      ... // If Express.js, redirect the user to the log in route
      break;

    ... // Other Parse API errors that you want to explicitly handle
  }
}

// For each API request, call the global error handler
query.find().then(function() {
  ...
}, function(err) {
  handleParseError(err);
});

Session Security

Session objects can only be accessed by the user specified in the user field. All Session objects have an ACL that is read and write by that user only. You cannot change this ACL. This means querying for sessions will only return objects that match the current logged-in user.

When you log in a user via a User login method, Parse will automatically create a new unrestricted Session object in your Parse Server. Same for signups and Facebook/Twitter logins.

You can configure Class-Level Permissions (CLPs) for the Session class just like other classes on Parse. CLPs restrict reading/writing of sessions via the Session API, but do not restrict Parse Server’s automatic session creation/deletion when users log in, sign up, and log out. We recommend that you disable all CLPs not needed by your app. Here are some common use cases for Session CLPs:

• Find, Delete — Useful for building a UI screen that allows users to see their active session on all devices, and log out of sessions on other devices. If your app does not have this feature, you should disable these permissions.
• Create — Useful for apps that provision user sessions for other devices from the phone app. You should disable this permission when building apps for mobile and web. For IoT apps, you should check whether your IoT device actually needs to access user-specific data. If not, then your IoT device does not need a user session, and you should disable this permission.
• Get, Update, Add Field — Unless you need these operations, you should disable these permissions.

Roles

As your app grows in scope and user-base, you may find yourself needing more coarse-grained control over access to pieces of your data than user-linked ACLs can provide. To address this requirement, Parse supports a form of Role-based Access Control. Roles provide a logical way of grouping users with common access privileges to your Parse data. Roles are named objects that contain users and other roles. Any permission granted to a role is implicitly granted to its users as well as to the users of any roles that it contains.

For example, in your application with curated content, you may have a number of users that are considered “Moderators” and can modify and delete content created by other users. You may also have a set of users that are “Administrators” and are allowed all of the same privileges as Moderators, but can also modify the global settings for the application. By adding users to these roles, you can ensure that new users can be made moderators or administrators, without having to manually grant permission to every resource for each user.

We provide a specialized class called Parse.Role that represents these role objects in your client code. Parse.Role is a subclass of Parse.Object, and has all of the same features, such as a flexible schema, automatic persistence, and a key value interface. All the methods that are on Parse.Object also exist on Parse.Role. The difference is that Parse.Role has some additions specific to management of roles.

Parse.Role Properties

Parse.Role has several properties that set it apart from Parse.Object:

• name: The name for the role. This value is required, and can only be set once as a role is being created. The name must consist of alphanumeric characters, spaces, -, or _. This name will be used to identify the Role without needing its objectId.
• users: A relation to the set of users that will inherit permissions granted to the containing role.
• roles: A relation to the set of roles whose users and roles will inherit permissions granted to the containing role.

Security for Role Objects

The Parse.Role uses the same security scheme (ACLs) as all other objects on Parse, except that it requires an ACL to be set explicitly. Generally, only users with greatly elevated privileges (e.g. a master user or Administrator) should be able to create or modify a Role, so you should define its ACLs accordingly. Remember, if you give write-access to a Parse.Role to a user, that user can add other users to the role, or even delete the role altogether.

To create a new Parse.Role, you would write:

// By specifying no write privileges for the ACL, we can ensure the role cannot be altered.
const roleACL = new Parse.ACL();
roleACL.setPublicReadAccess(true);
const role = new Parse.Role("Administrator", roleACL);
role.save();

You can add users and roles that should inherit your new role’s permissions through the “users” and “roles” relations on Parse.Role:

const role = new Parse.Role(roleName, roleACL);
role.getUsers().add(usersToAddToRole);
role.getRoles().add(rolesToAddToRole);
role.save();

Take great care when assigning ACLs to your roles so that they can only be modified by those who should have permissions to modify them.

Role Based Security for Other Objects

Now that you have created a set of roles for use in your application, you can use them with ACLs to define the privileges that their users will receive. Each Parse.Object can specify a Parse.ACL, which provides an access control list that indicates which users and roles should be granted read or write access to the object.

Giving a role read or write permission to an object is straightforward. You can either use the Parse.Role:

const moderators = /* Query for some Parse.Role */;
const wallPost = new Parse.Object("WallPost");
const postACL = new Parse.ACL();
postACL.setRoleWriteAccess(moderators, true);
wallPost.setACL(postACL);
wallPost.save();

You can avoid querying for a role by specifying its name for the ACL:

const wallPost = new Parse.Object("WallPost");
const postACL = new Parse.ACL();
postACL.setRoleWriteAccess("Moderators", true);
wallPost.setACL(postACL);
wallPost.save();

Role Hierarchy

As described above, one role can contain another, establishing a parent-child relationship between the two roles. The consequence of this relationship is that any permission granted to the parent role is implicitly granted to all of its child roles.

These types of relationships are commonly found in applications with user-managed content, such as forums. Some small subset of users are “Administrators”, with the highest level of access to tweaking the application’s settings, creating new forums, setting global messages, and so on. Another set of users are “Moderators”, who are responsible for ensuring that the content created by users remains appropriate. Any user with Administrator privileges should also be granted the permissions of any Moderator. To establish this relationship, you would make your “Administrators” role a child role of “Moderators”, like this:

const administrators = /* Your "Administrators" role */;
const moderators = /* Your "Moderators" role */;
moderators.getRoles().add(administrators);
moderators.save();

Files

Creating a Parse.File

Parse.File lets you store application files in the cloud that would otherwise be too large or cumbersome to fit into a regular Parse.Object. The most common use case is storing images, but you can also use it for documents, videos, music, and any other binary data.

Getting started with Parse.File is easy. There are a couple of ways to create a file. The first is with a base64-encoded String.

const base64 = "V29ya2luZyBhdCBQYXJzZSBpcyBncmVhdCE=";
const file = new Parse.File("myfile.txt", { base64: base64 });

Alternatively, you can create a file from an array of byte values:

const bytes = [ 0xBE, 0xEF, 0xCA, 0xFE ];
const file = new Parse.File("myfile.txt", bytes);

Parse will auto-detect the type of file you are uploading based on the file extension, but you can specify the Content-Type with a third parameter:

const file = new Parse.File("myfile.zzz", fileData, "image/png");

Client Side

In a browser, you’ll want to use an html form with a file upload control. To do this, create a file input tag which allows the user to pick a file from their local drive to upload:

<input type="file" id="profilePhotoFileUpload">

Then, in a click handler or other function, get a reference to that file:

const fileUploadControl = $("#profilePhotoFileUpload")[0];
if (fileUploadControl.files.length > 0) {
  const file = fileUploadControl.files[0];
  const name = "photo.jpg";

  const parseFile = new Parse.File(name, file);
}

Notice in this example that we give the file a name of photo.jpg. There’s two things to note here:

• You don’t need to worry about filename collisions. Each upload gets a unique identifier so there’s no problem with uploading multiple files named photo.jpg.
• It’s important that you give a name to the file that has a file extension. This lets Parse figure out the file type and handle it accordingly. So, if you’re storing PNG images, make sure your filename ends with .png.

Next you’ll want to save the file up to the cloud. As with Parse.Object, there are many variants of the save method you can use depending on what sort of callback and error handling suits you.

parseFile.save().then(function() {
  // The file has been saved to Parse.
}, function(error) {
  // The file either could not be read, or could not be saved to Parse.
});

Server Side

In Cloud Code you can fetch images or other files and store them as a Parse.File.

const request = require('request-promise');
const Parse = require('parse/node');

....

const options = {
  uri: 'https://bit.ly/2zD8fgm',
  resolveWithFullResponse: true,
  encoding: null, // <-- this is important for binary data like images.
};

request(options)
  .then((response) => {
    const data = Array.from(Buffer.from(response.body, 'binary'));
    const contentType = response.headers['content-type'];
    const file = new Parse.File('logo', data, contentType);
    return file.save();
  })
  .then((file => console.log(file.url())))
  .catch(console.error);

Embedding files in other objects

Finally, after the save completes, you can associate a Parse.File with a Parse.Object just like any other piece of data:

const jobApplication = new Parse.Object("JobApplication");
jobApplication.set("applicantName", "Joe Smith");
jobApplication.set("applicantResumeFile", parseFile);
jobApplication.save();