Getting started
Discover ObjectBox: The Lightning-Fast Mobile Database for Persistent Object Storage. Streamline Your Workflow, Eliminate Repetitive Tasks, and Enjoy a User-Friendly Data Interface.
Last updated
Was this helpful?
Discover ObjectBox: The Lightning-Fast Mobile Database for Persistent Object Storage. Streamline Your Workflow, Eliminate Repetitive Tasks, and Enjoy a User-Friendly Data Interface.
Last updated
Was this helpful?
ObjectBox tools and dependencies are available on .
To add ObjectBox to your Android project, follow these steps:
Open the Gradle build file of your root project (not the ones for your app or module subprojects) and add a global variable for the version and the ObjectBox Gradle plugin:
Open the Gradle build file for your app or module subproject and, after the com.android.application
plugin, apply the io.objectbox
plugin:
Then do "Sync Project with Gradle Files" in Android Studio so the Gradle plugin automatically adds the required ObjectBox libraries and code generation tasks.
Your project can now use ObjectBox, continue by defining entity classes.
Define your data model by creating a class with at least an ID property, a so called entity.
A simple entity representing a user with an ID and a name property could look like this:
Important:
Entities must also have a no-argument constructor, or for better performance, a constructor with all properties as arguments. In the above examples, a default, no-argument constructor is generated by the compiler.
For more details about entities, like how to create an index or a relation, check the Entity Annotations page.
Next, we generate some binding code based on the model defined in the previous step.
Build your project to generate the MyObjectBox
class and other classes required to use ObjectBox, for example using Build > Make Project in Android Studio.
To change the package of the MyObjectBox
class, see the annotation processor options on the Advanced Setup page.
Among other files ObjectBox generates a JSON model file, by default to
app/objectbox-models/default.json
for Android projects,
lib/objectbox-model.json
for Dart/Flutter projects, or
<user-module-dir>/objectbox-model.json
for Python projects
To change the model file path, see Advanced Setup.
This JSON file changes when you change your entity classes (or sometimes with a new version of ObjectBox).
Keep this JSON file, commit the changes to version control!
This file keeps track of unique IDs assigned to your entities and properties. This ensures that an older version of your database can be smoothly upgraded if your entities or properties change.
Create it using the builder returned by the generated MyObjectBox
class, for example in a small helper class like this:
It is possible to specify various options when building a store. Notably for testing or caching, to use an in-memory database that does not create any files:
These are some of the operations offered by the Box class:
put inserts a new object or updates an existing one (with the same ID). When inserting, an ID will be assigned to the just inserted object (this will be explained below) and returned. put
also supports putting multiple objects, which is more efficient.
get and getAll: Given an object’s ID, get
reads it from its box. To get all objects in the box use getAll
.
remove and removeAll: Remove a previously put object from its box (deletes it). remove
also supports removing multiple objects, which is more efficient. removeAll
removes (deletes) all objects in a box.
count: Returns the number of objects stored in this box.
ObjectBox has built-in support to run (typically multiple or larger) database operations asynchronously.
runInTxAsync and callInTxAsync: runs the given Runnable/Callable in a transaction on a background thread (the internal ObjectBox thread pool) and calls the given callback once done. In case of callInTxAsync the callback also receives the returned result.
awaitCallInTx (Kotlin Coroutines only): wraps callInTxAsync in a coroutine that suspends until the transaction has completed. Likewise, on success the return value of the given callable is returned, on failure an exception is thrown.
By default IDs for new objects are assigned by ObjectBox. When a new object is put, it will be assigned the next highest available ID:
For example, if there is an object with ID 1 and another with ID 100 in a box, the next new object that is put will be assigned ID 101.
If you try to assign a new ID yourself and put the object, ObjectBox will throw an error.
Object IDs can not be:
0
(zero) or null
(if using java.lang.Long) As said above, when putting an object with ID zero it will be assigned an unused ID (not zero).
0xFFFFFFFFFFFFFFFF
(-1 in Java) Reserved for internal use.
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()
.
To enable debug mode and for advanced use cases, see the Advanced Setup page.
If you encounter any problems in this or later steps, check out the and pages.
Prefer to look at example code? Check out .
ObjectBox tools and dependencies are available on .
To set up a Maven project, see the .
The instructions assume a is used.
add the :
For IntelliJ IDEA see the .
For Eclipse see the project and article.
On Windows you might have to install the latest to use ObjectBox.
Prefer to look at example code? Check out our .
Or to use (requires access to the Sync feature) instead run:
For Linux Desktop apps: the Flutter snap ships with an outdated version of CMake. instead to use the version of CMake installed on your system.
Prefer to look at example code? Check out our .
Install the for your system (on Windows you can use "Git Bash"):
Or to use (requires access to the Sync feature) instead run:
Natively compiled Dart applications that use ObjectBox Dart require a reference to the library. Hence, the shared library file downloaded with install.sh
needs to be shipped with the executable.
Prefer to look at example code? Check out our .
Entities must have exactly one 64-bit integer ID property (a Java long
, Kotlin Long
, Dart int
). If you need another type for the ID, like a string, for some tips. Also, the ID property must have non-private visibility (or non-private getter and setter methods).
is already built-in, but almost any type can be stored .
You can also .
The model file also enables you to keep data or to when two of your developers make changes at the same time.
(Java) or (Dart) is the entry point for using ObjectBox. It is the direct interface to the database and manages Boxes. Typically, you want to only have a single Store (single database) and keep it open while your app is running, not closing it explicitly.
If you encounter UnsatisfiedLinkError
or LinkageError
on the build call, see for solutions.
The best time to initialize ObjectBox is when your app starts. We suggest to do it in the onCreate
method of your :
If you encounter UnsatisfiedLinkError
or LinkageError
on the build call, see for solutions.
The best time to initialize ObjectBox is when your app starts. We suggest to do it in the onCreate
method of your :
For sandboxed macOS apps also pass macosApplicationGroup
to openStore()
. See the notes about "macOS application group" in of the Store
class.
On mobile devices or sandboxed apps data should be stored in the app's documents directory. See for more info. This is exactly what openStore()
does, if the directory
argument is not specified.
When using Dart isolates, note that , they do not share state on the Dart level.
However, as ObjectBox runs on the native or process level (so one native instance shared across all isolates), instead of creating a new Store in another isolate your code should instead .
When using Dart isolates, note that , they do not share state on the Dart level.
However, as ObjectBox runs on the native or process level (so one native instance shared across all isolates), instead of creating a new Store in another isolate your code should instead .
For more store configuration options: for Java see the and for Dart the documentation. (Python APIs will be published soon)
The is likely the class you interact with most. A Box instance gives you access to objects of a particular type. For example, if you have User
and Order
entities, you need a Box object to interact with each:
query: Starts building a query to return objects from the box that match certain conditions. See for details.
For a complete list of methods available in the Box class, check the API reference documentation for or .
To run multiple operations, it is more efficient to wrap the synchronous calls in an asynchronous transaction with runInTransactionAsync (): run a callback with multiple database operations within a write or read transaction in the background without blocking the user interface. Can return results.
There is also runAsync (): like runInTransactionAsync but does not start a transaction, leaving that to your callback code. This allows to supply a callback that is an async function.
If you need to assign IDs by yourself, have a look at and what side effects apply.
For a detailed explanation see the page on .
For more details check the separate .
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 and . if you have any questions!
Check out the .
Learn about and .
Learn .