Docs Home → Atlas App Services
Data Model Mapping
On this page
Overview
This page contains information on how the App Services Schema used by Atlas Device Sync maps to the Realm Object Schema used by the Realm SDKs.
To generate Realm SDK Schemas from your App Services Schemas, refer to Generate SDK Object Models. To generate App Services Schemas from Realm SDK client code, refer to Development Mode.
To learn more about how Device Sync uses these two schemas, refer to the Sync Data Model Overview.
Databases, Collections, and Objects
When you configure Device Sync, you specify the data source where you want to store data. This data source may contain multiple databases, and each database may contain multiple collections.
The App Services schema maps your Realm Database object
names to collections in databases in your Device Sync data source. The
title field in an App Services schema maps to the object type name in
Realm Database. Because the title name determines the mapping between
client objects and the appropriate Atlas collection, this name must be
unique among all schemas in your synced data source.
The title does not need to match the collection name.
Example
Consider an app with a database named Pets. It may contain multiple
collections, such as Canine and Feline. The App Services schema
for the Canine collection might resemble the example below, where the title field of
the schema is Dog. That would map a Realm Database object called
Dog to the Canine collection in the Pets database.
You could not have another schema whose title was Dog in the
same cluster. For example, you could not sync an object with a title
of Dog to both a Debug and a Test database in the
same cluster. If you want to sync the same object to different
collections for app development purposes, you must use different
data sources - one cluster for development and a different cluster
for production.
Mapping with Development Mode
When you enable Development Mode in your Device Sync configuration, App Services can automatically create collections and schemas for Realm Database objects that you sync. It creates those collections in the database you specify when you enable Development Mode.
With Development Mode enabled, Sync looks for a collection whose App Services
schema has a title that matches the name of your Realm Database object
type. This collection could be in any database in your linked data source.
It doesn't have to be in the database you add when you configure
Development Mode.
If there is no corresponding title in any App Services schema in your
linked data source, App Services creates a new collection for this object
type. This collection is created in the database you specify when you enable
Development Mode. The collection name matches the object's type, and the
corresponding App Services schema has a title field whose value is the
name of the object type. This creates the mapping between your Realm
Database object and the new collection.
Example
Consider an Atlas cluster with a database named Pets. It contains a
Feline collection with existing data.
In your application code, you define a new Dog object. You enable
Development Mode, and specify the Pets database as the database
in which to create collections for new object types. When you sync your
new Dog object, App Services creates a Dog collection in the
Pets database and creates a schema for it. The title of the
object in the schema is Dog.
If you later add a new Person object to your application code and
then sync it, App Services creates a new collection for this
Person object in the Pets database. If you wanted to create a
collection for the Person object in a different database, you
could define a schema for the Person object
in a different database. Or you could disable and re-enable Development
Mode, and select a different database in which to create new collections.
Mappings
Type Name
The title field contains the name of the object type represented by
the schema. This is equivalent to a class or schema name in a Realm SDK.
The type name must be unique among all schemas in your synced cluster
but is otherwise arbitrary and does not need to match the collection
name.
A conventional approach is to name each object type with a singular noun, like "Dog" or "Person". Schemas generated in development mode or by sampling existing documents use this convention.
Note
To work with Atlas Device Sync, type names cannot exceed 57 UTF-8 characters.
Property Types
You can configure the following constraints for a given property:
Parameter | Type | Description |
|---|---|---|
Type | String | Every property in a Realm Object Schema has a strongly defined data type. A property's type can be a primitive data type or an object type defined in the same Realm Object Schema. The type also specifies whether the property contains a single value or a list of values. Realm Database supports the following property types:
For more information on supported data types, refer to Schema Types. |
Optional | Boolean | Optional properties may contain a null value or be entirely
omitted from an object. By default, all properties are optional
unless explicitly marked as required. |
Default | Boolean | If a client application creates a new object that does not have a value for a defined property, the object uses the default value instead. If you open a Realm in the client with a schema subset that doesn't include a required property, the server will automatically populate the value of the required property with a zero or blank default value. When you attempt to create an object that is missing a value for a required field, it fails validation and does not persist to the realm. |
Indexed | Boolean | A property index significantly increases the speed of certain
read operations at the cost of additional overhead for write
operations. Indexes are particularly useful for equality
comparison, such as querying for an object based on the value of
a property. However, indexes consume additional storage. |
Realm SDK data type documentation:
Array Properties
Both Realm Object Schemas and App Services Schemas support array properties.
You can find information on using array data types in the Realm SDK documentation on defining a Realm Object Schema.
For more information on modeling array properties in an App Services Schema, refer to BSON Types - Array. App Services Schemas support certain constraints that Realm Object Schemas do not, such as specifying the minimum and maximum number of items.
Embedded Objects
Embedded objects are embedded as nested data inside of a parent object. An embedded object inherits the lifecycle of its parent object. It cannot exist as an independent Realm object.
Realm SDK embedded object documentation:
For more information on modeling to-one relationships in an App Services Schema, refer to Embedded Object Relationships.
Sets
Realm Object Schemas and App Services Schemas both support the Set data type. A set is a collection of unique values.
Realm SDK Set documentation:
For more information on modeling sets in an App Services Schema, refer to Set.
Dictionaries
Realm Object Schemas and App Services Schemas both support the Dictionary data type. A set is a collection of unique values. A dictionary is a collection of dynamic and unique string keys paired with values of a given type. A dictionary is functionally an object or document without pre-defined field names.
Realm SDK dictionary documentation:
The Realm Flutter SDK does not support Dictionaries yet
For more information on modeling dictionaries in an App Services Schema, refer to Dictionary.
Relationships
Realm Object Schemas support the following types of relationships:
To-one relationships: A to-one relationship means that an object is related in a specific way to no more than one other object.
To-many relationships: A to-many relationship means that an object is related in a specific way to multiple objects.
Inverse relationships: An inverse relationship links an object back to any other objects that refer to it in a defined to-one or to-many relationship.
App Services Schemas support to-one and to-many relationships. App Services Schemas do not support inverse relationships.
Realm SDK relationship documentation:
For more information on modeling relationships in an App Services Schema, refer to Relationships.
Example
This example shows how to model a Dog with Device Sync.
App Services Schema
This App Services Schema creates the Dog data model used by Device Sync.
{ "title": "Dog", "bsonType": "object", "required": [ "_id", "_partition", "name" ], "properties": { "_id": { "bsonType": "objectId" }, "_partition": { "bsonType": "string" }, "name": { "bsonType": "string" }, "age": { "bsonType": "int" } "breed": { "bsonType": "string" } } }
Realm Object Schema
The following code examples create the Dog Realm Object Schema in each of the
Realm SDKs.
Data in Atlas
An application using Device Sync for the Dog data model creates MongoDB documents
in Atlas that looks like the following example.
{ "_id": ObjectId('616f44305a205add93ff1081'), "age": 8, "breed": "Golden Retriever", "name": "Jasper" }