Docs Menu

Docs HomeAtlas App Services

Data Model Mapping

On this page

  • Overview
  • Databases, Collections, and Objects
  • Mapping with Development Mode
  • Mappings
  • Type Name
  • Property Types
  • Array Properties
  • Embedded Objects
  • Sets
  • Dictionaries
  • Relationships
  • Example
  • App Services Schema
  • Realm Object Schema
  • Data in Atlas

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.

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.

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.

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.

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:

  • boolean

  • integer

  • double

  • string

  • date

  • decimal128

  • objectId

  • uuid

  • mixed

  • array

  • object

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.

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:

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 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.

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.

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:

For more information on modeling dictionaries in an App Services Schema, refer to Dictionary.

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.

This example shows how to model a Dog with Device Sync.

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"
}
}
}

The following code examples create the Dog Realm Object Schema in each of the Realm SDKs.

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"
}
←  Make Breaking Schema ChangesConfigure Atlas Device Sync →
Share Feedback
© 2023 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.