Andrew Morgan

Staff Developer Advocate

In data modeling design reviews with customers, I often propose a schema where different documents in the same collection contain different types of data. This makes it efficient to fetch related documents in a single, indexed query. MongoDB's flexible schema is great for optimizing workloads in this way, but people can be concerned about losing control of what applications write to these collections.

Customers are often concerned about ensuring that only correctly formatted documents make it into a collection, and so I explain [MongoDB's schema validation feature](/docs/manual/core/schema-validation/). The question then comes: "How does that work with a polymorphic/single-collection schema?" This post is intended to answer that question — and it's simpler than you might think.

## The banking application and its data

The application I'm working on manages customer and account details. There's a many-to-many relationship between customers and accounts. The app needs to be able to efficiently query customer data based on the customer id, and account data based on either the id of its customer or the account id.

Here's an example of customer and account documents where my wife and I share a checking account but each have our own savings account:

```json
{
    "_id": "kjfgjebgjfbkjb",
    "customerId": "CUST-123456789",
    "docType": "customer",
    "name": {
        "title": "Mr",
        "first": "Andrew",
        "middle": "James",
        "last": "Morgan"
    },
    "address": {
        "street1": "240 Blackfriars Rd",
        "city": "London",
        "postCode": "SE1 8NW",
        "country": "UK"
    },
    "customerSince": ISODate("2005-05-20")
}

{
    "_id": "jnafjkkbEFejfleLJ",
    "customerId": "CUST-987654321",
    "docType": "customer",
    "name": {
        "title": "Mrs",
        "first": "Anne",
        "last": "Morgan"
    },
    "address": {
        "street1": "240 Blackfriars Rd",
        "city": "London",
        "postCode": "SE1 8NW",
        "country": "UK"
    },
    "customerSince": ISODate("2003-12-01")
}

{
    "_id": "dksfmkpGJPowefjdfhs",
    "accountNumber": "ACC1000000654",
    "docType": "account",
    "accountType": "checking",
    "customerId": [
        "CUST-123456789",
        "CUST-987654321"
    ],
    "dateOpened": ISODate("2003-12-01"),
    "balance": NumberDecimal("5067.65")
}

{
    "_id": "kliwiiejeqydioepwj",
    "accountNumber": "ACC1000000432",
    "docType": "account",
    "accountType": "savings",
    "customerId": [
        "CUST-123456789"
    ],
    "dateOpened": ISODate("2005-10-28"),
    "balance": NumberDecimal("10341.21")
}

{
    "_id": "djahspihhfheiphfipewe",
    "accountNumber": "ACC1000000890",
    "docType": "account",
    "accountType": "savings",
    "customerId": [
        "CUST-987654321"
    ],
    "dateOpened": ISODate("2003-12-15"),
    "balance": NumberDecimal("10341.89")
}
```

As an aside, these are the indexes I added to make those frequent queries I referred to more efficient:

```javascript
const indexKeys1 = { accountNumber: 1 };
const indexKeys2 = {  customerId: 1, accountType: 1 };
const indexOptions1 = { partialFilterExpression: { docType: 'account' }};
const indexOptions2 = { partialFilterExpression: { docType: 'customer' }};

db.getCollection(collection).createIndex(indexKeys1, indexOptions1);
db.getCollection(collection).createIndex(indexKeys2, indexOptions2);
```

## Adding schema validation

To quote [the docs](/docs/manual/core/schema-validation/)…

> Schema validation lets you create validation rules for your fields, such as allowed data types and value ranges.
>
> MongoDB uses a flexible schema model, which means that documents in a collection do not need to have the same fields or data types by default. Once you've established an application schema, you can use schema validation to ensure there are no unintended schema changes or improper data types.

The validation rules are pretty simple to set up, and tools like [Hackolade](https://hackolade.com/) can make it simpler still — even reverse-engineering your existing documents.

It's simple to imagine setting up a JSON schema validation rule for a collection where all documents share the same attributes and types. But what about polymorphic collections? Even in polymorphic collections, there is structure to the documents. Fortunately, the syntax for setting up the validation rules allows for the required optionality.

I have two different types of documents that I want to store in my `Accounts` collection — `customer` and `account`. I included a `docType` attribute in each document to identify which type of entity it represents.

I start by creating a JSON schema definition for each type of document:

```javascript
const customerSchema = {
    required: ["docType", "customerId", "name", "customerSince"],
    properties: {
        docType: { enum: ["customer"] },
        customerId: { bsonType: "string"},
        name: {
            bsonType: "object",
            required: ["first", "last"],
            properties: {
                title: { enum: ["Mr", "Mrs", "Ms", "Dr"]},
                first: { bsonType: "string" },
                middle: { bsonType: "string" },
                last: { bsonType: "string" }
            }
        },
        address: {
            bsonType: "object",
            required: ["street1", "city", "postCode", "country"],
            properties: {
                street1: { bsonType: "string" },
                street2: { bsonType: "string" },
                postCode: { bsonType: "string" },
                country: { bsonType: "string" }  
            }
        },
        customerSince: {
            bsonType: "date"
        }
    }
};

const accountSchema = {
    required: ["docType", "accountNumber", "accountType", "customerId", "dateOpened", "balance"],
    properties: {
        docType: { enum: ["account"] },
        accountNumber: { bsonType: "string" },
        accountType: { enum: ["checking", "savings", "mortgage", "loan"] },
        customerId: { bsonType: "array" },
        dateOpened: { bsonType: "date" },
        balance: { bsonType: "decimal" }
    }
};
```

Those definitions define what attributes should be in the document and what types they should take. Note that fields can be optional — such as `name.middle` in the `customer` schema.

It's then a simple matter of using the `oneOf` JSON schema operator to allow documents that match either of the two schema:

```javascript
const schemaValidation = {
    $jsonSchema: { oneOf: [ customerSchema, accountSchema ] }
};

db.createCollection(collection, {validator: schemaValidation});
```

I wanted to go a stage further and add some extra, semantic validations:

* For `customer` documents, the `customerSince` value can't be any earlier than the current time.
* For `account` documents, the `dateOpened` value can't be any earlier than the current time.
* For savings accounts, the `balance` can't fall below zero.

These documents represents these checks:

```javascript
const badCustomer = {
    "$expr": { "$gt": ["$customerSince", "$$NOW"] }
};

const badAccount = {
    $or: [ 
        {
            accountType: "savings",
            balance: { $lt: 0}
        },
        {
            "$expr": { "$gt": ["$dateOpened", "$$NOW"]}
        }
    ]
};

const schemaValidation = {
    "$and": [
        { $jsonSchema: { oneOf: [ customerSchema, accountSchema ] }},
        { $nor: [
            badCustomer,
            badAccount
         ]
        }
    ]
};
```

I updated the collection validation rules to include these new checks:

```javascript
const schemaValidation = {
    "$and": [
        { $jsonSchema: { oneOf: [ customerSchema, accountSchema ] }},
        { $nor: [
            badCustomer,
            badAccount
         ]
        }
    ]
};

db.createCollection(collection, {validator: schemaValidation} );
```

If you want to recreate this in your own MongoDB database, then just paste this into your [MongoDB playground in VS Code](/docs/mongodb-vscode/playgrounds/):

```javascript
const cust1 = {
    "_id": "kjfgjebgjfbkjb",
    "customerId": "CUST-123456789",
    "docType": "customer",
    "name": {
        "title": "Mr",
        "first": "Andrew",
        "middle": "James",
        "last": "Morgan"
    },
    "address": {
        "street1": "240 Blackfriars Rd",
        "city": "London",
        "postCode": "SE1 8NW",
        "country": "UK"
    },
    "customerSince": ISODate("2005-05-20")
}

const cust2 = {
    "_id": "jnafjkkbEFejfleLJ",
    "customerId": "CUST-987654321",
    "docType": "customer",
    "name": {
        "title": "Mrs",
        "first": "Anne",
        "last": "Morgan"
    },
    "address": {
        "street1": "240 Blackfriars Rd",
        "city": "London",
        "postCode": "SE1 8NW",
        "country": "UK"
    },
    "customerSince": ISODate("2003-12-01")
}

const futureCustomer = {
    "_id": "nansfanjnDjknje",
    "customerId": "CUST-666666666",
    "docType": "customer",
    "name": {
        "title": "Mr",
        "first": "Wrong",
        "last": "Un"
    },
    "address": {
        "street1": "240 Blackfriars Rd",
        "city": "London",
        "postCode": "SE1 8NW",
        "country": "UK"
    },
    "customerSince": ISODate("2025-05-20")
}

const acc1 = {
    "_id": "dksfmkpGJPowefjdfhs",
    "accountNumber": "ACC1000000654",
    "docType": "account",
    "accountType": "checking",
    "customerId": [
        "CUST-123456789",
        "CUST-987654321"
    ],
    "dateOpened": ISODate("2003-12-01"),
    "balance": NumberDecimal("5067.65")
}

const acc2 = {
    "_id": "kliwiiejeqydioepwj",
    "accountNumber": "ACC1000000432",
    "docType": "account",
    "accountType": "savings",
    "customerId": [
        "CUST-123456789"
    ],
    "dateOpened": ISODate("2005-10-28"),
    "balance": NumberDecimal("10341.21")
}

const acc3 = {
    "_id": "djahspihhfheiphfipewe",
    "accountNumber": "ACC1000000890",
    "docType": "account",
    "accountType": "savings",
    "customerId": [
        "CUST-987654321"
    ],
    "dateOpened": ISODate("2003-12-15"),
    "balance": NumberDecimal("10341.89")
}

const futureAccount = {
    "_id": "kljkdfgjkdsgjklgjdfgkl",
    "accountNumber": "ACC1000000999",
    "docType": "account",
    "accountType": "savings",
    "customerId": [
        "CUST-987654333"
    ],
    "dateOpened": ISODate("2030-12-15"),
    "balance": NumberDecimal("10341.89")
}

const negativeSavings = {
    "_id": "shkjahsjdkhHK",
    "accountNumber": "ACC1000000666",
    "docType": "account",
    "accountType": "savings",
    "customerId": [
        "CUST-9837462376"
    ],
    "dateOpened": ISODate("2005-10-28"),
    "balance": NumberDecimal("-10341.21")
}

const indexKeys1 = { accountNumber: 1 }
const indexKeys2 = {  customerId: 1, accountType: 1 } 
const indexOptions1 = { partialFilterExpression: { docType: 'account' }}
const indexOptions2 = { partialFilterExpression: { docType: 'customer' }}

const customerSchema = {
    required: ["docType", "customerId", "name", "customerSince"],
    properties: {
        docType: { enum: ["customer"] },
        customerId: { bsonType: "string"},
        name: {
            bsonType: "object",
            required: ["first", "last"],
            properties: {
                title: { enum: ["Mr", "Mrs", "Ms", "Dr"]},
                first: { bsonType: "string" },
                middle: { bsonType: "string" },
                last: { bsonType: "string" }
            }
        },
        address: {
            bsonType: "object",
            required: ["street1", "city", "postCode", "country"],
            properties: {
                street1: { bsonType: "string" },
                street2: { bsonType: "string" },
                postCode: { bsonType: "string" },
                country: { bsonType: "string" }  
            }
        },
        customerSince: {
            bsonType: "date"
        }
    }
}

const accountSchema = {
    required: ["docType", "accountNumber", "accountType", "customerId", "dateOpened", "balance"],
    properties: {
        docType: { enum: ["account"] },
        accountNumber: { bsonType: "string" },
        accountType: { enum: ["checking", "savings", "mortgage", "loan"] },
        customerId: { bsonType: "array" },
        dateOpened: { bsonType: "date" },
        balance: { bsonType: "decimal" }
    }
}

const badCustomer = {
    "$expr": { "$gt": ["$customerSince", "$$NOW"] }
}

const badAccount = {
    $or: [ 
        {
            accountType: "savings",
            balance: { $lt: 0}
        },
        {
            "$expr": { "$gt": ["$dateOpened", "$$NOW"]}
        }
    ]
}

const schemaValidation = {
    "$and": [
        { $jsonSchema: { oneOf: [ customerSchema, accountSchema ] }},
        { $nor: [
            badCustomer,
            badAccount
         ]
        }
    ]
}

const database = 'MongoBank';
const collection = 'Accounts';

use(database);
db.getCollection(collection).drop();
db.createCollection(collection, {validator: schemaValidation} )
db.getCollection(collection).replaceOne({"_id": cust1._id}, cust1, {upsert: true});
db.getCollection(collection).replaceOne({"_id": cust2._id}, cust2, {upsert: true});
db.getCollection(collection).replaceOne({"_id": acc1._id}, acc1, {upsert: true});
db.getCollection(collection).replaceOne({"_id": acc2._id}, acc2, {upsert: true});
db.getCollection(collection).replaceOne({"_id": acc3._id}, acc3, {upsert: true});

// The following 3 operations should fail

db.getCollection(collection).replaceOne({"_id": negativeSavings._id}, negativeSavings, {upsert: true});
db.getCollection(collection).replaceOne({"_id": futureCustomer._id}, futureCustomer, {upsert: true});
db.getCollection(collection).replaceOne({"_id": futureAccount._id}, futureAccount, {upsert: true});

db.getCollection(collection).dropIndexes();
db.getCollection(collection).createIndex(indexKeys1, indexOptions1);
db.getCollection(collection).createIndex(indexKeys2, indexOptions2);
```

## Conclusion

I hope that this short article has shown how easy it is to use schema validations with MongoDB's polymorphic collections and single-collection design pattern.

I didn't go into much detail about why I chose the data model used in this example. If you want to know more (and you should!), then here are some great resources on data modeling with MongoDB:

* Daniel Coupal and Ken Alger’s excellent series of blog posts on [MongoDB schema patterns](/developer/products/mongodb/polymorphic-pattern/)
* Daniel Coupal and Lauren Schaefer’s equally excellent series of blog posts on [MongoDB anti-patterns](/developer/products/mongodb/schema-design-anti-pattern-massive-arrays/)
* MongoDB University Course, [MongoDB Data Modeling Path](https://learn.mongodb.com/learn/learning-path/data-modeling-for-mongodb)

A great feature of MongoDB is its flexible document model. This post shows how to use document validation on polymorphic collections.

Document Validation for Polymorphic Collections

## Introduction

[Murphy's law](https://en.wikipedia.org/wiki/Murphy%27s_law) dictates that as soon as your mobile app goes live, you'll receive a request to add a new feature. Then another. Then another.

This is fine if these features don't require any changes to your data schema. But, that isn't always the case.

Fortunately, Realm has built-in functionality to make schema migration easier.

This tutorial will step you through updating an existing mobile app to add some new features that require changes to the schema. In particular, we'll look at the Realm migration code that ensures that no existing data is lost when the new app versions are rolled out to your production users.

We'll use the [Scrumdinger app that I modified in a previous post to show how Apple's sample Swift app could be ported to Realm](https://www.mongodb.com/developer/how-to/realm-swiftui-scrumdinger-migration/). The starting point for the app can be found in [this branch of our Scrumdinger repo](https://github.com/realm/Scrumdinger/tree/realm) and the final version is in [this branch](https://github.com/realm/Scrumdinger/tree/new-schema).

Note that the app we're using for this post doesn't use [Atlas Device Sync](https://www.mongodb.com/docs/atlas/app-services/sync/learn/overview/). If it did, then the schema migration process would be very different—that's covered in [Migrating Your iOS App's **Synced** Realm Schema in Production](https://www.mongodb.com/developer/how-to/realm-sync-migration/).

## Prerequisites

This tutorial has a dependency on [Realm-Cocoa 10.13.0+](https://github.com/realm/realm-cocoa/releases).

## Baseline App/Realm Schema

As a reminder, the starting point for this tutorial is the ["realm" branch of the Scrumdinger repo](https://github.com/realm/scrumdinger/tree/realm).

![Animated gif of the original Scrumdinger app in action](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/scrumdinger_original_b6a15f10ea.gif)

There are two Realm model classes that we'll extend to add new features to Scrumdinger. The first, [DailyScrum](https://github.com/realm/Scrumdinger/blob/realm/Scrumdinger/Models/DailyScrum.swift), represents one scrum:

``` swift
class DailyScrum: Object, ObjectKeyIdentifiable {
   @Persisted var title = ""
   @Persisted var attendeeList = RealmSwift.List<String>()
   @Persisted var lengthInMinutes = 0
   @Persisted var colorComponents: Components?
   @Persisted var historyList = RealmSwift.List<History>()


   var color: Color { Color(colorComponents ?? Components()) }
   var attendees: [String] { Array(attendeeList) }
   var history: [History] { Array(historyList) }
   ...
}
```

The second, [History](https://github.com/realm/Scrumdinger/blob/realm/Scrumdinger/Models/History.swift), represents the minutes of a meeting from one of the user's scrums:

``` swift
class History: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var date: Date?
   @Persisted var attendeeList = List<String>()
   @Persisted var lengthInMinutes: Int = 0
   @Persisted var transcript: String?
   var attendees: [String] { Array(attendeeList) }
   ...
}
```

We can use [Realm Studio](https://docs.mongodb.com/realm/studio/) to examine the contents of our Realm database after the `DailyScrum` and `History` objects have been created:

![DailyScrum data shown in RealmStudio](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Daily_Scrum_original_117e226072.png)

![History data shown in RealmStudio](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/History_original_fcc4e0b78d.png)

[Accessing Realm Data on iOS Using Realm Studio](https://www.mongodb.com/developer/how-to/realm-ios-database-access-using-realm-studio/) explains how to locate and open the Realm files from your iOS simulator.

## Schema Change #1—Mark Scrums as Public/Private

The first new feature we've been asked to add is a flag to indicate whether each scrum is public or private:

![Screen capture highlighting the new status - set to "Private"](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Scrumdinger_show_privacy_00eb2f407b.png)

![Screen capture showing the user setting the meeting status to "Public"](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Scrumdinger_edit_privacy_8df1447d57.png)

This feature requires the addition of a new `Bool` named `isPublic` to [DailyScrum](https://github.com/realm/Scrumdinger/blob/new-schema/Scrumdinger/Models/DailyScrum.swift):

``` swift
class DailyScrum: Object, ObjectKeyIdentifiable {
   @Persisted var title = ""
   @Persisted var attendeeList = RealmSwift.List<String>()
   @Persisted var lengthInMinutes = 0
   @Persisted var isPublic = false
   @Persisted var colorComponents: Components?
   @Persisted var historyList = RealmSwift.List<History>()


   var color: Color { Color(colorComponents ?? Components()) }
   var attendees: [String] { Array(attendeeList) }
   var history: [History] { Array(historyList) }
   ...
}
```

Remember that our original version of Scrumdinger is already in production, and the embedded Realm database is storing instances of `DailyScrum`. We don't want to lose that data, and so we must migrate those objects to the new schema when the app is upgraded.

Fortunately, Realm has built-in functionality to automatically handle the addition and deletion of fields. When adding a field, Realm will use a default value (e.g., `0` for an `Int`, and `false` for a `Bool`).

If we simply upgrade the installed app with the one using the new schema, then we'll get a fatal error. That's because we need to tell Realm that we've updated the schema. We do that by setting the schema version to 1 (the version defaulted to 0 for the original schema):

``` swift
@main
struct ScrumdingerApp: SwiftUI.App {
   var body: some Scene {
       WindowGroup {
           NavigationView {
               ScrumsView()
                   .environment(\.realmConfiguration,
                       Realm.Configuration(schemaVersion: 1))
           }
       }
   }
}
```

After upgrading the app, we can use [Realm Studio](https://docs.mongodb.com/realm/studio/) to confirm that our `DailyScrum` object has been updated to initialize `isPublic` to `false`:

![RealmStudio showing that the new, isPublic field has been initialised to false](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Daily_Scrum_updated_19c30fabd6.png)

## Schema Change #2—Store The Number of Attendees at Each Meeting

The second feature request is to show the number of attendees in the history from each meeting:

![Screen capture showing that the number of attendees is now displayed in the meeting minutes](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Scrumdinger_History_Change_5218655494.png)

We could calculate the count every time that it's needed, but we've decided to calculate it just once and then store it in our [History](https://github.com/realm/Scrumdinger/blob/new-schema/Scrumdinger/Models/History.swift) object in a new field named `numberOfAttendees`:

``` swift
class History: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var date: Date?
   @Persisted var attendeeList = List<String>()
   @Persisted var numberOfAttendees = 0
   @Persisted var lengthInMinutes: Int = 0
   @Persisted var transcript: String?
   var attendees: [String] { Array(attendeeList) }
   ...
}
```

We increment the schema version to 2. Note that the schema version applies to all Realm objects, and so we have to set the version to 2 even though this is the first time that we've changed the schema for `History`.

If we leave it to Realm to initialize `numberOfAttendees`, then it will set it to 0—which is not what we want. Instead, we provide a `migrationBlock` which initializes new fields based on the old schema version:

``` swift
@main
struct ScrumdingerApp: SwiftUI.App {
   var body: some Scene {
       WindowGroup {
           NavigationView {
               ScrumsView()
                   .environment(\.realmConfiguration, Realm.Configuration(
                       schemaVersion: 2,
                       migrationBlock: { migration, oldSchemaVersion in
                            if oldSchemaVersion < 1 {
                                // Could init the `DailyScrum.isPublic` field here, but the default behavior of setting
                                // it to `false` is what we want.
                            }
                            if oldSchemaVersion < 2 {
                                migration.enumerateObjects(ofType: History.className()) { oldObject, newObject in
                                    let attendees = oldObject!["attendeeList"] as? RealmSwift.List<DynamicObject>
                                    newObject!["numberOfAttendees"] = attendees?.count ?? 0
                                }
                            }
                            if oldSchemaVersion < 3 {
                                // TODO: This is where you'd add you're migration code to go from version
                                // to version 3 when you next modify the schema
                            }
                        }
                   ))
           }
       }
   }
}
```

Note that all other fields are migrated automatically.

It's up to you how you use data from the previous schema to populate fields in the new schema. E.g., if you wanted to combine `firstName` and `lastName` from the previous schema to populate a `fullName` field in the new schema, then you could do so like this:

``` swift
migration.enumerateObjects(ofType: Person.className()) { oldObject, newObject in
   let firstName = oldObject!["firstName"] as! String
   let lastName = oldObject!["lastName"] as! String
   newObject!["fullName"] = "\(firstName) \(lastName)"
}
```

We can't know what "old version" of the schema will be already installed on a user's device when it's upgraded to the latest version (some users may skip some versions,) and so the `migrationBlock` must handle all previous versions. Best practice is to process the incremental schema changes sequentially:

* `oldSchemaVersion < 1` : Process the delta between v0 and v1
* `oldSchemaVersion < 2` : Process the delta between v1 and v2
* `oldSchemaVersion < 3` : Process the delta between v2 and v3
* ...

Realm Studio shows that our code has correctly initialized `numberOfAttendees`:

![Realm Studio showing that the numberOfAttendees field has been set to 2 – matching the number of attendees in the meeting history](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/History_new_11564ec4b0.png)

## Conclusion

It's almost inevitable that any successful mobile app will need some schema changes after it's gone into production. Realm makes adapting to those changes simple, ensuring that users don't lose any of their existing data when upgrading to new versions of the app.

For changes such as adding or removing fields, all you need to do as a developer is to increment the version with each new deployed schema. For more complex changes, you provide code that computes the values for fields in the new schema using data from the old schema.

This tutorial stepped you through adding two new features that both required schema changes. You can view the final app in the [new-schema branch of the Scrumdinger repo](https://github.com/realm/Scrumdinger/tree/new-schema).

## Next Steps

This post focussed on schema migration for an iOS app. You can find some [more complex examples in the repo](https://github.com/realm/realm-cocoa/tree/master/examples/ios/swift/Migration).

If you're working with an app for a different platform, then you can find instructions in the docs:

* [Node.js](https://docs.mongodb.com/realm/sdk/node/examples/modify-an-object-schema/)
* [Android](https://docs.mongodb.com/realm/sdk/android/examples/modify-an-object-schema/)
* [iOS](https://docs.mongodb.com/realm/sdk/android/examples/modify-an-object-schema/)
* [.NET](https://docs.mongodb.com/realm/sdk/dotnet/examples/modify-an-object-schema/)
* [React Native](https://docs.mongodb.com/realm/sdk/react-native/examples/modify-an-object-schema/)

If you've any questions about schema migration, or anything else related to Realm, then please post them to our [community forum](https://www.mongodb.com/community/forums/c/realm-sdks/58).

Learn how to safely update your iOS app's Realm schema to support new functionality—without losing any existing data

Migrating Your iOS App's Realm Schema in Production

How to incorporate Realm into your iOS App. Building a chat app with SwiftUI and Realm-Cocoa

Building a Mobile Chat App Using Realm – Integrating Realm into Your App

The [Realm](https://www.realm.io) makes it much
faster to develop mobile applications. [Realm
Studio](https://github.com/realm/realm-studio) is a desktop app that
lets you view, manipulate, and import data held within your mobile app's
Realm database.

This article steps through how to track down the locations of your iOS
Realm database files, open them in Realm Studio, view the data, and make
changes. If you're developing an Android app, then finding the Realm
database files will be a little different (we'll follow up with an
Android version later), but if you can figure out how to locate the
Realm file, then the instructions on using Realm Studio should work.

## Prerequisites

If you want to build and run the app for yourself, this is what you'll
need:

-   A Mac.
-   Xcode – any reasonably recent version will work.
-   Realm Studio 10.1.0+ – earlier versions had an issue when working
    with Realms using [Atlas Device
    Sync](https://www.mongodb.com/app-services/device-sync).

I'll be using the data and schema from my existing
[RChat](https://github.com/ClusterDB/RChat) iOS app. You can use any
Realm-based app, but if you want to understand more about RChat, check
out [Building a Mobile Chat App Using Realm – Data Architecture](/how-to/realm-swiftui-ios-chat-app) and
[Building a Mobile Chat App Using Realm – Integrating Realm into Your App](/how-to/building-a-mobile-chat-app-using-realm).

## Walkthrough

This walkthrough shows you how to:

- [Install & Run Realm Studio](#install---run-realm-studio)
- [Track Down Realm Data Files – Xcode Simulator](#track-down-realm-data-files---xcode-simulator)
- [Track Down Realm Data Files – Real iOS Devices](#track-down-realm-data-files---real-ios-devices)
- [View Realm Data](#view-realm-data)
- [Add, Modify, and Delete Data](#add--modify--and-delete-data)

### Install & Run Realm Studio

I'm using [Realm Studio
10.1.1](https://studio-releases.realm.io/v10.1.1) to create this
article. If you have 10.1.0 installed, then that should work too.

If you don't already have Realm Studio 10.1.0+ installed, then [download
it here](https://studio-releases.realm.io/) and install.

That's it.

But, when you open the app, you're greeted by this:

![Realm Studio Splash Screen](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/Realm-Studio-Splash-Screen.png)

There's a single button letting me "Open Realm file," and when I click
on it, I get a file explorer where I can browse my laptop's file system.

Where am I supposed to find my Realm file? I cover that in the next
section.

### Track Down Realm Data Files – Xcode Simulator

If you're running your app in one of Xcode's simulators, then the Realm
files are stored in your Mac's file system. They're typically somewhere
along the lines of
`~/Library/Developer/CoreSimulator/Devices/???????/data/Containers/Data/Application/???????/Documents/mongodb-realm/???????/????????/???????.realm`.

The scientific way to find the file's location is to add some extra code
to your app or to use a breakpoint.

While my app's in development, I'll normally print the location of a
Realm's file whenever I open it. Don't worry if you're not explicitly
opening your Realm(s) in your code (e.g., if you're using the default
realm) as I'll cover the file search approach soon. This is the code to
add to your app once you've opened your realm – `realm`:

``` swift
print("User Realm User file location: \(realm.configuration.fileURL!.path)")
```

If you don't want to edit the code, then an Xcode breakpoint delivers
the same result:

![XCode breakpoint to find realm file](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/xcode-breakpoint-to-find-realm-file.png)

Once you have the file location, open it in Realm Studio from the
terminal:

``` bash
open /Users/andrew.morgan/Library/Developer/CoreSimulator/Devices/E7526AFE-E886-490A-8085-349C8E8EDC5B/data/Containers/Data/Application/C3ADE2F2-ABF0-4BD0-9F47-F21894E850DB/Documents/mongodb-realm/rchat-saxgm/60099aefb33c57e9a9828d23/%22user%3D60099aefb33c57e9a9828d23%22.realm
```

Less scientific but simpler is to take advantage of the fact that the
data files will always be of type `realm` and located somewhere under
`~/Library/Developer/CoreSimulator/Devices`. Open Finder in that folder:
`open ~/Library/Developer/CoreSimulator/Devices` and then create a
"saved search" so that you can always find all of your realm files.
You'll most often be looking for the most recent one.

![Create saved search](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/Create-Saved-Search.gif)

The nice thing about this approach is that you only need to create the
search once. Then click on "Realms," find the file you need, and then
double-click it to open it in Realm Studio.

### Track Down Realm Data Files – Real iOS Devices

Unfortunately, you can't use Realm Studio to interact with live Realm
files on a real iOS device.

What we can do is download a copy of your app's Realm files from your
iOS device to your laptop. You need to connect your iOS device to your
Mac, agree to trust the computer, etc.

Once connected, you can use Xcode to download a copy of the "Container"
for your app. Open the Xcode device manager—"Window/Devices and
Simulators." Find your device and app, then download the container:

![Download iOS app container](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/Download-iOS-app-container.gif)

Note that you can only access the containers for apps that you've built
and installed through Xcode, not ones you've installed through the App
Store.

Right-click the downloaded file and "Show Package Contents." You'll find
your Realm files under
`AppData/Documents/mongodb-realm/<app-name>/?????`. Find the file for
the realm you're interested in and double-click it to open it in Realm
Studio.

### View Realm Data

After opening a Realm file, Realm Studio will show a window with all of
the top-level Realm Object classes in use by your app. In this example,
the realm I've opened only contains instances of the `Chatster` class.
There's a row for each `Chatster` Object that I'd created through the
app:

![Top level chatster view](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/top-level-chatster-view.png)

If there are a lot of objects, then you can filter them using a simple
[query
syntax](https://docs.mongodb.com/realm-legacy/docs/javascript/latest/api/tutorial-query-language.html):

![Janey search](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/Janey-search.png)

If the Realm Object class contains a `List` or an `EmbeddedObject`, then
they will show as blue links—in this example, `conversations` and
`userPreferences` are a list of `Conversation` objects and an embedded
`UserPreferences` object respectively:

![User object](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/user-object.png)

Clicking on one of the `UserPreferences` links brings up the contents of
the embedded object:

![User preferences object](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/user-preferences-object.png)

### Add, Modify, and Delete Data

The ability to view your Realm data is invaluable for understanding
what's going on inside your app.

Realm Studio takes it a step further by letting you add, modify, and
delete data. This ability helps to debug and test your app.

As a first example, I click on "Create ChatMessage" to add a new message
to a conversation:

![Create chat message button](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/create-chatmessage-button.png)

Fill out the form and click "Create" to add the new `ChatMessage`
object:

![Create new message](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/create-new-message.png)

We can then observe the effect of that change in our app:

![Add message](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/add-message.gif)

I could have tested that change using the app, but there are different
things that I can try using Realm Studio.

I haven't yet included the ability to delete or edit existing messages,
but I can now at least test that this view can cope when the data
changes:

![Modify chat objects](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/modify-chat-objects.gif)

## Summary

In this article, we've seen how to find and open your iOS Realm data
files in Realm Studio. We've viewed the data and then made changes and
observed the iOS app reacting to those changes.

Realm Studio has several other useful features that I haven't covered
here. As it's a GUI, it's fairly easy to figure out how to use them, and
the [docs](https://docs.realm.io/sync/realm-studio) are available if you
get stuck. These functions include:

-   Import data into Realm from a CSV file.
-   Export your Realm data as a JSON file.
-   Edit the schema.
-   Open the Realm file from an app and export the schema in a different
    language. We used this for the [WildAid O-FISH
    project](https://github.com/wildaid). I created the schema in the
    iOS app, and another developer exported a Kotlin version of the
    schema from Realm Studio to use in the Android app.

## References

-   [GitHub Repo for RChat App](https://github.com/ClusterDB/RChat).
-   Read [Building a Mobile Chat App Using Realm – Data Architecture](/how-to/realm-swiftui-ios-chat-app) to understand the data model and partitioning strategy behind the RChat app.
-   Read [Building a Mobile Chat App Using Realm – Integrating Realm into Your App](/how-to/building-a-mobile-chat-app-using-realm) to learn how to create the RChat app.
-   If you're building your first SwiftUI/Realm app, then check out [Build Your First iOS Mobile App Using Realm, SwiftUI, & Combine](/how-to/realm-swiftui-combine-first-app).
-   [GitHub Repo for Realm-Cocoa SDK](https://github.com/realm/realm-cocoa).
-   [Realm Cocoa SDK documentation](https://realm.io/docs/swift/latest/).
-   [MongoDB's Realm documentation](https://docs.mongodb.com/realm/).

>
>
>If you have questions, please head to our [developer community
>website](https://community.mongodb.com/) where the MongoDB engineers and
>the MongoDB community will help you build your next big idea with
>MongoDB.
>
>


Discover how to access and manipulate your iOS App's Realm data using the Realm Studio GUI.

Accessing Realm Data on iOS Using Realm Studio

It's a MongoDB axiom that you get the best performance and scalability by storing together the data that's most commonly accessed together.

The simplest and most obvious approach to achieve this is to embed all related data into a single document. This works great in many cases, but there are a couple of scenarios where it can become inefficient:

* (Very) many to many relationships. This can lead to duplicated data. This duplication is often acceptable — storage is comparatively cheap, after all. It gets more painful when the duplicated data is frequently modified. You then have the cost of updating every document which embeds that data.
* Reading small parts of large documents. Even if your query is only interested in a small fraction of fields in a document, the whole document is brought into cache — taking up memory that could be used more effectively.
* Large, mutable documents. Whenever your application makes a change to a document, the entire document must be written back to disk at some point (could be combined with other changes to the same document). WiredTiger writes data to disk in 4 KB blocks after compression — that typically maps to a 16-20 KB uncompressed document. If you're making lots of small edits to a 20+ KB document, then you may be wasting disk IO.

If embedding all of the data in a single document isn't the right pattern for your application, then consider the single-collection design. The single-collection pattern can deliver comparable read performance to embedded documents, while also optimizing for updates.

There are variants on the single-collection pattern, but for this post, I focus on the key aspects:

* Related data that's queried together is stored in the same collection.
* The documents can have different structures.
* Indexes are added so that all of the data for your frequent queries can be fetched with a single index lookup.

At this point, your developer brain may be raising questions about how your application code can cope with this. It's common to read the data from a particular collection, and then have the MongoDB driver convert that document into an object of a specific class. How does that work if the driver is fetching documents with different shapes from the same collection? This is the primary thing I want to demonstrate in this post. 

I'll be using Swift, but the same principles apply to other languages. To see how to do this with Java/Spring Data, take a look at [Single-Collection Designs in MongoDB with Spring Data](https://www.mongodb.com/developer/languages/java/java-single-collection-springpart1/).

## Running the example code

I recently started using the [MongoDB Swift Driver](https://www.mongodb.com/docs/drivers/swift/) for the first time. I decided to build a super-simple Mac desktop app that lets you browse your collections (which [MongoDB Compass](https://www.mongodb.com/products/compass) does a **much** better job of) and displays Change Stream events in real time (which Compass doesn't currently do).

You can download the code from the [Swift-Change-Streams repo](https://github.com/mongodb-developer/Swift-Change-Streams). Just build and run from Xcode.

Provide your connection-string and then browse your collections. Select the "Enable change streams" option to display change events in real time.

![A simple desktop browser, connecting to a MongoDB cluster, browsing the collections, and enabling Change Streams. We then see change-stream events shown in the tool. Changes showup as a yellow JSON document which shows the changes as well as the new doc. Inserts show as green, and deletes as red.
](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Mongo_DB_swift_a13687ce13.gif)

The app will display data from most collections as generic JSON documents, with no knowledge of the schema. There's a special case for a collection named "Collection" in a database named "Single" — we'll look at that next.

### Sample data

The Simple.Collection collection needs to contain these (or similar) documents:

```json
{ _id: 'basket1', docType: 'basket', customer: 'cust101' }
{ _id: 'basket1-item1', docType: 'item', name: 'Fish', quantity: 5 }
{ _id: 'basket1-item2', docType: 'item', name: 'Chips', quantity: 3 }
```

This data represents a shopping basket with an `_id` of "basket1". There are two items associated with `basket1 — basket1-item1` and `basket1-item2`. A single query will fetch all three documents for the basket (find all documents where `_id` starts with "basket1"). There is always an index on the `_id` attribute, and so that index will be used.

Note that all of the data for a basket in this dataset is extremely small — **well** below the 16-20K threshold — and so in a real life example, I'd actually advise embedding everything in a single document instead. The single-collection pattern would make more sense if there were a large number of line items, and each was large (e.g., if they embedded multiple thumbnail images).

Each document also has a `docType` attribute to identify whether the document refers to the basket itself, or one of the associated items. If your application included a common query to fetch just the basket or just the items associated with the basket, then you could add a composite index: `{ _id: 1, docType: 1}`.

Other uses of the `docType` field include:

* A prompt to help humans understand what they're looking at in the collection.
* Filtering the data returned from a query to just certain types of documents from the collection.
* Filtering which types of documents are included when using MongoDB Compass to examine a collection's schema.
* Allowing an application to identify what type of document its received. The application code can then get the MongoDB driver to unmarshal the document into an object of the correct class. This is what we'll look at next.

### Handling different document types from the same collection

We'll use the same desktop app to see how your code can discriminate between different types of documents from the same collection.

The app has hardcoded knowledge of what a basket and item documents looks like. This allows it to render the document data in specific formats, rather than as a JSON document:

![The desktop tool is showing documents from the "Single.Collection" collection. Rather than showing the document as generic JSON, the app shows tiles for the basket and for each of the 2 items. Each tile renders data from the associated document in a format that makes sense for that document type.
](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/different_doc_types_2fb553a6ab.png)

The code to determine the document `docType` and convert the document to an object of the appropriate class can be found in [CollectionView.swift](https://github.com/mongodb-developer/Swift-Change-Streams/blob/main/MongoDBSwift/Views/CollectionView.swift). 

CollectionView fetches all of the matching documents from MongoDB and stores them in an array of `BSONDocument`s:

```swift
@State private var docs = [BSONDocument]()
```

The application can then loop over each document in `docs`, checks the `docType` attribute, and then decides what to do based on that value:

```swift
List(docs, id: \.hashValue) { doc in
    if path.dbName == "Single" && path.collectionName == "Collection" {      
        if let docType = doc["docType"] {
            switch docType {
            case "basket":
                if let basket = basket(doc: doc) {
                    BasketView(basket: basket)
                }
            case "item":
                if let item = item(doc: doc) {
                    ItemView(item: item)
                }
            default:
                Text("Unknown doc type")
            }
        }
    } else {
        JSONView(doc: doc)
    }
}
```

If `docType == "basket"`, then the code converts the generic doc into a `Basket` object and passes it to `BasketView` for rendering.

This is the `Basket` class, including initializer to create a `Basket` from a `BSONDocument`: 

```swift
struct Basket: Codable {
    let _id: String
    let docType: String
    let customer: String
    
    init(doc: BSONDocument) {
        do {
            self = try BSONDecoder().decode(Basket.self, from: doc)
        } catch {
            _id = "n/a"
            docType = "basket"
            customer = "n/a"
            print("Failed to convert BSON to a Basket: \(error.localizedDescription)")
        }
    }
}
```

Similarly for `Item`s:

```swift
struct Item: Codable {
    let _id: String
    let docType: String
    let name: String
    let quantity: Int
    
    init(doc: BSONDocument) {
        do {
            self = try BSONDecoder().decode(Item.self, from: doc)
        } catch {
            _id = "n/a"
            docType = "item"
            name = "n/a"
            quantity = 0
            print("Failed to convert BSON to a Item: \(error.localizedDescription)")
        }
    }
}
```

The sub-views can then use the attributes from the properly-typed object to render the data appropriately:

```swift
struct BasketView: View {
    let basket: Basket
    
    var body: some View {
        VStack {
            Text("Basket")
                .font(.title)
            Text("Order number: \(basket._id)")
            Text("Customer: \(basket.customer)")
        }
        .padding()
        .background(.secondary)
        .clipShape(RoundedRectangle(cornerRadius: 15.0))
    }
}
```

```swift
struct ItemView: View {
    let item: Item
    
    var body: some View {
        VStack {
            Text("Item")
                .font(.title)
            Text("Item name: \(item.name)")
            Text("Quantity: \(item.quantity)")
        }
        .padding()
        .background(.secondary)
        .clipShape(RoundedRectangle(cornerRadius: 15.0))
    }
}
```

### Conclusion

The single-collection pattern is a way to deliver read and write performance when embedding or [other design patterns](https://learn.mongodb.com/courses/m320-mongodb-data-modeling) aren't a good fit.

This pattern breaks the 1-1 mapping between application classes and MongoDB collections that many developers might assume. This post shows how to work around that:

* Extract a single docType field from the BSON document returned by the MongoDB driver.
* Check the value of docType and get the MongoDB driver to map the BSON document into an object of the appropriate class.

Questions? Comments? Head over to our [Developer Community](https://www.mongodb.com/community/forums/) to continue the conversation!

You can improve application performance by storing together data that’s accessed together. This can be done through embedding sub-documents, or by storing related documents in the same collection — even when they have different shapes. This post explains how to work with these polymorphic MongoDB collections from your Swift app.

Working with the MongoDB Single-Collection Pattern in Swift

My day job is to work with our biggest customers to help them get the best out of MongoDB when creating new applications or migrating existing ones. Their use cases often need side effects to be run whenever data changes — one of the most common requirements is to maintain an audit trail.

When customers are using MongoDB Atlas, it's a no-brainer to recommend [Atlas Triggers](https://www.mongodb.com/docs/atlas/triggers/). With triggers, you provide the code, and Atlas makes sure that it runs whenever the data you care about changes. There's no need to stand up an app server, and triggers are very efficient as they run alongside your data.

Unfortunately, there are still some workloads that customers aren't ready to move to the public cloud. For these applications, I recommend [change streams](https://www.mongodb.com/docs/manual/changeStreams/). Change streams are the underlying mechanism used by Triggers and many other MongoDB technologies — Kafka Connector, Charts, Spark Connector, Atlas Search, anything that needs to react to data changes.

Using change streams is surprisingly easy. Ask the MongoDB Driver to open a change stream and it returns a database cursor. Listen to that cursor, and your application receives an event for every change in your collection.

This post shows you how to use change streams from a Swift application. The principles are exactly the same for other languages. You can find a lot more on change streams at [Developer Center](https://www.mongodb.com/developer/products/mongodb/change-streams/).

## Running the example code

I recently started using the [MongoDB Swift Driver](https://www.mongodb.com/docs/drivers/swift/) for the first time. I decided to build a super-simple Mac desktop app that lets you browse your collections (which [MongoDB Compass](https://www.mongodb.com/products/compass) does a **much** better job of) and displays change stream events in real time (which Compass doesn't currently do).

You can download the code from the [Swift-Change-Streams repo](https://github.com/mongodb-developer/Swift-Change-Streams). Just build and run from Xcode.

Provide your connection-string and then browse your collections. Select the "Enable change streams" option to display change events in real time.

![A simple desktop browser, connecting to a MongoDB cluster, browsing the collections, and enabling Change Streams. We then see change-stream events shown in the tool. Changes showup as a yellow JSON document which shows the changes as well as the new doc. Inserts show as green, and deletes as red.
](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Mongo_DB_swift_a13687ce13.gif)

### The code

You can find this code in [CollectionView.swift](https://github.com/mongodb-developer/Swift-Change-Streams/blob/main/MongoDBSwift/Views/CollectionView.swift).

We need a variable to store the change stream (a database cursor)

```swift
@State private var changeStream: ChangeStream<ChangeStreamEvent<BSONDocument>>?
```

as well as one to store the latest change event received from the change stream (this will be used to update the UI):

```swift
@State private var latestChangeEvent: ChangeStreamEvent<BSONDocument>?
```

The `registerChangeStream` function is called whenever the user checks or unchecks the change stream option:

```swift
func registerChangeStream() async {
    // If the view already has an active change stream, close it down
    if let changeStream = changeStream {
        _ = changeStream.kill()
        self.changeStream = nil
    }
    if enabledChangeStreams {
        do {
            let changeStreamOptions = ChangeStreamOptions(fullDocument: .updateLookup)
            changeStream = try await collection?.watch(options: changeStreamOptions)
            _ = changeStream?.forEach({ changeEvent in
                withAnimation {
                    latestChangeEvent = changeEvent
                    showingChangeEvent = true
                    Task {
                        await loadDocs()
                    }
                }
            })
        } catch {
            errorMessage = "Failed to register change stream: \(error.localizedDescription)"
        }
    }
}
```

The function specifies what data it wants to see by creating a `ChangeStreamOptions` structure — you can see the available options in the [Swift driver docs](https://mongodb.github.io/mongo-swift-driver/docs/current/MongoSwift/Structs/ChangeStreamOptions.html). In this app, I specify that I want to receive the complete new document (in addition to the deltas) when a document is updated. Note that the full document is always included for insert and replace operations.

The code then calls `watch` on the current collection. Note that you can also [provide an aggregation pipeline as a parameter](https://www.mongodb.com/docs/manual/changeStreams/#modify-change-stream-output) named `pipeline` when calling `watch`. That pipeline can filter and reshape the events your application receives.

Once the asynchronous watch function completes, the `forEach` loop processes each change event as it's received.

When the loop updates our `latestChangeEvent` variable, the change is automatically propagated to the `ChangeEventView`:

```swift
 ChangeEventView(event: latestChangeEvent)
```

You can see all of the code to display the change event in [`ChangeEventView.swift`](https://github.com/mongodb-developer/Swift-Change-Streams/blob/main/MongoDBSwift/Views/ChangeEventView.swift). I'll show some highlights here.

The view receives the change event from the enclosing view (`CollectionView`):

```swift
let event: ChangeStreamEvent<BSONDocument>
```

The code looks at the `operationType` value in the event to determine what color to use for the window:

```swift
var color: Color {
    switch event.operationType {  
    case .insert:
        return .green
    case .update:
        return .yellow
    case .replace:
        return .orange
    case .delete:
        return .red
    default:
        return .teal
    }
}
```

`documentKey` contains the `_id` value for the document that was changed in the MongoDB collection:

```swift
if let documentKey = event.documentKey {
   ...
        Text(documentKey.toPrettyJSONString())
   ...
    }
}
```

If the database operation was an update, then the delta is stored in `updateDescription`:

```swift
if let updateDescription = event.updateDescription {
    ...
        Text(updateDescription.updatedFields.toPrettyJSONString())
    ...
    }
}
```

The complete document after the change was applied in MongoDB is stored in `fullDocument`:

```swift
if let fullDocument = event.fullDocument {
    ...
        Text(fullDocument.toPrettyJSONString())
    ...
    }
}
```

If the processing of the change events is a critical process, then you need to handle events such as your process crashing. 

The `_id.resumeToken` in the `ChangeStreamEvent` is a token that can be used when starting the process to continue from where you left off. Simply provide this token to the [`resumeAfter`](https://mongodb.github.io/mongo-swift-driver/docs/current/MongoSwift/Structs/ChangeStreamOptions.html#/s:10MongoSwift19ChangeStreamOptionsV11resumeAfterAA11ResumeTokenVSgvp) or [`startAfter`](https://mongodb.github.io/mongo-swift-driver/docs/current/MongoSwift/Structs/ChangeStreamOptions.html#/s:10MongoSwift19ChangeStreamOptionsV10startAfterAA11ResumeTokenVSgvp) options when opening the change stream. Note that this assumes that the events you've missed haven't rotated out of the [Oplog](https://www.mongodb.com/docs/manual/core/replica-set-oplog/).

### Conclusion

Use Change Streams (or Atlas triggers, if you're able) to simplify your code base by decoupling the handling of side-effects from each place in your code that changes data.

After reading this post, you've hopefully realized just how simple it is to create applications that react to data changes using MongoDB Change Streams. Questions? Comments? Head over to our [Developer Community](https://www.mongodb.com/community/forums/tags/c/data/drivers-odms/7/swift) to continue the conversation!

Change streams let you run your own logic when data changes in your MongoDB collections.  This post shows how to consume MongoDB change stream events from your Swift app.