Getting started

Search…
Getting started
ObjectBox is a super fast mobile database that persists objects. It lets you avoid many repetitive tasks and offers a simple interface to your data.
Add ObjectBox to your project
Java/Kotlin (Android)
Java/Kotlin (Desktop)
Flutter
Dart
Video Tutorial on Getting Started with ObjectBox for Android and Java
ObjectBox is available from the Central repository. To add ObjectBox to your Android project, open the root build.gradle file of your project (not the ones for your app or module) and add a global variable for the version and the ObjectBox Gradle plugin:
buildscript {
    ext.objectboxVersion = "3.3.1"
    repositories {
        mavenCentral()
        // Note: 2.9.0 and older are available on jcenter()
    }
    dependencies {
        // Android Gradle Plugin 3.3.0 or later supported.
        classpath("com.android.tools.build:gradle:7.2.2")
        classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
    }
}
Open the build.gradle file for your app or module and, after the com.android.application plugin, apply the io.objectbox plugin:
// Using plugins syntax:
plugins {
    id("com.android.application")
    id("kotlin-android") // Only for Kotlin projects.
    id("kotlin-kapt") // Only for Kotlin projects.
    id("io.objectbox") // Apply last.
}
​
// Or using the old apply syntax:
apply plugin: "com.android.application"
apply plugin: "kotlin-android" // Only for Kotlin projects.
apply plugin: "kotlin-kapt" // Only for Kotlin projects.
apply plugin: "io.objectbox" // Apply last.
If you encounter any problems in this or later steps, check out the FAQ and Troubleshooting pages.
Then do "Sync Project with Gradle Files" in Android Studio so the Gradle plugin automatically adds the required ObjectBox libraries and code generation tasks.
Optional: Advanced Setup
The ObjectBox plugin uses reasonable defaults and detects most configurations automatically. However, if needed you can configure the model file path, the MyObjectBox package, enable debug mode and more using advanced setup options.
ObjectBox for Java supports plain Java or Kotlin projects. See the following page on how to add ObjectBox to a plain Java project.
Java Desktop Apps
​
Video Tutorial on Getting Started with ObjectBox for Flutter
You can watch these video tutorials as well 😀:
​Restaurant: chef and order apps​
​Task-list app (in Spanish)​
Add these dependencies to your pubspec.yaml:
dependencies:
  objectbox: ^1.6.2
  objectbox_flutter_libs: any
  # for ObjectBox Sync use this dependency instead:
  # objectbox_sync_flutter_libs: any
​
dev_dependencies:
  build_runner: ^2.0.0
  objectbox_generator: any
Then install the packages: flutter pub get
For XCode/iOS only: increase the deployment target to iOS 11 and, under Architectures, replace ${ARCHS_STANDARD} with arm64 (or $ARCHS_STANDARD_64_BIT). 
For Flutter Desktop apps on Linux: the Flutter snap ships with an outdated version of CMake. Install Flutter manually instead to use the version of CMake installed on your system.
If you're creating a sandboxed macOS app: you need to specify an application group. Check all macos/Runner/*.entitlements files if they contain a <dict> section with correct group ID info. Change the string value to the DEVELOPMENT_TEAM you can find in your Xcode settings, plus an application-specific suffix, for example: 
macos/Runner/*.entitlements
<dict>
  <key>com.apple.security.application-groups</key>
  <array>
    <string>FGDTDLOBXDJ.demo</string>
  </array>  
...  
</dict>
Next, in your app code, pass the same string when opening the Store, for example: openStore(macosApplicationGroup: 'FGDTDLOBXDJ.demo').  Note: Pick a short group identifier; there's an internal limit in macOS that requires the complete string to be 19 characters or fewer.
To run unit tests on your machine, download a native ObjectBox library for your machine by running this script in a bash shell (e.g. Git Bash on Windows):
bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-dart/main/install.sh)
Add these dependencies to your pubspec.yaml:
dependencies:
  objectbox: ^1.6.2
​
dev_dependencies:
  build_runner: ^2.0.0
  objectbox_generator: any
Install the packages: dart pub get
Install objectbox-c (use "Git bash" on Windows):
bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-dart/main/install.sh)
By default the library is downloaded into the lib subdirectory of the working directory. It's not necessary to install the library system-wide. This also allows to use different versions for different projects. For details see below.
To install ObjectBox Sync variant of the native library, pass --sync argument to the script:
bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-dart/main/install.sh) --sync
​
Deploying Dart-native projects 
Natively compiled Dart applications that use ObjectBox Dart require a reference to the objectbox-c library. Hence, the shared library file downloaded with install.sh needs to be shipped with the executable.
The install.sh script downloads the library by default to the lib subdirectory of the working directory. An executable using ObjectBox Dart looks for the library in this lib directory.
If it is not found there, it falls back to using system directories (using Dart's DynamicLibrary.open):
Windows: working directory and %WINDIR%\system32. 
macOS: /usr/local/lib (and maybe others). 
Linux: /lib and /usr/lib (again, possibly others).
Define Entity Classes
Next, define your model by annotating at least one class with @Entity and @Id. A simple entity representing a user could look like this:
Java
Kotlin
Dart
User.java
@Entity
public class User {
    @Id 
    public long id;
    public String name;
}
models.kt
@Entity
data class User(
        @Id 
        var id: Long = 0,
        var name: String? = null
)
When using a data class, add default values for all parameters. This will ensure your data class will have a constructor that can be called by ObjectBox. (Technically this is only required if adding properties to the class body, like custom or transient properties or relations, but it's a good idea to do it always.)
models.dart
@Entity()
class User {
  // Annotate with @Id() if name isn't "id" (case insensitive).
  int id = 0;
  String? name;
)
Entities must have one ID property of type long (or Long in Kotlin, int in Dart). If you need to use other types, like a String ID, see the @Id annotation docs. Also, it must have non-private visibility (or non-private getter and setter methods).
Entities must also have a no-args constructor, or for better performance, a constructor with all properties as arguments. In the above example, a default, no-args constructor is generated by the compiler.
​Support for many property types is already built-in, but almost any type can be stored with a converter.
For a deeper explanation and a look at all other available annotations (e.g. for relations and indexes) check the Entity Annotations page.
Generate ObjectBox code
Java/Kotlin
Flutter
Dart
Build your project to generate the classes required to use ObjectBox, for example using Build > Make Project in Android Studio.
Note: If you make significant changes to your entities, e.g. by moving them or modifying annotations, make sure to rebuild the project so generated ObjectBox code is updated.
Run flutter pub run build_runner build  to generate the binding code required to use ObjectBox.
ObjectBox generator will look for all @Entity annotations in your lib folder and create a single database definition lib/objectbox-model.json and supporting code in lib/objectbox.g.dart
Add objectbox.g.dart to your version control ignore list (e.g. .gitignore), otherwise build_runner will complain about it being changed each time you pull a change.
Run dart run build_runner build to generate the binding code required to use ObjectBox.
ObjectBox generator will look for all @Entity annotations in your lib folder and create a single database definition lib/objectbox-model.json and supporting code in lib/objectbox.g.dart
Add objectbox.g.dart to your version control ignore list (e.g. .gitignore), otherwise build_runner will complain about it being changed each time you pull a change.
Keep the Model file
Among other files ObjectBox generates a JSON model file, by default to
app/objectbox-models/default.json for Android projects, or
lib/objectbox-model.json for Dart/Flutter projects.
In Android Studio you might have to switch the Project view from Android to Project to see the default.json model file.
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.
The model file also enables you to keep data when renaming entities or properties or to resolve conflicts when two of your developers make changes at the same time.
Create a Store
​BoxStore (Java) or Store (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.
Java (Android)
Kotlin (Android)
Flutter
Dart
Create it using the builder returned by the generated MyObjectBox class, for example in a small helper class like this:
public class ObjectBox {
    private static BoxStore boxStore;
​
    public static void init(Context context) {
        boxStore = MyObjectBox.builder()
                .androidContext(context.getApplicationContext())
                .build();
    }
​
    public static BoxStore get() { return boxStore; }
}
If you encounter UnsatisfiedLinkError or LinkageError on the build call, see App Bundle, split APKs and Multidex for solutions.
The best time to initialize ObjectBox is when your app starts. We suggest to do it in the onCreate method of your Application class:
public class ExampleApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        ObjectBox.init(this);
    }
}
Create it using the builder returned by the generated MyObjectBox class, for example in a small helper class like this:
object ObjectBox {
    lateinit var store: BoxStore
        private set
​
    fun init(context: Context) {
        store = MyObjectBox.builder()
                .androidContext(context.applicationContext)
                .build()
    }
}
If you encounter UnsatisfiedLinkError or LinkageError on the build call, see App Bundle, split APKs and Multidex for solutions.
The best time to initialize ObjectBox is when your app starts. We suggest to do it in the onCreate method of your Application class:
class ExampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        ObjectBox.init(this)
    }
}
Create it using the generated openStore() method, for example in a small helper class like this:
import 'package:path/path.dart' as p;
import 'package:path_provider/path_provider.dart';
import 'objectbox.g.dart'; // created by `flutter pub run build_runner build`
​
class ObjectBox {
  /// The Store of this app.
  late final Store store;
  
  ObjectBox._create(this.store) {
    // Add any additional setup code, e.g. build queries.
  }
​
  /// Create an instance of ObjectBox to use throughout the app.
  static Future<ObjectBox> create() async {
    final docsDir = await getApplicationDocumentsDirectory();
    // Future<Store> openStore() {...} is defined in the generated objectbox.g.dart
    final store = await openStore(directory: p.join(docsDir.path, "obx-example"));
    return ObjectBox._create(store);
  }
}
On mobile devices/sandboxed apps, data should be stored in the app's documents directory. See Flutter: read & write files for more info. This is exactly what openStore()does, if the directory argument is not specified.
On desktop systems it is recommended to specify a directory to create a custom sub-directory to avoid conflicts with other apps.
If your code passes a directory that the application can't write to, you get an error that looks somewhat like this: failed to create store: 10199 Dir does not exist: objectbox (30).
The best time to initialize ObjectBox is when your app starts. We suggest to do it in your app's main() function:
/// Provides access to the ObjectBox Store throughout the app.
late ObjectBox objectbox;
​
Future<void> main() async {
  // This is required so ObjectBox can get the application directory
  // to store the database in.
  WidgetsFlutterBinding.ensureInitialized();
​
  objectbox = await ObjectBox.create();
​
  runApp(MyApp());
}
Create it using the generated getObjectBoxModel() method, for example like this:
import 'objectbox.g.dart'; // created by `dart pub run build_runner build`
​
void main() {
  // Store openStore() {...} is defined in the generated objectbox.g.dart
  final store = openStore();
​
  // your app code ...
​
  store.close(); // don't forget to close the store
}
The above minimal example omits the argument to (directory: ), using the default - ./objectbox  - in the current working directory.
​
Basic Box operations
The Box class 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:
Java
Kotlin
Dart
Box<User> userBox = ObjectBox.get().boxFor(User.class);
Box<Order> orderBox = ObjectBox.get().boxFor(Order.class);
val userBox = ObjectBox.store.boxFor(User::class.java)
val orderBox = ObjectBox.store.boxFor(Order::class.java)
final userBox = store.box<User>();
final orderBox = store.box<Order>();
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.
Java
Kotlin
Dart
User user = new User("Tina");
userBox.put(user);
​
List<User> users = getNewUsers();
userBox.put(users);
val user = User("Tina")
userBox.put(user)
​
val users: List<User> = getNewUsers()
userBox.put(users)
final user = User(name: 'Tina');
userBox.put(user);
​
final users = getNewUsers();
userBox.putMany(users);
get and getAll: Given an object’s ID, get reads it from its box. To get all objects in the box use getAll .
Java
Kotlin
Dart
User user = userBox.get(userId);
​
List<User> users = userBox.getAll();
val user = userBox[userId]
​
val users = userBox.all
final user = userBox.get(userId);
​
final users = userBox.getMany(userIds);
​
final users = userBox.getAll();
query: Starts building a query to return objects from the box that match certain conditions. See queries for details.
Java
Kotlin
Dart
Query<User> query = userBox
    .query(User_.name.equal("Tom"))
    .order(User_.name)
    .build();
List<User> results = query.find();
query.close();
val query = userBox
    .query(User_.name.equal("Tom"))
    .order(User_.name)
    .build()
val results = query.find()
query.close()
final query =
    (userBox.query(User_.name.equals('Tom'))..order(User_.name)).build();
final results = query.find();
query.close();
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.
Java
Kotlin
Dart
boolean isRemoved = userBox.remove(userId);
​
userBox.remove(users);
// alternatively:
userBox.removeByIds(userIds);
​
userBox.removeAll();
val isRemoved = userBox.remove(userId)
​
userBox.remove(users)
// alternatively:
userBox.removeByIds(userIds)
​
userBox.removeAll()
final isRemoved = userBox.remove(userId);
​
userBox.removeMany(userIds);
​
userBox.removeAll();
count: Returns the number of objects stored in this box.
Java
Kotlin
Dart
long userCount = userBox.count();
val userCount = userBox.count()
final userCount = userBox.count();
For a complete list of methods available in the Box class, check the API reference documentation for Java or Dart.
Asynchronous operations
ObjectBox has some built-in support for running multiple or larger database operations asynchronously.
Java
Dart
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.
boxStore.callInTxAsync(() -> {
    Box<User> box = boxStore.boxFor(User.class);
    String name = box.get(userId).name;
    box.remove(userId);
    return text;
}, (result, error) -> {
    if (error != null) {
        System.out.println("Failed to remove user with id " + userId);
    } else {
        System.out.println("Removed user with name: " + 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.
try {
    val name = boxStore.awaitCallInTx {
        val box = boxStore.boxFor(User::class.java)
        val name = box.get(userId).name
        box.remove(userId)
        name
    }
    println("Removed user with name $name")
} catch (e: Exception) {
    println("Failed to remove user with id $userId")
}
putAsync: asynchronously inserts a new object or updates an existing one (with the same ID). The returned future completes when the object is successfully written to the database.
final user = User(name: 'Tina');
Future<int> idFuture = userBox.putAsync(user);
​
...
​
final id = await idFuture;
userBox.get(id); // after the future completed, the object is inserted
​
putQueued: Schedules the given object to be put later on, by an asynchronous queue, returns the id immediately even though the object may not have been written yet. You can use store's awaitAsyncCompletion() and awaitAsyncSubmitted() to wait for the async queue to finish.
for (int i = 0; i < 100; i++) {
  userBox.putQueued(User(name: 'User $i'));
}
store.awaitAsyncSubmitted();
// after `awaitAsync*`: objects are inserted
expect(userBox.count(), equals(100));
​
runInTransactionAsync (API reference): run a callback with multiple database operations within a write or read transaction in the background without blocking the user interface. This uses a worker isolate. Can return results.
It is currently not possible to return objects with relations as a result (they contain pointers which can not be sent between isolates).
// The callback must be a function that can be sent to an isolate: 
// either a top-level function, static method or a closure that only
// captures objects that can be sent to an isolate.
String? readNameAndRemove(Store store, int objectId) {
  var box = store.box<User>();
  final nameOrNull = box.get(objectId)?.name;
  box.remove(objectId);
  return nameOrNull;
}
final nameOrNull = 
  await store.runInTransactionAsync(TxMode.write, readNameAndRemove, objectId);
​
runAsync (API reference): 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.
​
Object IDs
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:
Java
Kotlin
Dart
User user = new User();
// user.id == 0
box.put(user);
// user.id != 0
long id = user.id;
val user = User()
// user.id == 0
box.put(user)
// user.id != 0
val id = user.id
final user = User();
// user.id == 0
box.put(user);
// user.id != 0
final id = user.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.
If you need to assign IDs by yourself, have a look at how to switch to self-assigned IDs and what side effects apply.
Reserved Object IDs
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.
For a detailed explanation see the page on Object IDs.
Transactions
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().
For more details check the separate transaction documentation.
Have an app with greenDAO? DaoCompat is for you!
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 the documentation and the example. Contact us if you have any questions!
Next steps
Check out the ObjectBox example projects on GitHub.
Learn about Queries and Relations.
ObjectBox Docs (Java, Kotlin, Dart)
Tutorial: Demo Project
Last modified 17d ago
Export as PDF
Copy link
Outline
Add ObjectBox to your project
Define Entity Classes
Generate ObjectBox code
Keep the Model file
Create a Store
Basic Box operations
Asynchronous operations
Object IDs
Reserved Object IDs
Transactions
Have an app with greenDAO? DaoCompat is for you!
Next steps