Realm オブジェクトモデルの定義 - Kotlin SDK
項目一覧
このページでは、Realm オブジェクトタイプと、アプリケーションのデータモデルの一部として Realm オブジェクトを定義する方法について説明します。 オブジェクトモデルを定義したら、定義したオブジェクトを含むスキーマで Realm を開き、Realm内でそれらを操作できます。
Kotlin SDK メモリは Realm オブジェクトをネイティブ Kotlin オブジェクトに直接マッピングするため、特別なデータアクセス ライブラリを使用する必要はありません。 アプリケーションのデータモデルは、アプリケーション コード オブジェクトで宣言された通常の Kotlin クラスを使用して定義します。
Realm オブジェクトモデルの定義後に Realm オブジェクトに変更を加える方法については、「 オブジェクトモデルの変更 」を参照してください。
注意
Device Sync を使用したデータモデルの定義
アプリが Atlas Device Sync を使用する場合は、データモデルを定義する際に追加の考慮事項があります。 詳細については、「 Device Sync によるデータのモデル化 - Kotlin SDK 」を参照してください。
Realm オブジェクト
Realm オブジェクトは、他のクラス インスタンスと同様に操作できる Kotlin クラスの一意の名前付きインスタンスです。
各オブジェクト クラスはオブジェクトタイプを表します。 同じ型のオブジェクトはオブジェクト スキーマを共有します。これは、その型のオブジェクトのプロパティと関係を定義します。 SDK は、Realm 内のすべてのオブジェクトがオブジェクトタイプのスキーマに準拠していることを保証し、オブジェクトが作成、変更、または削除されるたびにオブジェクトを検証します。
ただし、Realm オブジェクトには次の制約があることに注意してください。
Realm オブジェクトは、
RealmObject
クラスまたはそのサブクラス(EmbeddedRealmObject
またはAsymmetricRealmObject
から継承する必要があります。 Kotlin SDK はカスタム 基本クラスからの継承をサポートしていません。Kotlin SDK では、Realm オブジェクトが空のコンストラクターを持つ必要があります。 次のセクションに記載されている回避策の例を参照してください。
クラス名は最大 57 文字の UTF-8 文字に制限されています。
また、 Kotlin SDKはKotlin データ クラス の 使用をサポートしていませ ん 。 モデル データに渡す追加オプション。これは、データ クラスは通常不変データに使用され、 Realm Kotlin SDKがデータをモデル化する方法に適しているためです。
新しいオブジェクトタイプの定義
新しいオブジェクトタイプを定義するには、 RealmObject
、 EmbeddedRealmObject
、またはAsymmetricRealmObject
インターフェースのいずれかを実装する一意の名前を持つ Kotlin クラスを作成する必要があります。
注意
クラス名は最大 57 文字の UTF-8 文字に制限されています。
次に、次のようなオブジェクトのプロパティを指定します。
各プロパティのデータ型。 Kotlin SDK は次のデータ型をサポートしています。
BSON の限定的なサブセット types
Realm 固有のタイプ。一意の識別子、タイムスタンプ、カウンター、コレクションに使用できます
プロパティ 注釈。Realm オブジェクト内のプロパティに機能を追加します。 注釈を使用すると、次のことができます。
プロパティをプライマリキーとして指定
プロパティをインデックス可能としてマークします
プロパティを無視する
プロパティ名またはクラス名を別の名前にマッピング
他の Realm オブジェクトとの関係。
Realm オブジェクトモデルを定義した後、Realm を開くときにオブジェクト クラスのセットを Realm の構成に渡し、Realm 内のそれらのオブジェクトを操作します。
重要
Realm には空のコンストラクターが必要
Realm Kotlin SDK は、単一のプライマリ コンストラクターの存在をサポートしていません。 SDK では、 オブジェクトを作成するために空のコンストラクターが必要です。 回避策として、次のような操作を実行できます。
class Person(var name: String, var age: Int): RealmObject { constructor(): this("", 0) // Empty constructor required by Realm }
Realm オブジェクトタイプの定義
Realm オブジェクトタイプを定義するには、 RealmObjectインターフェースを実装する Kotlin クラスを作成します。
// Implements the `RealmObject` interface class Frog : RealmObject { // Empty constructor required by Realm var _id: ObjectId = ObjectId() var name: String = "" var age: Int = 0 var species: String? = null var owner: String? = null }
その後、オブジェクトをプロパティとして使用して、他の Realm オブジェクトとの関係を定義できます。
埋め込みオブジェクトタイプの定義
EmbeddedRealmObject
は、特定のオブジェクトに関する複雑なデータをモデル化する特殊なタイプの Realm オブジェクトです。 Realm は、各埋め込みオブジェクトを単一の特定の親オブジェクト内のネストされたデータとして扱います。
このため、埋め込みオブジェクトには次の制約があります。
埋め込みオブジェクトには親オブジェクトが必要であり、独立した Realm オブジェクトとして存在することはできません。 親オブジェクトが埋め込みオブジェクトを参照しなくなると、埋め込みオブジェクトは自動的に削除されます。
埋め込みオブジェクトは、親オブジェクトのライフサイクルを継承します。 たとえば、親オブジェクトを削除すると、埋め込みオブジェクトも削除されます。
埋め込みオブジェクトは親オブジェクトに対する厳密な所有権を持ちます。 埋め込みオブジェクトを別の親オブジェクトに再割り当てしたり、複数の親オブジェクト間で埋め込みオブジェクトを共有したりすることはできません。
埋め込みオブジェクトには プライマリキー を 設定できません 。
Tip
参照されたオブジェクトのライフサイクルを手動で管理する必要がある場合、または親オブジェクトを削除した後も参照されたオブジェクトを保持する必要がある場合は、代わりに 1 対 1 の関係を持つ通常の Realm オブジェクトを使用します。 詳細については、「関係 - Kotlin SDK 」を参照してください。
埋め込みオブジェクトタイプを定義するには、埋め込みRealmObjectインターフェースを実装する Kotlin クラスを作成します。
// Implements `EmbeddedRealmObject` interface class EmbeddedAddress : EmbeddedRealmObject { // CANNOT have primary key var street: String? = null var city: String? = null var state: String? = null var postalCode: String? = null var propertyOwner: Contact? = null }
埋め込みオブジェクトタイプは再利用可能で、構成可能です。 他の埋め込みオブジェクトタイプ内の複数の親オブジェクトタイプで同じ埋め込みオブジェクトタイプを使用できます。
埋め込みオブジェクトタイプを定義したら、データモデル内の親オブジェクトとの関係を定義する必要があります。 その方法については、 「 埋め込みオブジェクトの定義 」を参照してください。
非対称オブジェクトタイプの定義
バージョン 1.10.0 の新機能。
AsymmetricRealmObject
は、Atlas Device Sync 機能 Data Ingest で使用するための挿入専用オブジェクトです。 アプリケーションで Data Ingest を設定する方法については、「 Atlas へのデータのストリーム - Kotlin SDK 」を参照してください。
非対称オブジェクトは、いくつかの例外を除いて、 RealmObject
と同じプロパティタイプをほぼサポートしています。
非対称オブジェクトは、 Flexible Sync で構成された同期された Realm でのみ使用できます。 ただし、非対称オブジェクトへのサブスクリプションは作成できません。
AsymmetricRealmObject
にはEmbeddedRealmObject
型を含めることができますが、RealmObject
型やその他のAsymmetricRealmObject
型を含めることはできません。AsymmetricRealmObject
型は、他の Realm オブジェクトのプロパティとして使用することはできません。
さらに、非対称オブジェクトは他の Realm オブジェクトと同じように機能しません。 Realm から非対称オブジェクトを追加、読み取り、更新、または削除することはできません。 非対称オブジェクトのみを作成できます。その後、Device Sync でアプリにリンクされた Atlas データベースに一方向に同期します。 Realm は同期後にこのオブジェクトを削除します。
非対称オブジェクトタイプを定義するには、 AmetricRealmObjectインターフェースを実装する Kotlin クラスを作成します。
// Implements the `AsymmetricRealmObject` interface class WeatherSensor : AsymmetricRealmObject { var id: ObjectId = ObjectId() var deviceId: String = "" var temperatureInFarenheit: Float = 0.0F var barometricPressureInHg: Float = 0.0F var windSpeedInMph: Int = 0 }
Kotlin SDK バージョン1.11.1以前では、 AsymmetricRealmObject
型からRealmObject
型にリンクできません。 SDK バージョン1.12.0以降では、 AsymmetricRealmObject
タイプはEmbeddedRealmObject
タイプに加えてRealmObject
タイプにリンクできます。
コレクション プロパティを定義する
コレクションは、サポートされているデータ型の 0 個以上のインスタンスを含むオブジェクトです。 Realm コレクションは同種(コレクション内のすべてのオブジェクトは同じタイプ)であり、対応する組み込み Kotlin クラスによってサポートされています。 Kotlin SDK で使用されるコレクション タイプとサポートされているデータ型の詳細については、「コレクション タイプ 」を参照してください。
Kotlin SDK には、データモデルのプロパティとして使用できるいくつかのコレクション タイプが用意されていますRealmList
、 RealmSet
、 RealmDictionary
。
コレクションを使用すると、Realm オブジェクト間の 対多の関係を定義することもできます。 詳細については、 「 関係 - Kotlin SDK 」を参照してください。
重要
コレクション プロパティを初期化
コレクション タイプは null 以外です。 コレクション プロパティを定義するときは、それを初期化する必要があります。
RealmList の定義
プロパティをRealmListとして定義するには、オブジェクト スキーマ内でそのタイプをRealmList<E>
として指定し、 RealmListOf()を使用してデフォルト値を初期化します。
// RealmList<E> can be any supported primitive // or BSON type, a RealmObject, or an EmbeddedRealmObject class Frog : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" // List of RealmObject type (CANNOT be nullable) var favoritePonds: RealmList<Pond> = realmListOf() // List of EmbeddedRealmObject type (CANNOT be nullable) var favoriteForests: RealmList<EmbeddedForest> = realmListOf() // List of primitive type (can be nullable) var favoriteWeather: RealmList<String?> = realmListOf() } class Pond : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" }
RealmSet の定義
プロパティをRealmSetとして定義するには、オブジェクト スキーマ内でそのタイプをRealmSet<E>
として指定し、 RealmSetOf()を使用してデフォルト値を初期化します。
// RealmSet<E> can be any supported primitive or // BSON type or a RealmObject class Frog : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" // Set of RealmObject type (CANNOT be nullable) var favoriteSnacks: RealmSet<Snack> = realmSetOf() // Set of primitive type (can be nullable) var favoriteWeather: RealmSet<String?> = realmSetOf() } class Snack : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" }
RealmDictionary/RealmMap の定義
プロパティをRealmDictionaryとして定義するには、オブジェクト スキーマ内でそのタイプをRealmDictionary<K, V>
として指定し、 realmDictionaryOf()を使用してデフォルト値を初期化します。
// RealmDictionary<K, V> can be any supported // primitive or BSON types, a RealmObject, or // an EmbeddedRealmObject class Frog : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" // Dictionary of RealmObject type (value MUST be nullable) var favoriteFriendsByPond: RealmDictionary<Frog?> = realmDictionaryOf() // Dictionary of EmbeddedRealmObject type (value MUST be nullable) var favoriteTreesInForest: RealmDictionary<EmbeddedForest?> = realmDictionaryOf() // Dictionary of primitive type (value can be nullable) var favoritePondsByForest: RealmDictionary<String?> = realmDictionaryOf() }
Realm では、マップキーに.
または$
文字を使用できません。 パーセント エンコーディングとデコーディング を使用して、これらの許可されていない文字の 1 つを含むマップキーを保存できます。
// Percent encode . or $ characters to use them in map keys val mapKey = "Hundred Acre Wood.Northeast" val encodedMapKey = "Hundred Acre Wood%2ENortheast"
非構造化データの定義
バージョン2.0.0の新機能。
Kotlin SDK バージョン2.0.0以降、 RealmAny
プロパティ内に混合データのコレクションを保存できます。 この機能を使用すると、厳密なデータモデルを定義することなく、JSON や MongoDB ドキュメントなどの複雑なデータ構造をモデル化できます。
非構造化データとは、期待されるスキーマに簡単に準拠していないデータであるため、個々のデータ クラスにモデル化するのが困難または非効率的です。 たとえば、アプリには、実行時に構造が不明な高度に変数データや動的データがある場合があります。
コレクションを混合プロパティに保存すると、Device Sync を使用する際のパフォーマンス的な同期など、機能を犠牲にすることなく柔軟性が高まります。 そして、混合されていないコレクションと同じ方法でそれらを操作できます。
混合コレクションは最大100レベルまでネストできます。
混合コレクションのReactに対応する と をクエリできます。
個々の混合コレクション要素を検索して更新できます。
ただし、混合コレクションにデータを保存する場合、構造化スキーマを使用したり、JSON string を単一の string プロパティに直列化したりする場合よりパフォーマンスが低くなります。
アプリ内の非構造化データをモデル化するには、スキーマ内の適切なプロパティをRealmAny型として定義します。 次に、これらのRealmAny
プロパティをRealmListまたはRealmAny
要素のRealmDictionaryコレクションとして設定できます。 RealmAny
はRealmSet
または埋め込みオブジェクトを表すことができないことに注意してください。
Tip
型が不明であるが、各値には一意の識別子が付けられる場合は、混合データ型のマップを使用します。
型が不明であるが、オブジェクトの順序に意味がある場合は、混合データ型のリストを使用します。