Property Annotations - Flutter SDK

Required and Optional Properties

In Dart, value types are implicitly non-nullable, but can be made optional (nullable) by appending ?. Include ? to make properties optional.

class _Vehicle {
  @PrimaryKey()
  late ObjectId id;
  late String? maybeDescription; // optional value
  late double milesTravelled = 0; // 0 is default value
  @Ignored()
  late String notInRealmModel;
  @Indexed()
  late String make;
  @MapTo('wheels') // 'wheels' is property name in the RealmObject
  late int numberOfWheels;
}

Default Field Values

You can use the built-in language features to assign a default value to a property. Assign a default value in the property declaration.

class _Vehicle {
  @PrimaryKey()
  late ObjectId id;
  late String? maybeDescription; // optional value
  late double milesTravelled = 0; // 0 is default value
  @Ignored()
  late String notInRealmModel;
  @Indexed()
  late String make;
  @MapTo('wheels') // 'wheels' is property name in the RealmObject
  late int numberOfWheels;
}

Primary Keys

The PrimaryKey annotation indicates a primary key property. The primary key is a unique identifier for an object in a realm. No other objects of the same type may share an object's primary key.

Important aspects of primary keys:

• You cannot change a primary key after adding an object to a realm.

• Only add a primary key to one property in a RealmModel.

• Only String, int, ObjectId, and Uuid types can be primary keys.

• Realm automatically indexes primary keys.

• Primary keys are nullable. null can only be the primary key of one object in a collection.

class _Vehicle {
  @PrimaryKey()
  late ObjectId id;
  late String? maybeDescription; // optional value
  late double milesTravelled = 0; // 0 is default value
  @Ignored()
  late String notInRealmModel;
  @Indexed()
  late String make;
  @MapTo('wheels') // 'wheels' is property name in the RealmObject
  late int numberOfWheels;
}

Map a Property or Class to a Different Name

The MapTo annotation indicates that a model or property should be persisted under a different name. It's useful when opening a Realm across different bindings where code style conventions can differ. For example:

• To make it easier to work across platforms where naming conventions differ. For example, if your Device Sync schema property names use snake case, while your project uses camel case.

• To change a class or field name without forcing a migration.

@RealmModel()
@MapTo('naval_ship')
class _Boat {
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late int? maxKnots;
  late int? nauticalMiles;
}

class _Vehicle {
  @PrimaryKey()
  late ObjectId id;
  late String? maybeDescription; // optional value
  late double milesTravelled = 0; // 0 is default value
  @Ignored()
  late String notInRealmModel;
  @Indexed()
  late String make;
  @MapTo('wheels') // 'wheels' is property name in the RealmObject
  late int numberOfWheels;
}

Ignore Properties from Realm Schema

If you add the Ignored annotation to a property in your RealmModel, the realm object generator doesn't include the property in the RealmObject schema or persist it to Realm.

class _Vehicle {
  @PrimaryKey()
  late ObjectId id;
  late String? maybeDescription; // optional value
  late double milesTravelled = 0; // 0 is default value
  @Ignored()
  late String notInRealmModel;
  @Indexed()
  late String make;
  @MapTo('wheels') // 'wheels' is property name in the RealmObject
  late int numberOfWheels;
}

Index Properties

Add the Indexed annotation to create an index on the field. Indexes can greatly speed up some queries at the cost of slightly slower write times and additional storage and memory overhead. Realm stores indexes on disk, which makes your realm files larger. Each index entry is a minimum of 12 bytes. Indexes can be nullable.

The following data types can be indexed:

• bool

• int

• String

• ObjectId

• Uuid

• DateTime

• RealmValue

class _Vehicle {
  @PrimaryKey()
  late ObjectId id;
  late String? maybeDescription; // optional value
  late double milesTravelled = 0; // 0 is default value
  @Ignored()
  late String notInRealmModel;
  @Indexed()
  late String make;
  @MapTo('wheels') // 'wheels' is property name in the RealmObject
  late int numberOfWheels;
}

@RealmModel()
class _Rug {
    @PrimaryKey()
    late ObjectId id;
    @Indexed(RealmIndexType.fullText)
    late String pattern;
    @Indexed(RealmIndexType.fullText)
    late String material;
    late int softness;
}