🚀 Our mission is to revolutionize mobile app development by making it fast and efficient with our intuitive and user-friendly native-language APIs. With ObjectBox, you can easily store and synchronize objects in various programming languages such as Python, Java, C, Go, Kotlin, Dart, C++, and Swift. It works seamlessly across different platforms like Android, iOS, Windows, and Linux, and you can even use it with Docker.

💚 ! Community feedback is very important for us as we strive to make ObjectBox better for our users. Our feedback form is anonymous and only takes 2 minutes to fill in. Every response is highly appreciated. Thank you in advance! 🙏

To rate this documentation, use the "Was this page helpful?" smiley 🙃 at the end of each page.

🚩 Feel free to open an issue on GitHub (for or ) or send us your comments to contact[at]objectbox.io - Thank you! - and if you like what you see, we also appreciate a shout out :) or GitHub star ⭐

Learn all about Local Unit Tests, LiveData, Paging, and App Bundle. Please let us know, if our developer resources are helpful for you: The smiley at the bottom of the page already gives us an indication.

ObjectBox supports integration with the Paging library that is part of Google's Android Architecture Components. To that end, the ObjectBox Android library (objectbox-android) provides the ObjectBoxDataSource class. It is an implementation of the Paging library's PositionalDataSource.

Using ObjectBoxDataSource

Within your ViewModel, similar to , you first . But then, you construct an ObjectBoxDataSource factory with it instead. This factory is then passed to a LivePagedListBuilder to build the actual LiveData.

Here is an example of a ViewModel class doing just that:

Note that the LiveData holds your entity class, here Note, wrapped inside a PagedList. You observe the LiveData as usual in your activity or fragment, then submit the PagedList on changes to your PagedListAdapter of the Paging library.

We will not duplicate how this works here, see the for details about this.

Next steps

• Have a look at the .

• Check out .

• Learn how to .

ObjectBox - LiveData with Android Architecture Components

Do you have an existing app that already uses the greenDAO library? We created DaoCompat as a compatibility layer that gives you a greenDAO like API, but behind the scenes uses ObjectBox to store your app's data.

Check out the on how to easily migrate your app to ObjectBox. There is also an available.

Feel free to , or if you encounter a bug with DaoCompat .

ObjectBox – Embedded Database for Java Desktop Apps

Just like on Android, ObjectBox stands for a super simple API and high performance. It’s designed for objects and outperforms other database and ORM solutions. Because it is an embedded database, ObjectBox runs in your apps’ process and needs no maintenance. Read on to learn how to create a Java project using ObjectBox. We believe it’s fairly easy. Please let us know your thoughts on it.

Setup and Usage

See the Getting Started page on how to set up your project, add entities and use the ObjectBox APIs.

Examples

There are example command line apps available in .

Building Unit Tests

The setup and writing tests is identical to writing unit tests that run on the local JVM for Android, see .

The changelogs for each programming language are available at GitHub:

For other languages, please check there respective doc pages:

Your app might observe crashes due to UnsatisfiedLinkError or (since ObjectBox 2.3.4) LinkageError on some devices. This has mainly two reasons:

• If your app uses the App Bundle format, the legacy split APK feature or Multidex the native library can't be found.

• Or if your app's minimum SDK level is below API 23 (Marshmallow), there are known bugs in Android's native library loading code.

Let us know if the below suggestions do not resolve your crashes in .

App Bundle and split APKs

When using an App Bundle or split APKs Google Play only delivers the split APKs required for each user's device configuration, including its architecture (ABI). If users bypass Google Play to install your app ("sideloading") they might not install all of the required split APKs. If the split APK containing the ObjectBox native library required for the device ABI is missing, your app will crash with LinkageError when building BoxStore.

Using the Play Core library to check for missing splits

Add the to the dependencies block:

In the Application class add the missing split APKs check before calling super.onCreate():

If a broken installation is detected, users will see a message and Reinstall button asking them to re-install the app from Google Play.

See to use the Play Core library detection.

If the Play Core library should not be used, there are two alternatives:

Alternative: Catch exception and inform users

You can guard the MyObjectBox build call and for example display an activity with an info message (e.g. direct users to reinstall the app from Google Play, send you an error report, ...):

As an example see .

Alternative: turn off splitting by ABI

The simplest solution is to always include native libraries for all supported ABIs. However, this will increase the download size of your app for all users.

Source:

Buggy devices (API 22 or lower)

On some devices and if your minimum SDK is below API 23 (Android 6.0 Marshmallow), loading the native library may fail with LinkageError due to known bugs in Android's native library loading code. To counter this ObjectBox includes support for the tool which will try to extract the native library manually if loading it normally fails.

To enable this, just add ReLinker to your dependencies:

For ProGuard add this line:

For Multidex add a multiDexKeepProguard file to your build file:

And in the multidex-config.pro file add the same rule as above:

Enable ReLinker debug log

To enable debug logs for ReLinker you can pass a custom ReLinkerInstance when building BoxStore:

ObjectBox - Object IDs

Objects must have an ID property of type long. You are free to use the wrapper type java.lang.Long, but we advise against it in most cases. long IDs are enforced to make ObjectBox very efficient internally.

If your application requires other ID types (such as a string UID given by a server), you can model them as standard properties and use to look up entities by your application-specific ID.

Object ID: new vs. persisted entities

When you create new entity objects (on the language level), they are not persisted yet and their ID is (zero). Once an entity is put (persisted), ObjectBox will assign an ID to the entity. You can access the ID property right after the call to put().

Those are also applied the other way round: ObjectBox uses the ID as a state indication of whether an entity is new (zero) or already persisted (non-zero). This is used internally, e.g. for relations that heavily rely on IDs.

Special Object IDs

Object IDs may be any long value, with two exceptions:

• 0 (zero): Objects with an ID of zero (and null if the ID is of type Long) are considered new (not persisted before). Putting such an object will always insert a new object and assign an unused ID to it.

• 0xFFFFFFFFFFFFFFFF (-1 in Java): This value is reserved for internal use by ObjectBox and may not be used by the app.

Object ID assignment (default)

By default, object IDs are assigned by ObjectBox. For each new object, ObjectBox will assign an unused ID that is above the current highest ID value used in a box. For example, if there are two objects with ID 1 and ID 100 in a box the next object that is put will be assigned ID 101.

Also, note that this will mean in some circumstances IDs from deleted objects may be reused. So it is best to not rely on a specific ID getting assigned.

By default, only ObjectBox may assign IDs. If you try to put an object with an ID greater than the currently highest ID, ObjectBox will throw an error.

Manually assigned Object IDs

If your code needs to assign IDs by itself you can change the @Id annotation to:

This will allow putting an entity with any valid ID (see ). If the @Id field is writable, it can still be set to zero to let ObjectBox auto-assign a new ID.

String ID alias (future work)

Check on Github for status.

ObjectBox - Transactions

A transaction can group several operations into a single unit of work that either executes completely or not at all. If you are looking for a more detailed introduction to transactions in general, please consult other resources like Wikipedia on database transactions. For ObjectBox transactions continue reading:

You may not notice it, but almost all interactions with ObjectBox involve transactions. For example, if you call put a write transaction is used. Also if you get an object or query for objects, a read transaction is used. All of this is done under the hood and transparent to you. It may be fine to completely ignore transactions altogether in your app without running into any problems. With more complex apps however, it’s usually worth learning transaction basics to make your app more consistent and efficient.

TL;DR - a quick summary on Transactions

• Accessing data always happens inside an implicit transaction, the API hides this detail for convenience.

• You should use an explicit transaction for non-trivial operations for better speed and atomicity.

• Transactions manage multi-threading; e.g. a transaction is tied to a thread and vice versa.

• Read(-only) transactions never get blocked or block a write transaction.

Explicit Transactions

We learned that all ObjectBox operations run in implicit transactions – unless an explicit transaction is in progress. In the latter case, multiple operations share the (explicit) transaction. In other words, with explicit transactions, you control the transaction boundary. Doing so can greatly improve efficiency and consistency in your app.

The advantage of explicit transactions over the bulk put operations is that you can perform any number of operations and use objects of multiple boxes. In addition, you get a consistent (transactional) view on your data while the transaction is in progress.

Example for a write transaction:

Transaction Costs

Understanding transactions is essential to master database performance. If you just remember one sentence on this topic, it should be this one: a write transaction has its price.

Committing a transaction involves syncing data to physical storage, which is a relatively expensive operation for databases. Only when the file system confirms that all data has been stored in a durable manner (not just memory cached), the transaction can be considered successful. This file sync required by a transaction may take a couple of milliseconds. Keep this in mind and try to group several operations (e.g.putcalls) in one transaction.

Consider this example:

Do you see the performance issue with that code? An implicit write transaction is created for each user. This will consume a lot of resources, especially for a high number of user objects. It is much more efficient to put all users at once, in a single transaction:

Much better! Even if you would have a database with 1,000 users, the latter example would use a single write transaction to store all user objects at once. The first code example would use 1,000 (!) implicit transactions, causing a massive slow down.

Read Transactions

In ObjectBox, read transactions are cheap. In contrast to write transactions, there is no commit and thus no expensive sync to the file system. Operations like get , count , and queries run inside an implicit read transaction if they are not called when already inside an explicit transaction (read or write). Note that it is illegal to put when inside a read transaction: an exception will be thrown.

While read transactions are much cheaper than write transactions, there is still some overhead to starting a read transaction. Thus, for a high number of reads (e.g. hundreds, in a loop), you can improve performance by grouping those reads in a single read transaction (see explicit transactions below).

Multiversion Concurrency

ObjectBox gives developers semantics. This allows multiple concurrent readers (read transactions) which can execute immediately without blocking or waiting. This is guaranteed by storing multiple versions of (committed) data. Even if a write transaction is in progress, a read transaction can read the last consistent state immediately. Write transactions are executed sequentially to ensure a consistent state. Thus, it is advised to keep write transactions short to avoid blocking other pending write transactions. For example, it is usually a bad idea to do networking or complex calculations while inside a write transaction. Instead, do any expensive operation and prepare objects before entering a write transaction.

Note that you do not have to worry about making write transactions sequential yourself. If multiple threads want to write at the same time (e.g. via put or runInTx), one of the threads will be selected to go first, while the other threads have to wait. It works just like a lock or synchronized in Java.

Locking inside a Write Transaction

Avoid locking (e.g. via synchronized or java.util.concurrent.locks) when inside a write transaction when possible. Because write transactions run exclusively, they effectively acquire a write lock internally. As with all locks, you need to pay close attention when multiple locks are involved. Always obtain locks in the same order to avoid deadlocks. If you acquire a lock “X” inside a transaction, you must ensure that your code does not start another write transaction while having the lock “X”.

Android Local Unit Tests

ObjectBox supports local unit tests. This gives you the full ObjectBox functionality for running super fast test directly on your development machine.

On can either run on an Android device (or emulator), so called instrumented tests, or they can run on your local development machine. Running local unit tests is typically much faster.

To learn how local unit tests for Android work in general have a look at the Android developers documentation on . Read along to learn how to use ObjectBox in your local unit tests.

ObjectBox - Data Model Updates

ObjectBox manages its data model (schema) mostly automatically. The data model is defined by the entity classes you define. When you add or remove entities or properties of your entities, ObjectBox takes care of those changes without any further action from you.

For other changes like renaming or changing the type, ObjectBox needs extra information to make things unambiguous. This is done by setting a unique ID (UIDs) as an annotation, as we will see below.

UIDs

ObjectBox keeps track of entities and properties by assigning them unique IDs (UIDs). All those UIDs are stored in a file objectbox-models/default.json (Java, Kotlin) or lib/objectbox-model.json (Dart) which you should add to your version control system (e.g. git). If you are interested, we have . But let’s continue with how to rename entities or properties.

In short: To make UID-related changes, put an @Uid annotation (Java, Kotlin) or @Entity(uid: 0)/@Property(uid: 0) (Dart) on the entity or property and build the project to get further instructions. Repeat for each entity or property to change.

Renaming Entities and Properties

So why do we need that UID annotation? If you simply rename an entity class, ObjectBox only sees that the old entity is gone and a new entity is available. This can be interpreted in two ways:

• The old entity is removed and a new entity should be added, the old data is discarded. This is the default behavior of ObjectBox.

• The entity was renamed, the old data should be re-used.

So to tell ObjectBox to do a rename instead of discarding your old entity and data, you need to make sure it knows that this is the same entity and not a new one. You do that by attaching the internal UID to the entity.

The same is true for properties.

Now let’s walk through how to do that. The process works the same if you want to rename a property:

How-to and Example (Java/Kotlin and Dart)

Step 1: Add an empty UID to the entity/property you want to rename:

Step 2: Build the project (in Dart, run pub run build_runner build). The build will fail with an error message that gives you the current UID of the entity/property:

Step 3: Apply the UID from the [Rename] section of the error message to your entity/property:

Step 4: The last thing to do is the actual rename on the language level (Java, Kotlin, etc.):

Step 5: Build the project again, it should now succeed. You can now use your renamed entity/property as expected and all existing data will still be there.

Repeat the steps above to rename another entity or property.

How-to and Example (Python)

Since in Python there isn't a build step, the steps for renaming an Entity are different. Say we want to rename the Entity MyName to MyNewName:

Step 1: Find out the UID of the entity MyName:

Step 2: Rename MyName to MyNewName and explicitly specify the old UID:

This makes possible for Objectbox to associate the old entity to the new one, and retain persisted data. If you don't specify the old UID, Objectbox will discard the old data and add a fresh new entity called MyNameName to the schema.

Changing Property Types

There are two solutions to changing the type of a property:

• Add a new property with a different name (this only works if the property has no @Uid annotation already):

• Set a new UID for the property so ObjectBox treats it as a new property. Let’s walk through how to do that:

How-to and Example

Step 1: Add the @Uid annotation to the property where you want to change the type:

Step 2: Build the project. The build will fail with an error message that gives you a newly created UID value:

Step 3: Apply the UID from the [Change/reset] section to your property:

Step 4: Build the project again, it should now succeed. You can now use the property in your entity as if it were a new one.

Repeat the steps above to change the type of another property.

ObjectBox - Entity Super Classes

ObjectBox allows entity inheritance to share persisted properties in super classes. The base class can be an entity or non-entity class. For this purpose the @Entity annotation is complemented by the @BaseEntity annotation. There are three types of super classes, which are defined via annotations:

• No annotation: The base class and its properties are not considered for persistence.

• @BaseEntity: Properties are considered for persistence in sub classes, but the base class itself cannot be persisted.

• @Entity: Properties are considered for persistence in sub classes, and the base class itself is a normally persisted entity.

For example:

The model for Sub, Sub_, will now include all properties: id , baseString and subString .

It is also possible to inherit properties from another entity:

Notes on usage

• It is possible to have classes in the inheritance chain that are not annotated with @BaseEntity. Their properties will be ignored and will not become part of the entity model.

• It is not generally recommend to have a base entity class consisting of an ID property only. E.g. Java imposes an additional overhead to construct objects with a sub class.

• Depending on your use case using interfaces may be more straightforward.

Restrictions

• Superclasses annotated with @BaseEntity can not be part of a library.

• There are no polymorphic queries (e.g. you cannot query for a base class and expect results from sub classes).

• Currently any superclass, whether it is an @Entity or @BaseEntity, can not have any relations (like a ToOne or ToMany property).

ObjectBox and Kotlin

ObjectBox comes with full Kotlin support for Android. This allows entities to be modeled in Kotlin classes (regular and data classes). With Kotlin support you can build faster apps even faster.

Kotlin Entities

ObjectBox supports regular and data classes for entities. However, @Id properties must be var (not val) because ObjectBox assigns the ID after putting a new entity. They also should be of non-null type Long with the special value of zero for marking entities as new.

Can sealed classes be entities? Not directly. are abstract and can't be instantiated. But subclasses of a sealed class should work.

To learn how to create entities, look at these pages:

Defining Relations in Kotlin Entities

When in Kotlin, keep in mind that relation properties must be var. Otherwise they can not be initialized as described in the . To avoid null checks use a lateinit modifier. When using a data class this requires the relation property to be moved to the body.

See the Relations page for examples.

Using the provided extension functions

To simplify your code, you might want to use the Kotlin extension functions provided by ObjectBox. The library containing them is added automatically if the Gradle plugin detects a Kotlin project.

To add it manually, modify the dependencies section in your app's build.gradle file:

Now have a look at what is possible with the extensions compared to standard Kotlin idioms:

Get a box:

Queries

Build a query:

Use the in filter of a query:

Relations

Modify a :

Flow

Get a Flow from a Box or Query subscription (behind the scenes this is based on a ):

Something missing? what other extension functions you want us to add.

Coroutines

To run Box operations on a separate Dispatcher wrap them using withContext:

BoxStore provides an async API to run transactions. There is an extension function available that wraps it in a coroutine:

Next Steps

• Check out the .

• Continue with .

ObjectBox supports a wide range of . For types that aren't directly supported, you can use converters to map them to a built-in type.

Flex property converters

In ObjectBox for Java/Kotlin, use converters internally. You can exchange converters to fine-tune the conversion process. To override the default converter, use @Convert. For example to use another built-in FlexObjectConverter subclass:

Does ObjectBox support Kotlin? RxJava?

ObjectBox comes with full including data classes. And yes, it supports .

ObjectBox stores data as objects, which are instances of entity classes you define. Objects consist of properties, which are the individual fields that hold your data, like a user's name or age. This page covers the property types ObjectBox supports:

• Standard types for single values of a fixed type

• List/Vector types for collections of values of a fixed type

• The flex type for dynamic and schema-less data

Standard Types

Standard types include boolean, integers, floating point types, string, and date types. These are the most common types you will use in typical applications.

Quick Reference

Integers

ObjectBox supports all standard integer types, from 8-bit to 64-bit. Rule of thumb: use large enough integer types that are safe for your use case in the future. Use smaller types only if you are certain about the range of values as you cannot change the type of an existing property later.

Floating Point

Choose 32-bit floats for memory efficiency when ~7 digits of precision is enough. Use 64-bit doubles when you need ~15 digits.

Strings

Strings are stored as UTF-8 encoded bytes without a length limit.

Dates and Times

ObjectBox stores dates as 64-bit integers ("timestamps") representing time since the Unix epoch (January 1, 1970, 00:00:00 UTC). Choose your precision:

Note: while DateNano values are always stored as nanoseconds, the actual precision of the values depends on the platform and programming language. For example, Dart uses only microsecond precision (the last three digits of the nanosecond are "truncated").

IDs and Relations

Every ObjectBox entity must have exactly one ID property of type Long (64-bit integer). See for details.

"Relation" is used for one of two relation types available in ObjectBox. It's a 64-bit integer that references the ID of another object. Depending on the programming language you use, it may translate to a "to-one" construct. See for complete documentation.

Lists and Arrays

Store collections of values directly; no special tables or joins required. The internal type names are "vectors", but they may translate to lists or arrays in the programming language you use.

Quick Reference

Language Examples

Flex Properties

Flex properties can hold data values of various types, including complex structures, in a single property. They serve two main purposes:

• Dynamic data: you want to process JSON-like data dynamically

• Nested objects: as an alternative to relations, you can embed map-like data directly

Custom Types

If the existing property types do not fully cover your use case, check .

This page contains:

ObjectBox for Java - Advanced Setup

ObjectBox for Flutter/Dart - Advanced Setup

ObjectBox for Java - Advanced Setup

This page assumes you have added ObjectBox to your project.

To then change the default behavior of the ObjectBox plugin and processor read on for advanced setup options.

Manually Add Libraries

The ObjectBox Gradle plugin adds required libraries and the annotation processor to your projects dependencies automatically, but you can also add them manually.

Just make sure to apply the ObjectBox Gradle plugin after the dependencies block, so it does not replace manually added dependencies.

In your app's Gradle build script:

Add libraries for distribution

For JVM apps, by default, the ObjectBox Gradle plugin only adds the native (Linux, macOS or Windows) library required to run on your current system. If your app wants to support multiple platforms, manually add all of the required native libraries listed above when you distribute your app.

Processor Options

In your app’s Gradle build script, the following processor options, explained below, are available:

Change the Model File Path

By default, the ObjectBox model file is stored in module-name/objectbox-models/default.json. You can change the file path and name by passing the objectbox.modelPath argument to the ObjectBox annotation processor.

Change the MyObjectBox package

By default, the MyObjectBox class is generated in the same or a parent package of your entity classes. You can define a specific package by passing the objectbox.myObjectBoxPackage argument to the ObjectBox annotation processor.

Enable Debug Mode

You can enable debug output for the annotation processor if you encounter issues while setting up your project and entity classes.

In your app’s build.gradle file, enable the objectbox.debug option and then run Gradle with the --info option to see the debug output.

To enable debug mode for the ObjectBox Gradle plugin:

Enable DaoCompat mode

ObjectBox can help you migrate from greenDAO by generating classes with a greenDAO-like API.

See the on how to enable and use this feature.

ObjectBox for Flutter/Dart - Advanced Setup

Change the generated files directory

To customize the directory (relative to the package root) where the files generated by ObjectBox are written, add the following to your pubspec.yaml:

This tutorial will walk you through a simple note-taking app explaining how to do basic operations with ObjectBox. To just integrate ObjectBox into your project, look at the page.

You can check out the example code from GitHub. This allows you to run the code and explore it in its entirety. It is a simple app for taking notes where you can add new notes by typing in some text and delete notes by clicking on an existing note.

Unlike relational databases like SQLite, ObjectBox does not require you to create a database schema. That does not mean ObjectBox is schema-less. For efficiency reasons, ObjectBox manages a meta model of the data stored. This meta model is actually ObjectBox’s equivalent of a schema. It includes known object types including all properties, indexes, etc. A key difference to relational schemas is that ObjectBox tries to manage its meta model automatically. In some cases it needs your help. That’s why we will look at some details.

IDs

In the ObjectBox meta model, everything has an ID and a UID. IDs are used internally in ObjectBox to reference entities, properties, and indexes. For example, you have an entity “User” with the properties “id” and “name”. In the meta model the entity (type) could have the ID 42, and the properties the IDs 1 and 2. Property IDs must only be unique within their entity.

ObjectBox assigns meta model IDs sequentially (1, 2, 3, 4, …) and keeps track of the last used ID to prevent ID collisions.

UIDs

As a rule of thumb, for each meta model ID there’s a corresponding UID. They complement IDs and are often used in combination (e.g. in the JSON file). While IDs are assigned sequentially, UIDs are a random long value. The job of UIDs is detecting and resolving concurrent modifications of the meta model.

A UID is unique across entities, properties, indexes, etc. Thus unlike IDs, an UID already used for an entity may not be used for a property. As a precaution to avoid side effects, ObjectBox keeps track of “retired” UIDs to ensure previously used but now abandoned UIDs are not used for new artifacts.

JSON for consistent IDs

ObjectBox stores a part of its meta model in a JSON file. This file should be available to every developer and thus checked into a source version control system (e.g. git). The main purpose of this JSON file is to ensure consistent IDs and UIDs in the meta model across devices.

This JSON file is stored in

• objectbox-models/default.json for Android or Java projects,

• lib/objectbox-model.json for Dart or Flutter projects.

For example, look at a file from the :

As you can see, the “id” attributes combine the ID and UID using a colon. This protects against faulty merges. When applying the meta model to the database, ObjectBox will check for consistent IDs and UIDs.

Meta Model Synchronization

At build time, ObjectBox gathers meta model information from the entities (@Entity classes) and the JSON file. The complete meta model information is written into the generated class MyObjectBox.

Then, at runtime, the meta model assembled in MyObjectBox is synchronized with the meta model inside the ObjectBox database (file). UIDs are the primary keys to synchronize the meta model with the database. The synchronization involves a couple of consistency checks that may fail when you try to apply illegal meta data.

Stable Renames using UIDs

At some point you may want to rename an entity class or just a property. Without further information, ObjectBox will remove the old entity/property and add a new one with the new name. This is actually a valid scenario by itself: removing one property and adding another. To tell ObjectBox it should do a rename instead, you need to supply the property's previous UID.

Add an @Uid annotation without any value to the entity or property you want to rename and trigger a project build. The build will fail with a message containing the UID you need to apply to the @Uid annotation.

Also check out this for hands-on information on renaming and resetting.

Resolving Meta Model Conflicts

In the section on UIDs, we already hinted at the possibility of meta model conflicts. This means the meta model defined in the objectbox-models/default.json file conflicts with the model of the existing database file.

When creating a Store the meta model is passed and verified against the database file. If a conflict exists an exception or error is thrown, for example:

Such a conflict can be caused by

• developers changing the meta model at the same time (e.g. in different version control system branches), typically by adding entity classes or properties.

• the objectbox-models/default.json model file getting accidentally deleted, it is then generated on the next build with a new set of UIDs.

• a database file with a different model getting restored by or getting .

There are basically two ways to resolve this:

• Resolve conflicts in or reconstruct the default.json meta model file to match the model of an existing database file.

• Keep or create a fresh default.json model file and delete the database file. However, this will lose all existing data.

The two options are explained in detail below.

Manual conflict resolution

Usually, it is preferred to edit the JSON file to resolve conflicts and fix the meta model. This involves the following steps:

• Ensure IDs are unique: in the JSON file the id attribute has values in the format “ID:UID”. If you have duplicate IDs after a VCS merge, you should assign a new ID (keep the UID part!) to one of the two. Typically, the new ID would be “last used ID + 1”.

• Update last ID values: for entities, update the attribute lastEntityId; for properties, update the attribute lastPropertyId of the enclosing entity back to the ID:UID with the ID indicated by the error message.

• Check for other ID references:

To illustrate this with an example, let's assume the last assigned entity ID was 41. Thus the next entity ID will be 42. Now, the developers Alice and Bob add a new entity without knowing of each other. Alice adds a new entity “Ant” which is assigned the entity ID 42. At the same time, Bob adds the entity “Bear” which is also assigned the ID 42. After both developers committed their code, the ID 42 does not unique identify an entity type (“Ant” or “Bear”?). Furthermore, in Alice’s ObjectBox the entity ID 42 is already wired to “Ant” while Bob’s ObjectBox maps 42 to “Bear”. UIDs make this situation resolvable. Let’s say the UID is 12345 for “Ant” and 9876 for “Bear”. Now, when Bob pulls Alice’s changes, he is able to resolve the conflict. He manually assigns the entity ID 43 to “Bear” and updates the lastEntityId attribute accordingly to “43:9876” (ID:UID). After Bob commits his changes, both developers are able to continue with their ObjectBox files.

The Nuke Option

During initial development, it may be an option to just delete the meta model and all databases. This will cause a fresh start for the meta model, e.g. all UIDs will be regenerated. Follow these steps:

• Delete the JSON file (objectbox-models/default.json)

• Build the project to generate a new JSON file from scratch

• Commit the recreated JSON file to your VCS (e.g. git)

• Delete all previously created ObjectBox databases (e.g. for Android, delete the app’s data or uninstall the app)

While this is a simple approach, it has its obvious disadvantages. For example for a published app, all existing data would be lost.

ObjectBox Admin Web App

The ObjectBox Admin web app allows you to

• view data objects and schema of your database inside a regular web browser,

On this page:

• ObjectBox Java - Data Observers and Reactive Extensions

• ObjectBox Dart - Reactive Queries

ObjectBox Java - Data Observers and Reactive Extensions

ObjectBox for Java makes it easy for your app to react to data changes by providing:

• data observers,

• reactive extensions,

• and an optional library to work with RxJava.

This makes setting up data flows easy while taking care of threading details.

Reactive Observers: A First Example

Let’s start with an example to demonstrate what you can do with reactive data observers:

The first line creates a regular query to get Task objects where task.complete == false. The second line connects an observer to the query. This is what happens:

• the query is executed in the background

• once the query finishes the observer gets the result data

• whenever changes are made to Task objects in the future, the query will be executed again

Now, let’s dive into the details.

Data Observers Basics

When objects change, ObjectBox notifies subscribed data observers. They can either subscribe to changes of certain object types (via BoxStore) or to query results. To create a data observer you need to implement the generic io.objectbox.reactive.DataObserver interface:

This observer will be called by ObjectBox when necessary: typically shortly after subscribing and when data changes.

Observing General Changes

BoxStore allows a DataObserver to subscribe to object types. Let’s say we have a to-do list app where Task objects get added. To get notified when Task objects are added in another place in our app we can do the following:

Here onData() is not called with anything useful as data. If you need more than being notified, like to get a list of Task objects following the above example, read on to learn how to observe queries.

Observing Queries

ObjectBox let’s you to find the objects matching certain criteria. Queries are an essential part of ObjectBox: whenever you need a specific set of data, you will probably use a query.

Combining queries and observers results in a convenient and powerful tool: query observers will automatically deliver fresh results whenever changes are made to entities in a box. Let’s say you display a list of to-do tasks in your app. You can use a DataObserver to get all tasks that are not yet completed and pass them to a method updateUi() (note that we are using lambda syntax here):

So when is our observer lambda called? Immediately when an observer is subscribed, the query will be run in a separate thread. Once the query result is available, it will be passed to the observer. This is the first call to the observer.

Now let’s say a task gets changed and stored in ObjectBox. It doesn't matter where and how; it might be the user who marked a task as completed, or some backend thread putting additional tasks during synchronization with a server. In any case, the query will notify all observers with (potentially) updated query results.

Note that this pattern can greatly simplify your code: there is a single place where your data comes in to update your user interface. There is no separate initialization code, no wiring of events, no re-running queries, etc.

See the documentation for more details.

Canceling Subscriptions

When you call observer(), it returns a subscription object implementing the io.objectbox.reactive.DataSubscription interface:

Keep a reference to the DataSubscription for as long as results should be received, otherwise it can be garbage collected at any point. Also call cancel() on it once the observer should not be notified anymore, e.g. when leaving the current screen:

If you have more than one query subscription, you might find it useful to create a DataSubscriptionList instance instead to keep track of multiple DataSubscription objects. Pass the list to the query.subscribe(subList) overload. A basic example goes like this:

Observers and Transactions

Observer notifications occur after a transaction is committed. For some scenarios it is especially important to know transaction bounds. If you call box.put() or remove() individually, an implicit transaction is started and committed. For example, this code fragment would trigger data observers on User.class twice:

There are several ways to combine several operations into one transaction, for example using one of the runInTx() or callInTx() methods in the BoxStore class. For our simple example, we can simply use an overload of put() accepting multiple objects:

This results in a single transaction and thus in a single DataObserver notification.

Reactive Extensions

In the first part you saw how data observers can help you keep your app state up to date. But there is more: ObjectBox comes with simple and convenient reactive extensions for typical tasks. While most of these are inspired by RxJava, they are not actually based on RxJava. ObjectBox brings its own features because not all developers are familiar with RxJava (for the RxJava ObjectBox library see below). We do not want to impose the complexity (Rx is almost like a new language to learn) and size of RxJava (~10k methods) on everyone. So, let’s keep it simple and neat for now.

Thread Scheduling

On Android, UI updates must occur on the main thread only. Luckily, ObjectBox allows to switch the observer from a background thread over to the main thread. Let’s take a look on a revised version of the to-do task example from above:

Where is the difference? The additional on() call is all that is needed to tell where we want our observer to be called. AndroidScheduler.mainThread() is a built-in scheduler implementation. Alternatively, you can create an AndroidScheduler using a custom Looper, or build a fully custom scheduler by implementing the io.objectbox.reactive.Scheduler interface.

Transforming Data

Maybe you want to transform the data before you hand it over to an observer. Let’s say, you want to keep track of the count of all stored objects for each type. The BoxStore subscription gives you the classes of the objects, and this example shows you how to transform them into actual object counts:

Note that the transform operation takes a Class object and returns a Long number. Thus the DataObserver receives the object count as a Long parameter in onData().

While the lambda syntax is nice and brief, let’s look at the io.objectbox.reactive.Transformer interface for clarification of what the transform() method expects as a parameter:

Some additional notes on transformers:

• Transforms are not required to actually “transform” any data. Technically, it is fine to return the same data that is received and just do some processing with (or without) it.

• Transformers are always executed asynchronously. It is fine to perform long lasting operations.

ErrorObserver

Maybe you noticed that a transformer may throw any type of exception. Also, a DataObserver might throw a RuntimeException. In both cases, you can provide an ErrorObserver to be notified about an exception that occurred. The io.objectbox.reactive.ErrorObserver is straight-forward:

To specify your ErrorObserver, simply call the onError() method after subscribe().

Single Notifications vs. Only-Changes

When you subscribe to a query, the DataObserver gets both of the following by default:

• Initial query results (right after subscribing)

• Updated query results (underlying data was changed)

Sometimes you may by interested in only one of those. This is what the methods single() and onlyChanges() are for (call them after subscribe()). Single subscriptions are special in the way that they are cancelled automatically once the observer is notified. You can still cancel them manually to ensure no call to the observer is made at a certain point.

Weak References

Sometimes it may be nice to have a weak reference to a data observer. Note that for the sake of a deterministic flow, it is advisable to cancel subscriptions explicitly whenever possible. If that does not scare you off, use weak() after subscribe().

Threading overview

To summarize threading as discussed earlier:

• Query execution runs on a background thread (exclusive for this task)

• DataTransformer runs on a background thread (exclusive for this task)

• DataObserver and ErrorObserver run on a background thread unless a scheduler is specified via the on()

ObjectBox RxJava Extension Library

By design, there are zero dependencies on any Rx libraries in the core of ObjectBox. As you saw before ObjectBox gives you simple means to transform data, asynchronous processing, thread scheduling, and one time (single) notifications. However, you still might want to integrate with the mighty RxJava 2 (we have no plans to support RxJava 1). For this purpose we created the ObjectBox RxJava extension library:

It provides the classes RxQuery and RxBoxStore. Both offer static methods to subscribe using RxJava means.

For general object changes, you can use RxBoxStore to create an Observable. RxQuery allows to subscribe to query objects using:

• Flowable

• Observable

• Single

Example usage:

The extension library is open-source and available .

ObjectBox Dart - Reactive Queries

You can build a Stream from a query to get notified any time there is a change to the box of any of the queried entities:

For a Flutter app you typically want to get the latest results immediately when listening to the stream, and also get a list of objects instead of a query instance:

Unresolved reference: MyObjectBox (class not found, etc.)

MyObjectBox is a generated class, so make sure the project builds successfully. Resolve any other build errors.

Check that the project is configured correctly. E.g. for Kotlin, check that the kapt plugin is applied (apply plugin: 'kotlin-kapt') before the ObjectBox plugin.

android-apt is known to cause problems, try to remove it.

Merge conflict or DbSchemaException after concurrent data model modifications