ObjectBox Database Persistence with Entity Annotations

ObjectBox is a database that persists objects. For a clear distinction, we sometimes call those persistable objects entities. To let ObjectBox know which classes are entities you add annotations to them. Then ObjectBox can do its magic with your entities.

Here is an example:

The @Entity annotation identifies the Java class User as a persistable entity. This will trigger ObjectBox to generate persistence code tailored for this class.

Note: It’s often good practice to model entities as “dumb” data classes (POJOs) with just properties.

Note: Only Java classes are supported. If you prefer another language like Kotlin, your entity classes must still be Java.

Object IDs: @Id

In ObjectBox, every object has an ID of type long to efficiently get or reference objects. Use the @Id annotation on a  long property in your entity:

There are a few things you should know about object IDs:

  • The values 0 (zero) and -1 (0xFFFFFFFFFFFFFFFF) can not be used as IDs.
  • Objects with an ID of zero (and  null  if the ID is of type  Long) are considered new. Putting such an object will always insert a new object and assign an unused ID to it.
  • 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.
  • If you try to put an object with an ID greater than the currently highest ID, ObjectBox will throw an error.
  • To assign IDs by yourself you can change the ID annotation to   @Id(assignable = true) . This will allow putting an entity with any valid ID, including zero to let ObjectBox auto assign a new ID.

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 queries to look up entities by your application specific ID. An example:

Basic annotations for entity properties

@NameInDb lets you define a name on the database level for a property. This allows you to rename the Java field without affecting the property name on the database level. Note 1: for renames, UIDs are preferred. Note 2: you currently can only use inline constants to specify a column name.

@Transient (or alternatively the transient modifier) marks properties that should not be persisted, like the temporary counter above.

Property indexes

Use @Index on a property to create a database index for the corresponding database column. This can improve performance when frequently querying for that property.


Learn how to use the @Relation annotation on the separate object relations page.

Triggering generation

Once your entity schema is in place, you can trigger the code generation process by using Make project in your IDE. Or by directly executing the objectbox Gradle task.

If you encounter errors after changing your entity classes, try to rebuild your project to make sure old generated classes are cleaned.

Modifying generated code

Entity classes in ObjectBox are created and edited by the developer. However, during the code generation process ObjectBox may augment the source code of entities.

ObjectBox will add a @Generated annotation to methods and fields it created, to inform the developer and to prevent any loss of code. In most cases, you should not have to touch code annotated with @Generated.

As a precaution, ObjectBox will not overwrite existing code and raise an error if generated code was manually changed:

As the error message implies, there are usually two ways to resolve this:

  • Revert the changes to code annotated with @Generated. Alternatively, you can also delete the changed constructor or method completely. They will be regenerated with the next build.
  • Replace the @Generated annotation with a @Keep annotation. This will tell ObjectBox to never touch the annotated code. Keep in mind that your changes might break the contract between the entity and the rest of ObjectBox. Also, future releases of ObjectBox might expect different code in generated methods. So, be cautious! It’s a good idea to have unit tests in place to avoid trouble.

ObjectBox Gradle properties

You can get started with the ObjectBox Gradle plugin without any additional configuration. For some advanced features, you can use a configuration element in your Gradle build configuration file:

The objectbox configuration element supports the following options:

  • targetGenDir: The location where generated sources should be stored at. Defaults to the generated source folder inside the build directory ( build/generated/source/objectbox).
  • generateTests: Set to true to automatically generate unit tests. Defaults to false. The generated tests already take care of initializing everything you need to work with a specific entity, like setting up a BoxStore and Box instance in a @Before method and cleaning them up in an @After method. A simple test method is also pre-created, which may serve as a starting point for your individual tests. Once the test classes are generated, ObjectBox won’t overwrite them – you are in full control of your test classes.
  • targetGenDirTests: The base directory where generated unit tests should be stored at. Defaults to src/androidTest/java.
  • daoCompat: Flag for greenDAO compatibility. If true the plugin will generate additional compat DAO classes that work with existing greenDAO code, but use ObjectBox behind the scenes. Defaults to false.
Spread the love
Sign up for fresh ObjectBOX news here. No spam, just fresh developer news once in a while.