Definir um esquema de objeto Realm - Flutter SDK

Criar modelo

import 'package:realm/realm.dart';

import 'package:realm_dart/realm.dart';

part 'schemas.realm.dart';

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

dart run realm generate

dart run realm_dart generate

.
├── 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);

Usando esquemas com Device Sync

Um Esquema do App Services é uma lista de esquemas de objeto válidos que cada um define um tipo de objeto que um Aplicativo pode persistir. Todos os objetos sincronizados em um domínio devem estar em conformidade com o esquema do App Services.

Os aplicativos do cliente fornecem um Esquema de objetos quando abrem um domínio. Se um domínio já contiver dados, ele já terá um esquema e, quando for aberto, o Realm validará o esquema no cliente em relação ao esquema existente.

Você pode definir Esquemas do App Services das seguintes maneiras:

• Automaticamente com o esquema de objeto se o modo de desenvolvimento estiver habilitado.

• Defina explicitamente o esquema do App Services com o App Services.

Em seu esquema, você deve usar a anotação MapTo("_id") com sua chave primária no RealmModel para sincronizar com êxito seu esquema de objetos com o App Services.

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

Para obter mais informações sobre como definir seu esquema e quais dessas abordagens você deve considerar para seu aplicativo, consulte a documentação Criar um esquema Realm.

Tipos de dados suportados

Os esquemas do Realm suportam muitos tipos de dados da linguagem DART, além de alguns tipos específicos do Realm. Para uma referência abrangente de todos os tipos de dados suportados, consulte Tipos de dados.

Anotações da propriedade

Use anotações para adicionar funcionalidade às propriedades em seus modelos de objeto do Realm. Você pode usar anotações para coisas como marcar uma propriedade como anulável, definir uma chave primária, ignorar uma propriedade e muito mais. Para saber mais sobre as anotações de propriedade disponíveis, consulte Anotações de propriedade.

Definir Propriedades de Relacionamento

Você pode definir relações entre objetos de Realm em seu esquema. O Realm SDK Flutter oferece suporte a relacionamentos do tipo um para um, muitos para muitos, relacionamentos inversos e incorporação de objetos em outros objetos. Para saber mais sobre como definir relacionamentos em seu esquema de objetos de Realm, consulte Relacionamentos.

Mapear um Modelo ou Classe para um Nome Diferente

Você pode usar a anotação MapTo para mapear um modelo de objeto ou propriedade Realm para um nome armazenado diferente em Realm. Isto pode ser útil nos seguintes cenários. Por exemplo:

• Para facilitar o trabalho em plataformas onde as convenções de nomenclatura são diferentes. Por exemplo, se os nomes das propriedades do esquema Device Sync usarem snake case, enquanto seu projeto usa camel case.

• Para alterar um nome de campo ou classe sem forçar uma migração.

• Para oferecer suporte a várias classes de modelo com o mesmo nome em pacotes diferentes.

• Para usar um nome de classe maior que o limite de 57 caracteres imposto pelo Realm.

Se você estiver usando o Atlas Device Sync, o nome especificado na anotação MapTo será usado como o nome persistente do esquema do App Services.

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

Dados não estruturados do modelo

A partir do Flutter SDK versão 2.0.0, você pode armazenar collections de dados mistos dentro de uma propriedade RealmValue . Você pode usar esse recurso para modelar estruturas de dados complexas, como documentos JSON ou MongoDB , sem precisar definir um modelo de dados rigoroso.

Dados não estruturados são dados que não estão em conformidade com facilmente um esquema esperado, tornando difícil ou impraticável modelar classes de dados individuais. Por exemplo, seu aplicativo pode ter dados altamente variáveis ou dados dinâmicos cuja estrutura é desconhecida no tempo de execução.

O armazenamento de coleções em uma propriedade mista oferece flexibilidade sem sacrificar a funcionalidade, incluindo sincronização de desempenho ao usar o Device Sync. E você pode trabalhar com eles da mesma forma que faria com uma collection não mista:

• Você pode aninhar collections mistas em até 100 níveis.

• Você pode consultar e React a alterações em coleções mistas.

• Você pode localizar e atualizar elementos individuais de coleção mista.

No entanto, armazenar dados em coleções mistas é menos eficiente do que usar um esquema estruturado ou serializar blobs JSON em uma única propriedade de string.

Para modelar dados não estruturados em seu aplicativo, defina as propriedades apropriadas em seu esquema como tipos de RealmValue . Você pode então definir essas propriedades RealmValue como uma coleção RealmList ou RealmMap de RealmValue elementos. Observe que RealmValue não pode representar um RealmSet ou um objeto incorporado.

Por exemplo , você pode utilizar um RealmValue que contém um mapa de dados mistos ao modelar um objeto de log de evento variável:

// 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)

Gerar o RealmObject

Depois de concluir o modelo Realm, você deve gerar a classe RealmObject para usá-la em seu aplicativo.

Execute o seguinte comando para gerar RealmObjects:

dart run realm generate

dart run realm_dart generate

Executar isto cria uma classe pública em um novo arquivo no diretório onde você definiu a classe RealmModel de acordo com a seção Criar Modelo.

O arquivo gerado tem o mesmo nome de base que o arquivo com seu RealmModel, terminando com .realm.dart. Por exemplo, se o arquivo com seu RealmModel for denominado schemas.dart, o arquivo gerado será schemas.realm.dart.

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

Se quiser observar seus modelos de dados para gerar RealmObjects sempre que houver uma alteração, inclua o sinalizador --watch em seu comando.

dart run realm generate --watch

dart run realm_dart generate --watch

Para limpar os caches do gerador, inclua a bandeira --clean no seu comando. Limpar o cache do gerador pode ser útil ao depurar.

dart run realm generate --clean

dart run realm_dart generate --clean

Definir um objeto assimétrico

Objetos assimétricos exigem Flexible Sync. Para definir um objeto assimétrico, passe ObjectType.asymmetricObject para @RealmModel().

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

Nas versões 1.5.0 e anteriores do SDK Flutter, você não pode vincular de asymmetricObject tipos a RealmObjects. Nas versões 1.6.0 e posteriores do SDK, os tipos asymmetricObject podem ser vinculados a RealmObjects, além dos tipos de objetos incorporados.

Para mais informações sobre ingestão de dados, consulte Stream Data to Atlas.