ObjectBox Introduction: Setup and Basics

ObjectBox is a super fast mobile database that persists objects. It lets you avoid many repetitive tasks and offers a simple interface to your data.

Adding ObjectBox to your Android Project

ObjectBox is available from the jcenter repository.

To add ObjectBox to your Android project, open the build.gradle file for your project (not the ones for your app or module) and add a global variable for the version and the ObjectBox Gradle plugin:

Open the build.gradle file for your app or module and, after the com.android.application plugin, apply the io.objectbox plugin:

For Android projects using Kotlin, make sure to add kotlin-kapt as well:

When syncing the Gradle plugin now automatically adds the required ObjectBox libraries and code generation tasks.

Note: you can use ObjectBox in a plain Java project as well. And if you are using Kotlin in your Android project there are some additional tips and tricks.

Optional: Manually Add Libraries

If the ObjectBox plugin does not automatically add the required library and annotation processor to your dependencies, you can add them manually. In your app’s build.gradle file, add the objectbox-android library and the objectbox-processor annotation processor.

For Android projects using Java:

For Android projects using Kotlin:

Optional: 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.

In your app’s build.gradle file, add the necessary processor option.

For Android projects using Java:

For Android projects using Kotlin:

Optional: 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, add the necessary options and then run Gradle with the --info  option to see the debug output.

For Android projects using Java:

For Android projects using Kotlin:

Other annotation processor arguments are:

  • objectbox.daoCompat: set to true if you want to use DaoCompat (greenDAO-like API).

Entity Classes

Next you define your model by annotating at least one class with @Entity:

Note that ObjectBox uses IDs of type long (see Object IDs doc). And for details on @Entity and other annotations, check the entity annotations documentation.

Then make sure your project builds successfully, for example using Build > Make Project in Android Studio.

Core Classes

The following core classes are the essential interface to ObjectBox:

MyObjectBox: Generated based on your entity classes, MyObjectBox supplies a builder to set up a BoxStore for your app.

BoxStore: The entry point for using ObjectBox. BoxStore is your direct interface to the database and manages Boxes.

Box: A box persists and queries for entities. For each entity, there is a Box (supplied by BoxStore).

Core Initialization

Finally, the basic steps to initialize the core ObjectBox classes:

The example assumes a Note entity exists. With its Box ( notesBox object), we can call the persistence operation for this specific entity.

Basic Box operations

The Box class is likely the class you interact with most. As seen previously, you get Box instances via BoxStore.boxFor(). A Box instance gives you access to objects of a particular type. For example, if you have Customer and Order entities, you need two Box objects to interact with each:

These are some of the operations offered by the Box class:

  • put: Persist an object, which may overwrite an existing object with the same ID. In other words, use put  to insert or update objects (see also the docs for object IDs). When put returns, an ID will be assigned to the object. The various put overloads support putting multiple objects, which is convenient and more efficient.
  • get: Given an object’s ID, you can get it very efficiently using get. To get all objects of a type, use getAll .
  • remove: Remove a previously put object from its box (deletes it). There are method overloads to remove multiple entities, and removeAll  to remove (delete) all objects of a type.
  • count: Returns the number of objects stored in this box.
  • query: Returns a query builder. See queries for details.

For a complete list of methods available in the Box class, check its JavaDoc.


While ObjectBox offers powerful transactions, it is sufficient for many apps to consider just some basics guidelines about transactions:

  • A put  runs an implicit transaction.
  • Prefer put  bulk overloads for lists (like put(entities)) when possible.
  • For a high number of DB interactions in loops, consider explicit transactions, such as using  runInTx().

For more details please check the separate transaction documentation.

Have an app with greenDAO? DaoCompat is for you!

DaoCompat is a compatibility layer that gives you a greenDAO like API for ObjectBox. It makes switching from greenDAO to ObjectBox simple. Have a look at the documentation and the example. Contact us if you have any questions!

Further Docs

ObjectBox Documentation


Spread the love
Sign up for fresh ObjectBOX news here. No spam, just fresh developer news once in a while.