Dictionaries - React Native SDK

On this page

Overview

Realm Object Models
Create an Object with a Dictionary Value
Query for Objects with a Dictionary Property
Update a Dictionary
Delete Members of a Dictionary

New in version realm@10.5.0.

Overview

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

Realm Object Models

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

Create an Object with a Dictionary Value

To create an object with a dictionary value, use the new operator within a write transaction.

Example

In the following CreateHomeOwner example, we create a new object with a dictionary property.

The CreateHomeOwner component does the following:

Create React state that represents the homeowner's name and address, respectively.
Get access to an open realm instance by calling the useRealm() hook within the component.
Create a component method SubmitHomeOwner() that performs a write transaction and creates a new HomeOwner object based on the TextInput values for the homeowner's name and address, respectively.
Add an onPress event on the submit button that calls SubmitHomeOwner()

Query for Objects with a Dictionary Property

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 HomeOwner collection with a nested home dictionary, you could return all HomeOwner objects with a home with a "price" property by running the query: home.@keys = "price".

Example

In the following HomeList example, we query for objects that have dictionary properties.

The HomeList component does the following:

Performs a query for all homeowners by passing the HomeOwner class to the useQuery hook.
Performs a query for homeowners with a listed price by passing collection.filtered() the query: home.@keys = "price".
Performs a query for the summer hill house by running collection.filtered() using bracket notation to find the first homeowner with an address set to "Summerhill St." and getting their home by using dot syntax.
Performs a query for all homeowners with any field with a value of red by passing collection.filtered() the query: 'home.@values = "red"'. We then get the first homeowner's home.
Display the results of our queries in the UI by rendering information about the homes

Update a Dictionary

Update a dictionary's property by using the dictionary.set() method or dot notation to set its property to a new value.

Example

In the following UpdateHome example, we update a dictionary's property.

The UpdateHome component does the following:

Create a React state variable that represents the home address.
Get access to an opened realm instance by calling the useRealm() hook within the component.
Create a component method updateAddress() that performs a write transaction and uses dictionary.set() to set the home's address to the value of the address state variable. It also uses dot syntax to set the yearRenovated to 2004.
Render a TextInput that displays and changes the address state variable.
Add an onPress event on the "Update Address" button that calls updateAddress()

Delete Members of a Dictionary

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

Example

In the following HomeInfo example, we delete members of a dictionary.

The HomeInfo component does the following:

Get access to an open realm instance by calling the useRealm() hook within the component.
Retrieve the first homeowner that matches the name passed into the component as a prop. We do this by getting the first value returned from the query: useQuery(HomeOwner).filtered(`name == '${homeOwnerName}'`).
Create a component method deleteExtraHomeInfo() that performs a write transaction and calls dictionary.remove() to remove the yearRenovated and color properties.
Render the homeowner's name and home address in the UI.
Add an onPress event on the "Delete extra home info" button that calls deleteExtraHomeInfo().

← Collections - React Native SDK Sets - React Native SDK →