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。（iOS 7ではDynamic Frameworkが利用できないため、サポートされません。）
• Xcode 6.3以降。
• 現在の正式版はSwift 2.0を対象にしています。Swift 1.2を利用することも可能ですが、Appleが公式にSwift 2.0をリリースするまでは手動で切り替えて利用する必要があります。Swift 1.2のサポートは数か月のうちに非推奨になる予定です。

インストール (Swift 2.0)

• Dynamic Framework
• CocoaPods
• Carthage

インストール (Swift 1.2)

We’ll still be supporting Swift 1.2 via the swift-1.2 branch for some time to come, but we encourage you to move to Swift 2 as soon as possible.

継続してSwift 1.2のサポートをswift-1.2ブランチにて提供しています。しかし、できるだけ早く、Swift 2に移行することを推奨いたします。

• ソースコードから
• CocoaPods
• Carthage

# “Realm”と“RealmSwift”の両方を追加する必要があります
use_frameworks!
pod 'Realm', :git => 'https://github.com/realm/realm-cocoa.git', :branch => 'swift-1.2'
pod 'RealmSwift', :git => 'https://github.com/realm/realm-cocoa.git', :branch => 'swift-1.2'

tvOS

tvOSは現在ベータ版ですが、私たちは現在RealmがtvOSの上でどのように利用できるのか検証しています。もし、現時点でRealmをtvOS上で動作させる場合は、あくまでも開発のためにだけ利用し、プロダクションの用途にはまだ適していないことにご注意ください。 詳しくはこちらのPull Request #2506の議論をご覧ください。

Realm Browser

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

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

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

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

Xcode Plugin

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

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

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

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

API Reference

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

サンプルコード

最新のRealmのexamplesフォルダに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では、次に示すデータ型をサポートしています: Bool、Int8、Int16、Int32、Int64、Double、Float、String、NSDate（ミリ秒以下は切り捨てられます）、NSData。

CGFloat型はプラットフォーム（CPUアーキテクチャ）によって実際の定義が変わるため、使用しないようにしてください。

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

リレーションシップ（関連）

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

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

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

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

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

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

モデル間で１対１や１対多の関連を持たせるには、別の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はネストしたオブジェクトを必要に応じて自動的にフェッチします。

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

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

PersonクラスがDogクラスを１対多の関連として持つようにするには、次のように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にデータを保存しなければなりません。これらの操作は、トランザクションの中で行う必要があります。

オブジェクトの生成

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の取得はスレッドごとに１度だけ必要になります

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

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

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

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

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

オブジェクトの更新

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

// トランザクションを開始して、オブジェクトを更新する
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に含まれるObjectから、関連のオブジェクトを次々とたどりながら取得することもできます。

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

もっとも基本的なオブジェクトを取得する方法は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型のプロパティに対しては、==、!=、BEGINSWITH、CONTAINS、ENDSWITH演算子が使用できます。

  （例）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は、１つあるいは複数のプロパティの値を使って並べ替えることができます。下記は、先ほどの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かつ、nameがBからはじまる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 Configuration

Realmファイルの保存場所などの、Realmに対する設定をカスタマイズするには、Realm.Configurationオブジェクトを使います。

設定オブジェクトはRealmのインスタンスを取得する際にRealm(configuration: config)メソッドに渡すこともできますし、Realm.Configuration.defaultConfiguration = configメソッドを利用して、デフォルトRealmの設定とすることもできます。

例えば、次のようなアプリケーションを考えます。Web APIによるログイン認証があり、複数のアカウントを切り替えることができるとします。

その場合、アカウントごとにデフォルトRealmの保存場所を設定することで、それぞれのアカウントで別のRealmファイルを使い分けることができます。

func setDefaultRealmForUser(username: String) {
  var config = Realm.Configuration()

  // 保存先のディレクトリはデフォルトのままで、ファイル名をユーザー名を使うように変更します
  config.path = config.path.stringByDeletingLastPathComponent()
                           .stringByAppendingPathComponent(username)
                           .stringByAppendingPathExtension("realm")

  // ConfigurationオブジェクトをデフォルトRealmで使用するように設定します
  Realm.Configuration.defaultConfiguration = config
}

デフォルト以外のRealm

複数のRealmファイルを別の場所に保存して使い分けることができると便利です。例えば、事前に用意した組み込み済みデータを、メインのデータファイルとは別に読み込み専用のRealmとして利用するなどです。

下記のコードは、アプリケーションに同梱された別のRealmファイルからデータを読み込む例です。

let config = Realm.Configuration(
    // アプリケーションバンドルのパスを設定します
    path: NSBundle.mainBundle().pathForResource("MyBundledData", ofType:"realm"),
    // アプリケーションバンドルは書き込み不可なので、読み込み専用に設定します。
    readOnly: true)

// RealmをConfigurationオブジェクト使って作成します
let realm = Realm(configuration: config)

// バンドルのRealmからデータを取得します
let results = realm.objects(Dog).filter("age > 5")

Realmを初期化するときに指定するファイルパスは、書き込み可能な場所を指している必要があります。

書き込み可能であるもっとも普通な保存場所は、iOSでは”Documents”フォルダ、OS Xでは”Application Support”フォルダです。

AppleのiOS Data Storage Guidelinesによると、<Application_Home>/Library/Cachesフォルダに保存することが推奨されています。

In-Memory Realm

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

let realm = Realm(configuration: Realm.Configuration(inMemoryIdentifier: "MyInMemoryRealm"))

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

ディスクへの読み書きによるオーバーヘッドの無い、柔軟なデータアクセス機能が必要なときに有効です。

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

同じRealmファイルを複数のスレッドから使う場合は、各スレッドでRealmインスタンスをそれぞれ生成する必要があります。 同じ設定によって作られたRealmインスタンスは、ディスク上で同じものを指します。

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

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

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

Realmオブジェクトはスレッドセーフではないため、複数のスレッド間で共有することができません。それぞれのスレッド／dispatch_queueでRLMRealmオブジェクトを生成する必要があります。

下記は、バックグランド処理で100万個のオブジェクトを追加する例です。

dispatch_async(queue) {
  autoreleasepool {
    // このスレッドで使うRealmインスタンスを取得します
    let realm = Realm()

    // トランザクションを開始して、
    // 1000件単位で書き込みます
    for idx1 in 0..<1000 {
      realm.beginWrite()

      // ディクショナリからオブジェクトを作成する場合は、プロパティの順序を気にする必要はありません
      for idx2 in 0..<1000 {
        realm.create(Person.self, value: [
          "name": "\(idx1)",
          "birthdate": NSDate(timeIntervalSince1970: idx2)
        ])
      }

      // トランザクションを込みとして、
      // 他のスレッドのRealmからデータを利用できるようにします。
      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オブジェクトを作ります。

7. 同梱したRealmデータファイルが固定のデータのみを含んでいて、変更する必要が無いのであれば、Realm.ConfigurationでreadOnly = trueを指定して読み込み専用とし、直接バンドル内のファイルを開くことができます。 いっぽう、初期データを変更する必要があるなら、バンドルからドキュメントディレクトリなどにRealmファイルをNSFileManager.defaultManager().copyItemAtPath(_:toPath:error:)メソッドでコピーしてから利用します。

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

モデル定義のサブセット

各Realmファイルで保存されるモデルの定義を使い分けたいことがあります。

例えば、内部でRealmを利用する異なるコンポーネントを、２つのチームにより開発しているとします。

その場合、自分の開発しているコンポーネントに関係のないモデルに関するマイグレーション処理はやりたくないことでしょう。

下記のように、Realm.ConfigurationオブジェクトのobjectTypesプロパティを用いて、それぞれのRealmに保存されるモデルクラスを制限することができます。

let config = Realm.Configuration(objectTypes: [MyClass.self, MyOtherClass.self])
let realm = Realm(configuration: config)

通知

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

// Realmの通知を監視するように登録します
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
}

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

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

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

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

マイグレーション処理は、Realm.Configuration.migrationBlockを利用して定義します。

スキーマのバージョンはRealm.Configuration.schemaVersionを用いて設定します。

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

上記の設定オブジェクトを用いてRealmオブジェクトが作られたときに、スキーマバージョンが異なっていればマイグレーション処理が適用されます。

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

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

let config = Realm.Configuration(
  // 新しいスキーマバージョンを設定します。以前のバージョンより大きくなければなりません。
  // （スキーマバージョンを設定したことがなければ、最初は0が設定されています）
  schemaVersion: 1,

  // マイグレーション処理を記述します。古いスキーマバージョンのRealmを開こうとすると
  // 自動的にマイグレーションが実行されます。
  migrationBlock: { migration, oldSchemaVersion in
    // 最初のマイグレーションの場合、`oldSchemaVersion`は0です
    if (oldSchemaVersion < 1) {
      // 何もする必要はありません！
      // Realmは自動的に新しく追加されたプロパティと、削除されたプロパティを認識します。
      // そしてディスク上のスキーマを自動的にアップデートします。
    }
  })

// デフォルトRealmに新しい設定を適用します
Realm.Configuration.defaultConfiguration = config

// Realmファイルを開こうとしたときスキーマバージョンが異なれば、
// 自動的にマイグレーションが実行されます
let realm = Realm()

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

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

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

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

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

Realm.Configuration.defaultConfiguration = Realm.Configuration(
  schemaVersion: 1,
  migrationBlock: { 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 = "" // 追加したプロパティ
    dynamic var age = 0
}

// v2
class Person: Object {
    dynamic var fullName = ""
    dynamic var email = "" // 追加したプロパティ
    dynamic var age = 0
}

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

Realm.Configuration.defaultConfiguration = Realm.Configuration(
  schemaVersion: 1,
  migrationBlock: { 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"] = ""
      }
    }
  })

// 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を代入することを推奨します。

暗号化

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ファイルを開きます
let config = Realm.Configuration(encryptionKey: key)
var error: NSError?
let realm = Realm(configuration: config, error: &error)
if realm == nil {
    // もし暗号化キーが間違っている場合、`error`オブジェクトは"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を使う場合、わずかにパフォーマンスが下がり（10%未満）ます。

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

キー値監視（KVO）

Realmオブジェクトのほとんどのプロパティはキー値監視（KVO）に対応しています。

すべてのObjectのサブクラスにおける永続化対象（保存しないプロパティではない）のプロパティはKVOに対応しています。永続化される前のinvalidatedなObjectとListのプロパティも同様です。

永続化前（スタンドアローン）のObjectのサブクラスのオブジェクトに対するキー値監視は、一般的なdynamic propertyと同様に動作します。

しかし、監視対象のオブジェクトは、監視対象として登録されている間はrealm.add(obj)などのメソッドでRealmに保存することができないので注意してください。

永続化済みのオブジェクトに対するキー値監視は少し異なる動作をします。

永続化済みのオブジェクトにおいては、そのプロパティの変わるタイミングが３種類あります。プロパティに値を直接代入したとき、realm.refresh()メソッドを呼び出したとき、または別のスレッドがトランザクションをコミットして自動的にRealmが更新されたとき、そして別のスレッドから変更があったがその前にrealm.beginWrite()を呼び出してトランザクションを開始したために変更が通知されなかったときです。

直接代入する以外の２つのケースではすべての別スレッドから行われた変更は、一度に適用されます。そのため、KVOの通知は１回にまとめられます。途中の変更の状態は破棄されるので、1から10まで１つずつ数を増加させるプロパティがあった場合、10に変化する際の１つの通知だけを受け取ることになります。

トランザクションの外でプロパティの変更が行われる可能性があるので、-observeValueForKeyPath:ofObject:change:context:メソッドの中で永続化済みのRealmオブジェクトを変更することは推奨されません。

NSMutableArrayのプロパティとは異なり、Listのプロパティに対する変更を監視するには-mutableArrayValueForKey:を使う必要はありません（互換性のためにそのメソッドを利用しても同様に機能するようにはしていますが）。直接Listを変更するメソッドを呼び出すだけで（監視していれば）更新が通知されます。

一般のプロパティと異なり、RealmのListプロパティはKVOの監視対象とするためにdynamicとして定義する必要はありません。

サンプルコードに簡単なRealmとReactiveCocoa（Objective‑C）のサンプル、およびReactKit（Swift）のサンプルがありますので参考にしてください。

デバッグ

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ファイルを使うようにデフォルトRealmを設定します。

// A base class which each of your Realm-using tests should inherit from rather
// than directly from XCTestCase
class TestCaseBase: XCTestCase {
  override func setUp() {
    super.setUp()

    // テストケース名で区別して、テストごとにIn-memoryなRealmを使うようにします。
    // こうすることで、テストによってアプリケーションのデータを変更してしまうことと、
    // 他のテストに影響が及ぶことを防ぎます。
    // そして、In-memoryなRealmを使うので
    // 後始末として、データを削除する必要はありません。
    Realm.Configuration.defaultConfiguration.inMemoryIdentifier = self.name
  }
}

外部から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\": \"help@realm.io\"}"
  let jsonData = jsonString.dataUsingEncoding(NSUTF8StringEncoding)
  ClassBeingTested.createOrUpdateUserInRealm(testRealm, withData: jsonData)
  let expectedUser = User()
  expectedUser.email = "help@realm.io"
  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 1.2ではpublic修飾子を使い、Swift 2.0では@testableを使います。）

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のデータが変更されるたびに通知を受けることができますが、現在はどのような変更があったか（追加／更新／削除）を知ることができません。

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

キー値監視（KVO）はオブジェクトごとの変更通知として利用することができます。特定のオブジェクトが削除されたことを検知することもできます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Xcode 7 Beta 5でこの問題は修正されました。

FAQ

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

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

現在、配布されているRealmのライブラリは、iOSとwatchOS両方のシミュレータ用のバイナリやデバッグシンボル、そしてBitcodeを含むため著しく大きくなっています。それらはビルド時に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で利用可能です。