Navigation

Sets - Node.js SDK

On this page

  • Overview
  • Realm Object Models
  • Create an Object With a Set
  • Add Items to a Set
  • Check if a Set has Specific Items
  • Check the Size of a Set
  • Remove an Item from a Set
  • Remove all Items from a Set

New in version 10.5.0.

A Realm Set is a special object that allows you to store a collection of unique values. Realm Sets are based on JavaScript sets, but can only contain values of a single type and can only be modified within a write transaction. Sets allow you to perform math operations such as finding the union, intersection, or difference between two sets. To learn more about performing these operations, see the MDN docs for Implementing basic set operations.

Note
Realm Sets Do Not Guarantee Traversal Order

When using a forEach() loop or alternative iteration method to traverse the set in a loop, the content of the Realm Set may be in a different order than originally written to. If you require an ordered version of your set, you must implement that ordering yourself. If you require an ordered version of your set, you must implement that order yourself. You can do this by creating an array from the set, using Array.from(mySet) or the spread operator. You can keep that array updated by using a change listener to react to changes to the set.

To define a property type as a Realm Set, specify the data type you want in the set, followed by <>. For instance, for a set made of integer values, specify "int<>".

const characterSchema = {
name: "Character",
primaryKey: "_id",
properties: {
_id: "objectId",
name: "string",
levelsCompleted: "int<>",
inventory: "string<>",
},
};

To create an object with a Realm Set property, you must create the object within a write transaction. When defining your Realm object, initialize the Realm Set by passing an empty array or an array with your initial values.

let characterOne, characterTwo;
realm.write(() => {
characterOne = realm.create("Character", {
_id: new BSON.ObjectId(),
name: "CharacterOne",
inventory: ["elixir", "compass", "glowing shield"],
levelsCompleted: [4, 9],
});
characterTwo = realm.create("Character", {
_id: new BSON.ObjectId(),
name: "CharacterTwo",
inventory: ["estus flask", "gloves", "rune"],
levelsCompleted: [1, 2, 5, 24],
});
});

To add an item to a set, pass the new value to the <Realm.Set>.add() method within a write transaction.

realm.write(() => {
characterOne.inventory.add("hammer");
characterOne.levelsCompleted.add(32);
});

To determine if a set contains a particular value, pass the value to the <Realm.Set>.has() method. The set.has() method will return true if the set contains the value specified.

// check if the characterTwo has completed level 3 by calling the `Realm.Set.has()` method
const characterTwoHasCompletedLevelThree = characterTwo.levelsCompleted.has(3);
console.log(
`Is level three completed by the characterTwo: ${characterTwoHasCompletedLevelThree}`
);

To discover how many items are in a set, you can check the set's size property.

// check how many items the characterTwo has in his inventory through the `Realm.Set.size` property
const characterTwoInventorySize = characterTwo.inventory.size;
console.log(`The characterTwo has ${characterTwoInventorySize} inventory items`);

To remove a specific value from a set, pass the value to the <Realm.Set>.delete() method within a write transaction.

realm.write(() => {
// remove the compass from characterOne's inventory by calling `Realm.Set.delete()` within a write transaction
characterOne.inventory.delete("compass");
});

To clear the set, run the <Realm.Set>.clear() method within a write transaction.

realm.write(() => {
// clear all data from the inventory slot of the characterTwo by calling `Realm.Set.clear()` in a write transaction
characterTwo.inventory.clear();
});
Give Feedback

On this page

  • Overview
  • Realm Object Models
  • Create an Object With a Set
  • Add Items to a Set
  • Check if a Set has Specific Items
  • Check the Size of a Set
  • Remove an Item from a Set
  • Remove all Items from a Set