ObjectBox Entity Annotations

ObjectBox 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) are special and cannot be used as IDs.
  • A zero denotes that the object was not yet persisted. Putting this object will assign it a new ID.
  • By default, IDs are assigned like this: the highest assigned ID is queried (once) and stored internally. For each put of a new object, its value is increased by one and assigned to the new object.
  • If you try to put an object with an ID greater than the currently highest ID, ObjectBox will throw an error.
  • You can use @Id(assignable = true) to assign your own IDs (e.g. from the server). This will disable the previous check against the highest ID.

Basic annotations for entity properties

@Property lets you define a name on the database level for a property. Like this, you can later rename the Java field without affecting the property name on the database level. Note 1: there’s an alternative (and better) way to do so, documentation will follow. 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.


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:

Furthermore, 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. Generated tests take care of initializing everything you need to work with a specific entity. Basically it set up an BoxStore and Box instance in a @Before method and also does the clean up in an @After method. It also creates an initial test method, which may serve as a starting point for your individual test. Once the test file is generated, ObjectBox won’t overwrite it – you are in full control of the test class.
  • 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 DAO classes like used with greenDAO that work with ObjectBox. Defaults to false
Spread the love
Sign up for fresh ObjectBox news here. No spam, just fresh developer news once in a while.