SwiftDataの履歴機能によるモデル変更のトラッキング

SwiftDataの履歴機能によるモデル変更のトラッキング

SwiftDataを使用して、モデルの変更履歴を明らかにしましょう。履歴APIを使用すると、データストアがいつ変更されたのかを把握することができます。この情報をもとに、リモートサーバの同期やアプリでのプロセス外変更処理など、さまざまな機能を構築する方法を説明します。履歴APIのサポートをカスタムデータストアに取り入れる方法も取り上げます。

関連する章
- 0:00 - Introduction
- 0:45 - Fundamentals
- 5:18 - Transactions and changes
- 12:37 - Custom stores
リソース
関連ビデオ

WWDC24
- SwiftDataを使用したカスタムデータストアの作成
ダウンロード

こんにちは SwiftDataチームのエンジニア Davidです SwiftDataの履歴機能はアプリのデータに加えられた変更を追跡するための新しいテクノロジーですこの履歴機能を使えばアプリのデータへの様々な変更を処理する機能を構築できます例えばサーバとの同期や App Extensionからの変更への対応などを処理する機能です本セッションでは SwiftDataの履歴機能の基本を説明したあとサンプルアプリで履歴のトランザクションおよび変更を使って新しい機能を構築します
最後にカスタムデータストアで履歴機能をサポートする際の考慮事項を説明します
まず SwiftDataの履歴機能とは何かそしてなぜ使用したいのかを説明します
アプリを使い続けると SwiftDataに保存される内容は時間とともに変化します例えばアプリを起動するとモデルが作成されたりリモートサーバから取得したモデルが挿入されたりします
モデルコンテキストが保存されると保留中のすべての変更がデータストアに保存されます
時間が経つにつれて
ユーザーがアプリやその様々な機能を
使用し操作を行うことでこれらのモデルの一部が変更または削除されることがあります
アプリはいつでもストアに対してデータのクエリを実行できますが結果として返されるのはデータストアにその時点で保存されているデータのみですクエリを実行しても履歴を調べるか手動で差分比較しなければ前回のクエリ以降にどのモデルが追加削除更新されたかはわかりません SwiftDataの履歴機能を使えばデータストアが時間とともにどのように変化したかを簡単に効率よく追跡できます
この機能を使って様々な機能を構築できます例えばアプリがオフラインの時に追加された変更について時系列にそったログを作成し後でその変更をリモートサーバと効率的に同期させることができます
ウィジェットの拡張機能などのアプリとは別のプロセスで発生したデータの変更を検出しこれらの変更を適切にアプリに反映させたい場合もあるでしょう
または前回のクエリ以降にどのモデルが挿入または削除されたかを効率よく把握して実行時にステータスを更新できますこれらを実現する方法をご紹介します
SwiftDataの履歴機能を使うとアプリでクエリを実行して発生した順に変更を処理できます
この機能ではモデルが保存されるたびにすべての変更に関するメタデータを含むトランザクションを記録します
SwiftDataの履歴機能はトランザクションと変更で構成されていますトランザクションには ModelContextの保存時などの境界においてデータストアで発生したすべての変更がグループ化されますトランザクションは発生時点に基づいて順序づけされます
トランザクション内の一連の変更の間でも発生時点に基づき順序がつけられます各変更はモデルの挿入更新削除を示しており PersistentModelによってパラメータ化されていますそのため KeyPathによるPersistentModelのプロパティへの参照が可能です
SwiftDataの履歴機能ではトークンという概念を使いますトークンは履歴内のトランザクションのブックマークとして機能しますトークンを使うことで履歴の中で最後に処理されたトランザクションをアプリで追跡できるようになります
トークンは自身が関連づけられているデータストアに対してのみ有効です SwiftDataの履歴情報はモデルコンテキストを通じて削除できます
履歴から削除した部分のトークンは期限切れとなり履歴の取得に使用できなくなります
SwiftDataの履歴機能で期限切れのトークンを使おうとすると historyTokenExpiredエラーがスローされますこのような場合は無効になったトークンを破棄して新しいトークンを取得します
モデルが削除されるとモデル内のデータは破棄されますこれにより IDなどの重要なデータが失われアプリで履歴情報を処理するための十分な情報が得られなくなる可能性がありますこの問題に対処するために SwiftDataの履歴機能ではモデルの特定の属性を保持できるようになっていますモデルが削除されるとそれらのモデルの属性がトゥームストーン値として保存されるため削除されたモデルの履歴情報も引き続き処理できます
.preserveValueOnDeletion モディファイアでマークされた PersistentModelの属性がトゥームストーンに保存されますトゥームストーンはPersistentModelによりパラメータ化もされるため必要に応じ KeyPathを使ってトゥームストーン値を取得したり繰り返し履歴を処理したりできます
SwiftDataの履歴機能は使いやすく Swiftの充実した型システムを基盤として構築されています次にアプリでの履歴機能の使い方を説明します実際の動作を確認するために履歴機能を新機能として SampleTripsというアプリに追加してみますこのアプリにはお気に入りの旅行情報をすべて記録でき次の休暇を計画する際に便利です
変更があったけれどまだ読めていない旅行情報にバッジをつけ未読であることを示してくれる新機能を追加しますバッジ追加はリモートサーバとの同期などアプリ外の状況によって起こることもあればアプリのウィジェット内で起こることもあります
さらにウィジェットにホーム画面から直接個々の宿泊施設の予約を確認できる機能を追加しますこの機能を構築するには SwiftDataの履歴機能を使ってデータの変更日と変更した人物を確認し UIを更新できるようにします
そのための手順は次の3つですまず SwiftDataの履歴情報を取得し
次に変更のプロパティを確認して変更を処理し最後にユーザーインターフェイスを更新しますまず tokenパラメータとauthorに基づいてデータストア内のトランザクションを取得する関数を作成しますこの例ではトークンは DefaultHistoryToken型ですがこれはこのアプリがSwiftDataで DefaultStoreを使っているためです
次に HistoryDescriptorを作成してリクエストの制約事項を構成できるようにします
predicateを作成して提供されたトークン以降に発生したトランザクションを制約します
この関数ではウィジェットでの変更のみを確認できるようにしたいので指定したauthorによる変更のみを取得するという制約を追加しますトークンを使わずにこの関数を呼び出すと取得可能なすべての履歴情報を取得することになります
次に処理が必要なトランザクションを含めるための配列を作成します次に記述子を使って ModelContextでfetchHistoryを呼び出しますこれで一連の DefaultHistoryTransactionsが提供され以降の反復処理に使用できます以上で目的のトランザクションを取得できるようになりました次にこれらを処理するための別の関数を定義しますこの関数はトランザクションの配列を受け取り未読の変更とトークンの存在を示すバッジの付与が必要な旅行情報のセットを返します関数を実行するたびに新しいトークンが返されますこのトークンは次回に変更を確認する際に使用できます
まず ModelContextと未読の変更が含まれている旅行情報を保存するセットを定義します
各トランザクションとトランザクション内の各変更に対して History APIにより永続的なモデルIDが割り当てられます旅行情報のモデルインスタンスを取得するためにこの永続的なモデルIDを使って livingAccommodationの fetchDescriptorを作成します次にモデルのコンテキストからこのモデルを取得し LivingAccommodationに関連づけられている旅行情報を保存します
トランザクションに含まれる変更が挿入追加削除のどれか判断するために switch文を使って型を確認します
アプリでウィジェットによって LivingAccommodationモデルが挿入変更削除された場合は UIにバッジが表示されるようにしますそのためにはまずLivingAccommodationの DefaultHistoryInsert型が変更されているか確認しますこのケースが該当する場合 LivingAccommodationが挿入されたということでありこの旅行情報がセットに追加されます先ほども触れましたがこの型が DefaultHistoryInsertという名前なのはこの例ではこのモデルに DefaultStoreを使用しているためですさらに LivingAccommodationの DefaultHistoryUpdate型のケースを追加することで更新がないか確認します変更が更新によるものの場合はセットに含まれる旅行情報を更新します
旅行情報が削除されている場合アプリのインターフェイスでの操作は不要ですこれを処理するために LivingAccommodationの DefaultHistoryDelete型のケースを追加してセットから削除します
最後に旅行情報のセットとともに最後のトークンを返しますこれで今後この関数が呼び出された場合はこのトランザクション以降の変更のみが返されるようになります
SwiftDataの履歴機能をアプリに導入すると前回に変更を確認した時点以降にどの旅行情報がウィジェットによって変更されたか把握できるようになります次にこのトークンを保存する必要がありますこれにより前回変更を確認した時点以降の変更のみが確認の対象となりますそのためには 3つ目の関数を定義し UserDefaultsを使って最新のトークンを保存します利用可能なトークンがある場合は findUnreadTripsという関数でこのトークンを取得し JSONからデコードしたあとこのトークンを使って findTransactions関数を呼び出しますここではウィジェットを authorとして指定するためにウィジェットで ModelContextの.authorプロパティを TransactionAuthor.widgetに設定します
findTripsを呼び出して返されたトークンを UserDefaultsに保存しますこれで findUnreadTripsを呼び出すたびに前回の呼び出し以降にバッジをつける必要がある旅行情報のみが返されるようになります
もう少しで完成ですあと2つだけ追加が必要な要素があります
1つ目はアプリを開いた時に未読の旅行情報をチェックすることであり 2つ目は旅行情報がタップされた場合未読情報のセットから削除してバッジが消えるようにすることです SwiftUIビューで scenePhaseがアクティブになるたびに findUnreadTripIdentifiersを呼び出すとバッジが必要な新しい旅行情報を反映してインターフェイスが更新されます
さらに旅行情報が選択されたら unreadTripIdentifiersセットからその情報のIDを削除してバッジが消えるようにします
最後に unreadTripIdentifiersセットに含まれている旅行情報にバッジを追加します
以上で必要なコードをすべて記述できたのでビルドしてアプリを実行しましょうアプリには旅行情報がすでに入力済みなのでウィジェットの宿泊施設の予約を直接ホーム画面から確認してみましょう
をタップすると UIが更新され予約が確認済みになりました次回この旅行アプリを開くと Formation Flyoverの旅行情報に青色の未読バッジが表示され旅行情報に変更があったことが示されます旅行情報を確認するとこのバッジは消えます
SwiftDataを使ってカスタムデータストアを構築している場合も履歴機能を利用できます基盤となるモデルが対応している場合カスタムデータストアでも同じワークフローをサポートできますカスタムデータストアに履歴機能を追加するにはそのデータストアで使用する SwiftData History APIの基本要素を指定するために独自の型を実装する必要がありますこの基本要素にはトランザクションや各変更の型のほか複数のトランザクションの間でブックマークとして機能するトークンが含まれますカスタムデータストアはHistoryProvidingに準拠している必要もあります
トランザクションの境界は明確に定義する必要がありますデータストア内の書き込み操作を統合し順序づける必要があるためですデフォルトのストアでは ModelContextのモデルインスタンスへのすべての変更は保存時に1つのトランザクションとしてグループ化されます
トランザクションの型を作成する際は永続性バックエンドにおいてトランザクションを一意に識別する方法を定義する必要がありますトランザクションの境界と同様に変更の境界を定義する基準も明確に定義する必要があります DefaultStoreでは個々のモデルインスタンスの間が変更の境界になります
細かい変更を追跡できる識別子を選択しましょう
既存のすべての変更型をアプリで使う必要がない場合もあれば別の変更型が必要な場合もあります例えばアプリで挿入されるモデルが常に時系列ログのみである場合更新や削除の変更型は必要ないかもしれませんほかに考慮すべき事項としては値が削除された時アプリにその値を保存する必要があるかどうかの判断や削除された値の保存方法があります
履歴を提供するにはカスタムストアで HistoryProvidingプロトコルを実装する必要がありますそのためにはトランザクションと変更を定義しているストアからデータ行をまとめて取得できなければなりません
トランザクションの一部である行が識別できたら個々のモデルセットを構築する必要があります
デフォルトのデータストアの履歴情報には有効期限があります履歴をいつ削除するかはデベロッパ側で決定する必要があります SwiftDataの履歴機能は堅牢であり大量の履歴データを処理できますが状況によっては履歴データを削除した方がよい場合もあります例えばアプリからモデルを削除した場合そのモデルに関する履歴データは今後使うことのないものである場合がありますこの場合はデータストアの履歴を削除した方がよいでしょう
最後にカスタムストアに履歴機能を追加する際はカスタムの型のトークンを作成する必要があります HistoryTokenはトークンの基本プロトコルですトランザクション内の一連の処理の中で特定の位置を一意に識別するにはステータスが必要です
アプリで関連する複数のストアを使用する場合はトランザクションで使用される全ストアのステータスをカスタムトークンに含める必要があります
履歴機能は変更に関するクエリを実行できるパワフルな機能ですこれによりウィジェットの旅行情報が更新されたことなどを確認できます SwiftDataでは表現力に優れた Swiftの型システムによって各モデルの変更がアプリ内でどう使用されるか簡単に把握できます SwiftDataの履歴機能を活用すればアプリで素晴らしい体験を構築できます永続的な履歴を利用するためにアプリとCore Dataを併用している場合は SwiftDataの履歴機能への移行をおすすめしますカスタムストアを構築している場合は履歴のための独自の型を作成することで履歴追跡のすべての機能を利用できるようになりますご視聴ありがとうございました

4:57 - Preserve values in history on deletion

// Add .preserveValueOnDeletion to capture unique columns
import SwiftData

@Model 
class Trip {
    #Unique<Trip>([\.name, \.startDate, \.endDate])
    
    @Attribute(.preserveValueOnDeletion)
    var name: String
    var destination: String

    @Attribute(.preserveValueOnDeletion)
    var startDate: Date

    @Attribute(.preserveValueOnDeletion)
    var endDate: Date
    
    var bucketList: [BucketListItem] = [BucketListItem]()
    var livingAccommodation: LivingAccommodation?
}

6:26 - Fetch transactions from history

private func findTransactions(after token: DefaultHistoryToken?, author: String) -> [DefaultHistoryTransaction] {
    var historyDescriptor = HistoryDescriptor<DefaultHistoryTransaction>() 
    if let token {
        historyDescriptor.predicate = #Predicate { transaction in
            (transaction.token > token) && (transaction.author == author)
        }
    }
    
    var transactions: [DefaultHistoryTransaction] = []
    let taskContext = ModelContext(modelContainer)
    do {
        transactions = try taskContext.fetchHistory(historyDescriptor)
    } catch let error {
        print(error)
    }

    return transactions
}

7:34 - Process history changes

private func findTrips(in transactions: [DefaultHistoryTransaction]) -> (Set<Trip>, DefaultHistoryToken?) {
        let taskContext = ModelContext(modelContainer)
        var resultTrips: Set<Trip> = []
        for transaction in transactions {
            for change in transaction.changes {
                let modelID = change.changedPersistentIdentifier
                let fetchDescriptor = FetchDescriptor<Trip>(predicate: #Predicate { trip in
                    trip.livingAccommodation?.persistentModelID == modelID
                })
                let fetchResults = try? taskContext.fetch(fetchDescriptor)
                guard let matchedTrip = fetchResults?.first else {
                    continue
                }
                switch change {
                case .insert(_ as DefaultHistoryInsert<LivingAccommodation>):
                    resultTrips.insert(matchedTrip)
                case .update(_ as DefaultHistoryUpdate<LivingAccommodation>):
                    resultTrips.update(with: matchedTrip)
                case .delete(_ as DefaultHistoryDelete<LivingAccommodation>):
                    resultTrips.remove(matchedTrip)
                default: break
                }
            }
        }
        return (resultTrips, transactions.last?.token)
    }

10:19 - Save and use a history token

private func findUnreadTrips() -> Set<Trip> {
    let tokenData = UserDefaults.standard.data(forKey: UserDefaultsKey.historyToken)
    
    var historyToken: DefaultHistoryToken? = nil
    if let tokenData {
        historyToken = try? JSONDecoder().decode(DefaultHistoryToken.self, from: tokenData)
    }
    let transactions = findTransactions(after: historyToken, author: TransactionAuthor.widget)
    let (unreadTrips, newToken) = findTrips(in: transactions)
    
    if let newToken {
        let newTokenData = try? JSONEncoder().encode(newToken)
        UserDefaults.standard.set(newTokenData, forKey: UserDefaultsKey.historyToken)
    }
    return unreadTrips
}

11:30 - Update the user interface

struct ContentView: View {
    @Environment(\.scenePhase) private var scenePhase
    @State private var showAddTrip = false
    @State private var selection: Trip?
    @State private var searchText: String = ""
    @State private var tripCount = 0
    @State private var unreadTripIdentifiers: [PersistentIdentifier] = []

    var body: some View {
        NavigationSplitView {
            TripListView(selection: $selection, tripCount: $tripCount,
                         unreadTripIdentifiers: $unreadTripIdentifiers,
                         searchText: searchText)
            .toolbar {
                ToolbarItem(placement: .topBarLeading) {
                    EditButton()
                        .disabled(tripCount == 0)
                }
                ToolbarItemGroup(placement: .topBarTrailing) {
                    Spacer()
                    Button {
                        showAddTrip = true
                    } label: {
                        Label("Add trip", systemImage: "plus")
                    }
                }
            }
        } detail: {
            if let selection = selection {
                NavigationStack {
                    TripDetailView(trip: selection)
                }
            }
        }
        .task {
            unreadTripIdentifiers = await DataModel.shared.unreadTripIdentifiersInUserDefaults
        }
        .searchable(text: $searchText, placement: .sidebar)
        .sheet(isPresented: $showAddTrip) {
            NavigationStack {
                AddTripView()
            }
            .presentationDetents([.medium, .large])
        }
        .onChange(of: selection) { _, newValue in
            if let newSelection = newValue {
                if let index = unreadTripIdentifiers.firstIndex(where: {
                    $0 == newSelection.persistentModelID
                }) {
                    unreadTripIdentifiers.remove(at: index)
                }
            }
        }
        .onChange(of: scenePhase) { _, newValue in
            Task {
                if newValue == .active {
                    unreadTripIdentifiers += await DataModel.shared.findUnreadTripIdentifiers()
                } else {
                    // Persist the unread trip names for the next launch session.
                    await DataModel.shared.setUnreadTripIdentifiersInUserDefaults(unreadTripIdentifiers)
                }
            }
        }
        #if os(macOS)
        .onReceive(NotificationCenter.default.publisher(for: NSApplication.didBecomeActiveNotification)) { _ in
            Task {
                unreadTripIdentifiers += await DataModel.shared.findUnreadTripIdentifiers()
            }
        }
        .onReceive(NotificationCenter.default.publisher(for: NSApplication.willTerminateNotification)) { _ in
            Task {
                await DataModel.shared.setUnreadTripIdentifiersInUserDefaults(unreadTripIdentifiers)
            }
        }
        #endif
    }
}

特定のトピックをお探しの場合は、上にトピックを入力すると、関連するトピックにすばやく移動できます。

クエリの送信中にエラーが発生しました。インターネット接続を確認して、もう一度お試しください。

関連する章

リソース

関連ビデオ

WWDC24