Model Data with Device Sync - Kotlin SDK

Generate a Schema from the Client App

If you are developing a new client application, you likely want to iterate on the data model in the client app. After you define an object model directly in your client app code, you can enable Development Mode in App Services to generate a matching App Services schema automatically.

Development Mode is a configuration setting that allows Device Sync to infer and update schemas based on client-side data models when you sync data from the client. For more information, refer to Development Mode in the App Services documentation.

Generate a Schema with Existing Atlas Data

If you are developing a client application that works with data that already exists in Atlas, you can generate a schema from that data, and then generate SDK object models to use in your Kotlin client app. To learn more, refer to Sync Data in Atlas with a Client Application in the App Services documentation.

Map To-One Relationships

A to-one relationship relationship maps one property to a single instance of another Realm object. To-one relationships must be optional. For more information on how to-one relationships are defined in Kotlin SDK, refer to Define a To-One Relationship Property.

Using the objects in the example above, consider a case where a Frog can have one favorite pond. We can add a favoritePond property to our Frog model that is an optional link to a Pond object.

class Frog : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var age: Int? = null
    // To-one relationship (MUST be optional)
    var favoritePond: Pond? = null
}

In the App Services schema, we see the new property translates to a field favoritePond:

• The field is not in the required array because it is an optional property.

• Its type is an objectId that links to a specific Pond object in the separate Pond collection. This is because we defined the primary key on our Pond model as an objectId.

The Pond schema doesn't change. Because this is a to-one relationship, it's a one-way relationship; the Pond has no relationship back to Frog.

{
  "title": "Frog",
  "type": "object",
  "required": [
    "_id",
    "name"
  ],
  "properties": {
    "_id": {
      "bsonType": "objectId"
    },
    "age": {
      "bsonType": "long"
    },
    "favoritePond": {
      "bsonType": "objectId"
    },
    "name": {
      "bsonType": "string"
    }
  }
}

To-Many Relationship

A to-many relationship relationship maps one property to zero or more instances of another Realm object. For more information on how to-many relationships are defined in Kotlin SDK, refer to Define a To-Many Relationship Property.

Consider another case where a Frog can have many favorite ponds instead of only one. We add a favoritePonds property to our Frog model that is a list of Pond objects. If the frog has no favorite ponds, this is an empty list. As the frog gets favorite ponds, we can create new Pond objects and append them to the frog's favoritePonds list.

class Frog : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var age: Int? = null
    // To-many relationship (can have many ponds)
    var favoritePonds: RealmList<Pond> = realmListOf()
}

In the App Services schema, we see the new property translates to a favoritePonds field that contains all of the Pond objects related to the Frog object:

• The field is not in the required array because it is an optional property.

• The type of this field is an array of type objectId. This is because we defined the primary key on our Pond model as an objectId.

Again, that the Pond schema doesn't change because the Pond has no relationship back to Frog.

{
  "title": "Frog",
  "type": "object",
  "required": [
    "_id",
    "name"
  ],
  "properties": {
    "_id": {
      "bsonType": "objectId"
    },
    "age": {
      "bsonType": "long"
    },
    "favoritePonds": {
      "bsonType": "array",
      "items": {
        "bsonType": "objectId"
      }
    },
    "name": {
      "bsonType": "string"
    }
  }
}

Inverse Relationship

An inverse relationship links an object back to any other objects that refer to it in a defined to-one or to-many relationship called a backlink. For more information on how inverse relationships are defined in Kotlin SDK, refer to Define an Inverse Relationship.

App Services schemas do not support inverse relationships. This is because inverse relationship represent an implicit relationship in Realm that is automatically updated when the backlink is modified. This means that you cannot directly set the value of an inverse relationship, and the relationship does not exist in Atlas. Instead, Realm derives and updates those relationships for you in the client application based on your Realm object model.

Consider a case where the Pond object has an inverse relationship to the Frog object.

class Pond : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    // Backlink to the `Frog` that has this `Pond` as its favorite
    val frog: RealmResults<Frog> by backlinks(Frog::favoritePonds)
}
class Frog : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var age: Int? = null
    // To-many relationship (can have many ponds)
    var favoritePonds: RealmList<Pond> = realmListOf()
}

In the App Services schema, we see the Frog has the to-many relationship to the Pond through the favoritePonds property. However, the frog property that represents the inverse relationship to a Frog from our Pond model is not present. This is because the inverse relationship cannot be explicitly defined in Atlas. However, Realm will update it automatically whenever you add or remove an object from the relationship.

// `Pond` schema in App Services DOES NOT contain the
// `frog` inverse relationship property
{
  "title": "Pond",
  "type": "object",
  "required": [
    "_id",
    "name"
  ],
  "properties": {
    "_id": {
      "bsonType": "objectId"
    },
    "name": {
      "bsonType": "string"
    }
  }
}
{
  "title": "Frog",
  "type": "object",
  "required": [
    "_id",
    "name"
  ],
  "properties": {
    "_id": {
      "bsonType": "objectId"
    },
    "age": {
      "bsonType": "long"
    },
    "favoritePonds": {
      "bsonType": "array",
      "items": {
        "bsonType": "objectId"
      }
    },
    "name": {
      "bsonType": "string"
    }
  }
}

Embedded Objects

Embedded objects represent nested data inside of a single, specific parent object. You can reference an embedded object type from parent object types in the same way as you would define a relationship. For more information on how embedded objects are defined in Kotlin SDK, refer to Define an Embedded Object.

However, unlike regular Realm objects, embedded objects are not stored in their own collection in Atlas. Instead, they are stored as part of the parent object's document and are not accessible outside of the parent object.

In the following example, we have a Frog object with a favoritePond property that references a single embedded Pond object and a Forest object with forestPonds relationship property that references a list of many embedded Pond objects:

class Frog : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var age: Int? = null
    // Embed a single object (MUST be optional)
    var favoritePond: EmbeddedPond? = null
}
class Forest : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    // Embed multiple objects (can have many ponds)
    var forestPonds: RealmList<EmbeddedPond> = realmListOf()
}
class EmbeddedPond : EmbeddedRealmObject {
    var name: String? = null
}

In the App Services schema, we see the embedded objects map to documents in each parent type:

{
  "title": "Frog",
  "type": "object",
  "required": [
    "_id",
    "name"
  ],
  "properties": {
    "_id": {
      "bsonType": "objectId"
    },
    "age": {
      "bsonType": "long"
    },
    "favoritePond": {
      "title": "EmbeddedPond",
      "type": "object",
      "required": [],
      "properties": {
        "name": {
          "bsonType": "string"
        }
      }
    },
    "name": {
      "bsonType": "string"
    }
  }
}
{
  "title": "Forest",
  "type": "object",
  "required": [
    "_id",
    "name"
  ],
  "properties": {
    "_id": {
      "bsonType": "objectId"
    },
    "forestPonds": {
      "bsonType": "array",
      "items": {
        "title": "EmbeddedPond",
        "type": "object",
        "required": [],
        "properties": {
          "name": {
            "bsonType": "string"
          }
        }
      }
    },
    "name": {
      "bsonType": "string"
    }
  }
}

Kotlin Types

The following table lists the supported Kotlin data types and examples of how the declared properties map between a Realm schema and an App Services schema.

For more information on the Kotlin data types supported by the Kotlin SDK and how to define them in your data model, refer to Kotlin Data Types.

var stringReq: String = ""

"stringReq": {
  "bsonType": "string"
}

var byteReq: Byte = 0

"byteReq": {
  "bsonType": "long"
}

var shortReq: Short = 0

"shortReq": {
  "bsonType": "long"
}

var intReq: Int = 0

"intReq": {
  "bsonType": "long"
}

var longReq: Long = 0L

"longReq": {
  "bsonType": "long"
}

var floatReq: Float = 0.0f

"floatReq": {
  "bsonType": "float"
}

var doubleReq: Double = 0.0

"doubleReq": {
  "bsonType": "double"
}

var boolReq: Boolean = false

"boolReq": {
  "bsonType": "bool"
}

var charReq: Char = 'a'

"charReq": {
  "bsonType": "long"
}

BSON Types

The following table lists the supported MongoDB BSON data types and examples of how the declared properties map between a Realm schema and an App Services schema.

For more information on the MongoDB BSON data types supported by the Kotlin SDK and how to define them in your data model, refer to Kotlin Data Types.

var objectIdReq: ObjectId = ObjectId()

"objectIdReq": {
  "bsonType": "objectId"
}

var decimal128Req: Decimal128 = Decimal128("123.456")

"decimal128Req": {
  "bsonType": "decimal"
}

Realm Types

The following table lists the supported Realm-specific data types and examples of how the declared properties map between a Realm schema and an App Services schema.

For more information on the Realm-specific data types supported by the Kotlin SDK and how to define them in your data model, refer to Kotlin Data Types.

var uuidReq: RealmUUID = RealmUUID.random()

"uuidReq": {
  "bsonType": "uuid"
}

var realmInstantReq: RealmInstant = RealmInstant.now()

"realmInstantReq": {
  "bsonType": "date"
}

var realmAnyOpt: RealmAny? = RealmAny.create("foo")

"realmAnyOpt": {
  "bsonType": "mixed"
}

var mutableRealmIntReq: MutableRealmInt = MutableRealmInt.create(0)

"mutableRealmIntReq": {
  "bsonType": "long"
}

var listReq: RealmList<CustomObjectType> = realmListOf()

"listReq": {
  "bsonType": "array",
  "items": {
    "bsonType": "uuid"
  }
}

var setReq: RealmSet<String> = realmSetOf()

"setReq": {
  "bsonType": "array",
  "uniqueItems": true,
  "items": {
    "bsonType": "string"
  }
}

var dictionaryReq: RealmDictionary<String> = realmDictionaryOf()

"dictionaryReq": {
  "bsonType": "object",
  "additionalProperties": {
    "bsonType": "string"
  }
}

var realmObjectPropertyOpt: CustomObjectType? = null

"realmObjectPropertyOpt": {
  "bsonType": "<PRIMARY_KEY_TYPE>"
}

var embeddedProperty: EmbeddedObjectType? = null

"embeddedProperty": {
  "title": "EmbeddedObjectType",
  "type": "object",
  "required": [],
  "properties": {
    "name": {
      "bsonType": "string"
    }
  }
}