ObjectBox Sync
Sync HomeBlogTwitterGitHub
  • Data Synchronization
  • Sync Client
  • ObjectBox Sync Server
  • Sync Server Configuration
    • JWT Authentication
  • Data model evolution
  • Sync Cluster
  • MongoDB Sync Connector
    • MongoDB Configuration
    • ObjectBox Sync Connector Setup
    • MongoDB Data Mapping
  • Advanced Sync
    • Object IDs and Sync
    • Embedded Sync Server
  • Troubleshooting Sync
  • GraphQL
    • GraphQL Queries
    • GraphQL Mutations
    • GraphQL Python Client
  • ObjectBox Database Developer Docs
    • Java, Kotlin, Flutter/Dart
    • C, C++
    • Swift
    • Go
Powered by GitBook
On this page
  • Objects and Documents
  • ID mapping
  • To-One Relations
  • Many-to-Many Relations

Was this helpful?

  1. MongoDB Sync Connector

MongoDB Data Mapping

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

PreviousObjectBox Sync Connector SetupNextAdvanced Sync

Last updated 3 days ago

Was this helpful?

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.

Note: nested documents are supported via the ObjectBox "Flex" property type, which can hold a map-like (JSON-like) structure. We are also considering alternatives to this, so please let us know if you have specific requirements.

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.

Besides the Object ID, 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. For example, a definition of the ID field in the ObjectBox entities would look similar to this pseudo code (syntax varies according to programming language):

@Id @ExternalType(UUID) int64 id;

The following table shows the supported ID types:

MongoDB type
Incoming from MongoDB
IDs for new documents created in ObjectBox

Object ID

UUID (Binary with UUID subtype)

String

Binary

Uses default MongoDB Object ID

Int64

Uses default MongoDB Object ID

Int32

Uses default MongoDB Object ID

To-One Relations

ObjectBox Sync also automatically maps IDs used in relations (starting with version Alpha 3 of MongoDB Sync Connector).

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:

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.

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 that occurs on each ObjectBox device.

This is the default type

External types: Uuid (V7) or UuidV4

External types: UuidString (V7) or UuidV4String

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

internal ID mapping docs
relation documentation
✅
✅
✅
✅
✅
✅
✅
✅
✅
Figure 1: ObjectBox Object vs. MongoDB Document (Simplified)
Figure 2: To-One Relationship Example (motherId)
Comparison of ObjectBox Object and MongoDB Document structure
To-One Relationship Example: motherId mapping