Object Models - .NET SDK

Object Schema

An object schema is a configuration object that defines the properties and relationships of a Realm object. Realm client applications define object schemas with the native class implementation in their respective language using the Object Schema.

Object schemas specify constraints on object properties such as the data type of each property and whether or not a property is required. Schemas can also define relationships between object types in a realm.

Every App has a App Services Schema composed of a list of object schemas for each type of object that the realms in that application may contain. Realm guarantees that all objects in a realm conform to the schema for their object type and validates objects whenever they're created, modified, or deleted.

Primary Key

A primary key is a property that uniquely identifies an object. You can create a primary key with any of the following types (or their nullable counterparts):

• ObjectId

• UUID

• string

• char

• byte

• short

• int

• long

You may define a primary key on a single property for an object type as part of the object schema. Realm automatically indexes primary key properties, which allows you to efficiently read and modify objects based on their primary key.

If an object type has a primary key, then all objects of that type must include the primary key property with a value that is unique among objects of the same type in a realm.

The following example demonstrates how to designate a primary key in an object schema:

public partial class Dog : IRealmObject
{
    [PrimaryKey]
    public string Name { get; set; }
    public int Age { get; set; }
    public Person? Owner { get; set; }
}

Indexes

Indexes significantly improve query times in a Realm. Without indexes, Realm scans every document in a collection to select the documents that match the given query. However, if an applicable index exists for a query, Realm uses the index to limit the number of documents that it must inspect.

You can index properties with the following types:

• bool

• byte

• short

• int

• long

• DateTimeOffset

• char

• string

• ObjectId

• UUID

To index a property, use the Indexed attribute. With the Indexed attribute, you can specify the type of index on the property by using the IndexType enum. In the following example, we have a default ("General") index on the Name property:

public partial class Person : IRealmObject
{
    [Indexed(IndexType.General)]
    public string Name { get; set; }
    [Indexed(IndexType.FullText)]
    public string Biography { get; set; }
}

Full-Text Search Indexes

In addition to standard indexes, Realm also supports Full-Text Search (FTS) indexes on string properties. While you can query a string field with or without a standard index, an FTS index enables searching for multiple words and phrases and excluding others.

For more information on querying full-text indexes, see Full Text Search (LINQ) and Full Text Search (RQL).

To index an FTS property, use the Indexed attribute with the IndexType.FullText enum. In the following example, we have a FullText index on the Biography property:

public partial class Person : IRealmObject
{
    [Indexed(IndexType.General)]
    public string Name { get; set; }
    [Indexed(IndexType.FullText)]
    public string Biography { get; set; }
}

Default Field Values

You can use the built-in language features to assign a default value to a property. In C#, you can assign a default value on primitives in the property declaration. You cannot set a default value on a collection, except to set it to null!. Even if you set a collection to null!, collections are always initialized on first access, so will never be null.

public partial class Person : IRealmObject
{
    public string Name { get; set; } = "foo";
    public IList<PhoneNumber> PhoneNumbers { get; } = null!;
}

Ignore a Property

If you don't want to save a property in your model to a realm, you can ignore that property. A property is ignored by default if it is not autoimplemented or does not have a setter.

Ignore a property from a Realm object model with the Ignored attribute:

// Rather than store an Image in Realm,
// store the path to the Image...
public string ThumbnailPath { get; set; }
// ...and the Image itself can be
// in-memory when the app is running:
[Ignored]
public Image? Thumbnail { get; set; }

Rename a Property

By default, Realm uses the name defined in the model class to represent properties internally. In some cases you might want to change this behavior:

• To make it easier to work across platforms, since naming conventions differ.

• To change a property name in .NET without forcing a migration.

Choosing an internal name that differs from the name used in model classes has the following implications:

• Migrations must use the internal name when creating classes and properties.

• Schema errors reported will use the internal name.

Use the [MapTo] attribute to rename a property:

public partial class Person : IRealmObject
{
    [MapTo("moniker")]
    public string Name { get; set; }
}

Rename a Class

By default, Realm uses the name defined in the model class to represent classes internally. In some cases you might want to change this behavior:

• To support multiple model classes with the same simple name in different namespaces.

• To make it easier to work across platforms, since naming conventions differ.

• To use a class name that is longer than the 57 character limit enforced by Realm.

• To change a class name in .NET without forcing a migration.

Use the [MapTo] attribute to rename a class:

[MapTo("Human")]
public partial class Person : IRealmObject
{
    public string Name { get; set; }
}

Custom Setters

Realm will not store a property with a custom setter. To use a custom setter, store the property value in a private property and then map that value to a public property with the custom setter. Realm will store the private property, while you modify its value via the public property. In the following code, the private email property is stored in the realm, but the public Email property, which provides validation, is not persisted:

// This property will be stored in the Realm
private string email { get; set; }
// Custom validation of the email property.
// This property is *not* stored in Realm.
public string Email
{
    get { return email; }
    set
    {
        if (!value.Contains("@")) throw new Exception("Invalid email address");
        email = value;
    }
}

Ignoring Nullability

You may prefer to have more flexibility in defining the nullability of properties in your Realm objects. You can do so by setting realm.ignore_objects_nullability = true in a global configuration file.

If you enable realm.ignore_objects_nullability, nullability annotations will be ignored on Realm object properties, including collections of Realm objects.