Navigation

Dictionaries (Beta) - .NET SDK

On this page

  • Overview
  • Dictionary Types
  • Usage Example
  • Data Binding

New in version 10.2.0-beta.1.

Warning

This feature is currently in beta. We encourage you to try out the feature and give feedback, but please be aware that:

  • The API may change.
  • New data types are not backwards compatible.

To add new data types via development mode, you must update the client SDK. Realm Sync client applications using older protocol versions will no longer be able to connect.

A Realm dictionary is an implementation of IDictionary that has keys of type String and supports values of any Realm type except collections. To define a dictionary, use a getter-only IDictionary<string, TValue> property, where TValue is any of the supported types.

A dictionary of objects can contain null objects. Likewise, dictionaries of primitive types can also contain null values. If you do not want to allow null values in a dictionary, then either use non-nullable types in the dictionary declaration (for example, use IDictionary<string, double> instead of IDictionary<string, double?>), or add the [Required] attribute if the dictionary contains nullable reference types, such as string or byte[].

Important
Not Supported with Sync

Local-only Realm Databases support collections of nullable (optional) values, but Sync does not.

The following code shows examples of dictionary types:

public class Inventory : RealmObject
{
// The key must be of type string; the value can be
// of any Realm-supported type, including objects
// that inherit from RealmObject or EmbeddedObject
public IDictionary<string, Plant> PlantDict { get; }
public IDictionary<string, bool> BooleansDict { get; }
// Nullable types are supported in local-only
// Realms, but not with Sync
public IDictionary<string, int?> NullableIntDict { get; }
// For C# types that are implicitly nullable, you can
// use the [Required] attribute to prevent storing null values
[Required]
public IDictionary<string, string> RequiredStringsDict { get; }
}

The following code shows how to create, write to, and read from Dictionaries.

Note

You cannot use Linq to query against a Realm Dictionary. Instead, use a string query.

var storeInventory = new Inventory()
{
Id = ObjectId.GenerateNewId().ToString()
};
storeInventory.PlantDict.Add("Petunia", new Plant());
storeInventory.NullableIntDict.Add("random things", 7);
storeInventory.RequiredStringsDict.Add("foo", "bar");
var storeInventory2 = new Inventory()
{
Id = ObjectId.GenerateNewId().ToString()
};
storeInventory2.RequiredStringsDict.Add("foo", "Bar");
realm.Write(() =>
{
realm.Add<Inventory>(storeInventory);
realm.Add<Inventory>(storeInventory2);
});
// Find all Inventory items that have "Petunia"
// as a key in their PlantDict.
var petunias = realm.All<Inventory>()
.Filter("PlantDict.@keys == 'Petunia'");
// Find all Inventory items that have at least one value in their
// IntDict that is larger than 5
var matchesMoreThanFive = realm.All<Inventory>()
.Filter("NullableIntDict.@values > 5");
// Find all Inventory items where any RequiredStringsDict has a key
// "Foo", and the value of that key contains the phrase "bar"
// (case insensitive)
var matches = realm.All<Inventory>().Filter("RequiredStringsDict['foo'] CONTAINS[c] 'bar'");
// matches.Count() == 2

Like other Realm collections, IDictionary implements INotifyCollectionChanged, so you can use it in data-binding scenarios (for example, when watching for changes).

Give Feedback

On this page

  • Overview
  • Dictionary Types
  • Usage Example
  • Data Binding