Docs Menu
Docs Home
/ /
Atlas Device SDKs
/
/
/

Property Annotations - Flutter SDK

On this page

  • Required and Optional Properties
  • Default Field Values
  • Primary Keys
  • Map a Property or Class to a Different Name
  • Ignore Properties from Realm Schema
  • Index Properties
  • Full-Text Search Indexes

You can use annotations to add functionality to properties in your Realm object models.

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;
}

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;
}

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;
}

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.

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;
}

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;
}

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 FTS indexes, see Filter with Full-Text Search.

To create an FTS index on a property, use the @Indexed annotation and specify the RealmIndexType as fullText. This enables full-text queries on the property. In the following example, we mark the pattern and material properties with the FTS annotation:

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