Define a Realm Object Schema - Flutter SDK

Create Model

part 'schemas.realm.dart';

@RealmModel()
class _Car {
  @PrimaryKey()
  late ObjectId id;
  late String make;
  late String? model;
  late int? miles;
}

.
├── schemas.dart
├── schemas.realm.dart // newly generated file
├── myapp.dart
└── ...rest of application

import './schemas.dart';
final hondaCivic = Car(ObjectId(), 'Honda', model: 'Civic', miles: 99);

Using Schemas with Device Sync

An App Services Schema is a list of valid object schemas that each define an object type that an App may persist. All synced objects in a realm must conform to the App Services Schema.

Client applications provide a Object Schema when they open a realm. If a realm already contains data, then it already has a schema, and when it is opened, Realm validates the schema on the client against the existing schema.

You can define App Services Schemas in the following ways:

• Automatically with the Object Schema if development mode is enabled.

• Explicitly define the App Services Schema with App Services.

In your schema you must use the MapTo("_id") annotation with your primary key in the RealmModel to successfully sync your Object Schema with App Services.

@RealmModel()
class _SyncSchema {
  @PrimaryKey()
  @MapTo("_id")
  late ObjectId id;
  // ... other properties
}

For further information on defining your schema and which of these approaches you should consider for your application, refer to the Create a Realm Schema documentation.

Supported Data Types

Realm schemas support many Dart-language data types, in addition to some Realm-specific types. For a comprehensive reference of all supported data types, refer to Data Types.

Property Annotations

Use annotations to add functionality to properties in your Realm object models. You can use annotations for things like marking a property as nullable, setting a primary key, ignoring a property, and more. To learn more about the available property annotations, refer to Property Annotations.

Define Relationship Properties

You can define relationships between Realm objects in your schema. The Realm Flutter SDK supports to-one relationships, to-many relationships, inverse relationships, and embedding objects within other objects. To learn more about how to define relationships in your Realm object schema, refer to Relationships.

Map a Model or Class to a Different Name

You can use the MapTo annotation to map a Realm object model or property to a different stored name in Realm. This can be useful in the following scenarios. 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.

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

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

If you're using Atlas Device Sync, the name that you specify in the MapTo annotation is used as the persisted App Services Schema name.

Model Unstructured Data

Starting in Flutter SDK version 2.0.0, you can define nested collections of mixed data within a RealmValue property.

The ability to nest collections of mixed data enables you to define data that doesn't otherwise conform to an expected schema, including data with variable structure or data whose shape or type is not known at runtime. For example, you might have highly variable user-created objects, event logs, or survey response data that are collected and stored in a variety of JSON formats. This approach allows you to react to changes in the nested data and to update specific elements, but it is less performant than using a structured schema or serializing JSON blobs into a single string property.

To model unstructured data in your schema using collections of mixed type, define the appropriate properties in your schema as RealmValue types. You can then set these RealmValue properties as a RealmList or a RealmMap collection of RealmValue elements. Note that RealmValue cannot represent a RealmSet or an embedded object.

For example, you might use a RealmValue that contains a map of mixed data when modeling a variable event log object:

// Define class with a `RealmValue` property
@RealmModel()
class _EventLog {
  @PrimaryKey()
  late ObjectId id;
  late String eventType;
  late DateTime timestamp;
  late String userId;
  late RealmValue details;
}

realm.write(() {
  // Add `eventLog` property data as a map of mixed data, which 
  // also includes nested lists of mixed data 
  realm.add(EventLog(ObjectId(), 'purchase', DateTime.now(), 'user123',
      details: RealmValue.from({
        'ipAddress': '192.168.1.1',
        'items': [
          {'id': 1, 'name': 'Laptop', 'price': 1200.00},
          {'id': 2, 'name': 'Mouse', 'price': 49.99}
        ],
        'total': 1249.99
      })));
  final eventLog = realm.all<EventLog>().first;
  final items = eventLog.details.asMap();
  print('''
      Event Type: ${eventLog.eventType}
      Timestamp: ${eventLog.timestamp}
      User ID: ${eventLog.userId}
      Details:
        Item: 
  ''');
  for (var item in items.entries) {
    print('${item.key}: ${item.value}');
  }

Event Type: purchase
Timestamp: 2024-03-18 13:50:58.402979Z
User ID: user123
Details:
Item:
   ipAddress: RealmValue(192.168.1.1)
   items: RealmValue([RealmValue({id: RealmValue(1), name: RealmValue(Laptop), price: RealmValue(1200.0)}), RealmValue({id: RealmValue(2), name: RealmValue(Mouse), price: RealmValue(49.99)})])
   total: RealmValue(1249.99)

Generate the RealmObject

Once you've completed your Realm model, you must generate the RealmObject class to use it in your application.

Run the following command to generate RealmObjects:

Running this creates a public class in a new file in the directory where you defined the RealmModel class per the Create Model section.

The generated file has the same base name as the file with your RealmModel, ending with .realm.dart. For example if the file with your RealmModel is named schemas.dart, the generated file will be schemas.realm.dart.

// ...import packages
part 'schemas.realm.dart';
@RealmModel()
// ...model definition

If you'd like to watch your data models to generate RealmObjects whenever there's a change, include the --watch flag in your command.

To clean the generator caches, include the --clean flag in your command. Cleaning the generator cache can be useful when debugging.

Define an Asymmetric Object

Asymmetric objects require Flexible Sync. To define an asymmetric object, pass ObjectType.asymmetricObject to @RealmModel().

@RealmModel(ObjectType.asymmetricObject)
class _WeatherSensor {
  @PrimaryKey()
  @MapTo("_id")
  late ObjectId id;
  late String deviceId;
  late double modtemperatureInFahrenheitel;
  late double barometricPressureInHg;
  late double windSpeedInMph;
}

In Flutter SDK versions 1.5.0 and earlier, you cannot link from asymmetricObject types to RealmObjects. In SDK versions 1.6.0 and later, asymmetricObject types can link to RealmObjects in addition to embedded object types.

To learn more about Data Ingest, refer to Stream Data to Atlas.