Realm Dart & Flutter SDK

Realm provides several ways to retrieve data and react to changes:

• Retrieve all objects: Use realm.all<T>() to get all instances of a type.
• Query with filters: Use .query() with a string expression. You can use positional arguments (e.g., $0) to prevent injection and handle dynamic values.
• Find by Primary Key: Use realm.find<T>(id) to retrieve a specific object.
• Observe changes: Use the .changes property on a result set to listen to a stream of updates (insertions, deletions, and modifications).

// Querying
var cars = realm.all<Car>().query("make == 'Tesla'");
var carsWithArgs = realm.all<Car>().query(r'make == $0', ['Tesla']);

// Finding by Primary Key
var myCar = realm.find<Car>(0);

// Observing changes
final carsStream = realm.all<Car>().query(r'make == $0', ['Tesla']);
carsStream.changes.listen((changes) {
  print('Inserted: ${changes.inserted}');
  print('Deleted: ${changes.deleted}');
  print('Modified: ${changes.modified}');
});

To use Realm, you follow a three-step process: define a data model, generate the concrete RealmObject class, and then interact with the database using a Realm instance.

1. Define the Model: Create a class starting with an underscore (e.g., _Car) and annotate it with @RealmModel(). Use late for required properties.
2. Generate the Class: Run the generator command to create the concrete class (e.g., Car) and the required .realm.dart part file.
3. Use the Model: Open a Realm instance with a Configuration.local containing your schema, and perform operations within realm.write() blocks.

import 'package:realm/realm.dart';

part 'app.realm.dart';

@RealmModel()
class _Car {
  late String make;
  late String model;
  int? kilometers = 500;
}

// After running 'dart run realm generate':
var config = Configuration.local([Car.schema]);
var realm = Realm(config);

var car = Car("Tesla", "Model Y", kilometers: 5);
realm.write(() {
  realm.add(car);
});

To synchronize data between a local Realm and Atlas App Services, follow these three steps:

1. Initialize and Authenticate: Create an App instance using your appId and log in a user (e.g., using Credentials.anonymous()).
2. Open a Synced Realm: Use Configuration.flexibleSync(user, [schema]) to create a realm configuration that links to your authenticated user and specific object schemas.
3. Manage Subscriptions and Write Data: Use realm.subscriptions.update to define which data subsets should be synced to the device. Only data matching these queries will be downloaded. Always call await realm.subscriptions.waitForSynchronization() before performing writes to ensure the subscription state is established.

// 1. Initialize and Authenticate
String appId = "<Atlas App ID>";
final appConfig = AppConfiguration(appId);
final app = App(appConfig);
final user = await app.logIn(Credentials.anonymous());

// 2. Open a synced realm
final config = Configuration.flexibleSync(user, [Task.schema]);
final realm = Realm(config);

// 3. Add a sync subscription and write data
realm.subscriptions.update((mutableSubscriptions) {
  mutableSubscriptions.add(realm.query<Task>(r'status == $0 AND progressMinutes == $1', ["completed", 100]));
});
await realm.subscriptions.waitForSynchronization();

realm.write(() {
  realm.add(Task(ObjectId(), "Send an email", "completed", 4));
  realm.add(Task(ObjectId(), "Create a meeting", "completed", 100));
  realm.add(Task(ObjectId(), "Call the manager", "init", 2));
});

realm.close();