objectbox/objectbox-java

Getting Started • Documentation • Example Apps • Issues

ObjectBox - Fast and Efficient Java Database (Android, JVM) with Vector Search

ObjectBox Java is a lightweight yet powerful on-device database & vector database designed specifically for Java and Kotlin applications. Store and manage data effortlessly in your Android or JVM Linux, macOS or Windows app with ObjectBox. Easily manage vector data alongside your objects and perform superfast on-device vector search to empower your apps with RAG AI, generative AI, and similarity search. Enjoy exceptional speed, battery-friendly resource usage, and environmentally-friendly development. 💚

ObjectBox provides a store with boxes to put objects into:

JVM + Java example

// Annotate a class to create a Box
@Entity
public class Person {
  private @Id long id;
  private String firstName;
  private String lastName;

  // Constructor, getters and setters left out for simplicity
}
 
BoxStore store = MyObjectBox.builder()
        .name("person-db")
        .build();
 
Box<Person> box = store.boxFor(Person.class);
 
Person person = new Person("Joe", "Green");
long id = box.put(person);    // Create
person = box.get(id);         // Read
person.setLastName("Black");
box.put(person);              // Update
box.remove(person);           // Delete

Android + Kotlin example

// Annotate a class to create a Box
@Entity
data class Person(
    @Id var id: Long = 0,
    var firstName: String? = null,
    var lastName: String? = null
)
 
val store = MyObjectBox.builder()
                .androidContext(context)
                .build()
 
val box = store.boxFor(Person::class)
 
var person = Person(firstName = "Joe", lastName = "Green")
val id = box.put()   // Create
person = box.get(id) // Read
person.lastName = "Black"
box.put(person)     // Update
box.remove(person)  // Delete

Table of Contents

• Key Features
• Getting Started
  • Gradle setup
  • Maven setup
• Why use ObjectBox?
• Community and Support
• Changelog
• Other languages/bindings
• License

Key Features

🧠 First on-device vector database: easily manage vector data and perform fast vector search 🏁 High performance: exceptional speed, outperforming alternatives like SQLite and Realm in all CRUD operations.
💚 Efficient Resource Usage: minimal CPU, power and memory consumption for maximum flexibility and sustainability.
🔗 Built-in Object Relations: built-in support for object relations, allowing you to easily establish and manage relationships between objects.
👌 Ease of use: concise API that eliminates the need for complex SQL queries, saving you time and effort during development.

Getting Started

[!NOTE] Prefer to look at example code? Check out our examples repository.

You can add the ObjectBox Java SDK using a:

• Gradle setup
• Maven setup

ObjectBox tools and dependencies are available on the Maven Central repository.

The database libraries available for the ObjectBox Java SDK support:

• JVM 8 or newer
  • Linux (x64, arm64, armv7)
  • macOS (x64, arm64)
  • Windows (x64)
• Android 5.0 (API level 21) or newer

The ObjectBox Java SDK supports:

• Java 8 or newer
• Kotlin 1.7 or newer

The ObjectBox Gradle plugin supports:

• Gradle 7.0 or newer
• Android Gradle Plugin 8.1 or newer
• JDK 11 or newer

Gradle setup

For Gradle projects, add the required plugins to your root Gradle script.

When using a TOML version catalog and plugins syntax (for alternatives see below):

# gradle/libs.versions.toml

[versions]
# For an Android project
agp = "AGP_VERSION"
# If using Kotlin
kotlin = "KOTLIN_VERSION"

# Define a variable for the version of the ObjectBox plugin
objectbox = "6.0.0-beta"

[plugins]
# For an Android project, using Android Gradle Plugin 9.0 or newer
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-kapt = { id = "com.android.legacy-kapt", version.ref = "agp" }

# For an Android project, using Android Gradle Plugin 8.13 or older
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "kotlin" }

# For a JVM project, if using Kotlin 
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "kotlin" }

# Add an alias for the ObjectBox plugin
objectbox = { id = "io.objectbox", version.ref = "objectbox" }

// build.gradle.kts

plugins {
    // For an Android project, using Android Gradle Plugin 9.0 or newer
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.kapt) apply false  
  
    // For an Android project, using Android Gradle Plugin 8.13 or older
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.kotlin.kapt) apply false

    // For a JVM project, if using Kotlin
    alias(libs.plugins.kotlin.jvm) apply false
    alias(libs.plugins.kotlin.kapt) apply false
  
    // Add the ObjectBox plugin
    alias(libs.plugins.objectbox) apply false  
}

// settings.gradle.kts

pluginManagement {
    repositories {
        // Add Maven Central to the plugin repositories
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        // Add Maven Central to the dependency repositories
        mavenCentral()
    }
}

Then, in the Gradle script of your subproject apply the necessary plugins:

// app/build.gradle.kts

plugins {
    // For an Android project, using Android Gradle Plugin 9.0 or newer
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.kapt)
    
    // For an Android project, using Android Gradle Plugin 8.13 or older
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.kapt)
    
    // For a JVM project
    id("application") // or id("java-library")
    // Optional, if using Kotlin
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.kotlin.kapt)

    // Finally, apply the ObjectBox plugin
    alias(libs.plugins.objectbox)
}

Finally, sync the Gradle project with your IDE (for ex. using "Sync Project with Gradle Files" in Android Studio).

Your project can now use ObjectBox, continue by defining entity classes.

Alternatives

// build.gradle.kts

plugins {
    // Add the ObjectBox plugin
    id("io.objectbox") version "6.0.0-beta" apply false
}

// settings.gradle.kts

pluginManagement {
    repositories {
        // Add Maven Central to the plugin repositories
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        // Add Maven Central to the dependency repositories
        mavenCentral()
    }
}

// build.gradle.kts

buildscript {
    // Define a variable for the ObjectBox plugin version
    val objectboxVersion by extra("6.0.0-beta")
  
    repositories {
        // Add Maven Central to the plugin repositories     
        mavenCentral()    
    }
  
    dependencies {
        // Add the ObjectBox plugin
        classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
    }
}

allprojects {
    repositories {
        // Add Maven Central to the dependency repositories
        mavenCentral()
    }
}

// build.gradle

buildscript {
    // Define a variable for the ObjectBox plugin version
    ext.objectboxVersion = "6.0.0-beta"
  
    repositories {        
        // Add Maven Central to the plugin repositories
        mavenCentral()    
    }
  
    dependencies {
        // Add the ObjectBox plugin
        classpath("io.objectbox:objectbox-gradle-plugin:$objectboxVersion")
    }
}

allprojects {
    repositories {
        // Add Maven Central to the dependency repositories
        mavenCentral()
    }
}

Then, in the Gradle script of your subproject apply the necessary plugins using their IDs:

// app/build.gradle.kts

plugins {
    // For an Android project, using Android Gradle Plugin 9.0 or newer
    id("com.android.application") // or id("com.android.library")
    id("com.android.legacy-kapt") 
  
    // For an Android project, using Android Gradle Plugin 8.13 or older
    id("com.android.application") // or id("com.android.library")
    id("org.jetbrains.kotlin.android") // or kotlin("android")
    id("org.jetbrains.kotlin.kapt") // or kotlin("kapt")  
  
    // For a JVM project
    id("application") // or id("java-library")
    // Optional, if using Kotlin
    id("org.jetbrains.kotlin.jvm") // or kotlin("jvm")
    id("org.jetbrains.kotlin.kapt") // or kotlin("kapt")  

    // Finally, apply the ObjectBox plugin
    id("io.objectbox")
}

Maven setup

This is currently only supported for JVM projects.

To set up a Maven project, see the README of the Java Maven example project.

Frequently Asked Questions and Troubleshooting

If you encounter any problems, check out the FAQ and Troubleshooting pages.

Why use ObjectBox for Java data management?

ObjectBox is a NoSQL Java database designed for local data storage on resource-restricted devices, prioritizing offline-first functionality. It is a smart and sustainable choice for local data persistence in Java and Kotlin applications. It offers efficiency, ease of use, and flexibility.

Fast but resourceful

Optimized for speed and minimal resource consumption, ObjectBox is an ideal solution for mobile devices. It has excellent performance, while also minimizing CPU, RAM, and power usage. ObjectBox outperforms SQLite and Realm across all CRUD (Create, Read, Update, Delete) operations. Check out our Performance Benchmarking App repository.

Simple but powerful

With its concise language-native API, ObjectBox simplifies development by requiring less code compared to SQLite. It operates on plain objects (POJOs) with built-in relations, eliminating the need to manage rows and columns. This approach is efficient for handling large data volumes and allows for easy model modifications.

Functionality

💐 Queries: filter data as needed, even across relations
💻 Multiplatform: supports Android and JVM on Linux (also on ARM), Windows and macOS
🌱 Scalable: handling millions of objects resource-efficiently with ease
🦮 Statically typed: compile time checks & optimizations
📃 Automatic schema migrations: no update scripts needed

And much more than just data persistence
🔄 ObjectBox Sync: keeps data in sync between devices and servers
🕒 ObjectBox TS: time series extension for time based data

Community and Support

❤ Tell us what you think! Share your thoughts through our Anonymous Feedback Form.

At ObjectBox, we are dedicated to bringing joy and delight to app developers by providing intuitive and fun-to-code-with APIs. We genuinely want to hear from you: What do you love about ObjectBox? What could be improved? Where do you face challenges in everyday app development?

We eagerly await your comments and requests, so please feel free to reach out to us:

• Add GitHub issues
• Upvote important issues 👍
• Drop us a line via contact[at]objectbox.io
• ⭐ us on GitHub if you like what you see!

Thank you! Stay updated with our blog.

Changelog

For notable and important changes in new releases, read the changelog.

Other languages/bindings

ObjectBox supports multiple platforms and languages. Besides JVM based languages like Java and Kotlin, ObjectBox also offers:

• C and C++ SDK: native speed with zero copy access to FlatBuffer objects
• Dart and Flutter SDK: cross-platform for mobile and desktop apps
• Go SDK: great for data-driven tools and embedded server applications
• Swift SDK: build fast mobile apps for iOS (and macOS)

License

Copyright 2017-2025 ObjectBox Ltd.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Note that this license applies to the code in this repository only. See our website on details about all licenses for ObjectBox components.