古いバージョンのドキュメントを表示しています。
最新版のドキュメントはこちらからご覧になれます

Objective‑CまたはObjective‑CとSwiftを混ぜてRealmを利用する場合は、Realm Objective‑C をご使用ください。 Realm Objective‑CとRealm Swiftを併用することはサポートしていません。

Realm はアプリケーションのモデル層を効率的に安全で迅速な方法で記述することができます。 下記の例をご覧ください:

// 通常のSwiftのクラスと同じように定義します
class Dog: Object {
  dynamic var name = ""
  dynamic var age = 0
}
class Person: Object {
  dynamic var name = ""
  dynamic var picture = NSData()
  let dogs = List<Dog>()
}

// 通常のSwiftのオブジェクトと同じように扱えます
let mydog = Dog()
mydog.name = "Rex"
println("name of dog: \(mydog.name)")

// データを永続化するのはとても簡単です
let realm = Realm()
realm.write {
  realm.add(mydog)
}

// サブスレッドで検索を実行する例です
dispatch_async(dispatch_queue_create("background", 0)) {
  realm.objects(Dog).filter("age > 8") // => Results<Dog>
}

はじめに

Realm をダウンロード ソースコードはGitHubにあります

必要条件

  • iOS 8以降、またはOS X 10.9以降、およびwatchOS。
  • Xcode 6.3以降。
  • 現在の正式版はSwift 1.2を対象にしています。Swift 2.0を利用することも可能ですが、Appleが公式にSwift 2.0をリリースするまでは手動で切り替えて利用する必要があります

インストール (Swift 1.2)

  1. こちらから最新版のRealmをダウンロードしてzipファイルを展開してください。
  2. Xcodeでプロジェクトをクリックしプロジェクト設定の“General”タブを表示します。展開したフォルダの中にあるios/またはosx/フォルダからRealmSwift.frameworkRealm.frameworkを“Embedded Frameworks”にドラッグ&ドロップしてください。このとき、Copy items if neededにチェックが入ってることを確認してからFinishをクリックしてください。
  3. ユニットテストのターゲットを選択して“Build Settings”タブの“Framework Search Paths”にRealmSwift.frameworkの親フォルダのパスを追加してください。
  4. iOSのプロジェクトで利用する場合は、アプリケーションのターゲットの“Build Phases”タブで新しく“Run Script Phase”を追加し、以下のスクリプトをそのままコピー&ペーストしてください。 bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Realm.framework/strip-frameworks.sh" この手順はアプリケーションを申請する際のiTunes Connectの不具合を回避するために必要です。
  1. CococaPods 0.37.1以降をインストールしてください
  2. Podfileにuse_frameworks!と追加します。そしてアプリケーションとテストのターゲットに対してpod 'RealmSwift'と追加してください。
  3. コマンドラインでpod installを実行してください。
  4. CocoaPodsによって作られた.xcworkspaceファイルを開いてください。
  1. Carthage 0.7.5以降をインストールしてください
  2. Cartfileにgithub "realm/realm-cocoa"と追加してください。
  3. コマンドラインでcarthage update を実行してください。
  4. iOS: RealmSwift.frameworkRealm.frameworkCarthage/Build/iOS/ディレクトリからXcodeの“General”タブにある“Linked Frameworks and Libraries”にドラッグしてください。

    OS X: RealmSwift.frameworkRealm.frameworkCarthage/Build/Mac/ディレクトリからXcodeの“General”タブにある“Embedded Binaries”にドラッグしてください。

  5. iOS: アプリケーションのターゲットの“Build Phases”の“+”ボタンをクリックし、以下のような“New Run Script Phase”を追加します。

    /usr/local/bin/carthage copy-frameworks

    このとき、“Input Files”にはフレームワークのパスを指定します。

    例:

    $(SRCROOT)/Carthage/Build/iOS/Realm.framework
    $(SRCROOT)/Carthage/Build/iOS/RealmSwift.framework

    この手順はアプリケーションを申請する際のiTunes Connectの不具合を回避するために必要です。

インストール (Swift 2.0)

Swift 2.0のサポートをswift-2.0ブランチにて提供しています。このブランチはAppleが正式にSwift 2.0をリリースするまでマージされません。

  1. RealmをGitHubのレポジトリからクローンし、swift-2.0ブランチをチェックアウトしてください。
  2. クローンしたレポジトリでsh build.sh buildを実行します。
  3. 既存のプロジェクトにインストールする場合は、古いRealmSwift.frameworkRealm.frameworkを削除してください。
  4. Xcodeでプロジェクトをクリックしプロジェクト設定の“General”タブを表示します。展開したフォルダの中にあるiosまたはosxフォルダからRealmSwift.frameworkRealm.frameworkを“Embedded Frameworks”にドラッグ&ドロップしてください。このとき、Copy items if neededにチェックが入ってることを確認してからFinishをクリックしてください。
  5. ユニットテストのターゲットを選択して“Build Settings”タブの“Framework Search Paths”にRealmSwift.frameworkの親フォルダのパスを追加してください。

Podfileのアプリケーションとテストターゲット対して下記のように追加してください: ruby # “Realm”と“RealmSwift”の両方を追加する必要があります use_frameworks! pod 'Realm', :git => 'https://github.com/realm/realm-cocoa.git', :branch => 'swift-2.0' pod 'RealmSwift', :git => 'https://github.com/realm/realm-cocoa.git', :branch => 'swift-2.0'

Swift 2.0対応のRealmをCarthageでインストールすることはできません。Realm Swiftでは事前にビルドしたバイナリを使っており、これは Carthage がビルド時にスキーマを指定する方法を提供していないことが理由です

Realm Browser

RealmBrowserは、.realmデータベースを閲覧、編集するMac アプリケーションです。

Realm Browser

また、Tools > Generate demo database と選択すると、サンプルデータを含むテスト用のRealmデータベースを作ることができます。

開発中のアプリのRealmファイルがどの場所に格納されているかは、このStackOverflowの回答が参考になります。

Realm BrowserMac App Store からダウンロードできます。

Xcode Plugin

Xcodeプラグインを使うことでRealmモデルファイルの作成が簡単になります。

このXcodeプラグインをインストールする一番簡単な方法は、Alcatrazで“RealmPlugin”と検索することです。

また、手動でインストールする場合は、最新版のRealmplugin/RealmPlugin.xcodeprojをビルドすることでインストールができます。

プラグインをインストール後にXcodeを再起動すると、Xcodeで新しくファイルを作成時(File > New > File...または⌘N)にRealm Modelという選択肢が追加されています。

API Reference

Realmで使用できるすべてのクラスとメソッドに関しては、API Referenceをご覧ください。

サンプルコード

最新のRealmexamplesフォルダにiOSとOS Xそれぞれのサンプルコードがあります。 マイグレーション、UITableViewControllerとの使い方、暗号化やコマンドラインツールなど、さまざまな機能が紹介されています。ぜひ、ご参考にしてください。

ヘルプ

  • 使い方に困ったときは、StackOverflowで#realmタグを付けて質問してください。私たちは毎日StackOverflowをチェックしています。
  • さらに複雑な問題に対する質問は、こちらの Slackチャットにて聞いてください。Slack上で毎月のオフィスアワーも開催しています。(質問は日本語で構いません)
  • バグ報告や機能リクエストについては GitHubのIssuesにご報告ください。
  • Community Newsletterに参加することで定期的にRealmに関するTipsやユースケース、ブログの更新やチュートリアルなど、Realm の最新情報が届きます。

モデル

Realmのモデルは、普通ののクラスとして定義できます。 Objectまたは既存のモデルクラスのサブクラスを作ることでアプリケーションで使うデータモデルを作成できます。

Realmのモデルオブジェクトは、他のオブジェクトとほとんど同様に機能するので、一般的なクラスと同様にメソッドやプロトコルを追加することができます。

主な制限としては、Realmモデルクラスのインスタンスは他のスレッドに渡すことができません。またプロパティのインスタンス変数に直接アクセスすることはできません。

リレーションシップとネストしたデータ構造は、対象の型のプロパティを持たせるかListを利用します。

import RealmSwift

// Dog model
class Dog: Object {
    dynamic var name = ""
    dynamic var owner: Person? // Can be optional
}

// Person model
class Person: Object {
    dynamic var name = ""
    dynamic var birthdate = NSDate(timeIntervalSince1970: 1)
    let dogs = List<Dog>()
}

Realmはアプリケーションの起動時に、定義されたすべてのモデルクラスを解析しています。まったく使われていないクラスも含めて、すべてのモデルクラスは正しく定義されていなければなりません。

詳しくはObjectをご覧ください。

対応しているデータ型

Realmでは、次に示すデータ型をサポートしています: BoolInt8Int16Int32Int64DoubleFloatStringNSDate(ミリ秒以下は切り捨てられます)NSData

1対1や、1対多のようなリレーションシップのためにList<Object>Object のサブクラスのプロパティも定義できます。

リレーションシップ(関連)

ObjectはプロパティにObjectやListを使用して、他のオブジェクトとの関連を定義することができます。

ListはArrayとよく似たAPIを持ち、添え字を使って各要素にアクセスすることもできます。

Arrayと異なる点は、ListはObjectのサブクラスのみ格納することができるということです。 詳しくはListをご覧ください。

すでにこれまでのステップでPersonモデルを定義しました。もう一つDogモデルを作成し関連を定義してみましょう。

class Dog: Object {
    dynamic var name = ""
}

1対1のリレーションシップ

モデル間で1対1や1対多の関連を持たせるには、別のObjectモデルクラスを持つプロパティを下記のように定義します:

class Dog: Object {
    ... // other property declarations
    dynamic var owner: Person?
}

このプロパティは以下のように使えます:

let jim = Person()
let rex = Dog()
rex.owner = jim

Object をプロパティとして持つとき、ネストされたプロパティには通常のオブジェクトのプロパティと同じ文法でアクセスできます。 上記の例では、rex.owner.address.countryとすると、Realmはネストしたオブジェクトを必要に応じて自動的にフェッチします。

1対多のリレーションシップ

1対多の関連を定義するにはListを持つプロパティを定義します。Listは別のObjectを含み、ミュータブルなArrayとよく似たAPIを持ちます。

PersonクラスがDogクラスを1対多の関連として持つようにするには、次のようにList<Dog>のプロパティを定義します:

class Person: Object {
    ... // other property declarations
    let dogs = List<Dog>()
}

これで、下記のようにしてList型のプロパティに対してアクセスしたり、オブジェクトを追加したりできるようになりました:

let someDogs = Realm().objects(Dog).filter("name contains 'Fido'")
jim.dogs.extend(someDogs)
jim.dogs.append(rex)

逆方向の関連

逆方向の関連(バックリンクとも言われます)を設定することで、関連元のオブジェクトを特定のプロパティを使って取得することができます。 例えばDogクラスのオブジェクトからObject().linkingObjects(_:forProperty:)を使うとそのオブジェクトに関連する特定のモデルのオブジェクトをすべて取得することができます。この方法を使うと、Dogクラスにownersという読み取り専用のプロパティを追加するというパターンをシンプルに実装できます:

class Dog: Object {
    dynamic var name = ""
    dynamic var age = 0
    var owners: [Person] {
        // Realm doesn't persist this property because it only has a getter defined
        // Define "owners" as the inverse relationship to Person.dogs
        return linkingObjects(Person.self, forProperty: "dogs")
    }
}

プロパティ属性

Realmモデルのプロパティは専用のアクセスメソッドに置き換えられるため、var dynamic属性となければなりません。

このルールには一つだけ例外があり、Listプロパティはdynamicとして定義できません。なぜなら動的ディスパッチを利用したときに使われるObjective‑CランタイムではGenericsを表現できないため、dynamicは使用できません。

インデックス付きプロパティ

クラスメソッドのObject.indexedProperties()をオーバーライドすることで、インデックスに追加するプロパティを指定できます:

class Book: Object {
  dynamic var price = 0
  dynamic var title = ""

  override static func indexedProperties() -> [String] {
    return ["title"]
  }
}

プライマリキー

クラスメソッドのObject.primaryKey()をオーバーライドすることで、そのモデルのプライマリキーを指定できます。プライマリキーを使うと、オブジェクトを効率的に検索・更新することができ、一意性を保つこともできます。

class Person: Object {
  dynamic var id = 0
  dynamic var name = ""

  override static func primaryKey() -> String? {
    return "id"
  }
}

保存しないプロパティ

クラスメソッドのObject.ignoredProperties()をオーバーライドすることで、Realmに保存しないプロパティを指定することができます。

保存しないプロパティについてはRealmはプロパティの操作に介入しません。つまり普通のプロパティとしてインスタンス変数に値は格納され、getter/setterメソッドをオーバーライドすることも自由にできます。

class Person: Object {
  dynamic var tmpID = 0
  var name: String { // 計算済みプロパティは自動的に保存しないプロパティとして扱われます
    return "\(firstName) \(lastName)"
  }
  dynamic var firstName = ""
  dynamic var lastName = ""

  override static func ignoredProperties() -> [String] {
    return ["tmpID"]
  }
}

書き込み

Realmへのオブジェクトの追加、変更、削除は、トランザクションの内部で行う必要があります。

Realmモデルクラスは、通常のオブジェクトと同じようにインスタンス化し、使うことができます。

スレッド間でデータを共有したり、アプリキーションの再起動時に以前のデータを利用するには、Realmにデータを保存しなければなりません。これらの操作は、トランザクションの中で行う必要があります。

オブジェクトの生成

Objectのサブクラスとして定義したモデルをインスタンス化して、新しいオブジェクトとしてRealmに保存します。 次のような簡単なモデルを考えます:

class Dog: Object {
    dynamic var name = ""
    dynamic var age = 0
}

オブジェクトを作成するにはいくつかの方法があります:

// (1) Dogクラスのオブジェクトを作成し、プロパティに値をセットする
var myDog = Dog()
myDog.name = "Rex"
myDog.age = 10

// (2) Dictionaryの値を使ってDogクラスのオブジェクトを作成する
let myOtherDog = Dog(value: ["name" : "Pluto", "age": 3])

// (3) Arrayの値を使ってDogクラスのオブジェクトを作成する
let myThirdDog = Dog(value: ["Fido", 5])
  1. Objective‑Cにおけるalloc-initや、Swiftにおける指定イニシャライザを使うのはオブジェクトを作るもっともわかりやすい方法です。 すべてのプロパティの値を、オブジェクトがRealmに追加される前にセットする必要があるので注意してください。
  2. 適切なキーと値の組み合わせを持つディクショナリからオブジェクトを生成することもできます。
  3. 最後の方法は配列からオブジェクトを作る方法です。配列の各要素は、生成するモデルのプロパティと同じ順序で並んでいる必要があります。

ネストしたオブジェクト

Objectのサブクラス、またはListのプロパティを持つモデルオブジェクトは、ネストした配列やディクショナリを使って再帰的にオブジェクトをセットすることができます。 そのとき、配列またはディクショナリを使って、下記のように簡単にそれぞれのオブジェクトを生成することができます:

// すでに存在するオブジェクトを渡す代わりに...
let aPerson = Person(value: ["Jane", 30, [aDog, anotherDog]])

// ...配列を使ってその場で値を渡すことができます
let aPerson = Person(value: ["Jane", 30, [["Buster", 5], ["Buddy", @6]]])

この方法は、ネストした配列やディクショナリがどのような組み合わせであっても動作します。 この場合のListはObjectのオブジェクトだけを格納できることに注意してください。Stringのような他の基本的な型は格納できません。

オブジェクトの追加

オブジェクトをRealmに追加するには次のようにします:

// オブジェクトを作成する
let author = Person()
author.name = "David Foster Wallace"

// デフォルトRealmを取得する
let realm = Realm()
// Realmの取得はスレッドごとに1度だけ必要になります

// トランザクションを開始して、オブジェクトをRealmに追加する
realm.write {
  realm.add(author)
}

オブジェクトをRealmに追加した後も、続けて使用することができます。そして、オブジェクトに対するすべての変更が保存されます。(オブジェクトを変更は、トランザクションの中で行わなければなりません)。別のスレッドで、同じRealmに保存されているオブジェクトに変更があった場合は、トランザクションが完了した時点ですべての変更が適用されます。

同時に発生した書き込み処理は、互いの書き込み処理をブロックします。 これは類似の他のデータベースでも同様で、よく使われるベストプラクティスとして、書き込み処理を別のスレッドに分けることを推奨します。

RealmはMVCCアーキテクチャーを採用しているので、書き込み処理の最中でも読み込み処理をブロックすることはありません。同時に複数のスレッドから書き込みをするのでなければ、大きな単位でトランザクションを使いましょう。細かいトランザクションを使うよりこの特性を活かすことができます。

詳しくは、RealmObjectをご覧ください。

オブジェクトの更新

オブジェクトを更新するには、トランザクションの中でプロパティをセットします。

// トランザクションを開始して、オブジェクトを更新する
realm.write {
  author.name = "Thomas Pynchon"
}

プライマリキーを使ってオブジェクトを更新する

モデルにプライマリキーを指定しているなら、Realm().add(_:update:)を使って、オブジェクトがすでに存在する場合は更新、存在しない場合は新しく追加というように、追加または更新を一度に行うことができます。

// 以前に保存したものと同じプライマリキーを持つBookオブジェクトを作成する
let cheeseBook = Book()
cheeseBook.title = "Cheese recipes"
cheeseBook.price = 9000
cheeseBook.id = 1

// id = 1のBookオブジェクトの値を更新する
realm.write {
  realm.add(cheeseBook, update: true)
}

ここでid = 1のBookオブジェクトがRealmに保存されていない場合は、新しいBookオブジェクトが追加されます。

オブジェクトのプロパティを部分的に更新するには、下記のように更新したいプロパティの値とプライマリキーだけが含まれたディクショナリを渡します。

// プライマリキーが`1`のBookオブジェクトがすでにあるとき、
realm.write {
  realm.create(Book.self, value: ["id": 1, "price": 9000.0], update: true)
  // タイトルはそのままで値段のプロパティだけを更新することができます。
}

キー値コーディング

Object、Result、Listクラスはいずれも キー値コーディング(KVC)に対応しています。 実行時にアップデートするプロパティが決定する場合に使用すると便利です。

また、キー値コーディングをコレクションオブジェクトに対して使用すると、多数のオブジェクトをループしてインスタンス化することが避けられるので、一括の更新を非常に効率的に行うことができます。

let persons = Realm().objects(Person)
Realm().write {
  persons.first?.setValue(true, forKeyPath: "isFirst")
  // すべてのPersonオブジェクトのプロパティを"Earth"に更新します
  persons.setValue("Earth", forKeyPath: "planet")
}

オブジェクトの削除

オブジェクトを削除するには、トランザクションの中で削除したいオブジェクトをRealm().delete(_:)メソッドに渡します。

let cheeseBook = ... // 保存されているBookオブジェクトを取得して、

// トランザクションを開始してオブジェクトを削除します
realm.write {
  realm.delete(cheeseBook)
}

下記のように、Realmに保存されてるオブジェクトをすべて削除することもできます。 ディスクスペースを効率的に再利用するために、Realmファイルのサイズはそのまま維持されることに注意してください。

// Realmに保存されているすべてのオブジェクトを削除します。
realm.write {
  realm.deleteAll()
}

クエリ

クエリを実行するとObjectを含んだResultsオブジェクトが結果として返ってきます。 Resultsは、Arrayに非常によく似たようなAPIを持ち、添え字を使ってオブジェクトにアクセスすることもできます。 Arrayと違うのは、Resultsは、Objectのサブクラスのみを含むことができるという点です。

Realmにおけるすべてのクエリとプロパティへのアクセスを含むは遅延ロードされます。プロパティにアクセスした時に、初めてデータが読み込まれます。

クエリを実行したときに返ってくる結果は、コピーではありません。トランザクションを使ってそのデータを変更した場合、ディスクのデータを直接変更したことになります。 同様に、Resultsに含まれるObjectsから、関連のオブジェクトを次々とたどりながら取得することもできます。

型を使ったオブジェクトの取得

もっとも基本的なオブジェクトを取得する方法はRealm().objects(_:)メソッドを使うことです。 このメソッドは、デフォルトRealmに保存されているObjectオブジェクトのうち、指定したクラスのすべてのインスタンスを含むResultsを返します。

// Realmに対してクエリを実行します
let dogs = Realm(path: "pets.realm").objects(Dog)

検索条件を指定する

普段からNSPredicateの扱いに慣れているなら、Realmにおけるオブジェクトの検索方法を知っているも同然です。

Objects、Realm、List、Resultsはすべて特定のObjectオブジェクトをNSPredicateを使って検索するためのメソッドをサポートしています。 NSArrayを検索するときと同じように、直接NSPredicateオブジェクトを渡す、条件部分だけを文字列で渡す、などの方法が利用できます。

下記の例は、Results().filter(_:...)メソッドを使って、Dogクラスのcolor = "tan"かつ、nameの値がBから始まるという条件に合致するDog クラスのインスタンスをデフォルトRealmから取得します。

let realm = Realm()
// 文字列で検索条件を指定します
var tanDogs = realm.objects(Dog).filter("color = 'tan' AND name BEGINSWITH 'B'")

// NSPredicateを使って検索条件を指定します
let predicate = NSPredicate(format: "color = %@ AND name BEGINSWITH %@", "tan", "B")
tanDogs = realm.objects(Dog).filter(predicate)

詳しくは、AppleのPredicates Programming GuideやRealmが提供しているNSPredicateチートシートをご覧ください。Realmでは多数のNSPredicate構文をサポートしています。

  • 比較演算子はプロパティ名と定数に対して使用できます。左辺と右辺のうち少なくとも一方はプロパティ名でなければなりません。
  • 比較演算子として==<=<>=>!=BETWEENがint、long、long long、float、double、NSDateに対して使用できます。

    (例)age == 45

  • 同一性の比較==!=

    (例)Results<Employee>().filter("company == %@", company)

  • bool型のプロパティに対しては比較演算子として==!=が使用できます。
  • NSStringとNSData型のプロパティに対しては、==!=BEGINSWITHCONTAINSENDSWITH演算子が使用できます。

    (例)name CONTAINS ‘Ja’

  • 文字列に対して大文字小文字を無視して比較するには、name CONTAINS[c] ‘Ja’のようにします。大文字小文字として扱われるのはアルファベットの”A-Z”および”a-z”であることに注意してください。
  • 論理演算子として“AND”“OR”“NOT”が使用できます。

    (例)name BEGINSWITH ‘J’ AND age >= 32

  • いずれかの条件と一致するかどうか: IN

    (例)name IN {‘Lisa’, ‘Spike’, ‘Hachi’}

  • nilとの比較: ==, !=

    (例)Results<Company>().filter("ceo == nil")

nilとの比較は関連に対してのみ機能します。この例ではceoプロパティがCompanyの関連として定義されています。

  • いずれかの要素が条件と一致するかどうか: ANY

    (例)ANY student.age < 21

  • 集計関数はサポートしていませんが、BETWEEN演算子は使えます。

    (例)Results<Person>.filter("age BETWEEN %@", [42, 43]]).

詳しくは、Results().filter(_:...)をご覧ください。

並べ替え

Resultsは、1つあるいは複数のプロパティの値を使って並べ替えることができます。 下記は、先ほどのDogオブジェクトを検索した結果を、nameプロパティのアルファベット順で並べ替える例です。

// color = 'tan'かつ名前が"B"から始まるDogオブジェクトを、名前の昇順で取得します
let sortedDogs = Realm().objects(Dog).filter("color = 'tan' AND name BEGINSWITH 'B'").sorted("name")

詳しくは、Results().filter(_:...) and Results().sorted(_:ascending:)をご覧ください。

クエリの連鎖

他のデータベースと比較してRealmを使う利点として、非常に小さなオーバーヘッドで、連鎖したクエリを実行できる点が挙げられます。 例えば、color = tanかつ、nameBからはじまるDogオブジェクトを検索したい場合、以下のように連鎖的にメソッドを呼び出すことができます。

let tanDogs = Realm().objects(Dog).filter("color = 'tan'")
let tanDogsWithBNames = tanDogs.filter("name BEGINSWITH 'B'")

Realmについて

デフォルトRealm

すでにお気づきだと思いますが、これまでRealm()メソッドを呼ぶことで、変数realmを初期化してきました。 このメソッドは、各アプリケーションのDocumentsフォルダに作られた”default.realm”ファイルのRLMRealmオブジェクトを返します。

Realm.defaultPathメソッドを使って、デフォルトRealmの場所と名前を変更できます。この機能はユニットテストやiOS 8以降で利用可能なShared Containerで役立ちます。

デフォルト以外のRealm

場合によっては、それぞれ別の場所に保存される複数のRealmが必要なことがあります。例えば、事前に用意した組み込みデータを、読み込み専用のRealmとして利用するなどです。詳しくは、Realm(path:)Realm(path:encryptionKey:error:)をご覧ください。

Realmを初期化するときに指定するファイルパスは、書き込み可能な場所を指している必要があります。書き込み可能なもっとも普通の保存場所はiOSでは”Documents”フォルダ、OS Xでは”Application Support”フォルダです。AppleのiOS Data Storage Guidelinesによると、<Application_Home>/Library/Cachesフォルダに保存することが推奨されています。

In-Memory Realm

通常は、Realmはディスクにデータを保存しますが、Realm(inMemoryIdentifier:)を利用することで、データをメモリ上のみに保持するRealmオブジェクトを作ることができます。

let realm = Realm(inMemoryIdentifier: "MyInMemoryRealm")

In-memory Realmでは、データをディスクに保存しないのでアプリケーションを終了するとデータは消えてしまいます。それ以外のクエリ、リレーションシップ、スレッドセーフなどの機能はすべて通常のRealmと同様に利用することができます。 ディスクへの読み書きによるオーバーヘッドの無い、柔軟なデータアクセス機能が必要なときに有効です。

In-memory Realmは一時ディレクトリにファイルを書き込むことがあります。 (例)プロセス間通信のために名前付きパイプをセットアップする場合やスワップのためです。

注意: スコープを外れ、In-Memory Realmインスタンスへの参照がすべて無くなると、そのRealm内に保存されている、すべてのデータは解放されます。アプリの起動中は、In-MemoryなRealmインスタンスへの強参照を常に保持しておく必要があります。

複数スレッド間でRealmを使う

同じRealmファイルを複数のスレッドから使う場合は、各スレッドでRealmインスタンスをそれぞれ生成する必要があります。 Realmファイルへのパスさえ同じであれば、Realmインスタンスはディスク上で同じものを指します。

複数のスレッド間で、Realmインスタンスを共有することはサポートされていません。 同じRealmファイルを指すRealmのインスタンスのrealdOnlyプロパティは同じでなければなりません。(すべてreadwriteまたはすべてreadonlyである必要があります)

Realmは、大量のデータを追加するときには、一つのトランザクション中に複数の一括更新をすることにより、非常に効率よく動作します。

また、メインスレッドをブロックすることを避けるためGrand Central Dispatchを使い、トランザクションをバックグラウンドで実行することができます。

RLMRealmオブジェクトはスレッドセーフではないため、複数のスレッド間で共有することができません。それぞれのスレッド/dispatch_queueでRLMRealmオブジェクトを生成する必要があります。 下記は、バックグランド処理で100万個のオブジェクトを追加する例です。

dispatch_async(queue) {
  autoreleasepool {
    // Get realm and table instances for this thread
    let realm = Realm()

    // Break up the writing blocks into smaller portions
    // by starting a new transaction
    for idx1 in 0..<1000 {
      realm.beginWrite()

      // Add row via dictionary. Property order is ignored.
      for idx2 in 0..<1000 {
        realm.create(Person.self, value: [
          "name": "\(idx1)",
          "birthdate": NSDate(timeIntervalSince1970: idx2)
        ])
      }

      // Commit the write transaction
      // to make this data available to other threads
      realm.commitWrite()
    }
  }
}

Realm間のオブジェクトのコピー

Realmに保存されたオブジェクトを他のRealmへコピーするには、Realm().create(_:value:update:)メソッドにコピー元のオブジェクトを引数として渡します。 例えば、Realm().create(MyObjectSubclass.self, value: originalObjectInstance)のように使います。

Realmファイルの探し方

アプリケーション内のRealmファイルの場所がわからないときは、このStackOverflowの回答を参考にしてください。

初期データとしてRealmをアプリケーションにバンドルする

初回起動を素早くするためなどに、アプリケーションに初期データを組み込むことはよくあります。 下記はRealmを初期データとしてバンドルする例です:

  1. はじめに、初期データの入ったRealmを用意します。リリースする時と同じデータモデルを定義し、データを入れます。Realmファイルは、クロスプラットフォームで利用可能ですので、データの作成はOS Xや、iOSシミュレータ上で行っても問題ありません。(JSONImportの例をご覧ください)
  2. 初期データを入れるコードの終わりに、Realmファイルをコピーをするメソッドを使用し、Realm ファイルのサイズを最適化してください(Realm().writeCopyToPath(_:encryptionKey:))をご覧ください。)。このメソッドを使ってRealmファイルをコピーすると、Realmのファイルサイズを小さくでき、最終的にアプリケーションのサイズが軽くなるのでユーザが速くダウンロードできます。
  3. コピーされたRealmファイルを、Xcodeのプロジェクトナビゲーターにドラッグ&ドロップします。
  4. プロジェクト設定のBuild Phaseタブで、”Copy Bundle Resources”にRealmファイルを追加します。
  5. この時点で、追加したRealmファイルにアプリケーションからアクセスできるようになります。NSBundle.mainBundle().pathForResource(_:ofType:)メソッドを使って、ファイルパスを取得します。
  6. こうして、Realm(path:readOnly:encryptionKey:error:)メソッドで読み込み専用のRealmオブジェクトを作ることもできますし、その初期データを含んだRealmに書き込みたい場合は、NSFileManager.defaultManager().copyItemAtPath(_:toPath:error:)メソッドを使って、アプリケーションのDocumentsディレクトリにRealmファイルをコピーしてから、Realm(path:)を使って、Realmオブジェクトを作ります。

Realmファイルを初期データとして組み込む例として、マイグレーションのサンプルコードを参考にしてください。

通知

他のスレッドでトランザクションが完了するたびに、残りのRealmインスタンスに対して通知が送られます。 通知を受け取るには、下記のようにコールバックをブロックとして登録します。

// Observe Realm Notifications
let token = realm.addNotificationBlock { notification, realm in
    viewController.updateUI()
}

戻り値の“Notificaiton Token”が保持されている限り、通知は有効です。 更新の通知を登録したクラスの“Notificaiton Token”の強参照を保持しておく必要があります。 “Notificaiton Token”が解放されると、登録された通知は自動的に解除されます。

詳しくは、Realm().addNotificationBlock(_:) and Realm().removeNotification(_:)をご覧ください。

マイグレーション

データベースを使ってる場合、時間が経つにつれ、データモデルは変更されていくものです。 Realmでのデータモデルは、シンプルなインターフェースで定義されてますので、インターフェースに変更を加えるだけで、簡単にデータモデルを変えられます。 例えば、以下のPersonモデルについて考えてみてください。

class Person: Object {
    dynamic var firstName = ""
    dynamic var lastName = ""
    dynamic var age = 0
}

ここで、firstNamelastNameを一つにして、fullNameプロパティが必要になったとします。 そこで以下のような単純な変更をインターフェースに加えることにします。

class Person: Object {
    dynamic var fullName = ""
    dynamic var age = 0
}

ここでのポイントは、もし以前に前のデータモデルでのデータが保存されている場合、新しく定義し直したデータモデルとディスクに保存されている古いデータモデルとの間に不整合が生じてしまいます。 マイグレーションを実行せずにRealmを使おうとすると、例外が発生します。

マイグレーションを実行する

マイグレーション処理は、setSchemaVersion(_:_:_:)メソッドの引数として渡すブロックの中に定義します。

このとき、スキーマのバージョンごとにマイグレーション処理の分岐を書く必要があります。

マイグレーションブロックの中には、すべての古いデータモデルから新しいデータモデルへ移行させるためのロジックが書かれていなければなりません。 setSchemaVersion(_:_:_:)が呼ばれた後に、自動的にマイグレーションブロックが実行されます。

たとえば、上記のPersonクラスのマイグレーションについて考えてみましょう。 最低限必要なマイグレーション処理は、以下のようなものです:

// application(application:didFinishLaunchingWithOptions:)の中に書きます

// setSchemaVersionで1を設定します。スキーマバージョンは自分で任意の値を設定します。
// スキーマバージョンは必ず以前(oldSchemaVersion)より大きくなければなりません。そうでなければ、例外が発生します。
setSchemaVersion(1, Realm.defaultPath, { migration, oldSchemaVersion in
  // We haven’t migrated anything yet, so oldSchemaVersion == 0
  if oldSchemaVersion < 1 {
    // 何もする必要はありません!
    // Realmは自動的に新しく追加されたプロパティと、削除されたプロパティを認識します。
    // そしてディスク上のスキーマを自動的にアップデートします。
  }
})
// `setSchemaVersion(_:_:_:)`を呼び出してから、古いスキーマバージョンのRealmを開こうとすると
// Realmは自動的にマイグレーションを実行し、成功したらRealmを開きます。
// i.e. Realm()

Realmによって自動的にスキーマが更新されることを示すために、ここでは空のブロックでマイグレーションを実行しています。

これは最低限のマイグレーションですが、おそらく何かデータを新しいプロパティ(ここではfullName)に入れるために、ここに処理を記述すると思います。

マイグレーションブロックの中では、特定の型の列挙を行うためにMigration().enumerate(_:_:)を呼ぶことができます。

下記では、必要なマイグレーションロジックを適用しています。 変数oldObjectを使って既にあるデータにアクセスし、新しく更新するデータには変数newObjectを使ってアクセスしています。

// application(application:didFinishLaunchingWithOptions:)の中に書きます

setSchemaVersion(1, Realm.defaultPath, { migration, oldSchemaVersion in
  if oldSchemaVersion < 1 {
    // enumerate(_:_:)メソッドで保存されているすべての
    // Personオブジェクトを列挙します
    migration.enumerate(Person.className()) { oldObject, newObject in
      // firstNameとlastNameをfullNameプロパティに結合します
      let firstName = oldObject!["firstName"] as! String
      let lastName = oldObject!["lastName"] as! String
      newObject!["fullName"] = "\(firstName) \(lastName)"
    }
  }
})

一度マイグレーション処理が適用されると、その後は通常どおりにRealmとRealmオブジェクトが使用できます。

バージョンの追加方法

Personクラスについて、以前に異なる2つのデータモデルをとっていた場合を考えてみましょう:

// v0
class Person: Object {
    dynamic var firstName = ""
    dynamic var firstName = ""
    dynamic var age = 0
}

// v1
class Person: Object {
    dynamic var fullName = "" // new property
    dynamic var age = 0
}

// v2
class Person: Object {
    dynamic var fullName = ""
    dynamic var email = "" // new property
    dynamic var age = 0
}

ここでのマイグレーションブロックの中に書くロジックは、下記のようになります。

setSchemaVersion(2, Realm.defaultPath, { migration, oldSchemaVersion in
  // enumerate(_:_:)メソッドで保存されているすべての
  // Personオブジェクトを列挙します
  migration.enumerate(Person.className()) { oldObject, newObject in
    // スキーマバージョンが0のときだけ、'fullName'プロパティを追加します
    if oldSchemaVersion < 1 {
      let firstName = oldObject!["firstName"] as! String
      let lastName = oldObject!["lastName"] as! String
      newObject!["fullName"] = "\(firstName) \(lastName)"
    }

    // スキーマバージョンが0または1のとき、'email'プロパティを追加します
    if oldSchemaVersion < 2 {
        newObject!["email"] = ""
    }
  }
})

// `setSchemaVersion(_:_:_:)`を呼び出してから、古いスキーマバージョンのRealmを開こうとすると
// Realmは自動的にマイグレーションを実行し、成功したらRealmを開きます。
let realm = Realm()

完全なマイグレーション処理のコードについては、マイグレーション処理のサンプルコードをご覧ください。

複数世代のマイグレーション

二人のユーザーがいると考えてください。JPとTimです。

JPはよくアプリケーションをアップデートします。しかしTimはいくつかのバージョンをスキップすることがあります。

JPはすべてのバージョンをインストールしてることになるので、段階的にすべてのスキーマのアップデートを適用していることになります。V0からV1、V1からV2のようにスキーマはアップデートしていきます。

対照的に、Timの場合はV0からV2と突然バージョンがジャンプする可能性があります。

マイグレーションブロックは、たとえどのバージョンのスキーマから始めたとしても、ネストしていないif (oldSchemaVersion < X)で必要なアップデート処理が行われるように構成しなければなりません。

また、他のケースで、ユーザーがバージョンをスキップをしてアプリケーションをアップデートしたとします。もしあなたが”email”プロパティを一度バージョン2で削除し バージョン3で再び追加したとします。

そしてユーザーがバージョン1からバージョン3へと、バージョン2をスキップしてアップデートした場合、Realmはコードのスキーマ定義とディスクのスキーマに違いは無いので、”email”プロパティが一度消されたということを自動的に判別することはできません。これは、Tim の Person クラスで起こりうることで、バージョン1時点のプロパティの値をバージョン3バージョンのプロパティの値として保持される可能性があります。

このことは、内部的に”email”プロパティの表現形式を変えるなどしていなければ、問題にならないかもしれません(ISO形式のメールアドレスから独自の形式にするなどです。)。

しかし、問題を避けるためif (oldSchemaVersion < 3)の中で、データセットがバージョン3バージョンのものであることを保証するために、一度nilを代入することを推奨します。

暗号化

Realmの暗号化APIはiOS、OS XおよびWatchKitで利用できます。ただし、watchOSでは利用できません

なぜなら、暗号化の仕組みとして使用している<mach/mach.h><mach/exc.h>のAPIが__WATCHOS_PROHIBITEDとなっているためwatchOSでは利用できないからです。

Appleに不具合として報告しています: rdar://22063654

Please take note of the Export Compliance section of our LICENSE, as it places restrictions against the usage of Realm if you are located in countries with an export restriction or embargo from the United States.

iOSでは、標準のNSFileProtectionAPIを使用することで、ほんのわずかのオーバーヘッドでRealmファイルを暗号化することができます。ただし、この方法でファイルを保護する場合、2つの注意点があります。

1) 他のプラットフォームで利用できなくなります。(NSFileProtectionはiOSでのみ有効な機能です)

2) パスコードロックを使用していないデバイスでは、Realmファイルは暗号化されません。

これらの制限を避けるために(もしくはOS Xアプリケーションで利用する場合は)、Realmの提供する暗号化機能を使用することを推奨します。

Realmには64バイトの暗号化キーを用いてAES-256とSHA-2暗号化方式でデータベースファイルを暗号化する機能があります。

// ランダムな暗号化キーを生成します
let key = NSMutableData(length: 64)!
SecRandomCopyBytes(kSecRandomDefault, UInt(key.length),
    UnsafeMutablePointer<UInt8>(key.mutableBytes))

// 暗号化されたRealmファイルを開きます
var error: NSError?
let realm = Realm(path: Realm.defaultPath,
    readOnly: false, encryptionKey: key, readOnly: false, error: &error)
if realm == nil {
    // If the encryption key is wrong, `error` will say that it's an invalid database
    println("Error opening realm: \(error)")
    return
}

// 使い方は暗号化なしのRealmと変わりません
let dogs = realm.objects(Dog).filter("name contains 'Fido'")

この機能を使用すると、ディスクに保存されるデータが透過的にAES-256で必要に応じて暗号/複合化され、SHA-2 HMACによって検証されます。

暗号化したRealmファイルのインスタンスを作成するには同じ暗号化キーが必要になります。

インスンタス作成後は、メモリ上に暗号化キーを保持され、指定したパス先にある Realm ファイルへアクセスは、自動的に暗号化キーが使用されるようになります。

例えば、デフォルトRealmに暗号化キーを指定するコードは下記のようになります。

// ランダムな暗号化キーを生成します
let key = NSMutableData(length: 64)!
SecRandomCopyBytes(kSecRandomDefault, UInt(key.length),
    UnsafeMutablePointer<UInt8>(key.mutableBytes))

// デフォルトRealmに暗号化キーを設定します
Realm.setEncryptionKey(key, forPath: Realm.defaultPath)

// 使い方は暗号化なしのRealmと変わりません
let dogs = realm.objects(Dog).filter("name contains 'Fido'")

詳しくは暗号化のサンプルコードをご覧ください。暗号化キーの作り方、キーチェーンへの安全な保存方法、Realmへのキーの渡し方などが理解できます。

暗号化したRealmを使う場合、わずかにパフォーマンスが下がり(10%未満)ます。

サードパーティのクラッシュレポートツール(CrashlyticsやPLCrashReporterなど)は、暗号化したRealmを初めて開く前に登録する必要があります。そうしないと、アプリが実際にクラッシュしていないにもかかわらず、誤ったクラッシュレポートを受け取る可能性があります。

デバッグ

Realm Swift APIを使っている場合、アプリケーションのデバッグはLLDBコンソールを使う必要があります。

注意することとして、Realmの変数を調べるLLDBスクリプトをXcode Plugin経由でインストールしていたとしても、Swiftの場合これは正しく機能せず実際と異なるデータが表示されます。代わりにLLDBコンソールでpoコマンドを使ってRealmに保存されたデータを調べてください。

暗号化されたRealmをデバッグする

暗号化されたRealmを使用しているプロセスにデバッガのセッションを接続することは現在サポートされていません

REALM_DISABLE_ENCRYPTION=YES環境変数を設定することでこの問題を避けることができます。コードを変更せずにデバッグを可能にするために、この環境変数は強制的に暗号化APIを無効にします。

当然ながら、セキュリティを保つためにすでに暗号化済みのRealmデータベースについては有効になりません(File::AccessErrorの例外が発生します)。 新しくRealmファイルを作る場合に有効です。

テスト

デフォルトRealmの保存先を変更する

Realmをテストするときの最も簡単な方法は、デフォルトRealmを使用することです。

テストコードを実行する前に、Realm.defaultPath = "/path/to/file.realm"を使ってテスト用のデフォルトRealmのパスを変更し、アプリケーションで使用するデータを上書きすることを避けられます。

外部からRealmインスタンスを渡す

別の方法としては、すべてのRealmに関係するコードのメソッドを、Realmインスタンスを受け取るようにします。アプリケーションの実行時とテスト実行時で、異なる Realm インスタンスを渡すようにします。

例えば、以下のテストコードは、JSON APIからユーザー情報を取得し、正しくデータが保存されているかをテストしています。

// Application Code
static func updateUserFromServer() {
  let url = NSURL(string: "http://myapi.example.com/user")
  NSURLSession.sharedSession().dataTaskWithURL(url) { data, _, _ in
    self.createOrUpdateUserInRealm(Realm(), withData: data)
  }
}

public static func createOrUpdateUserInRealm(realm: Realm, withData data: NSData) {
  let object: [String: String] =
          NSJSONSerialization.JSONObjectWithData(data, options: nil, error: nil)
  realm.write {
    realm.create(object, update: true)
  }
}

// Test Code
func testThatUserIsUpdatedFromServer() {
  let testRealm = Realm(path: kTestRealmPath)
  let jsonString: NSString = "{\"email\": \"[email protected]\"}"
  let jsonData = jsonString.dataUsingEncoding(NSUTF8StringEncoding)
  ClassBeingTested.createOrUpdateUserInRealm(testRealm, withData: jsonData)
  let expectedUser = User()
  expectedUser.email = "[email protected]"
  XCTAssertEqual(realm.objects(User).first!,
                 expectedUser,
                 "User was not properly updated from server.")
}

Realm.frameworkとテストターゲットをリンクしない

ダイナミックフレームワークとして Realm を使用している場合、ユニットテストのターゲットがRealmフレームワークを見つけられるようにしておく必要があります。 そのためには、ユニットテストの”Framework Search Paths”にRealmSwift.frameworkの親フォルダの場所を追加します。

テスト実行時に"Object type '...' not persisted in Realm"というエラーが出る場合、RealmSwift.frameworkがテストターゲットにリンクされていることが原因です。 問題を解決するために、テストターゲットからRealmのリンクを解除してください。

また、モデルクラスのファイルはアプリケーションのターゲットか、フレームワークのターゲットのどちらか一方にのみリンクされている必要があります。 そうなってなければ、テスト時にモデルクラスに重複が生じて問題が発生する可能性があります。 詳しくはこちらのIssueをご覧下さい。

テストするコードは、全てテストターゲットからアクセス可能である必要があります。(Swiftではpublic修飾子を使います)

テストごとにデータをリセットする

一般的に、ユニットテストはそれぞれ独立しているほうが扱いやすいです。そのため、Realmファイルをテストごとにディスクから削除し、新しく作成し直すことを推奨します。以下のコードでは、XCTest での setUpメソッドとtearDownメソッドの中でデータの削除と再生成を行っています:

// Helpers

let realmPathForTesting = ""

func deleteRealmFilesAtPath(path: String) {
  let fileManager = NSFileManager.defaultManager()
  fileManager.removeItemAtPath(path, error: nil)
  let lockPath = path + ".lock"
  fileManager.removeItemAtPath(lockPath, error: nil)
}

// In XCTestCase subclass:

override func setUp() {
  super.setUp()
  deleteRealmFilesAtPath(realmPathForTesting)
  Realm.defaultPath = realmPathForTesting
}

override func tearDown() {
  super.tearDown()
  deleteRealmFilesAtPath(realmPathForTesting)
}

REST API

Realmは簡単にREST APIと組み合わせて使うことができます。そして、ローカルにデータを保存しない場合に比べて下記のような利点があります。

  • データをRealmにキャッシュすることでオフラインでもアプリケーションが使用できるようになります。
  • すべてのデータをデータをRealmキャッシュすると、ローカルでクエリを実行して、データを高速に検索できるのでユーザーエクスペリエンスが向上します。
  • サーバーからデータをダウンロードする処理を、変更のあったものだけに減らすことができます。

ベストプラクティス

  1. 非同期通信 — 通信処理や時間のかかる処理は、UIを長時間ブロックしないように、バックグラウンドで行うべきです。同じように、Realmに大量のデータを追加/変更する場合も、バックグラウンドで行われるべきです。バックグラウンドで行われた変更に応答するには、Notifications 機能を使用します。
  2. 大量のデータをキャッシュする - 可能になったときに、事前にデータを取得してRealmに保存することを推奨します。そうすると、ローカルのデータに対して検索することができます。
  3. 追加と更新 - プライマリキーのようなユニークな識別子をデータセットが持っている場合、Realm().add(_:update:)を使うことで、REST APIから受け取ったレスポンスで、より簡単にデータを追加/更新することができます。このメソッドは、更新が必要かどうか、すでに存在するデータかどうかなどを自動的にチェックしてくれます。

サンプルコード

下記は、単純なRealmとREST APIを連携させる例です。この例では、Foursquare APIからJSONデータを取得して、Default Realmにオブジェクトとして保存します。

似たような例として、この ビデオも参考になります。

まず始めに、デフォルトRealmのインスタンスを生成します。そして、APIからデータを取得します。 単純なコードにするためにここでは、NSData(contentsOfURL:)を使っています。

// Call the API
let url = NSURL(string: "https://api.foursquare.com/v2/venues/search?near=San%20Francisco&limit=50")!
let response = NSData(contentsOfURL: url)!

// De-serialize the response to JSON
let json = (NSJSONSerialization.JSONObjectWithData(response,
    options: NSJSONReadingOptions(0),
      error: nil) as! NSDictionary)["response"]

The response contains a JSON array of venues similar to this:

{
  "venues": [
    {
      "id": "4c82f252d92ea09323185072",
      "name": "Golden Gate Park",
      "contact": {
        "phone": "4152522590"
      },
      "location": {
        "lat": 37.773835608329,
        "lng": -122.41962432861,
        "postalCode": "94103",
        "cc": "US",
        "state": "California",
        "country": "United States"
      }
    }
  ]
}

JSONをRealmにインポートするには、いくつか方法があります。Objectの対応するプロパティにJSONの値をマッピングするカスタムメソッドを作ることでも実現できます。

このサンプルの注目すべき点は、そのようにNSDicionaryを操作するのではなく、自動的にObjectにJSONをマッピングしているところです。

この仕組みを正しく動作させるためには、Objectのプロパティの構造と、JSONのキーを完全に一致させておく必要があります。

もし、それらが違っている場合、そのプロパティまたはキーは無視されます。以下のObjectの定義では、問題なく動作します。

class Contact: Object {
    dynamic var phone = ""

    static func primaryKey() -> String? {
        return "phone"
    }
}

class Location: Object {
    dynamic var lat = 0.0  // latitude
    dynamic var lng = 0.0  // longitude
    dynamic var postalCode = ""
    dynamic var cc = ""
    dynamic var state = ""
    dynamic var country = ""
}

class Venue: Object {
    dynamic var id = ""
    dynamic var name = ""
    dynamic var contact = Contact()
    dynamic var location = Location()

    static func primaryKey() -> String? {
        return "id"
    }
}

レスポンスデータはJSONの配列として返ってくるので、配列をループしてRealm().create(Venue.self, value: value)を使ってオブジェクトを作っています。

JSON データからVenueオブジェクトと関連のオブジェクトをデフォルトRealmに追加しています。

//Extract the array of venues from the response
let venues = json["venues"] as! [NSDictionary]

let realm = Realm()
realm.write {
  // Save one Venue object (and dependents) for each element of the array
  for venue in venues {
    realm.create(Venue.self, value: venue, update: true)
  }
}

現バージョンにおける制限事項

現在のRealmはベータバージョンであり、バージョン1.0のリリースに向けて、継続的に機能追加および不具合の修正が行われています。

既知の問題についてのわかりやすい一覧はGitHub Issuesをご覧ください。

一般的な制限事項

Realmは、柔軟性とパフォーマンスのバランスをうまく保つため、保存するデータに対していくつかの制限事項があります。

  1. クラス名の長さは63バイト以下でなければなりません。UTF-8に含まれる文字をサポートしています。それ以上の長さのクラスがある場合、初期化の際に例外が投げられます。
  2. プロパティ名の長さは63バイト以下でなければなりません。UTF-8に含まれる文字をサポートしています。それ以上の長さのプロパティがある場合、初期化の際に例外が投げられます。
  3. NSData型のプロパティは、16MB以上のデータを保存することはできません。 それ以上のデータを保存するには、16MB以下の複数のデータにに分割するか、ファイルとして保存し、Realmにはファイルパスを記録します。 16MB以上のデータを保存しようとすると、実行時に例外が投げられます。
  4. NSDate型のプロパティは、保存したときにミリ秒以下が切り捨てられます。詳しくは、NSDateについてをご覧ください。
  5. 各Realmファイルのサイズは、アプリケーションごとにに割り当てられるメモリサイズを超えてはいけません。割り当てられるメモリサイズは、デバイスごとに異なり、実行時のメモリの断片化にも依存します。(詳しくは、rdar://17119975 をご覧ください)それ以上のデータを保存される場合は、Realmファイルを複数に分割してください。

きめ細やかな通知(Fine-grained notifications)は未サポートです

Realmのデータが変更されるたびに通知を受けることができますが、現在はどのような変更があったか(追加/更新/削除)を知ることができません。

近い将来、どのオブジェクトにどんな変更がなされたのかを含めて通知する機能を追加する予定です。

NSDateはミリ秒以下が切り捨てられます

NSDateは、いったんRealmに保存されるとミリ秒以下が切り捨てられます。 この問題は、現在修正中です。 詳しくは、 GitHub issue #875 をご覧ください。

それまで、ミリ秒以下の精度を持つ時間を保存したい場合は、NSTimeInterval型のプロパティをお使いください。

モデルクラスのsetterおよびgetterメソッドはオーバーライドできません

Realmは、データベースのプロパティとデータベースの操作を連動させて、遅延ロードや高速な性能を実現するために、モデルクラスのsetterおよびgetterをオーバーライドしています。そのため、Realmモデルクラスではプロパティのsetterおよびgetterメソッドをオーバーライドすることはできません。

簡単な解決方法は保存しないプロパティとして宣言することです。保存しないプロパティのsetterおよびgetterメソッドは自由にオーバーライドすることが可能です。

KVOは未サポートです

現在、KVOはサポートされていませんが、独自の通知を受ける仕組みがあります。もちろんKVOのサポートも予定しています: GitHub issue #601

ファイルサイズと中間データについて

SQLiteなどにデータを保存した時より、ディスクの使用容量が少なくなることを期待されることかと思います。 Realmファイルの容量が考えているよりも大き場合はRealmは古い履歴データを残している可能性があります。

データの一貫性を保つために、Realmは最新のデータにアクセスしたときのみ履歴をアップデートします。 このことは、別のスレッドが多くのデータを長い時間をかけて書き込んでいる最中にデータを読み出そうとした場合、履歴はアップデートされずに古いデータを読み出すことになります。結果として、履歴の中間データが増加していくことになります。

この余分な領域は、最終的には再利用されるか消去されます。(強制的に空き領域を消去するには、 Realm().writeCopyToPath(_:encryptionKey:)を使ってファイルをコピーします。そのとき、自動的にファイルサイズが最適化されます。)

この問題を避けるには、invalidateメソッドを呼び出し、Realmにこれまでに取得したデータはもう必要なくなったことを知らせてください。 そうすると、Realmは中間データの履歴を解放します。そして、次のアクセスのときに最新のデータを使うようにRealmが更新されます。

また、GCDを使ってRealmにアクセスしたときにも、この問題が発生する可能性があります。ブロックの実行が終了した後も、オートリリースプールのオブジェクトが解放されずに、Realmが解放されるまで古い履歴のデータが残ることによります。

この問題を避けるためにGCDのブロック内でRealmにアクセスするときは、明示的にオートリリースプールを利用してください。

Objective‑CからListプロパティへのアクセスはできません

Realm SwiftをObjective‑Cから使用する場合Listプロパティをprivateinternalに指定する必要があります。 これは現在、確認されているSwiftの不具合のため、自動的に生成されるObjective‑Cヘッダ(-Swift.h)はコンパイルすることができません。 詳しくはGitHub issue #1925もご覧ください。

FAQ

Realmのライブラリは、どのくらいの容量がありますか?

アプリケーションをリリース用ビルドすると、Realmライブラリによってサイズは1MB程度増加します。

現在、配布されているRealmのライブラリは複数のアーキテクチャ(ARM、ARM64、シミュレータ用のx86)に対応していることに加え、デバッグシンボルが含まれてるため、著しく大きく(iOS版は約37MB, OSX版は、約2.4MB)なっています。それらはビルド時にXcodeが自動的に取り除いてくれます。

Realmをプロダクション環境で使うことはできますか?

Realmは、2012年から商用のプロダクトで利用されています。

現在のRealmを利用する場合は、RealmのObjective‑C、およびSwiftのAPIが、コミュニティのフィードバックを受けて変わりうるものだとしてお使いください。 機能追加、不具合の修正も同様に考えてください。

Realmを使うために料金を支払う必要がありますか?

いいえ、Realmは完全に無料です。商用の製品で利用することも可能です。

Realmはどのようなビジネスプランなのですか?

すでにエンタープライズ向けの商品の販売や、周辺サービスによって収益を得ています。もし現在リリースされているrealm-cocoa以上の機能が必要であれば、いつでもメールで、お気軽にご連絡ください。

また私たちのビジネスとは関係なく、realm-cocoaはオープンソースのまま開発を続け、Apache License 2.0として公開し続けます。

“tightdb”や”core”という文字をコードの中で見たのですが、これは何ですか?

TightDBというのは、C++で実装されたストレージエンジンの古い名前です。現在、コアのソースコードはオープンソースではありませんが、近い将来Apache License 2.0で公開する予定です。 バイナリについては、Realm Core (TightDB) Binary Licenseで利用可能です。