Create Objects
On this page
- Write Transactions
- Managed and Unmanaged Objects
- Create Object Methods
- Create One Object
- Create Multiple Objects
- Create or Update an Object (Upsert)
- Initialize Objects with a Value
- Create Objects from JSON
- Create an Unmanaged Copy of an Object
- Copy an Object to Another Database
- Create Objects in the Background
This page describes the concepts of write transactions and managed objects in a database, then explains how to create and persist a new object to a local or synced database using Atlas Device SDK. To learn more about object models and how to define them, refer to Define an SDK Object Model.
You can create objects whose object type is managed by the database instance. For more information, refer to:
With Sync: Configure & Open a Synced Database
Without Sync: Configure & Open a Database File
Note
Write to a Synced Database
The syntax to write a new object to the database is the same for a local or a synced database. However, there are additional considerations that determine whether the write operation in a synced database is successful. For more information, refer to Write Data to a Synced Database.
Write Transactions
The Atlas Device SDK persistence layer handles writes in terms of transactions. All writes must happen within a transaction. A transaction is a list of read and write operations that the database treats as a single indivisible operation: either all of the operations succeed or none of the operations in the transaction take effect.
The SDK represents each transaction as a callback function that contains zero or more read and write operations. To run a transaction, you define a transaction callback and pass it to one of the database's write methods. Within this callback, you can access a database instance and then create, read, update, and delete objects within the database.
A database file allows only one open write transaction at a time. The SDK blocks other writes on other threads until the open transaction on the database file is complete. This means there is never a race condition when reading values from the database within a transaction.
When you are done with your transaction, the SDK either commits it or cancels it:
When the SDK commits a write transaction, it writes all changes to disk. For synced databases, the SDK then queues the change for synchronization with the backend.
When the SDK cancels a write transaction or an operation in the transaction causes an error, it discards all changes.
Managed and Unmanaged Objects
The SDK's APIs may refer to objects as managed or unmanaged. When you create an object with the SDK, it is unmanaged until it is added to the database, which creates a managed instance.
Managed objects are SDK objects that persist in a database instance. Managed objects can only be accessed from an open database file. They can be updated with changes within write transactions as long as that database remains open. Managed objects are tied to the database instance from which they originated and cannot be directly written to another database. However, some of the SDKs supply a method to copy managed objects from one database file to another. Refer to the Copy an Object to Another Database section on this page.
You can use the SDK's APIs with managed objects. For example, managed objects can have relationships with other objects and you can observe them for changes. You can also create an unmanaged copy of a managed object. Refer to the Create an Unmanaged Copy of an Object or Collection section on this page.
Unmanaged objects are SDK objects that behave like normal objects, but they are not persisted in the database. All SDK objects are unmanaged until you add them to a database within a write transaction. You cannot use the SDK's APIs with unmanaged objects or observe them for changes.
Create Object Methods
The SDK provides a variety of methods to create objects and perform write operations.
Create One Object
To create a new object and persist it to the database:
You can also upsert into a database using specific criteria. Refer to the Create or Update an Object (Upsert) section on this page.
Create Multiple Objects
Some of the SDKs provide a dedicated API to create multiple objects from a sequence or collection.
Create or Update an Object (Upsert)
An upsert is a write operation that either inserts a new object with a given primary key or updates an existing object that already has that primary key. We call this an upsert because it is an "update or insert" operation. This is useful when an object may or may not already exist, such as when bulk importing a dataset into an existing database. Upserting lets you update existing entries while adding any new entries.
Initialize Objects with a Value
Some of the SDKs provide specific methods to initialize objects with a value. Others use language-idiomatic methods to set the values of objects during initialization.
Some Property Types are Only Mutable in a Write Transaction
Some property types are only mutable in a write transaction. For example, you can instantiate an object with a Set property, but you can only set that property's value in a write transaction. You cannot initialize the object with a value for that property unless you do so inside a write transaction.
Create Objects from JSON
Working with JSON returned from an API is a common development use case. Most of the supported SDK languages do not directly support creating objects from JSON. However, you may use language or platform-idiomatic APIs to transform JSON to a structure that matches your object schema, and create a matching object. Or you may model unstructured data to work with unstructured data that is highly variable or whose structure is unknown at runtime.
Create an Unmanaged Copy of an Object
Some of the SDKs provide APIs to create an unmanaged, in-memory copy of a managed object or collection. In other SDKs, this API is not needed or not currently implemented.
Copy an Object to Another Database
You can copy objects that are managed by one database instance to another database instance.
Create Objects in the Background
When performing large write operations, you may want to create objects in the background. This avoids blocking the UI thread while performing large write operations. This is particularly useful when using Device Sync, where you don't know when and for how long the Sync client will be writing.