🚀 Our mission is to revolutionize mobile app development by making it fast and efficient with our intuitive and user-friendly native-language APIs. With ObjectBox, you can easily store and synchronize objects in various programming languages such as Python, Java, C, Go, Kotlin, Dart, C++, and Swift. It works seamlessly across different platforms like Android, iOS, Windows, and Linux, and you can even use it with Docker.

💚 Please share your feedback! Community feedback is very important for us as we strive to make ObjectBox better for our users. Our feedback form is anonymous and only takes 2 minutes to fill in. Every response is highly appreciated. Thank you in advance! 🙏

👍 To rate this documentation, use the "Was this page helpful?" smiley 🙃 at the end of each page.

🚩 Feel free to open an issue on GitHub (for Java & Kotlin or Dart/Flutter) or send us your comments to contact[at]objectbox.io - Thank you! - and if you like what you see, we also appreciate a shout out :) or GitHub star ⭐

Learn all about Local Unit Tests, LiveData, Paging, and App Bundle. Please let us know, if our developer resources are helpful for you: The smiley at the bottom of the page already gives us an indication.

Android Local Unit Tests

ObjectBox supports local unit tests. This gives you the full ObjectBox functionality for running super fast test directly on your development machine.

On Android, unit tests can either run on an Android device (or emulator), so called instrumented tests, or they can run on your local development machine. Running local unit tests is typically much faster.

To learn how local unit tests for Android work in general have a look at the Android developers documentation on Building Local Unit Tests. Read along to learn how to use ObjectBox in your local unit tests.

Set Up Your Testing Environment

Add the native ObjectBox library for your operating system to your existing test dependencies in your app’s build.gradle file:

dependencies {
    // Required -- JUnit 4 framework
    testImplementation("junit:junit:4.12")
    // Optional -- manually add native ObjectBox library to override auto-detection
    testImplementation("io.objectbox:objectbox-linux:$objectboxVersion")
    testImplementation("io.objectbox:objectbox-macos:$objectboxVersion")
    testImplementation("io.objectbox:objectbox-windows:$objectboxVersion")
    // Not added automatically:
    // Since 2.9.0 we also provide ARM support for the Linux library
    testImplementation("io.objectbox:objectbox-linux-arm64:$objectboxVersion")       
    testImplementation("io.objectbox:objectbox-linux-armv7:$objectboxVersion")
}

Create a Local Unit Test Class

You create your local unit test class as usual under module-name/src/test/java/. To use ObjectBox in your test methods you need to build a BoxStore instance using the generated MyObjectBox class of your project. You can use the directory(File) method on the BoxStore builder to ensure the test database is stored in a specific folder on your machine. To start with a clean database for each test you can delete the existing database using BoxStore.deleteAllFiles(File).

The following example shows how you could implement a local unit test class that uses ObjectBox:

public class NoteTest {
    
    private static final File TEST_DIRECTORY = new File("objectbox-example/test-db");
    private BoxStore store;
    
    @Before
    public void setUp() throws Exception {
        // Delete any files in the test directory before each test to start with a clean database.
        BoxStore.deleteAllFiles(TEST_DIRECTORY);
        store = MyObjectBox.builder()
                // Use a custom directory to store the database files in.
                .directory(TEST_DIRECTORY)
                // Optional: add debug flags for more detailed ObjectBox log output.
                .debugFlags(DebugFlags.LOG_QUERIES | DebugFlags.LOG_QUERY_PARAMETERS)
                .build();
    }
    
    @After
    public void tearDown() throws Exception {
        if (store != null) {
            store.close();
            store = null;
        }
        BoxStore.deleteAllFiles(TEST_DIRECTORY);
    }
    
    @Test
    public void exampleTest() {
        // get a box and use ObjectBox as usual
        Box<Note> noteBox = store.boxFor(Note.class);
        assertEquals(...);
    }
    
}

open class NoteTest {

    private var _store: BoxStore? = null
    protected val store: BoxStore
        get() = _store!!

    @Before
    fun setUp() {
        // Delete any files in the test directory before each test to start with a clean database.
        BoxStore.deleteAllFiles(TEST_DIRECTORY)
        _store = MyObjectBox.builder()
            // Use a custom directory to store the database files in.
            .directory(TEST_DIRECTORY)
            // Optional: add debug flags for more detailed ObjectBox log output.
            .debugFlags(DebugFlags.LOG_QUERIES or DebugFlags.LOG_QUERY_PARAMETERS)
            .build()
    }

    @After
    fun tearDown() {
        _store?.close()
        _store = null
        BoxStore.deleteAllFiles(TEST_DIRECTORY)
    }
    
    @Test
    fun exampleTest() {
        // Get a box and use ObjectBox as usual
        val noteBox = store.boxFor(Note::class.java)
        assertEquals(...)
    }

    companion object {
        private val TEST_DIRECTORY = File("objectbox-example/test-db")
    }
}

Base class for tests

It’s usually a good idea to extract the setup and tear down methods into a base class for your tests. E.g.:

public class AbstractObjectBoxTest {

    private static final File TEST_DIRECTORY = new File("objectbox-example/test-db");

    protected BoxStore store;

    @Before
    public void setUp() throws Exception {
        // Delete any files in the test directory before each test to start with a clean database.
        BoxStore.deleteAllFiles(TEST_DIRECTORY);
        store = MyObjectBox.builder()
                // Use a custom directory to store the database files in.
                .directory(TEST_DIRECTORY)
                // Optional: add debug flags for more detailed ObjectBox log output.
                .debugFlags(DebugFlags.LOG_QUERIES | DebugFlags.LOG_QUERY_PARAMETERS)
                .build();
    }

    @After
    public void tearDown() throws Exception {
        if (store != null) {
            store.close();
            store = null;
        }
        BoxStore.deleteAllFiles(TEST_DIRECTORY);
    }
}

open class AbstractObjectBoxTest {

    private var _store: BoxStore? = null
    protected val store: BoxStore
        get() = _store!!

    @Before
    fun setUp() {
        // Delete any files in the test directory before each test to start with a clean database.
        BoxStore.deleteAllFiles(TEST_DIRECTORY)
        _store = MyObjectBox.builder()
            // Use a custom directory to store the database files in.
            .directory(TEST_DIRECTORY)
            // Optional: add debug flags for more detailed ObjectBox log output.
            .debugFlags(DebugFlags.LOG_QUERIES or DebugFlags.LOG_QUERY_PARAMETERS)
            .build()
    }

    @After
    fun tearDown() {
        _store?.close()
        _store = null
        BoxStore.deleteAllFiles(TEST_DIRECTORY)
    }

    companion object {
        private val TEST_DIRECTORY = File("objectbox-example/test-db")
    }
}

Testing Entities with Relations

To test entities that have relations, like ToOne or ToMany properties, on the local JVM you must initialize them and add a transient BoxStore field.

See the documentation about "initialization magic" for an example and what to look out for.

Background: the "initialization magic" is normally done by the ObjectBox plugin using the Android Gradle Plugin Transform API or a Gradle task running after the Java compiler which allows to modify byte-code. However, this does currently not work for Kotlin code in Kotlin desktop projects.

Your app might observe crashes due to UnsatisfiedLinkError or (since ObjectBox 2.3.4) LinkageError on some devices. This has mainly two reasons:

• If your app uses the App Bundle format, the legacy split APK feature or Multidex the native library can't be found.

• Or if your app's minimum SDK level is below API 23 (Marshmallow), there are known bugs in Android's native library loading code.

Let us know if the below suggestions do not resolve your crashes in GitHub issue 605.

App Bundle and split APKs

When using an App Bundle or split APKs Google Play only delivers the split APKs required for each user's device configuration, including its architecture (ABI). If users bypass Google Play to install your app ("sideloading") they might not install all of the required split APKs. If the split APK containing the ObjectBox native library required for the device ABI is missing, your app will crash with LinkageError when building BoxStore.

Using the Play Core library to check for missing splits

Add the Play Core library to the dependencies block:

implementation 'com.google.android.play:core:1.7.3'

In the Application class add the missing split APKs check before calling super.onCreate():

public class App extends Application {

    @Override
    public void onCreate() {
        if (MissingSplitsManagerFactory.create(this).disableAppIfMissingRequiredSplits()) {
            return; // Skip app initialization.
        }
        super.onCreate();
        // ...
    }
}

If a broken installation is detected, users will see a message and Reinstall button asking them to re-install the app from Google Play.

See how we updated our example app to use the Play Core library detection.

If the Play Core library should not be used, there are two alternatives:

Alternative: Catch exception and inform users

You can guard the MyObjectBox build call and for example display an activity with an info message (e.g. direct users to reinstall the app from Google Play, send you an error report, ...):

// guard the build call and set some flag (here setting the boxStore field null)
try {
    boxStore = MyObjectBox.builder()
            .androidContext(context.getApplicationContext())
            .build();
} catch (LinkageError e) {
    boxStore = null;
    Log.e(App.TAG, "Failed to load ObjectBox: " + e.getMessage());
}


// then for example in the main activity check the flag in onCreate and 
// direct to an info/error message without the app crashing:
if (ObjectBox.get() == null) {
    startActivity(new Intent(this, ErrorActivity.class));
    finish();
    return;
}

As an example see how we added this to our Android app example.

Alternative: turn off splitting by ABI

The simplest solution is to always include native libraries for all supported ABIs. However, this will increase the download size of your app for all users.

android {
    bundle {
        abi {
            // This property is set to true by default.
            enableSplit = false
        }
    }
}

Source: Android Developers

Buggy devices (API 22 or lower)

On some devices and if your minimum SDK is below API 23 (Android 6.0 Marshmallow), loading the native library may fail with LinkageError due to known bugs in Android's native library loading code. To counter this ObjectBox includes support for the ReLinker tool which will try to extract the native library manually if loading it normally fails.

To enable this, just add ReLinker to your dependencies:

// https://github.com/KeepSafe/ReLinker/releases
implementation 'com.getkeepsafe.relinker:relinker:1.4.1'

For ProGuard add this line:

-keep class com.getkeepsafe.relinker.** { *; }

For Multidex add a multiDexKeepProguard file to your build file:

android {
    buildTypes {
        release {
            multiDexKeepProguard file('multidex-config.pro')
        }
    }
}

And in the multidex-config.pro file add the same rule as above:

-keep class com.getkeepsafe.relinker.** { *; }

Enable ReLinker debug log

To enable debug logs for ReLinker you can pass a custom ReLinkerInstance when building BoxStore:

boxStore = MyObjectBox.builder()
    .androidContext(App.this)
    .androidReLinker(ReLinker.log(new ReLinker.Logger() {
        @Override
        public void log(String message) { Log.d(TAG, message); }
    }))
    .build();

ObjectBox - LiveData with Android Architecture Components

As an alternative to ObjectBox’ data observers and reactive queries, you can opt for the LiveData approach supplied by Android Architecture Components. ObjectBox comes with ObjectBoxLiveData, a class that can be used inside your ViewModel classes.

A simple ViewModel implementation for our note example app includes the special ObjectBoxLiveData that is constructed using a regular ObjectBox query:

public class NoteViewModel extends ViewModel {
    
    private ObjectBoxLiveData<Note> noteLiveData;
    
    public ObjectBoxLiveData<Note> getNoteLiveData(Box<Note> notesBox) {
        if (noteLiveData == null) {
            // query all notes, sorted a-z by their text
            noteLiveData = new ObjectBoxLiveData<>(notesBox.query().order(Note_.text).build());
        }
        return noteLiveData;
    }
}

Note that we did choose to pass the box to getNoteLiveData() . Instead you could use AndroidViewModel , which provides access to the Application context, and then call ((App)getApplication()).getBoxStore().boxFor() inside the ViewModel. However, the first approach has the advantage that our ViewModel has no reference to Android classes. This makes it easier to unit test.

Now, when creating the activity or fragment we get the ViewModel, access its LiveData and finally register to observe changes:

NoteViewModel model = ViewModelProviders.of(this).get(NoteViewModel.class);
model.getNoteLiveData(notesBox).observe(this, new Observer<List<Note>>() {
    @Override
    public void onChanged(@Nullable List<Note>; notes) {
        notesAdapter.setNotes(notes);
    }
});

The ObjectBoxLiveData will now subscribe to the query and notify observers when the results of the query change, if there is at least one observer. In this example the activity is notified if a note is added or removed. If all observers are destroyed, the LiveData will cancel the subscription to the query.

If you have used ObjectBox observers in the past this might sound familiar. Well, because it is! ObjectBoxLiveData just wraps a DataObserver on the query you give to it.

ObjectBox supports integration with the Paging library that is part of Google's Android Architecture Components. To that end, the ObjectBox Android library (objectbox-android) provides the ObjectBoxDataSource class. It is an implementation of the Paging library's PositionalDataSource.

Using ObjectBoxDataSource

Within your ViewModel, similar to creating a LiveData directly, you first build your ObjectBox query. But then, you construct an ObjectBoxDataSource factory with it instead. This factory is then passed to a LivePagedListBuilder to build the actual LiveData.

Here is an example of a ViewModel class doing just that:

public class NotePagedViewModel extends ViewModel {
    
    private LiveData<PagedList<Note>> noteLiveDataPaged;
    
    public LiveData<PagedList<Note>> getNoteLiveDataPaged(Box<Note> notesBox) {
        if (noteLiveDataPaged == null) {
            // query all notes, sorted a-z by their text
            Query<Note> query = notesBox.query().order(Note_.text).build();
            // build LiveData
            noteLiveDataPaged = new LivePagedListBuilder<>(
                    new ObjectBoxDataSource.Factory<>(query),
                    20 /* page size */
            ).build();
        }
        return noteLiveDataPaged;
    }
}

Note that the LiveData holds your entity class, here Note, wrapped inside a PagedList. You observe the LiveData as usual in your activity or fragment, then submit the PagedList on changes to your PagedListAdapter of the Paging library.

We will not duplicate how this works here, see the Paging library documentation for details about this.

Next steps

• Have a look at the ObjectBox Architecture Components example code.

• Check out ObjectBox support for LiveData.

• Learn how to build queries.

Vector search is the task of searching for objects whose vector is near to a given input query vector. Applications include semantic/similarity search (often performs better than full text search (FTS)), multi-modal search (text, images, video), recommendation engines and various use cases in AI.

You can use ObjectBox as a plain vector database and store only vectors and IDs. Or, you can have your entire data model stored in ObjectBox since it is also a full database. Choose anything in between that best suits your needs.

To use ObjectBox as a vector database follow these 3 simple steps:

1. Define your data model along with a vector index,

2. Insert your data/vectors,

3. Search for nearest neighbors.

An Example: Cities and their Location

To illustrate these steps, we will use a simplified example using cities throughout the next sections. Each city has a location expressed as latitude and longitude. And thus, we can search cities that are close to a certain point.

In the diagram above, let's look at which are the closest cities to the red point, which is located at latitude 53.0 and longitude 15.0. One can intuitively see that Berlin is closest, followed by Copenhagen and Vienna. In search terms, Berlin, Copenhagen and Vienna are the 3 nearest neighbors to the given point.

A city's location has only 2 dimensions, which is easy to grasp. While even 3D space can still be quite intuitive, we humans typically have a hard time when dimensions increase beyond that. But this is exactly where vector databases shine: they handle high-dimensional data with typically hundreds or thousands of dimensions.

Data Model and Vector Index

In order to enable efficient vector search, a vector database needs to "index" the data. This is true for ordinary data too, just that a vector index is a "special" index. ObjectBox relies on Hierarchical Navigable Small Worlds (HNSW), a state-of-the-art algorithm for approximate nearest neighbor (ANN) search that performs very fast and is very scalable.

So, this is what a City data class with an HNSW index definition can look like:

As a starting point the index configuration only needs the number of dimensions. To optimize the index, you can supply additional options via the annotation later once you got things up and running:

• dimensions (required): how many dimensions of the vector to use for indexing. This is a fixed value that depends on your specific use case (e.g. on your embedding model) and you will typically only use vectors of that exact dimension. For special use cases, you can insert vectors with a higher dimension. However, if the vector of an inserted object has less dimensions, it is completely ignored for indexing (it cannot be found).

• distanceType: the algorithm used to determine the distance between two vectors. By default, (squared) Euclidean distance is used: d(v, w) = length(v - w) Other algorithms, based on cosine, Haversine distance and dot product, are available.

• neighborsPerNode (aka "M" in HNSW terms): the maximum number of connections per node (default: 30). A higher number increases the graph connectivity which can lead to better results, but higher resources usage. Try e.g. 16 for faster but less accurate results, or 64 for more accurate results.

• indexingSearchCount (aka "efConstruction" in HNSW terms): the number of neighbors searched for while indexing (default: 100). The default value serves as a starting point that can likely be optimized for specific datasets and use cases. The higher the value, the more accurate the search, but the longer the indexing will take. If indexing time is not a major concern, a value of at least 200 is recommended to improve search quality.

There are also some advanced options available:

• flags to turn on debug log output, to turn off SIMD padding, or to limit graph reparation when nodes are removed.

• reparationBacklinkProbability: when a node is removed, its neighborhood is repaired. Use this to configure the probability of adding backlinks between repaired nodes (defaults to 1.0, which is always).

• vectorCacheHintSizeKB: a non-binding hint for the maximum size of the vector cache (default: 2 GB). Note: memory is only allocated for caching as needed. E.g. smaller data sets will reserve less memory.

Insert Vector Objects

Vector objects are inserted like any other data objects in ObjectBox (the indexing is done automatically behind the scenes):

Perform a nearest neighbor search

Once the query is built, one of its "find" methods is called to execute it. For vector search, a special set of "find with scores" methods is available, that also return the distance (the "score") to the queried vector. Additionally, only the "find with scores" methods will return the results ordered by the distance (nearest first). And as with other find methods, you can either only retrieve result IDs or complete objects.

And that's it! You have successfully performed your first vector search with ObjectBox. 🎉

AI Embeddings

Vector search is a central component in AI applications. In this context you will often be confronted with the term "embeddings". So, let's have a closer look:

To make complex data (e.g. texts, images, videos, ...) accessible, it is transformed into an N-dimensional vector representation. This is called an embedding. An embedding has a certain meaning (or semantics) based on a given model and is associated with its source document. For example with multi-modal models, the word "cat" would be transformed to a vector that is nearby a vector that originated from a picture of a cat. This is the power of embeddings: they capture the essence of the data they represent. For AI Large Language Models (LLMs) these vector embeddings also mimic some "understanding" and semantics become "computable".

Note that ObjectBox works with vectors, so it is your responsibility to create these vectors. E.g. you need access to some model that transforms data into vectors (embeddings). These models can be online or offline.

Typically, you will also use the model to transform the query. Let's say you have associated all your pictures with a vector by a multi-modal model and stored all vectors into ObjectBox. Now using the same model, you create a search vector to find similar pictures. The input to get this vector can be a single word like "cat", a sentence like "birthday party with friends", or an image showing a specific car.

RAG

To take the previous section on embeddings a bit further, let's enter Retrieval Augmented Generation (RAG). RAG allows interactions between an LLM and external sources to produce better and individual results. Vector databases like ObjectBox are extremely efficient in that regard as they speak the "native language" of LLMs: vector embeddings. In contrast, a standard web search is magnitudes slower. In short, you can make individual data available in ObjectBox and wire it to an LLM to make this knowledge available. This wiring is already done by various libraries such as LangChain.

LangChain

For Python, we offer the package "langchain-objectbox" that integrates ObjectBox into the LangChain framework:

Once installed, you can use ObjectBox as a local on-device vector store. It implements VectorStore and thus you can instantiate it with e.g. from_documents or from_texts or there asynchronous variants. Example:

Current Limitations and Future Plans

Current limitations:

• Python APIs are non-final and subject to change

Expect more features to come:

• Releases for all programming languages supported by ObjectBox

• Closer integration into queries to prefilter objects

• Performance improvements, e.g. on ARM CPUs

• Additional distance functions

• Quantization and support for non-float vectors

Vector Search FAQ

How does this compare to libraries like FAISS?

ObjectBox Vector Search offers significant advantages by combining the capabilities of a vector search engine with the robustness of a full-featured database:

1. No Memory Limitations

   • Unlike in-memory libraries like FAISS, ObjectBox uses disk storage when data exceeds available memory, enabling scalability.

   • Smart caching ensures frequently accessed data remains in memory for optimal performance.

2. Instant Readiness

   • There's no need for an initial data load when starting the application. Simply open the database, and you can immediately begin performing vector searches.

3. Efficient Updates

   • When data changes (e.g., adding, modifying, or deleting entries), ObjectBox only persists the changes (deltas).

   • In contrast, most libraries rewrite the entire dataset, if they even support persistent storage.

4. ACID Transactions

   • ObjectBox ensures all updates are safely persisted, offering robust data integrity.

   • This eliminates concerns about data corruption during unexpected events, such as power outages.

5. Unified Data Storage

   • Vector data is rarely standalone; it often ties to related objects or metadata.

   • ObjectBox enables you to store your entire data model, keeping all related data in one place. For example:

     • An embedding model can generate vectors for images. These vectors can be stored alongside related properties like creation date, tags, filenames, etc.

     • Additionally, associated objects like users (e.g., the creator or those who liked the image) can also be stored within the same database.

With ObjectBox Vector Search, you get a powerful, flexible, and scalable solution tailored for modern applications where data relationships matter.

ObjectBox - Transactions

A transaction can group several operations into a single unit of work that either executes completely or not at all. If you are looking for a more detailed introduction to transactions in general, please consult other resources like Wikipedia on database transactions. For ObjectBox transactions continue reading:

You may not notice it, but almost all interactions with ObjectBox involve transactions. For example, if you call put a write transaction is used. Also if you get an object or query for objects, a read transaction is used. All of this is done under the hood and transparent to you. It may be fine to completely ignore transactions altogether in your app without running into any problems. With more complex apps however, it’s usually worth learning transaction basics to make your app more consistent and efficient.

TL;DR - a quick summary on Transactions

• Accessing data always happens inside an implicit transaction, the API hides this detail for convenience.

• You should use an explicit transaction for non-trivial operations for better speed and atomicity.

• Transactions manage multi-threading; e.g. a transaction is tied to a thread and vice versa.

• Read(-only) transactions never get blocked or block a write transaction.

• There can only be a single write transaction at any time; they run strictly one after the other (sequential).

• Sequential execution simplifies user code that is run in write transactions and makes it safer.

• Keep write transactions short to optimize throughput, e.g. prepare data before entering it.

Explicit Transactions

We learned that all ObjectBox operations run in implicit transactions – unless an explicit transaction is in progress. In the latter case, multiple operations share the (explicit) transaction. In other words, with explicit transactions, you control the transaction boundary. Doing so can greatly improve efficiency and consistency in your app.

The advantage of explicit transactions over the bulk put operations is that you can perform any number of operations and use objects of multiple boxes. In addition, you get a consistent (transactional) view on your data while the transaction is in progress.

Example for a write transaction:

boxStore.runInTx(() -> {
   for(User user: allUsers) {
     if(modify(user)) box.put(user);
     else box.remove(user);
   }
});

with store.write_tx():
    for user in allUsers:
        if modify(user):
            box.put(user)
        else:
            box.remove(user)

Transaction Costs

Understanding transactions is essential to master database performance. If you just remember one sentence on this topic, it should be this one: a write transaction has its price.

Committing a transaction involves syncing data to physical storage, which is a relatively expensive operation for databases. Only when the file system confirms that all data has been stored in a durable manner (not just memory cached), the transaction can be considered successful. This file sync required by a transaction may take a couple of milliseconds. Keep this in mind and try to group several operations (e.g.putcalls) in one transaction.

Consider this example:

for(User user: allUsers) {
   modify(user); // modifies properties of given user
   box.put(user);
}

Do you see what’s wrong with that code? There is an implicit transaction for each user which is very inefficient, especially for a high number of objects. It is much more efficient to use one of the put overloads to store all users at once:

for(User user: allUsers) {
   modify(user); // modifies properties of given user
}
box.put(allUsers);

Much better! If you have 1,000 users, the latter example uses a single transaction to store all users. The first code example uses 1,000 (!) implicit transactions, causing a massive slow down.

Read Transactions

In ObjectBox, read transactions are cheap. In contrast to write transactions, there is no commit and thus no expensive sync to the file system. Operations like get , count , and queries run inside an implicit read transaction if they are not called when already inside an explicit transaction (read or write). Note that it is illegal to put when inside a read transaction: an exception will be thrown.

While read transactions are much cheaper than write transactions, there is still some overhead to starting a read transaction. Thus, for a high number of reads (e.g. hundreds, in a loop), you can improve performance by grouping those reads in a single read transaction (see explicit transactions below).

Multiversion Concurrency

ObjectBox gives developers Multiversion concurrency control (MVCC) semantics. This allows multiple concurrent readers (read transactions) which can execute immediately without blocking or waiting. This is guaranteed by storing multiple versions of (committed) data. Even if a write transaction is in progress, a read transaction can read the last consistent state immediately. Write transactions are executed sequentially to ensure a consistent state. Thus, it is advised to keep write transactions short to avoid blocking other pending write transactions. For example, it is usually a bad idea to do networking or complex calculations while inside a write transaction. Instead, do any expensive operation and prepare objects before entering a write transaction.

Note that you do not have to worry about making write transactions sequential yourself. If multiple threads want to write at the same time (e.g. via put or runInTx), one of the threads will be selected to go first, while the other threads have to wait. It works just like a lock or synchronized in Java.

Locking inside a Write Transaction

Avoid locking (e.g. via synchronized or java.util.concurrent.locks) when inside a write transaction when possible. Because write transactions run exclusively, they effectively acquire a write lock internally. As with all locks, you need to pay close attention when multiple locks are involved. Always obtain locks in the same order to avoid deadlocks. If you acquire a lock “X” inside a transaction, you must ensure that your code does not start another write transaction while having the lock “X”.

On this page:

• ObjectBox Java - Data Observers and Reactive Extensions

• ObjectBox Dart - Reactive Queries

ObjectBox Java - Data Observers and Reactive Extensions

ObjectBox for Java makes it easy for your app to react to data changes by providing:

• data observers,

• reactive extensions,

• and an optional library to work with RxJava.

This makes setting up data flows easy while taking care of threading details.

Reactive Observers: A First Example

Let’s start with an example to demonstrate what you can do with reactive data observers:

// Keep a reference until the subscription is cancelled
// to avoid garbage collection.
private DataSubscription subscription;

// ...

// Build a regular query.
Query<Task> query = taskBox.query().equal(Task_.complete, false).build();
// Subscribe to its results.
subscription = query.subscribe()
     .on(AndroidScheduler.mainThread())
     .observer(data -> updateResultDisplay(data));

// Cancel to no longer receive updates (e.g. leaving screen).
subscription.cancel();

private void updateResultDisplay(List<Task> tasks) {
   // Do something with the given tasks.
}

The first line creates a regular query to get Task objects where task.complete == false. The second line connects an observer to the query. This is what happens:

• the query is executed in the background

• once the query finishes the observer gets the result data

• whenever changes are made to Task objects in the future, the query will be executed again

• once updated query results are in, they are propagated to the observer

• the observer is called on Android’s main thread

Now, let’s dive into the details.

Data Observers Basics

When objects change, ObjectBox notifies subscribed data observers. They can either subscribe to changes of certain object types (via BoxStore) or to query results. To create a data observer you need to implement the generic io.objectbox.reactive.DataObserver interface:

public interface DataObserver<T> {
    void onData(T data);
}

This observer will be called by ObjectBox when necessary: typically shortly after subscribing and when data changes.

Observing General Changes

BoxStore allows a DataObserver to subscribe to object types. Let’s say we have a to-do list app where Task objects get added. To get notified when Task objects are added in another place in our app we can do the following:

DataObserver<Class<Task>> observer = new DataObserver<Class<Task>>() {
    @Override public void onData(Class<Task> data) {
        // TODO Do something, e.g. run a query.
        // Just observing a query can also be done 
        // more easily, read on!
        List<Task> results = store.boxFor(Task.class)
            .query(Task_.text.contains("TODO"))
            .build()
            .find(offset, limit);
    }
};
// Keep the subscription while used 
// to avoid garbage collection of the observer.
subscription = boxStore.subscribe(Task.class).observer(observer);

val observer = object : DataObserver<Class<Task>> {
    override fun onData(data: Class<Task>) {
        // TODO Do something, e.g. run a query.
        // Just observing a query can also be done 
        // more easily, read on!
        val results = store.boxFor(Task::class)
            .query(Task_.text.contains("TODO"))
            .build()
            .find(offset, limit)
    }
}
// Keep the subscription while used 
// to avoid garbage collection of the observer.
subscription = store.subscribe(Task::class.java).observer(observer)

Here onData() is not called with anything useful as data. If you need more than being notified, like to get a list of Task objects following the above example, read on to learn how to observe queries.

Observing Queries

ObjectBox let’s you build queries to find the objects matching certain criteria. Queries are an essential part of ObjectBox: whenever you need a specific set of data, you will probably use a query.

Combining queries and observers results in a convenient and powerful tool: query observers will automatically deliver fresh results whenever changes are made to entities in a box. Let’s say you display a list of to-do tasks in your app. You can use a DataObserver to get all tasks that are not yet completed and pass them to a method updateUi() (note that we are using lambda syntax here):

Query<Task> query = taskBox.query().equal(Task_.completed, false).build();
subscription = query.subscribe().observer(data -> updateResultDisplay(data));

So when is our observer lambda called? Immediately when an observer is subscribed, the query will be run in a separate thread. Once the query result is available, it will be passed to the observer. This is the first call to the observer.

Now let’s say a task gets changed and stored in ObjectBox. It doesn't matter where and how; it might be the user who marked a task as completed, or some backend thread putting additional tasks during synchronization with a server. In any case, the query will notify all observers with (potentially) updated query results.

Note that this pattern can greatly simplify your code: there is a single place where your data comes in to update your user interface. There is no separate initialization code, no wiring of events, no re-running queries, etc.

See the subscribe()-method documentation for more details.

Canceling Subscriptions

When you call observer(), it returns a subscription object implementing the io.objectbox.reactive.DataSubscription interface:

public interface DataSubscription {
    void cancel();
    boolean isCanceled();
}

Keep a reference to the DataSubscription for as long as results should be received, otherwise it can be garbage collected at any point. Also call cancel() on it once the observer should not be notified anymore, e.g. when leaving the current screen:

// Keep a reference for as long as updates should be received.
DataSubscription subscription = boxStore.subscribe().observer(myObserver);

// To no longer receive updates (e.g. leaving screen):
subscription.cancel();

If you have more than one query subscription, you might find it useful to create a DataSubscriptionList instance instead to keep track of multiple DataSubscription objects. Pass the list to the query.subscribe(subList) overload. A basic example goes like this:

private DataSubscriptionList subscriptions = new DataSubscriptionList();

protected void onStart() {
  super.onStart();
  Query<A> queryA = boxA.query().build();
  queryA.subscribe(subscriptions).observe(someObserverForAs);
  Query<B> queryB = boxB.query.build();
  queryB.subscribe(subscriptions).observe(someObserverForBs);
}

protected void onStop() {
  super.onStop();
  // Cancels both subscriptions (for A and B).
  subscriptions.cancel();
}

Observers and Transactions

Observer notifications occur after a transaction is committed. For some scenarios it is especially important to know transaction bounds. If you call box.put() or remove() individually, an implicit transaction is started and committed. For example, this code fragment would trigger data observers on User.class twice:

box.put(friendUser);
box.put(myUser);

// Log:
// User friendUser put.
// Observers of User called.
// User myUser put.
// Observers of User called.

There are several ways to combine several operations into one transaction, for example using one of the runInTx() or callInTx() methods in the BoxStore class. For our simple example, we can simply use an overload of put() accepting multiple objects:

box.put(friendUser, myUser);

// Log:
// Users friendUser and myUser put.
// Observers of User called.

This results in a single transaction and thus in a single DataObserver notification.

Reactive Extensions

In the first part you saw how data observers can help you keep your app state up to date. But there is more: ObjectBox comes with simple and convenient reactive extensions for typical tasks. While most of these are inspired by RxJava, they are not actually based on RxJava. ObjectBox brings its own features because not all developers are familiar with RxJava (for the RxJava ObjectBox library see below). We do not want to impose the complexity (Rx is almost like a new language to learn) and size of RxJava (~10k methods) on everyone. So, let’s keep it simple and neat for now.

Thread Scheduling

On Android, UI updates must occur on the main thread only. Luckily, ObjectBox allows to switch the observer from a background thread over to the main thread. Let’s take a look on a revised version of the to-do task example from above:

Query<Task> query = taskBox.query().equal(Task_.complete, false).build();
// updateResultDisplay is always called on the Android main thread.
subscription = query.subscribe()
    .on(AndroidScheduler.mainThread())
    .observer(data -> updateResultDisplay(data));

Where is the difference? The additional on() call is all that is needed to tell where we want our observer to be called. AndroidScheduler.mainThread() is a built-in scheduler implementation. Alternatively, you can create an AndroidScheduler using a custom Looper, or build a fully custom scheduler by implementing the io.objectbox.reactive.Scheduler interface.

Transforming Data

Maybe you want to transform the data before you hand it over to an observer. Let’s say, you want to keep track of the count of all stored objects for each type. The BoxStore subscription gives you the classes of the objects, and this example shows you how to transform them into actual object counts:

subscription = boxStore.subscribe()
    .transform(clazz -> return boxStore.boxFor(clazz).count())
    .observer(count -> updateCount(count));

Note that the transform operation takes a Class object and returns a Long number. Thus the DataObserver receives the object count as a Long parameter in onData().

While the lambda syntax is nice and brief, let’s look at the io.objectbox.reactive.Transformer interface for clarification of what the transform() method expects as a parameter:

public interface DataTransformer<FROM, TO> {
    TO transform(FROM source) throws Exception;
}

Some additional notes on transformers:

• Transforms are not required to actually “transform” any data. Technically, it is fine to return the same data that is received and just do some processing with (or without) it.

• Transformers are always executed asynchronously. It is fine to perform long lasting operations.

ErrorObserver

Maybe you noticed that a transformer may throw any type of exception. Also, a DataObserver might throw a RuntimeException. In both cases, you can provide an ErrorObserver to be notified about an exception that occurred. The io.objectbox.reactive.ErrorObserver is straight-forward:

public interface ErrorObserver {
    void onError(Throwable th);
}

To specify your ErrorObserver, simply call the onError() method after subscribe().

Single Notifications vs. Only-Changes

When you subscribe to a query, the DataObserver gets both of the following by default:

• Initial query results (right after subscribing)

• Updated query results (underlying data was changed)

Sometimes you may by interested in only one of those. This is what the methods single() and onlyChanges() are for (call them after subscribe()). Single subscriptions are special in the way that they are cancelled automatically once the observer is notified. You can still cancel them manually to ensure no call to the observer is made at a certain point.

Weak References

Sometimes it may be nice to have a weak reference to a data observer. Note that for the sake of a deterministic flow, it is advisable to cancel subscriptions explicitly whenever possible. If that does not scare you off, use weak() after subscribe().

Threading overview

To summarize threading as discussed earlier:

• Query execution runs on a background thread (exclusive for this task)

• DataTransformer runs on a background thread (exclusive for this task)

• DataObserver and ErrorObserver run on a background thread unless a scheduler is specified via the on() method.

ObjectBox RxJava Extension Library

By design, there are zero dependencies on any Rx libraries in the core of ObjectBox. As you saw before ObjectBox gives you simple means to transform data, asynchronous processing, thread scheduling, and one time (single) notifications. However, you still might want to integrate with the mighty RxJava 2 (we have no plans to support RxJava 1). For this purpose we created the ObjectBox RxJava extension library:

implementation "io.objectbox:objectbox-rxjava:$objectboxVersion"

It provides the classes RxQuery and RxBoxStore. Both offer static methods to subscribe using RxJava means.

For general object changes, you can use RxBoxStore to create an Observable. RxQuery allows to subscribe to query objects using:

• Flowable

• Observable

• Single

Example usage:

// Keep a reference until the disposable is disposed
// to avoid garbage collection.
private Disposable disposable;

// ...

Query query = box.query().build();
disposable = RxQuery.observable(query).subscribe(this);

The extension library is open-source and available GitHub.

ObjectBox Dart - Reactive Queries

You can build a Stream from a query to get notified any time there is a change to the box of any of the queried entities:

Stream<Query<Note>> watchedQuery = box.query(condition).watch();
final sub1 = watchedQuery.listen((Query<Note> query) {
  // This gets triggered any time a box of any of the queried entities
  // has changes, e.g. objects are put or removed.
  // Call any query method here, for example:
  print(query.count());
  print(query.find());
});
...
sub1.cancel(); // Cancel the subscription after your code is done.

For a Flutter app you typically want to get the latest results immediately when listening to the stream, and also get a list of objects instead of a query instance:

// Build and watch the query,
// set triggerImmediately to emit the query immediately on listen.
return box.query(condition)
    .watch(triggerImmediately: true)
    // Map it to a list of objects to be used by a StreamBuilder.
    .map((query) => query.find());

ObjectBox – Embedded Database for Java Desktop Apps

Just like on Android, ObjectBox stands for a super simple API and high performance. It’s designed for objects and outperforms other database and ORM solutions. Because it is an embedded database, ObjectBox runs in your apps’ process and needs no maintenance. Read on to learn how to create a Java project using ObjectBox. We believe it’s fairly easy. Please let us know your thoughts on it.

Setup and Usage

See the Getting Started page on how to set up your project, add entities and use the ObjectBox APIs.

Examples

There are example command line apps available in our examples repository.

Building Unit Tests

The setup and writing tests is identical to writing unit tests that run on the local JVM for Android, see Android Local Unit Tests.

ObjectBox and Kotlin

ObjectBox comes with full Kotlin support for Android. This allows entities to be modeled in Kotlin classes (regular and data classes). With Kotlin support you can build faster apps even faster.

Kotlin Entities

ObjectBox supports regular and data classes for entities. However, @Id properties must be var (not val) because ObjectBox assigns the ID after putting a new entity. They also should be of non-null type Long with the special value of zero for marking entities as new.

Can sealed classes be entities? Not directly. Sealed classes are abstract and can't be instantiated. But subclasses of a sealed class should work.

To learn how to create entities, look at these pages:

Defining Relations in Kotlin Entities

When defining relations in Kotlin, keep in mind that relation properties must be var. Otherwise they can not be initialized as described in the relations docs. To avoid null checks use a lateinit modifier. When using a data class this requires the relation property to be moved to the body.

See the Relations page for examples.

Using the provided extension functions

To simplify your code, you might want to use the Kotlin extension functions provided by ObjectBox. The library containing them is added automatically if the Gradle plugin detects a Kotlin project.

To add it manually, modify the dependencies section in your app's build.gradle file:

dependencies {
    implementation("io.objectbox:objectbox-kotlin:$objectboxVersion")
}

Now have a look at what is possible with the extensions compared to standard Kotlin idioms:

Get a box:

// Regular:
val box = store.boxFor(DataClassEntity::class.java)

// With extension:
val box: Box<DataClassEntity> = store.boxFor()

Queries

Build a query:

// Regular:
val query = box.query().run {
    equal(property, value)
    order(property)
    build()
}

// With extension:
val query = box.query {
    equal(property, value)
    order(property)
}

Use the in filter of a query:

// Regular:
val query = box.query().`in`(property, array).build()

// With extension:
val query = box.query().inValues(property, array).build()

Relations

Modify a ToMany:

// Regular:
toMany.apply { 
    reset()
    add(entity)
    removeById(id)
    applyChangesToDb()
}

// With extension:
toMany.applyChangesToDb(resetFirst = true) { // default is false
    add(entity)
    removeById(id)
}

Flow

Get a Flow from a Box or Query subscription (behind the scenes this is based on a Data Observer):

// Listen to all changes to a Box
val flow = store.subscribe(TestEntity::class.java).toFlow()
// Get the latest query results on any changes to a Box
val flow = box.query().subscribe().toFlow()

Something missing? Let us know what other extension functions you want us to add.

Coroutines

To run Box operations on a separate Dispatcher wrap them using withContext:

suspend fun putNote(
    note: Note, 
    dispatcher: CoroutineDispatcher
) = withContext(dispatcher) {
    boxStore.boxFor(Note::class.java).put(note)
}

BoxStore provides an async API to run transactions. There is an extension function available that wraps it in a coroutine:

// Calls callInTxAsync behind the scenes.
val id = boxStore.awaitCallInTx {
    box.put(Note("Hello", 1))
}

Next Steps

• Check out the Kotlin example on GitHub.

• Continue with Getting Started.

ObjectBox - Relations

Objects may reference other objects, for example using a simple reference or a list of objects. In database terms, we call those references relations. The object defining a relation we call the source object, the referenced object we call the target object. So a relation has a direction.

If there is one target object, we call the relation to-one. And if there can be multiple target objects, we call it to-many. Relations are lazily initialized: the actual target objects are fetched from the database when they are first accessed. Once the target objects are fetched, they are cached for further accesses.

To-One Relations

You define a to-one relation using the ToOne class, a smart proxy to the target object. It gets and caches the target object transparently. For example, an order is typically made by one customer. Thus, we could model the Order class to have a to-one relation to the Customer like this:

// Customer.java
@Entity
public class Customer {
    
    @Id public long id;
    
}

// Order.java
@Entity
public class Order {
    
    @Id public long id;
    
    public ToOne<Customer> customer;
    
}

@Entity
data class Customer(
        @Id var id: Long = 0
)

@Entity
data class Order(
        @Id var id: Long = 0
) {
    lateinit var customer: ToOne<Customer>
}

@Entity()
class Customer {
  int id;
}

@Entity()
class Order {
  int id;
  
  final customer = ToOne<Customer>();
}

Now let’s add a customer and some orders. To set the related customer object, call setTarget() (or assign target in Kotlin) on the ToOne instance and put the order object:

Customer customer = new Customer();
Order order = new Order();
order.customer.setTarget(customer);
// Puts order and customer:
long orderId = boxStore.boxFor(Order.class).put(order);

val customer = Customer()
val order = Order()
order.customer.target = customer
// Puts order and customer:
val orderId = boxStore.boxFor(Order::class.java).put(order)

final customer = Customer();
final order = Order();

// set the relation
order.customer.target = customer;
// Or you could create the target object in place:
// order.customer.target = Customer();

// Save the order and customer to the database
int orderId = store.box<Order>().put(order);

If the customer object does not yet exist in the database (i.e. its ID is zero), ToOne will put it (so there will be two puts, one for Order, one for Customer). If it already exists, ToOne will only create the relation (so there's only one put for Order, as explicitly written in the code). See further below for details about updating relations.

Have a look at the following code how you can get (read) the customer of an order:

Order order = boxStore.boxFor(Order.class).get(orderId);
Customer customer = order.customer.getTarget();

val order = boxStore.boxFor(Order::class.java)[orderId]
val customer = order.customer.target

final order = store.box<Order>().get(orderId);
final customer = order.customer.target;

This will do a database call on the first access (lazy loading). It uses lookup by ID, which is very fast in ObjectBox. If you only need the ID instead of the whole target object, you can completely avoid this database operation because it's already loaded: use order.customer.targetId/getTargetId().

We can also remove the relationship to a customer:

order.customer.setTarget(null);
boxStore.boxFor(Order.class).put(order);

order.customer.target = null
boxStore.boxFor(Order::class.java).put(order)

order.customer.target = null; // same as  .targetId = 0;
store.box<Order>().put(order);

Note that this does not remove the customer from the database, it just dissolves the relationship.

How ToOne works behind the scenes

If you look at your model in objectbox-models/default.json (or lib/bjectbox-model.json in Dart) you can see, a ToOne property is not actually stored. Instead, the ID of the target object is saved in a virtual property named like the ToOne property appended with Id.

Expose the ToOne target ID property

You can directly access the target ID property by defining a long (or Long in Kotlin) property in your entity class with the expected name:

@Entity
public class Order {
    @Id public long id;
    
    public long customerId; // ToOne target ID property
    public ToOne<Customer> customer;
}

@Entity
data class Order(
        @Id var id: Long = 0,
        var customerId: Long = 0
) {
    lateinit var customer: ToOne<Customer>
}

You can change the name of the expected target ID property by adding the @TargetIdProperty(String) annotation to a ToOne.

Initialization Magic

Did you notice that the ToOne field customer was never initialized in the code example above? Why can the code still use customer without any NullPointerException? Because the field actually is initialized – the initialization code just is not visible in your sources.

The ObjectBox Gradle plugin will transform your entity class (supported for Android projects and Java JVM projects) to do the proper initialization in constructors before your code is executed. Thus, even in your constructor code, you can just assume ToOne and ToMany/ List properties have been initialized and are ready for you to use.

@Entity
public class Example {
​    
    // Initialize ToOne and ToMany manually.
    ToOne<Order> order = new ToOne<>(this, Example_.order);   
    ToMany<Order> orders = new ToMany<>(this, Example_.orders);
 
    // Add a BoxStore field.
    transient BoxStore __boxStore;
    
}

@Entity
class Example() {

    // Initialize ToOne and ToMany manually.
    var order = ToOne<Order>(this, Example_.order)   
    var orders = ToMany<Order>(this, Example_.orders)

    // Add a BoxStore field.
    @JvmField
    @Transient
    @Suppress("PropertyName")
    var __boxStore: BoxStore? = null

}

Improve Performance

To improve performance when ObjectBox constructs your entities, you should provide an all-properties constructor.

For a ToOne you have to add an id parameter, typically named like the ToOne field appended with Id . Check your objectbox-models/default.json file to find the correct name.

An example:

@Entity
public class Order {
    
    @Id public long id;
    
    public ToOne<Customer> customer;
    
    public Order() { /* default constructor */ }
    
    public Order(long id, long customerId /* virtual ToOne id property */) {
        this.id = id;
        this.customer.setTargetId(customerId);
    }
    
}

To-Many Relations

To define a to-many relation, you can use a property of type ToMany. As the ToOne class, the ToMany class helps you to keep track of changes and to apply them to the database.

Note that to-many relations are resolved lazily on first access, and then cached in the source entity inside the ToMany object. So subsequent calls to any method, like size() of the ToMany, do not query the database, even if the relation was changed elsewhere. To get the latest data fetch the source entity again or call reset() on the ToMany.

There is a slight difference if you require a one-to-many (1:N) or many-to-many (N:M) relation. A 1:N relation is like the example above where a customer can have multiple orders, but an order is only associated with a single customer. An example for an N:M relation is students and teachers: students can have classes by several teachers but a teacher can also instruct several students.

One-to-Many (1:N)

To define a one-to-many relation, you need to annotate your relation property with @Backlink. It links back to a to-one relation in the target object. Using the customer and orders example, we can modify the customer class to have a to-many relation to the customer's orders:

// Customer.java
@Entity
public class Customer {
    
    @Id public long id;
    
    @Backlink(to = "customer")
    public ToMany<Order> orders;
    
}

// Order.java
@Entity
public class Order {
    
    @Id public long id;
    public String name;
    
    public ToOne<Customer> customer;
    
    public Order(String name) {
        this.name = name;
    }
    
    public Order() {
    }
}

@Entity
data class Customer(
        @Id var id: Long = 0
) {    
    @Backlink(to = "customer")
    lateinit var orders: ToMany<Order>
}

@Entity
data class Order(
        @Id var id: Long = 0,
        var name: String? = ""
) {
    lateinit var customer: ToOne<Customer>
}

@Entity()
class Customer {
  int id;

  @Backlink('customer')
  final orders = ToMany<Order>();
}

@Entity()
class Order {
  int id;

  final customer = ToOne<Customer>();
}

Let’s add some orders together with a new customer. ToMany implements the Java List interface, so we can simply add orders to it:

Customer customer = new Customer();
customer.orders.add(new Order("Order #1"));
customer.orders.add(new Order("Order #2"));
// Puts customer and orders:
long customerId = boxStore.boxFor(Customer.class).put(customer);

val customer = Customer()
customer.orders.add(Order("Order #1"))
customer.orders.add(Order("Order #2"))
// Puts customer and orders:
val customerId = boxStore.boxFor(Customer::class.java).put(customer)

Customer customer = Customer();
customer.orders.add(Order()); // Order #1
customer.orders.add(Order()); // Order #2
// Puts customer and orders:
final customerId = store.box<Customer>().put(customer);

If the order entities do not yet exist in the database, ToMany will put them. If they already exist, it will only create the relation (but not put them). See further below for details about updating relations.

We can easily get the orders of a customer back by accessing the list of orders:

Customer customer = boxStore.boxFor(Customer.class).get(customerId);
for (Order order : customer.orders) {
    // Do something with each order.
}

val customer = boxStore.boxFor(Customer::class.java).get(customerId)
for (order in customer.orders) {
    // Do something with each order.
}

Customer customer = store.box<Customer>().get(customerId);
// you can use any List<> functions, for example:
final valueSum = customer.orders.fold(0, (sum, order) => sum + order.value);
// though you could use property queries and their .sum() function for that

Removing orders from the relation works as expected:

// Remove the relation to the first order in the list
Order order = customer.orders.remove(0);
boxStore.boxFor(Customer.class).put(customer);
// Optional: also remove the order entity from its box:
// boxStore.boxFor(Order.class).remove(order);

// Remove the relation to the first order in the list
val order = customer.orders.removeAt(0)
boxStore.boxFor(Customer::class.java).put(customer)
// Optional: also remove the order entity from its box:
// boxStore.boxFor(Order::class.java).remove(order)

// Remove the relation to the first order in the list
Order order = customer.orders.removeAt(0);
store.box<Customer>().put(customer);
// Optional: also remove the order entity from its box:
// store.box<Order>().remove(order);

Many-to-Many (N:M)

To define a many-to-many relation you simply add a property using the ToMany class. Assuming a students and teachers example, this is how a simple student class that has a to-many relation to teachers can look like:

// Teacher.java
@Entity
public class Teacher{
    
    @Id public long id;
    public String name;
    
    public Teacher(String name) {
        this.name = name;
    }
    
    public Teacher() {
    }
}

// Student.java
@Entity
public class Student{
    
    @Id public long id;
    
    public ToMany<Teacher> teachers;
    
}

@Entity
data class Teacher(
        @Id var id: Long = 0,
        var name: String? = ""
)

@Entity
data class Student(
        @Id var id: Long = 0
) {
    lateinit var teachers: ToMany<Teacher>
}

@Entity()
class Teacher{
  int id;
}

@Entity()
class Student{
  int id;
  
  final teachers = ToMany<Teacher>();
}

Adding the teachers of a student works exactly like with a list:

Teacher teacher1 = new Teacher("Teacher 1");
Teacher teacher2 = new Teacher("Teacher 2");

Student student1 = new Student();
student1.teachers.add(teacher1);
student1.teachers.add(teacher2);

Student student2 = new Student();
student2.teachers.add(teacher2);

// Puts students and teachers:
boxStore.boxFor(Student.class).put(student1, student2);

val teacher1 = Teacher("Teacher 1")
val teacher2 = Teacher("Teacher 2")

val student1 = Student()
student1.teachers.add(teacher1)
student1.teachers.add(teacher2)

val student2 = Student()
student2.teachers.add(teacher2)

// Puts students and teachers:
boxStore.boxFor(Student::class.java).put(student1, student2)

Teacher teacher1 = Teacher();
Teacher teacher2 = Teacher();

Student student1 = Student();
student1.teachers.add(teacher1);
student1.teachers.add(teacher2);

Student student2 = Student();
student2.teachers.add(teacher2);

// saves students as well as teachers in the database
store.box<Student>().putMany([student1, student2]);

If the teacher entities do not yet exist in the database, ToMany will also put them. If they already exist, ToMany will only create the relation (but not put them). See further below for details about updating relations.

To get the teachers of a student we just access the list:

Student student = boxStore.boxFor(Student.class).get(studentId);
for (Teacher teacher : student.teachers) {
    // Do something with each teacher.
}

val student = boxStore.boxFor(Student::class.java).get(studentId)
for (teacher in student.teachers) {
    // Do something with each teacher.
}

Student student = store.box<Student>().get(studentId);
// you can use any List<> functions, for example:
student.teachers.forEach((Teacher teacher) => ...);

And if a student drops out of a class, we can remove a teacher from the relation:

student.teachers.remove(0);
// Simply put the student again:
// boxStore.boxFor(Student.class).put(student);
// Or more efficient (than writing the thole object), store just the relations:
student.teachers.applyChangesToDb();

student.teachers.removeAt(0)
// Simply put the student again:
// boxStore.boxFor(Student::class.java).put(student)
// Or more efficient (than writing the thole object), store just the relations:
student.teachers.applyChangesToDb()

student.teachers.removeAt(0)
// Simply put the student again:
// store.box<Student>().put(student);
// Or more efficient (than writing the thole object), store just the relations:
student.teachers.applyToDb();

Access Many-To-Many in the reverse direction

Following the above example, you might want an easy way to find out what students a teacher has. Instead of having to perform a query, you can just add a to-many relation to the teacher and annotate it with the @Backlink annotation:

// Teacher.java
@Entity
public class Teacher{
    
    @Id public long id;
    
    // Backed by the to-many relation in Student:
    @Backlink(to = "teachers")
    public ToMany<Student> students;
    
}

// Student.java
@Entity
public class Student{
    
    @Id public long id;
    
    public ToMany<Teacher> teachers;
    
}

@Entity
data class Teacher(
        @Id var id: Long = 0
) {
    // Backed by the to-many relation in Student:
    @Backlink(to = "teachers")
    lateinit var students: ToMany<Student>
}

@Entity
data class Student(
        @Id var id: Long = 0
) {
    lateinit var teachers: ToMany<Teacher>
}

@Entity()
class Teacher{
  int id;
  
  // Backed by the to-many relation in Student:
  @Backlink()
  final students = ToMany<Student>();
}

@Entity()
public class Student{
  int id;
  
  final teachers = ToMany<Teacher>();
}

Using the List interface for to-many

Instead of the ToMany type it is also possible to use List (or MutableList in Kotlin) for a to-many property. At runtime the property will still be a ToMany instance (ToMany does implement the List interface) due to the initialization magic described above, or if manually initialized as seen in the example below.

// Teacher.java
@Entity
public class Teacher{    
    @Id public long id;    
}

// Student.java
@Entity
public class Student{    
    @Id public long id;    
    public List<Teacher> teachers = new ToMany<>(this, Student_.teachers);   
}

@Entity
data class Teacher(
        @Id var id: Long = 0
)

@Entity
data class Student(
        @Id var id: Long = 0
) {
    var teachers: MutableList<Teacher> = ToMany<>(this, Student_.teachers)
}

Box<Student> studentBox = store.boxFor(Student.class);
Student student = new Student();
Teacher teacher = new Teacher();

// Simulate what a JSON deserialzer would do:
// replace ToMany instance with ArrayList.
student.teachers = new ArrayList();
student.teachers.add(teacher);
// Put will skip the teachers property.
studentBox.put(student);
System.out.println(store.boxFor(Teacher.class).count());
// prints 0

// Need to manually create the relation.
Student student2 = studentBox.get(student.id);
student2.teachers.addAll(student.teachers);
studentBox.put(student2);

Updating Relations

The ToOne and ToMany relation classes assist you to persist the relation state. They keep track of changes and apply them to the database once you put the Object containing them. ObjectBox supports relation updates for new (not yet persisted; ID == 0) and existing (persisted before; ID != 0) Objects.

For convenience, ToOne and ToMany will put Objects added to them if they do not yet exist (ID == 0). If they already exist (their ID != 0, or you are using @Id(assignable = true)), only the relation will be created or destroyed (internally the Object ID is added to or removed from the relation). In that case, to put changes to the properties of related Objects use their specific Box instead:

// update a related entity using its box
Order orderToUpdate = customer.orders.get(0);
orderToUpdate.text = "Revised description";
// DOES NOT WORK
// boxStore.boxFor(Customer.class).put(customer);
// WORKS
boxStore.boxFor(Order.class).put(orderToUpdate);

// update a related entity using its box
Order orderToUpdate = customer.orders.getAt(0);
orderToUpdate.text = "Revised description";
// DOES NOT WORK
// boxStore.boxFor(Customer::class.java).put(customer);
// WORKS
boxStore.boxFor(Order::class.java).put(orderToUpdate);

// update a related entity using its box
Order orderToUpdate = customer.orders[0];
orderToUpdate.text = 'Revised description';
// DOES NOT WORK - the change to the order is not saved
// store.box<Customer>().put(customer);
// WORKS
store.box<Order>().put(orderToUpdate);

Updating ToOne

The ToOne class offers the following methods to update the relation:

• setTarget(target) makes the given (new or existing) Object the new relation target; pass null to clear the relation.

• setTargetId(targetId) sets the relation target based on the given ID of an existing Object; pass 0 (zero) to clear the relation.

• Java/Kotlin only: setAndPutTarget(target) makes the given (new or existing) Object the new relation target and puts the owning, source Object and if needed the target Object.

// Option 1: set target and put.
order.customer.setTarget(customer);
// Or set target via Object ID: 
// order.customer.setCustomerId(customer.getId());
orderBox.put(order);

// Option 2: combined set target and put.
order.customer.setAndPutTarget(customer);

// Option 1: set target and put.
order.customer.setTarget(customer)
// Or set target via Object ID: 
// order.customer.setCustomerId(customer.getId())
orderBox.put(order)

// Option 2: combined set target and put.
order.customer.setAndPutTarget(customer)

Order order = new Order();
orderBox.attach(order);
order.customer.setAndPutTarget(customer);

Customer customer = new Customer();
// If ID is manually assigned, put target Object first
customer.id = 12;
customerBox.put(customer);
// Then can safely set as target
order.customer.setTarget(customer);
// Or set target via Object ID
// order.customer.setCustomerId(customer.getId());
orderBox.put(order);

Updating ToMany

The ToMany relation class is based on a standard List with added change tracking for Objects. As mentioned above, it will put new Objects (ID == 0) that are added to it once the Object owning it is put. And when removing Objects from it, just the relation is cleared, the Objects are not removed from their Box.

See the documentation on One-to-Many and Many-to-Many above for details.

If the owning, source Object uses @Id(assignable = true) attach its Box before modifying its ToMany:

// If source has a manually assigned ID attach Box first
customer.id = 12;
customerBox.attach(customer);
// Then can safely modify ToMany
customer.orders.add(order);
customerBox.put(customer);

If the target Object, like Order above, is using manually assigned IDs put the target Objects before adding them to the ToMany relation:

// If ID is manually assigned put target Object first
order.id = 42;
orderBox.put(order);
// Then can safely add target Object to ToMany
customer.orders.add(order);
customerBox.put(customer);

The above steps are required because, when putting the Object owning the ToMany only the relation is updated. This is because ObjectBox only puts target Objects with an ID of 0. See the documentation about IDs for the background information.

Example: Extending the Model with an Address

A typical extension to the customer/order example we have started earlier would be to add an Address type. While you could model street, ZIP and so on directly into Customer, it usually makes sense to normalize that out into a separate entity. And when you think about the usual shopping sites, they all let you have multiple addresses...

So, typically, this is how you would model that:

• an address is bound to a customer; add a ToOne<Customer> customer to Address

• an order is shipped to one address, and might have a diverging billing address optionally; add ToOne<Address> shippingAddress and ToOne<Address> billingAddress to Order

• For each ToOne you could have a matching ToMany on the other side of the relation (backlink)

Example: Modelling Tree Relations

You can model a tree relation with a to-one and a to-many relation pointing to itself:

@Entity
public class TreeNode {
    @Id long id;
    
    ToOne<TreeNode> parent;
    
    @Backlink
    ToMany<TreeNode> children;
}

@Entity
data class TreeNode(
        @Id var id: Long = 0
) {
    lateinit var parent: ToOne<TreeNode>
    
    @Backlink
    lateinit var children: ToMany<TreeNode>
}

This lets you navigate a tree nodes parent and children:

TreeNode parent = treeNode.parent.getTarget();
List<TreeNode> children = treeNode.children;

val parent: TreeNode = treeNode.parent.target
val children: List<TreeNode> = treeNode.children

This tutorial will walk you through a simple note-taking app explaining how to do basic operations with ObjectBox. To just integrate ObjectBox into your project, look at the Getting Started page.

You can check out the example code from GitHub. This allows you to run the code and explore it in its entirety. It is a simple app for taking notes where you can add new notes by typing in some text and delete notes by clicking on an existing note.

git clone https://github.com/objectbox/objectbox-examples.git
cd objectbox-examples/android-app

git clone https://github.com/objectbox/objectbox-examples.git
cd objectbox-examples/android-app-kotlin

git clone https://github.com/objectbox/objectbox-dart.git
cd objectbox-dart/objectbox/examples/flutter/objectbox_demo

git clone https://github.com/objectbox/objectbox-python.git
cd objectbox-python

The Note entity and Box class

To store notes there is an entity class called Note (or Task in Python). It defines the structure or model of the data persisted (saved) in the database for a note: its id, the note text and the creation date.

@Entity
public class Note {
    
    @Id
    long id;
    
    String text;
    String comment;
    Date date;
    
    ...
}

@Entity
data class Note(
        @Id var id: Long = 0,
        var text: String? = null,
        var comment: String? = null,
        var date: Date? = null
)

@Entity()
class Note {
  int id;
  String text;
  String? comment;
  DateTime date;

  ...
}

@Entity()
class Task:
    id = Id()
    text = String()
    date_created = Date(py_type=int)
    date_finished = Date(py_type=int)

In general, an ObjectBox entity is an annotated class persisted in the database with its properties. In order to extend the note or to create new entities, you simply modify or create new plain classes and annotate them with @Entity and @Id; in Python opt-in uid argument i.e. @Entity(uid=).

# Make sure to install objectbox >= 4.0.0
$ pip install --upgrade objectbox
$ ls example
ollama 
tasks
vectorsearch-cities

$ cd tasks
$ python main.py

Welcome to the ObjectBox tasks-list app example. Type help or ? for a list of commands.
> 

Inserting notes

To see how new notes are added to the database, take a look at the following code fragments. The Box provides database operations for Note objects. A Box is the main interaction with object data.

@Override
public void onCreate(Bundle savedInstanceState) {
    ...
    notesBox = ObjectBox.get().boxFor(Note.class);
    ...
}

public override fun onCreate(savedInstanceState: Bundle?) {
    ...
    notesBox = ObjectBox.boxStore.boxFor()
    ...
}

class ObjectBox {
  late final Store _store;
  late final Box<Note> _box;
  
  ObjectBox._create(this._store) {
    _noteBox = Box<Note>(_store);
    ...

class TasklistCmd(Cmd):
    # ...

    def __init__(self):
        # ...
        self._store = Store(directory="tasklist-db")
        self._task_box = self._store.box(Task)

When a user adds a note the method addNote() is called. There, a new Note object is created and put into the database using the Box reference:

private void addNote() {
    ...
    Note note = new Note();
    note.setText(noteText);
    note.setComment(comment);
    note.setDate(new Date());
    notesBox.put(note);
    Log.d(App.TAG, "Inserted new note, ID: " + note.getId());
    ...
}

private fun addNote() {
    ...
    val note = Note(text = noteText, comment = comment, date = Date())
    notesBox.put(note)
    Log.d(App.TAG, "Inserted new note, ID: " + note.id)
    ...
}

Future<void> addNote(String text) => _noteBox.putAsync(Note(text));

def add_task(self, text: str):
    task = Task(text=text, date_created=now_ms())
    self._task_box.put(task)

Note that the ID property (0 when creating the Note object), is assigned by ObjectBox during a put.

Removing/deleting notes

When the user taps a note, it is deleted. The Box provides remove() to achieve this:

OnItemClickListener noteClickListener = new OnItemClickListener() {
    @Override
    public void onItemClick(AdapterView<?> parent, View view, int position, long id) {
        Note note = notesAdapter.getItem(position);
        notesBox.remove(note);
        Log.d(App.TAG, "Deleted note, ID: " + note.getId());
        ...
    }
};

private val noteClickListener = OnItemClickListener { _, _, position, _ ->
    notesAdapter.getItem(position)?.also {
        notesBox.remove(it)
        Log.d(App.TAG, "Deleted note, ID: " + it.id)
    }
    ...
}

Future<void> removeNote(int id) => _noteBox.removeAsync(id);

def remove_task(self, task_id: int) -> bool:
    is_removed = self._task_box.remove(task_id)
    return is_removed

Querying notes

To query and display notes in a list a Query instance is built once:

@Override
public void onCreate(Bundle savedInstanceState) {
    ...
    // Query all notes, sorted a-z by their text.
    notesQuery = notesBox.query().order(Note_.text).build();
    ...
}

public override fun onCreate(savedInstanceState: Bundle?) {
    ...
    // Query all notes, sorted a-z by their text.
    notesQuery = notesBox.query {
        order(Note_.text)
    }
    ...
}

Stream<List<Note>> getNotes() {
  // Query for all notes, sorted by their date.
  // https://docs.objectbox.io/queries
  final builder = _noteBox.query().order(Note_.date, flags: Order.descending);
  ...

def __init__(self):
    # ...
    self._query = self._task_box.query().build()

And then executed each time any notes change:

private void updateNotes() {
    List<Note> notes = notesQuery.find();
    notesAdapter.setNotes(notes);
}

private fun updateNotes() {
    val notes = notesQuery.find()
    notesAdapter.setNotes(notes)
}

  ...
  // Build and watch the query,
  // set triggerImmediately to emit the query immediately on listen.
  return builder
      .watch(triggerImmediately: true)
      // Map it to a list of notes to be used by a StreamBuilder.
      .map((query) => query.find());
}

def find_tasks(self):
    return self._query.find()

In addition to a result sort order, you can add various conditions to filter the results, like equality or less/greater than, when building a query.

Updating notes and more

What is not shown in the example, is how to update an existing (== the ID is not 0) note. Do so by just modifying any of its properties and then put it again with the changed object:

note.setText("This note has changed.");
notesBox.put(note);

note.text = "This note has changed."
notesBox.put(note)

note.text = "This note has changed.";
_noteBox.putAsync(note);

task.text = "This task has changed."
self._task_box.put(task)

There are additional methods to put, find, query, count or remove entities. Check out the methods of the Box class in API docs (for Java/Kotlin or Dart) to learn more.

Setting up the database

Now that you saw ObjectBox in action, how did we get that database (or store) instance? Typically you should set up a BoxStore or Store once for the whole app. This example uses a helper class as recommended in the Getting Started guide.

Remember: ObjectBox is a NoSQL database on its own and thus NOT based on SQL or SQLite. That’s why you do not need to set up “CREATE TABLE” statements during initialization.

More In-Depth Tutorials

🌿 Learn how to build a Food Sharing app with ObjectBox in Flutter/Dart

Add ObjectBox to your project

Define 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:

@Entity
public class User {
    @Id 
    public long id;
    public String name;
}

@Entity
data class User(
        @Id 
        var id: Long = 0,
        var name: String? = null
)

@Entity()
class User {
  @Id()
  int id = 0;
  
  String? name;
}

from objectbox import Entity, Id, String

@Entity()
class User:
  id = Id
  name = String
  

Important:

• 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, see the @Id annotation docs for some tips. Also, the ID property must have non-private visibility (or non-private getter and setter methods).

• 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.

Support for many property types is already built-in, but almost any type can be stored with a converter.

For more details about entities, like how to create an index or a relation, check the Entity Annotations page.

You can also learn more about the ObjectBox model.

Generate ObjectBox code

Next, we generate some binding code based on the model defined in the previous step.

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 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, not closing it explicitly.

public class ObjectBox {
    private static BoxStore store;

    public static void init(Context context) {
        store = MyObjectBox.builder()
                .androidContext(context)
                .build();
    }

    public static BoxStore get() { return store; }
}

public class ExampleApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        ObjectBox.init(this);
    }
}

object ObjectBox {
    lateinit var store: BoxStore
        private set

    fun init(context: Context) {
        store = MyObjectBox.builder()
                .androidContext(context)
                .build()
    }
}

class ExampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        ObjectBox.init(this)
    }
}

public class ObjectBox {
    private static BoxStore store;

    public static void init(Context context) {
        store = MyObjectBox.builder()
                .name("objectbox-notes-db")
                .build();
    }

    public static BoxStore get() { return store; }
}

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);
  }
}

/// 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());
}

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
}

from objectbox import Store
  
store = Store()

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:

BoxStore inMemoryStore = MyObjectBox.builder()
        .androidContext(context)
        .inMemory("test-db")
        .build();

 final inMemoryStore =
     Store(getObjectBoxModel(), directory: "memory:test-db");

store = Store(directory="memory:testdata")

For more store configuration options: for Java see the BoxStoreBuilder and for Dart the Store documentation. (Python APIs will be published soon)

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:

Box<User> userBox = store.boxFor(User.class);
Box<Order> orderBox = store.boxFor(Order.class);

val userBox = store.boxFor(User::class)
val orderBox = store.boxFor(Order::class)

final userBox = store.box<User>();
final orderBox = store.box<Order>();

user_box = store.box(User)
order_box = 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.

User user = new User("Tina");
userBox.put(user);

List<User> users = getNewUsers();
userBox.put(users);

val user = User(name = "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);

user = User(name="Tina")
user_box.put(user)

users = get_new_users()
user_box.put(*users)

get and getAll: Given an object’s ID, get reads it from its box. To get all objects in the box use getAll .

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();

user = user_box.get(user_id)

users = user_box.get_all()

query: Starts building a query to return objects from the box that match certain conditions. See queries for details.

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();

query = user_box \
    .query(User.name.equals('Tom')) \
    .build()
results = query.find()

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.

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();

is_removed = user_box.remove(user_id)

user_box.remove_all()

count: Returns the number of objects stored in this box.

long userCount = userBox.count();

val userCount = userBox.count()

final userCount = userBox.count();

user_box.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 built-in support to run (typically multiple or larger) database operations asynchronously.

store.callInTxAsync(() -> {
    Box<User> box = store.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);
    }
});

try {
    val name = store.awaitCallInTx {
        val box = store.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")
}

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

// 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);

for (int i = 0; i < 100; i++) {
  userBox.putQueued(User(name: 'User $i'));
}

// Optional: wait until submitted items are processed.
store.awaitQueueSubmitted();
expect(userBox.count(), equals(100));

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:

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;

user = User()
box.put(user)
id: int = 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.

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.

• Learn how to write unit tests.

• To enable debug mode and for advanced use cases, see the Advanced Setup page.

ObjectBox Admin Web App

The ObjectBox Admin web app allows you to

• view data objects and schema of your database inside a regular web browser,

• display additional information,

• and download objects in JSON format.

The web app runs directly on your device or on your development machine. Behind the scenes, this is done by embedding a lightweight HTTP server into ObjectBox. It runs completely local (no Cloud whatsoever) and you can simply open the Admin in your Browser.

Run via Docker

Once Admin has started, open the local URL printed by the script (typically http://127.0.0.1:8081) in your browser. You should see the Data page for an entity type.

Admin for Android

We strongly recommend using Admin only for debug builds as it ships with additional resources and configuration not intended for production code.

Finally, after creating the store, to start Admin:

Browse data on your test device

When Admin is started it will print the URL where to access the web app to the logs, e.g. something like:

The URL can be opened on the device or emulator. To open the web app on your dev machine, see the instructions below.

For ObjectBox for Java, the app also displays a notification to access Admin. (Don't see the notification on Android 13 or newer? Try to manually turn on notifications for the app!) Tapping it will launch a service to keep the app alive and opens the Admin web app in the web browser on the device.

Stop the keep-alive service from the notification.

Browse data on your dev machine

To open the web app on your development machine find the Admin URL log message as noted above.

Then open the web app URL in a web browser on your dev machine.

Download Objects

To download all objects of the currently viewed box tap the download all button at the very bottom. The exported data is in JSON format.