Dictionaries (beta) - React Native SDK

New in version 10.5.0-beta.1.


This feature is currently in beta. While we encourage you to try out the feature and give feedback, please be aware the API may change.

You can use the dictionary data type to manage a collection of unique String keys paired with values. The dictionary data maps to the Javascript Object type.

To define a dictionary of mixed values in your schema, set the data type of your field to an empty object, "{}". Alternatively, to create a dictionary with values of a specific type, add the data type before the brackets. For instance, "int{}" to specify that dictionary values must be integers or "string{}" to specify that dictionary values must be strings.

const PersonSchema = {
name: "Person",
properties: {
name: "string",
home: "{}",

Create an object with a dictionary value by running the realm.create() method within a write transaction.

let johnDoe;
let janeSmith;
realm.write(() => {
johnDoe = realm.create("Person", {
name: "John Doe",
home: {
windows: 5,
doors: 3,
color: "red",
address: "Summerhill St.",
price: 400123,
janeSmith = realm.create("Person", {
name: "Jane Smith",
home: {
address: "100 northroad st.",
yearBuilt: 1990,

To filter a query, run collection.filtered() to specify a subset of results based on the value(s) of one or more object properties. You can specify results based on the value of a dictionary's properties by using bracket-notation.

You can also determine whether a results collection has a certain key or value by using <dictionary>.@keys or <dictionary>.@values. For instance, if you had a Person collection with a nested home dictionary, you could return all Person objects with a home with a "price" property by running the query: home.@keys = "price".

// query for all Person objects
const persons = realm.objects("Person");
// run the `.filtered()` method on all the returned persons to find the house with the address "Summerhill St."
const summerHillHouse = persons.filtered(
`home['address'] = "Summerhill St."`
// Find all people that have a house with a listed price
const peopleWithHousesWithAListedPrice = persons.filtered(
`home.@keys = "price" `
// find a house that has any field with a value of 'red'
const redHouse = persons.filtered(`home.@values = "red" `)[0].home;

You can add a listener to a dictionary by running the dictionary.addListener() method. The addListener method's callback function has two parameters, the changed dictionary and an array of changes describing how the dictionary was changed.


Learn more about change notifications.

summerHillHouse.addListener((changedHouse, changes) => {
console.log("A change has occurred to the Summer Hill House object");

To update a dictionary's properties, use dot notation or the dictionary.put() method.

realm.write(() => {
// use the `put()` method to update a field of a dictionary
summerHillHouse.put({ price: 400100 });
// alternatively, update a field of a dictionary through dot notation
summerHillHouse.color = "brown";
// update a dictionary by adding a field
summerHillHouse.yearBuilt = 2004;

To delete members of a dictionary, use the dictionary.remove() method with an array of properties to remove from the dictionary.

realm.write(() => {
// remove the 'windows' and 'doors' field of the Summerhill House.
summerHillHouse.remove(["windows", "doors"]);
Give Feedback

On this page