MongoDB Data Mapping

Ensure smooth data synchronization between MongoDB and ObjectBox by correctly mapping data and types.

The data model used by ObjectBox defines types, which are mapped to MongoDB collections. Similarly, the properties of a type are mapped to keys inside a MongoDB document. Thus, you should ensure that the ObjectBox data model matches the MongoDB schema. For example, if you have an existing MongoDB database, ensure to match the names when you create the ObjectBox model.

Objects and Documents

When you compare the data structure of simple data elements, the difference is not significant. Without nested data, the main difference you will note is the ID type.

Figure 1: ObjectBox Object vs. MongoDB Document (Simplified)

Note: nested documents are supported via the ObjectBox "flex properties" type or JSON strings. See the section below for details.

ID mapping

ObjectBox Sync automatically maps IDs when syncing with an external system like MongoDB. This way, you can use the native IDs in each system: 64-bit integer IDs in ObjectBox and, for example, 12-byte object IDs in MongoDB. This also means that the MongoDB ID is not present in ObjectBox objects and vice versa.

ObjectBox IDs are only valid on their local device. Do not store them manually (apart from relations) e.g. as a custom list or vector, when you want to sync to other devices. For details, you can refer to the internal ID mapping docs that occurs on each ObjectBox device.

Special ID types

If you only use standard MongoDB object IDs, you do not need to do anything special. This section is only relevant if you want to use other ID types.

ObjectBox supports most common ID types offered by MongoDB. IDs of incoming documents from MongoDB are automatically detected and mapped to ObjectBox local IDs. This mapping is persisted, and thus any change made on the ObjectBox side can be mapped back to the initial ID type and value.

For newly created (inserted) objects on the ObjectBox side, a new MongoDB object ID (OID) is created by default. You can customize the MongoDB ID types in the ObjectBox data model: for the ID property, define an "external property type" on the ID property. Then, ObjectBox will create a new UUID-based ID for the MongoDB document.

Java

@ExternalType(ExternalPropertyType.UUID)
private byte[] externalId;

Recommended types for IDs: UUID (UUIDv7), UUIDString (UUIDv7 as string), UUIDV4, UUIDV4String.

Swift

// objectbox: externalType="uuid"
var externalId: Int

Recommended types for IDs: uuid (UUIDv7), uuidString (UUIDv7 as string), uuidV4, uuidV4String.

Dart/Flutter

  @Id()
  @ExternalType(type: ExternalPropertyType.uuid)
  int id = 0;

Recommended types for IDs: uuid (UUIDv7), uuidString (UUIDv7 as string), uuidV4, uuidV4String.

The following table shows the supported ID types:

MongoDB type	Incoming from MongoDB	IDs for new documents created in ObjectBox
Object ID	✅	✅ This is the default type
UUID (Binary with UUID subtype)	✅	✅ External types: Uuid (V7) or UuidV4
String	✅	✅ External types: UuidString (V7) or UuidV4String
Binary	✅	Uses default MongoDB Object ID
Int64	✅	Uses default MongoDB Object ID
Int32	✅	Uses default MongoDB Object ID

To-One Relations

If you want to learn more about ObjectBox relations, check the relation documentation.

ObjectBox Sync also automatically maps IDs used in relations.

Consider ObjectBox to-one relations, which have a single relation property pointing to another object using a 64-bit integer ID. This becomes a reference field in MongoDB's document containing the MongoDB object ID (OID). See the following illustration for an example:

Figure 2: To-One Relationship Example (motherId)

The supported ID types also apply for relations. For example, if a "Person" document uses a UUID as its _id field value, relations to it would also use the UUID as the relation ID on the MongoDB side.

Many-to-Many Relations

Many-to-many relations work a bit differently. As illustrated in the table above, many-to-many relations work differently in ObjectBox and MongoDB. For mapping between them, the following rules apply:

• On the MongoDB side, many-to-many relations are stored as an array of ID references:

  • The IDs are stored inside the document "owning" the relationship.

  • The owning side of a relationship is always the same type (collection).

  • If you want to, you can make this relation bidirectional by adding IDs to the "target side" of the relationship. Do not make this visible in the ObjectBox data model.

• On the ObjectBox side, its native many-to-many relationships are used:

  • They are bidirectional, e.g. you can define it on the owning and target side.

  • They can be updated efficiently without touching the object.

  • They can be used in queries to link types (aka join).

As to-many relations consist of ID values, all supported types can be used. In theory, different ID types can be used in the same to-many relation. However, it is usually good practice to stick to a single ID type per MongoDB collection if possible.

Nested Documents

MongoDB documents are key-value pairs. And because values may be documents, it is possible to have documents inside a document. This is known as "nested documents", "embedded documents" or "sub documents". ObjectBox offers two ways to handle this: flex properties and JSON strings.

The following table shows the current support for the two variants per programming language:

Programming Language	Flex	JSON String
Java	✅	✅
Kotlin	✅	✅
Swift		✅
Dart/Flutter		✅
C and C++		(✅)*

*) C and C++ via API (Generator support is pending)

Flex Properties Mapping

To map nested documents with flex properties, you define maps with string keys in your entity definition directly on the ObjectBox side:

Java

@Nullable Map<String, Object> stringMap;

Kotlin

var myStringMap: MutableMap<String, Any?>? = null

Flex properties characteristics and notes:

• Directly access the data as maps in your code

• Nested documents and arrays are supported

• The precision of integer types on the MongoDB side may change, e.g. Int32 to Long (64-bit)

• The order of keys is not preserved

JSON String Mapping

An alternative is to store the nested document as a JSON string on the ObjectBox side. This is done with a standard string property and the external property type "JSON to native". Thus, on the ObjectBox side, you can use a JSON API of your choice to access the nested document.

Java

@ExternalType(ExternalPropertyType.JSON_TO_NATIVE)
private String myNestedDocumentJson;

Kotlin

@ExternalType(ExternalPropertyType.JSON_TO_NATIVE)
var name: String? = myNestedDocumentJson

Dart/Flutter

@ExternalType(type: ExternalPropertyType.jsonToNative)
String? myNestedDocumentJson;

Swift

// objectbox: externalType="jsonToNative"
var myNestedDocumentJson: String?

JSON string characteristics and notes:

• JSON API to access the data

• Nested documents and arrays are supported

• The precision of integer types on the MongoDB side may change, e.g. Int32 to Long (64-bit)

• The order of keys is preserved

Heterogeneous Arrays

Homogeneous arrays (all values of the same type) are mapped automatically by ObjectBox.

Similar to nested documents, arrays with values of different types can be used inside a MongoDB document. This is supported in ObjectBox and MongoDB. The same rules apply as for nested documents.

Flex Properties Mapping

To map nested arrays, you define lists in your entity definition directly on the ObjectBox side:

Java

@Nullable List<Object> myArray;

Kotlin

var myArray: MutableList<Any?>? = null

JSON String Mapping

Exactly the same approach as for nested documents applies (see above). Instead of a JSON object, a JSON array is used.