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: If you prefer to use Kotlin to define your entity classes, have a look at the ObjectBox and Kotlin documentation.

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:

Make entity data accessible

ObjectBox needs to access the data of your entity’s properties (e.g. in generated Cursor classes). You have two options:

  1. Give your property fields at least “package private” (not “private”) visibility. In Kotlin, you can use @JvmField.
  2. Provide standard getters (your IDE can generate them easily).

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.


Creating to-one and to-many relations between objects is possible as well, see the Relations documentation for details.

Triggering generation

Once your entity schema is in place, you can trigger the code generation process by compiling your project. For example using Build > Make project in Android Studio.

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


Spread the love