プロパティ注釈 - Kotlin SDK

プライマリキーの指定

プライマリキーは、Realm 内のオブジェクトの一意の識別子です。 同じタイプの他のオブジェクトは、オブジェクトのプライマリキーを共有できません。

オブジェクトタイプのプライマリキーとしてプロパティを指定するには、 @PrimaryKey注釈を使用します。

@PrimaryKey
var _id: ObjectId = ObjectId() // Primary key property

プライマリキーの重要な要素：

• オブジェクト スキーマごとに定義できるプライマリキーは 1 つだけです。

• オブジェクトタイプのプライマリキー フィールドは、そのタイプのオブジェクトを Realm に追加した後では、変更できません。

• プライマリキー値は、Realm 内のオブジェクトのすべてのインスタンスで一意である必要があります。 重複するプライマリキー値を挿入しようとすると、エラーが発生します。

• プライマリキーの値は不変です。 オブジェクトのプライマリキー値を変更するには、元のオブジェクトを削除し、別のプライマリキー値を持つ新しいオブジェクトを挿入する必要があります。

• プライマリキーは null 可能です。 プライマリキー値は一意である必要があるため、 nullはコレクション内の 1 つのオブジェクトのプライマリキーになることができます。

• Realm はプライマリキーを自動的にインデックス化するため、プライマリキーに基づいてオブジェクトを効率的に読み取り、変更できます。

次のいずれかのタイプのプライマリキーを作成できます。

• String

• Byte

• Char

• Short

• Int

• Long

• ObjectId

• RealmUUID

プロパティまたはクラスを別の名前にマッピング

デフォルトでは、Realm はモデル クラスで定義された名前を使用して、クラスとフィールドを内部的に表します。 Kotlin SDK を使用すると、プロパティ名またはクラス名を、コードで使用される名前とは異なる永続名にマッピングできます。 Realm に別の名前を保持すると便利な場合があります。次のような場合です。

• 命名規則が異なるプラットフォーム間での操作を容易にします。 たとえば、Device Sync スキーマのプロパティ名がスニペットのケースを使用する場合、プロジェクトはキャメルケースを使用します。

• 移行を強制せずに Kotlin でクラスまたはフィールド名を変更します。

• 異なるパッケージで同じ単純名を持つ複数のモデル クラスをサポートします。

• Realm によって強制される 57 文字の制限よりも長いクラス名を使用します。

コード内の Kotlin クラスまたはプロパティ名を、Realm に永続化する別の名前にマッピングするには、次の手順に従います。

1. Kotlin クラスまたはプロパティで@PersistedNameアノテーションを使用します。

2. Realm に永続化するクラスまたはプロパティnameを指定します。

@PersistedName(name = "Frog_Entity") // Remapped class name
class Frog : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var age: Int = 0
    var species: String? = null
    var owner: String? = null
}

@PersistedName("latin_name")
var species: String? = null // Remapped property

同期された Realm に書き込むと、Sync スキーマは永続化されたクラスまたはプロパティ名を使用して保存された値を確認します。 次の点に注意してください。

• 移行では、永続化されたクラスまたはプロパティ名を使用する必要があります。

• 報告されたスキーマ エラーでは、永続化された名前が使用されます。

Realm スキーマからのプロパティの無視

デフォルトでは、Realm は Realm オブジェクトモデルで定義されたプロパティを管理します。 ただし、Realm に保持したくないプロパティを無視することもできます。

プロパティを無視して、そのプロパティが Realm に保持されないようにするには、 @Ignoreアノテーションを使用します。

@Ignore
var age: Int = 0 // Ignored property

無視されたプロパティは、データベースに保存されないこと、クエリで使用できないこと、およびtriggerRealm 通知が されないことを除いて、管理対象プロパティと完全に同様に動作します。クラス内で管理対象プロパティと無視されているプロパティを混在させることができます。

インデックスのプロパティ

インデックスは、Realm のデータのごく一部を簡単に走査できる形式で保存する特別なデータ構造です。 インデックスは、Realm 内でより効率的なクエリの実行をサポートします。 クエリに適切なインデックスがある場合、Realm ではそのインデックスを使用して検査する必要があるドキュメントの数が制限されます。 それ以外の場合、Realm はコレクション内のすべてのドキュメントをスキャンし、クエリに一致するドキュメントを選択する必要があります。

インデックスには、特定のフィールドの値が、フィールド値の順に保存されます。 インデックス エントリの順序付けは、効率的な等価一致と範囲ベースのクエリ操作をサポートします。 インデックスにより一部のクエリは高速化されますが、書込みは若干遅くなります。 追加のストレージとメモリのオーバーヘッドが伴います。 Realm はインデックスをディスクに保存するため、Realm ファイルが大きくなります。 各インデックスエントリは 12 バイト以上です。

プロパティにインデックスを作成するには、プロパティで@Indexアノテーションを使用します。

@Index
var name: String = "" // Indexed property

次のタイプのフィールドをインデックスできます。

• String

• Byte

• Short

• Int

• Long

• Boolean

• RealmInstant

• ObjectId

• RealmUUID

同じプロパティで、標準インデックスと全文検索（FTS）インデックスを組み合わせることはできません。 プロパティに FTS インデックスを作成するには、 「 全文検索インデックス 」セクションを参照してください。

全文検索インデックス

標準インデックスに加えて、Realm はStringプロパティで全文検索（FTS）インデックスもサポートしています。 標準インデックスの有無にかかわらず string フィールドをクエリできますが、FTS インデックスを使用すると複数の単語とフレーズを検索し、その他を除外できます。

プロパティに FTS インデックスを作成するには、 @FullTextアノテーションを使用します。

@FullText
var physicalDescription: String? = null // Full-text search indexed property

FTS インデックスの次の制約に注意してください。

• FTS インデックスは、 Stringタイプのプロパティでのみ作成できます。

• 同じプロパティで FTS インデックスと標準インデックスを組み合わせることはできません。 プロパティに標準インデックスを作成するには、「インデックス プロパティ」セクションを参照してください。

全文インデックスのクエリの詳細については、 「 全文検索でフィルタリング（FTS）プロパティ 」を参照してください。