Docs Menu
Docs Home
/ /
Atlas Device SDKs

Quick Start

On this page

  • Before You Begin
  • Import the SDK
  • Define Your Object Model
  • Open a Database
  • Create, Read, Update, and Delete Objects
  • Create
  • Read and Filter
  • Update
  • Delete
  • Watch for Changes
  • Close a Database
  • Add Device Sync
  • Prerequisites
  • Initialize the App
  • Authenticate a User
  • Open a Synced Database
  • Read, Write, and React to Changes
  • Next: Check out Demos and Example Projects

This quick start demonstrates how to use Atlas Device SDK. If you'd prefer a guided quick start experience using a template app, check out our Device Sync tutorials.

Before you can get started, you must Install the SDK.

Tip

Atlas Device SDK was previously named Realm. The SDK library names still reflect Realm naming. To import Atlas Device SDK, you import Realm.

You can define your object model directly in code. If you want to use Device Sync, your client object models also require a matching schema in Atlas. For more details, refer to Model Data with Device Sync.

For more information, refer to Configure & Open a Database File.

Once you have opened a database, you can modify it and its objects in a write transaction block.

To instantiate a new object and add it to the database in a write block:

For more information, refer to Create Objects.

To retrieve a results collection of all objects of a given type in the database:

For more information, refer to Read Objects.

To filter that same results collection:

For more information about the SDK query engines, refer to Filter Data.

To modify an object, update its properties in a write transaction block:

For more information, refer to Update Objects.

To delete an object from the database:

For more information, refer to Delete Objects.

You can watch a database, a collection, or an object for changes:

For more information about reacting to changes, including details about unregistering the listener to stop watching and free up resources, refer to React to Changes.

If you want to sync data across devices with the SDK, you can enable Device Sync in Atlas. For more information on Device Sync, refer to Atlas Device Sync in the App Services documentation.

Before you can sync device data, you must:

  • Create an App Services App

  • Enable anonymous authentication

  • Enable Device Sync with Development Mode toggled to On.

  • Define the rules that determine which permissions users have when using Device Sync.

The SDK uses an App to connect to Atlas, manage users, and report certain types of errors.

To use App Services features such as authentication and sync, access your App Services App using your App ID. You can find your App ID in the App Services UI.

To initialize the App connection:

For more details about configuring and initializing the App connection, refer to Connect to Atlas.

This quick start uses anonymous authentication to log in users without requiring them to provide any identifying information. After authenticating the user, you can open a database for that user.

The SDK provides additional ways to authenticate, register, and link users. For other authentication providers, refer to Authenticate Users.

For more details about opening a synced database, refer to Configure & Open a Synced Database.

For more details about Sync subscriptions, refer to Manage Sync Subscriptions.

The syntax to read, write, and watch for changes on a synced database is identical to the syntax for non-synced databases above.

However, reads and writes to a synced databases have the following additional constraints:

  • Sync permissions that determine whether users can read or write.

  • Sync subscriptions that determine what data the synced database can read or write.

In the following example, we set Sync permissions to Users can only read and write their own data, and add a property that lets us subscribe to only the current user's todos. Users can only read and write their own data.

For more information about Device Sync permissions, refer to Role-based Permissions in the App Services documentation.

While you work with local data, a background thread efficiently integrates, uploads, and downloads changesets.

Every write transaction for a subscription set has a performance cost. If you need to make multiple updates to a database object during a session, consider keeping edited objects in memory until all changes are complete. This improves sync performance by only writing the complete and updated object to your database instead of every change.

Check out the template apps to see an implementation of a platform-specific Atlas Device SDK application. Each SDK has an application that integrates Atlas Device SDK and Atlas Device Sync in a platform-idiomatic todo app.

Check out our list of curated Atlas Device SDK Example Projects to browse example applications for specific use cases and implementations.

← 
 →