Modelling entities

To use ObjectBox in a project you create an entity model representing the persistent data in your application. Then, based on this model ObjectBox generates Java code for its Box classes.

The model itself is defined using Java classes with annotations.


You can get started with the ObjectBox Gradle plugin without any additional configuration. Though, you should consider setting at least the schema version:

Furthermore, the objectbox configuration element supports the following configuration options:

  • schemaVersion: The current version of the database schema. This is used to migrate between schema versions. If you change your entity/database schema, this value has to be increased. Defaults to 1.
  • daoPackage: The package name for classes generated by ObjectBox. Defaults to the package name of your source entities.
  • 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.
  • 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

Entities and Annotations

ObjectBox uses annotations to define entities. Here is a quick example:

The @Entity annotation turns the Java class User into a database-backed entity. This will also instruct ObjectBox to generate the necessary code.

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

The @Entity Annotation

As you saw in the example above, the @Entity annotation marks a Java class as a persistable entity for ObjectBox.

While it is usually fine to go without any additional parameters, you can still configure some details using @Entity:

Basic properties

The @Id annotation selects a long property as the entity ID. In database terms, this is the primary key. The parameter monotonic is a flag to make the ID value ever increasing (not reusing old values), however this is a little slower.

@Property lets you define a non-default column name, which the property is mapped to. If absent, ObjectBox will use the field name in a SQL-ish fashion (upper case, underscores instead of camel case, for example customName will become CUSTOM_NAME). Note: you currently can only use inline constants to specify a column name.

@Transient marks properties to be excluded from persistence. Use those for temporary states, etc. Alternatively, you can also use the transient keyword from Java.

Primary key restrictions

Currently, entities must have a long property as their primary key. This is recommended practice for Android.

Property indexes

Use @Index at a property to create a database index for the corresponding database column.


ObjectBox tries to work with reasonable defaults, so developers don’t have to configure each and every bit.

For example the table and column name on the database side are derived from the entity and property names. Instead of the camel case style used in Java, the default database names are in uppercase using an underscore to separate word.

For example, a property called creationDate will become a database column CREATION_DATE.

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.
Spread the love