ObjectBox Docs (Java, Kotlin, Dart)
ObjectBox is an object database for Mobile and IoT developers and a full SQLite alternative. These are the official Java/Kotlin, Dart/Flutter docs for ObjectBox and Data Sync.
We are on a mission to bring joy and delight to app developers. We do want to give you the easiest and fastest solution to store and retrieve data.
Your feedback is highly appreciated. 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 shoutout :)

ObjectBox for Java Changelog

V3.0.0 - 2021/10/19

2021/10/19: Released version 3.0.1, which contains a fix for Android Java projects.
    A new Query API is available that works similar to the ObjectBox for Dart/Flutter Query API and makes it easier to create nested conditions. #201
    1
    // equal AND (less OR oneOf)
    2
    val query = box.query(
    3
    User_.firstName equal "Joe"
    4
    and (User_.age less 12
    5
    or (User_.stamp oneOf longArrayOf(1012))))
    6
    .order(User_.age)
    7
    .build()
    Copied!
    For the existing Query API, String property conditions now require to explicitly specify case. See the documentation of StringOrder for which one to choose (typically StringOrder.CASE_INSENSITIVE).
    1
    // Replace String conditions like
    2
    query().equal(User_.firstName, "Joe")
    3
    // With the one accepting a StringOrder
    4
    query().equal(User_.firstName, "Joe", StringOrder.CASE_INSENSITIVE)
    Copied!
    Subscriptions now publish results in serial instead of in parallel (using a single thread vs. multiple threads per publisher). Publishing in parallel could previously lead to outdated results getting delivered after the latest results. As a side-effect transformers now run in serial instead of in parallel as well (on the same single thread per publisher). #793
    Support annotating a single property with @Unique(onConflict = ConflictStrategy.REPLACE) to replace an existing Object if a conflict occurs when doing a put. #509
    1
    @Entity
    2
    data class Example(
    3
    @Id
    4
    var id: Long = 0,
    5
    @Unique(onConflict = ConflictStrategy.REPLACE)
    6
    var uniqueKey: String? = null
    7
    )
    Copied!
    Support @Unsigned to indicate that values of an integer property (e.g. Integer and Long in Java) should be treated as unsigned when doing queries or creating indexes.
    Store time in nanoseconds using the new @Type annotation:
    1
    @Type(DatabaseType.DateNano)
    2
    var timeInNanos: Long;
    Copied!
    Package FlatBuffers version into library to avoid conflicts with apps or other libraries using FlatBuffers. #894
    Kotlin: add Flow extension functions for BoxStore and Query. #900
    Data browser: display query results if a property has a NaN value. #984
    Android 12: support using Data Browser if targeting Android 12 (SDK 31). #1007

New supported property types

    String arrays (Java String[] and Kotlin Array<String>). Using the new containsElement("item") condition, it is also possible to query for entities where "item" is equal to one of the array items.
    1
    @Entity
    2
    data class Example(
    3
    @Id
    4
    var id: Long = 0,
    5
    var stringArray: Array<String>? = null,
    6
    var stringMap: MutableMap<String, String>? = null
    7
    )
    8
    9
    // matches [“first”, “second”, “third”]
    10
    box.query(Example_.stringArray.containsElement(“second”)).build()
    Copied!
    String maps (Java Map<String, String> or Kotlin MutableMap<String, String>). Stored internally as a byte array using FlexBuffers.
    Flexible maps:
      map keys must all have the same type,
      map keys or values must not be null,
      map values must be one of the supported database type, or a list of them (e.g. String, Boolean, Integer, Double, byte array...).

Sync

    The generated JSON model file no longer contains Java-specific flags that would lead to errors if used with Sync server.
    Additional checks when calling client or server methods.

V2.9.2-RC4 - 2021/08/19

Note: this is a preview release. Future releases may add, change or remove APIs.
    A new experimental Query API provides support for nested AND and OR conditions. #201
    Subscriptions now publish results in serial instead of in parallel (using a single thread vs. multiple threads per publisher). Publishing in parallel could previously lead to outdated results getting delivered after the latest results. As a side-effect transformers now run in serial instead of in parallel as well (on the same single thread per publisher). #793
    Add documentation that string property conditions ignore case by default. Point to using case-sensitive conditions for high-performance look-ups, e.g. when using string UIDs.
    Support annotating a single property with @Unique(onConflict = ConflictStrategy.REPLACE) to replace an existing Object if a conflict occurs when doing a put. #509
    Support @Unsigned to indicate that values of an integer property (e.g. Integer and Long in Java) should be treated as unsigned when doing queries or creating indexes. See the Javadoc of the annotation for more details.
    Store time in nanoseconds by annotating a Long property with @Type(DatabaseType.DateNano).
    Package FlatBuffers version into library to avoid conflicts if your code uses FlatBuffers as well. #894
    Kotlin: add Flow extension functions for BoxStore and Query. #900
    Data browser: display query results if a property has a NaN value. #984
New supported property types
When adding new properties, a converter is no longer necessary to store these types:
    String arrays (Java String[] and Kotlin Array<String>). Using the new containsElement("item") condition, it is also possible to query for entities where "item" is equal to one of the array items.
    String maps (Java Map<String, String> or Kotlin MutableMap<String, String>). Stored internally as a byte array using FlexBuffers.
Sync
    The generated JSON model file no longer contains Java-specific flags that would lead to errors if used with Sync server.
    Additional checks when calling client or server methods.

V2.9.1 - 2021/03/15

This is the first release available on the Central repository (Sonatype OSSRH). Make sure to adjust your build.gradle files accordingly:
1
repositories {
2
mavenCentral()
3
}
Copied!
Changes:
    Javadoc for find(offset, limit) of Query is more concrete on how offset and limit work.
    Javadoc for between conditions explicitly mentions it is inclusive of the two given values.
    Sync: Instead of the same name and a Maven classifier, Sync artifacts now use a different name. E.g. objectbox-android:2.9.0:sync is replaced with objectbox-sync-android:2.9.1.

V2.9.0 - 2021/02/16

    Query: Add lessOrEqual and greaterOrEqual conditions for long, String, double and byte[] properties.
    Support Java applications on ARMv7 and AArch64 devices. #657
    To use, add implementation "io.objectbox:objectbox-linux-armv7:$objectboxVersion or implementation "io.objectbox:objectbox-linux-arm64:$objectboxVersion to your dependencies. Otherwise the setup is identical with Java Desktop Apps.
    Resolve rare ClassNotFoundException: kotlin.text.Charsets when running processor. #946
    Ensure Query setParameters works if running the x86 library on x64 devices (which could happen if ABI filters were set up incorrectly). #927

V2.8.1 - 2020/11/10

    Minor improvements to Sync tooling.
See the 2.8.0 release notes below for the latest changes.

V2.8.0 - 2020/11/05

    Added Sync API.
    Fixed "illegal reflective access" warning in the plugin.
    The data browser notification is now silent by default, for quieter testing. #903
    Updated and improved API documentation in various places (e.g. on how Query.findLazy() and Query.findLazyCached() work with LazyList #906).
    Print full name and link to element for @Index and @Id errors. #902
    Explicitly allow to remove a DbExceptionListener by accepting null values for BoxStore.setDbExceptionListener(listener).

V2.7.1 - 2020/08/19

    Fix exception handling during BoxStoreBuilder.build() to allow retries. For example, after a FileCorruptException you could try to open the database again using the recently added usePreviousCommit() option.
    Add PagesCorruptException as a special case of FileCorruptException.
    DbExceptionListener is called more robustly.

V2.7.0 - 2020/07/30

    Several database store improvements forBoxStore and BoxStoreBuilder
      New configuration options to open the database, e.g. a new read-only mode and using the previous data snapshot (second last commit) to potentially recover data.
      Database validation. We got a GitHub report indicating that some specific devices ship with a broken file system. While this is not a general concern (file systems should not be broken), we decided to detect some typical problems and provide some options to deal with these.
      Get the size on disk
    Add an efficient check if an object exist in a Box via contains(id).
    Android improvements
      Resolve Android Studio Build Analyzer warning about a prepare tasks not specifying outputs.
      Data Browser drawables are no longer packaged in the regular Android library. GitHub #857
    Fixes for one-to-many relations, e.g. allow removing both entity classes of a one-to-many relation. GitHub #859

V2.6.0 - 2020/06/09

    @DefaultValue("") annotation for properties to return an empty string instead of null. This is useful if a not-null property is added to an entity, but there are existing entities in the database that will return null for the new property. GH#157
    RxJava 3 support library objectbox-rxjava3. Also includes Kotlin extension functions to more easily obtain Rx types, e.g. use query.observable() to get an Observable. GH#83
    The annotation processor is incremental by default. GH#620
    Fix error handling if ObjectBox can't create a Java entity (the proper exception is now thrown).
    Support setting an alias after combining conditions using and() or or(). GH#83
    Turn on incremental annotation processing by default. GH#620
    Add documentation that string property conditions ignore case by default. Point to using case-sensitive conditions for high-performance look-ups, e.g. when using string UIDs.
    Repository Artifacts are signed once again.
Changes since 2.6.0-RC (released on 2020/04/28):
    Performance improvements with query links (aka "joins"). Note: the order of results has changed unless you explicitly specified properties to order by. Remember: you should not depend on any internal order. If you did, this is a good time to fix it.
    objectbox-java no longer exposes the greenrobot-essentials and FlatBuffers dependencies to consuming projects.
    Minor code improvements.

V3.0.0-alpha2 - 2020/03/24

Note: this is a preview release. Future releases may add, change or remove APIs.
    Add Kotlin infix extension functions for creating conditions using the new Query API. See the documentation for examples.
    The old Query API now also supports setting an alias after combining conditions using and() or or(). GH#834
    Add documentation that string property conditions ignore case by default. Point to using case-sensitive conditions for high-performance look-ups, e.g. when using string UIDs.
    Java's String[] and Kotlin's Array<String> are now a supported database type. A converter is no longer necessary to store these types. Using the arrayProperty.equal("item") condition, it is possible to query for entities where "item" is equal to one of the array items.
    Support @Unsigned to indicate that values of an integer property (e.g. Integer and Long in Java) should be treated as unsigned when doing queries or creating indexes. See the Javadoc of the annotation for more details.
    Add new library to support RxJava 3, objectbox-rxjava3. In addition objectbox-kotlin adds extension functions to more easily obtain Rx types, e.g. use query.observable() to get an Observable. GH#839
To use this release change the version of objectbox-gradle-plugin to 3.0.0-alpha2. The plugin now properly adds the preview version of objectbox-java to your dependencies.
1
buildscript {
2
dependencies {
3
classpath "io.objectbox:objectbox-gradle-plugin:3.0.0-alpha2"
4
}
5
}
6
7
dependencies {
8
// Artifacts with native code remain at 2.5.1.
9
implementation "io.objectbox:objectbox-android:2.5.1"
10
}
Copied!
The objectbox-android, objectbox-linux, objectbox-macos and objectbox-windows artifacts shipping native code remain at version 2.5.1 as there have been no changes. If you explicitly include them, make sure to specify their version as 2.5.1.

V3.0.0-alpha1 - 2020/03/09

Note: this is a preview release. Future releases may add, change or remove APIs.
    A new Query API provides support for nested AND and OR conditions. See the documentation for examples and notable changes. GH#201
    Subscriptions now publish results in serial instead of in parallel (using a single thread vs. multiple threads per publisher). Publishing in parallel could previously lead to outdated results getting delivered after the latest results. As a side-effect transformers now run in serial instead of in parallel as well (on the same single thread per publisher). GH#793
    Turn on incremental annotation processing by default. GH#620
To use this release change the version of objectbox-gradle-plugin to 3.0.0-alpha1 and add a dependency on objectbox-java version 3.0.0-alpha1.
1
buildscript {
2
dependencies {
3
classpath "io.objectbox:objectbox-gradle-plugin:3.0.0-alpha1"
4
}
5
}
6
7
dependencies {
8
implementation "io.objectbox:objectbox-java:3.0.0-alpha1"
9
// Artifacts with native code remain at 2.5.1.
10
implementation "io.objectbox:objectbox-android:2.5.1"
11
}
Copied!
The objectbox-android, objectbox-linux, objectbox-macos and objectbox-windows artifacts shipping native code remain at version 2.5.1 as there have been no changes. However, if your project explicitly depends on them they will pull in version 2.5.1 of objectbox-java. Make sure to add an explicit dependency on of objectbox-java version 3.0.0-alpha1 as mentioned above.

V2.5.1 - 2020/02/10

    Support Android Gradle Plugin 3.6.0. GH#817
    Support for incremental annotation processing. GH#620 It is off by default. To turn it on set objectbox.incremental to true in build.gradle :
1
android {
2
defaultConfig {
3
javaCompileOptions {
4
annotationProcessorOptions {
5
arguments = [ "objectbox.incremental" : "true" ]
6
}
7
}
8
}
9
}
Copied!

V2.5.0 - 2019/12/12

Important bug fix - please update asap if you are using N:M relations!

    Fixed corner case for N:M ToMany (not the backlinks for ToOne) returning wrong results

Improvements and New Features

    Property queries compute sums and averages more precisely (improved algorithms and wider internal types)
    Query adds "describe" methods to obtain useful debugging information
    New method removeAllObjects() in BoxStore to clear the database of all data

V2.4.1 - 2019/10/29

    More helpful error messages if annotations can not be combined.
    Improved documentation on various annotations.

V2.4.0 - 2019/10/15

Upgrade Notes

    Android: the AAR libraries ship Java 8 bytecode. Your app will not build unless you upgrade com.android.tools.build:gradle to 3.2.1 or later.
    Android: the ObjectBox LiveData and Paging integration migrated from Android Support Libraries to Jetpack (AndroidX) Libraries. If you are using them the library will not work unless you make the following changes in your app:
      Upgrade com.android.tools.build:gradle to 3.2.1 or later.
      Upgrade compileSdkVersion to 28 or later.
      Update your app to use Jetpack (AndroidX); follow the instructions in Migrating to AndroidX.
    Note: this version requires backwards-incompatible changes to the generated MyObjectBox file. Make sure to rebuild your project before running your app so the MyObjectBox file is re-generated.

Improvements & Fixes

V2.4.0 - 2019/10/15
    Class transformation works correctly if absolute path contains special characters. GH#135
V2.4.0-RC - Release Candidate 2019/10/03
    Box: add getRelationEntities, getRelationBacklinkEntities,getRelationIds and getRelationBacklinkIds to directly access relations without going through ToMany.
    Box: add putBatched to put entities using a separate transaction for each batch.
    Box.removeByKeys() is now deprecated; use removeByIds() instead.
    Query: fixed performance regressions introduced in version 2.3 on 32 bit devices in combination with ordered results
    Fixed removing a relation and the related entity class. GH#490
    Resolved issue to enable query conditions on the target ID property of a ToOne relation. GH#537
    Box.getAll always returns a mutable list. GH#685
    Do not overwrite existing objectbox-java or objectbox-kotlin dependency. GH#693
    Resolved a corner case build time crash when parsing package elements. GH#698
    When trying to find an appropriate get-method for a property, also check if the return type matches the property type. GH#720
    Explicitly display an error if two entities with the same name are detected. GH#744
    The code in MyObjectBox is split up by entity to make it less likely to run into the Java method size limit when using many @Entity classes. GH#750
    Query: improved performance for ordered results with a limit. GH#769
    Query: throw if a filter is used incorrectly with count or remove. GH#771
    Documentation and internal improvements.

V2.3.4 - 2019/03/19

    Avoid UnsatisfiedLinkError on Android devices that are not identifying as Android correctly
    Fix displaying large objects in Object Browser 32 bit
    Kotlin properties starting with "is" of any type are detected
    Add objectbox-kotlin to dependencies if kotlin-android plugin is applied (previously only for kotlin plugin)
    @BaseEntity classes can be generic

V2.3.3 - 2019/02/14

    Fixed a bug introduced by V2.3.2 affecting older Android versions 4.3 and below

V2.3.2 - 2019/02/04

    Potential work around for UnsatisfiedLinkError probably caused by installation errors mostly in alternative app markets
    Support for Android Gradle Plugin 3.3.0: resolves deprecated API usage warnings.

V2.3.1 - 2019/01/08

    Fixed a corner case for Box.getAll() after removeAll() to return a stale object if no objects are stored

V2.3 - 2018/12/30

Improvements & Fixes

    Query improvements: findIds and LazyList also consider the order; offset and limit for findIds
    Improved 32 bit support: Windows 32 version officially deployed, fixed a corner case crash
    Property queries for a boolean property now allow sum()
    Added Box.isEmpty()
    Supporting older Linux distributions (now starting at e.g. Ubuntu 16.04 instead of 18.04)
    Fix for a corner case with Box.count() when using a maximum
    Minor improvements to the ObjectBox code generator
    Android: set extractNativeLibs to false to avoid issues with extracting the native library

V2.2 - 2018/09/27

Improvements & Fixes
    Fix: the unique check for string properties had false positives resulting in UniqueViolationException. This occurs only in combination with IndexType.HASH (the default) when hashes actually collide. We advise to update immediately to the newest version if you are using hashed indexes.
    The release of new ObjectBox C API made us change name of the JNI library
    for better distinction. This should not affect you unless you depended on that (internal) name.
    Improved compatibility with class transformers like Jacoco
    Fixed query links for M:N backlinks
    Improved error messages for the build tools
    The Object Browser AAR now includes the required Android permissions

V2.1 - 2018/08/16

Minor Improvements & Fixes

    Entity counts are now cached for better performance
    Deprecated aggregate function were removed (deprecation in 1.4 with introduction of PropertyQuery)
    Object browser hot fix: the hashed indexes introduced in 2.0 broke the object browser
    Object browser fixes: filters with long ints, improved performance in the schema view
    NPE fix in ToOne
    Added a specific NonUniqueResultException if a query did not return an expected unique result

V2.0 - 2018/07/25

New Features/Improvements

ObjectBox 2.0 introduces index types for String. Before, every index used the property value for all look-ups. Now, ObjectBox can also use a hash to build an index. Because String properties are typically taking more space than scalar values, ObjectBox switched the default index type to hash for strings.
When migrating data from pre-2.0 ObjectBox versions, for String properties with a plain @Index annotation this will update the indexes automatically: the old value-based indexes will be deleted and the new hash-bashed indexes will be built.
A side effect of this is that the database file might grow in the process. If you want to prevent this, you can instruct ObjectBox to keep using a value-based index for a String property by specifying the index type using @Index(type = IndexType.VALUE).
Other changes:
    Links and relation completeness and other features already announced in the 2.0 beta
    Unique constraint for properties via @Unique annotation
    Support for char type (16 bit)
    RX lib deployed in JCenter
    Rework of Query APIs: type safe properties (property now knows its owning entity)
    Allow query conditions of links using properties (without parameter alias)
    Query performance improvements when using order
    Property based count: query for non-null or unique occurrences of entity properties (non-null and unique)
    Additional query conditions for strings: "greater than", "less than", "in"
    Added query conditions for byte arrays
    Set query parameters for "in" condition (int[] and long[])

V2.0 beta – 2018/06/26

New Features/Improvements

    Query across relation bounds using links (aka "join"): queries just got much more powerful. For example, query for orders that have a customer with an address on "Sesame Street". Or all persons, who have a grand parent called "Alice".
    Backlinks for to-many relations: now ObjectBox is "relation complete" with a bi-directional many-to-many relation.
    Query performance improvements: getting min/max values of indexed properties in constant time
    Android: added Paging library support (architecture components)
    Kotlin extensions: more Kotlin fun with ObjectBox KTX
    Query parameters aliases: helps setting query parameters in complex scenarios (e.g. for properties of linked entities)
    Improved query parameter verification
    Many internal improvements to keep us going fast in the future

V1.5 and earlier

Check the release history for older releases

Last modified 8d ago