objectbox-java

• Examples: added Vector Search example that demonstrates how to perform on-device approximate nearest neighbor (ANN) search.
• Revert deprecation of Box.query(), it is still useful for queries without any condition.
• Add note on old query API methods of QueryBuilder that they are not recommended for new projects. Use the new query APIs instead.
• Update and expand documentation on ToOne and ToMany.

ObjectBox now supports Vector Search to enable efficient similarity searches.

This is particularly useful for AI/ML/RAG applications, e.g. image, audio, or text similarity. Other
use cases include semantic search or recommendation engines.

Create a Vector (HNSW) index for a floating point vector property. For example, a City with a
location vector:

@Entity
public class City {

    @HnswIndex(dimensions = 2)
    float[] location;
    
}

Perform a nearest neighbor search using the new nearestNeighborsF32(queryVector, maxResultCount)
query condition and the new "find with scores" query methods (the score is the distance to the
query vector). For example, find the 2 closest cities:

final float[] madrid = {40.416775F, -3.703790F};
final Query<City> query = box
        .query(City_.location.nearestNeighbors(madrid, 2))
        .build();
final City closest = query.findWithScores().get(0).get();

For an introduction to Vector Search, more details and other supported languages see the
Vector Search documentation.

• BoxStore: deprecated Store.sizeOnDisk(). Instead use one of the new APIs to determine the size of a database:
  • Store.getDbSize() which for a file-based database returns the file size and for an in-memory database returns the approximately used memory,
  • Store.getDbSizeOnDisk() which only returns a non-zero size for a file-based database.
• Query: add properly named setParameter(prop, value) methods that only accept a single parameter value, deprecated the old setParameters(prop, value) variants.
• Sync: add SyncCredentials.userAndPassword(user, password).
• Gradle plugin: the license of the Gradle plugin has changed to the GNU Affero General Public License (AGPL).

• Support creating file-less in-memory databases, e.g. for caching and testing. To create one use inMemory() when building a BoxStore:

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

  See the BoxStoreBuilder.inMemory() documentation for details.
• Change BoxStore.deleteAllFiles() to support deleting an in-memory database.
• The maxDataSizeInKByte() option when building a store is ready for production use. This is different from the existing maxSizeInKByte() option in that it is possible to remove data after reaching the limit and continue to use the database. See its documentation for more details.
• Admin will now print a warning when it does not have permission to show the Admin notification. When testing your app on a device with Android 13 or newer, developers should manually turn on notifications to make use of the Admin notification.
• Added examples on how to use Kotlin's unsigned integer types to https://docs.objectbox.io/advanced/custom-types
• Restore compatibility with Kotlin 1.5. However, need to exclude kotlin-stdlib 1.8 from objectbox-kotlin as it includes classes previously in the -jdk7/-jdk8 libraries to avoid duplicate class file errors. So if not absolutely needed, we still recommend to use at least Kotlin 1.8.

• Throw an exception instead of crashing when trying to create a query on a closed store. #1154
• The Gradle plugin now requires at least Gradle 7.0 and Android Gradle Plugin 4.1.
• The Android library now requires Android 4.4 (API 19) or newer.

• A new key/value validation option validateOnOpenKv() is available on MyObjectBox.builder() to help diagnose FileCorruptException: Corrupt DB, min key size violated issues. If enabled, the build() call will throw a FileCorruptException if corruption is detected with details on which key/value is affected. #1143
• Admin: integer and floating point arrays introduced with the previous release are now nicely displayed and collapsed if long.
• Admin: the data table again displays all items of a page. #1135
• The __cxa_pure_virtual crash should not occur anymore; if you get related exceptions, they should contain additional information to better diagnose this issue. Let us know details in #1131
• Queries: all expected results are now returned when using a less-than or less-or-equal condition for a String property with index type VALUE. Reported via objectbox-dart#318
• Queries: when combining multiple conditions with OR and adding a condition on a related entity ("link condition") the combined conditions are now properly applied. Reported via objectbox-dart#546
• Some flags classes have moved to the new config package:
  • io.objectbox.DebugFlags is deprecated, use io.objectbox.config.DebugFlags instead.
  • io.objectbox.model.ValidateOnOpenMode is deprecated, use io.objectbox.config.ValidateOnOpenModePages instead.

• Support for integer and floating point arrays: store

  • short[], char[], int[], long[] and
  • float[] and double[]

  (or their Kotlin counterparts, e.g. FloatArray) without a converter.

  A simple example is a shape entity that stores a palette of RGB colors:

  @Entity
  public class Shape {
  
      @Id public long id;
  
      // An array of RGB color values that are used by this shape.
      public int[] palette;
  
  }
  
  // Find all shapes that use red in their palette
  try (Query<Shape> query = store.boxFor(Shape.class)
          .query(Shape_.palette.equal(0xFF0000))
          .build()) {
          query.findIds();
  }
  

  This can also be useful to store vector embeddings produced by machine learning, e.g.:

  @Entity
  public class ImageEmbedding {
  
      @Id public long id;
  
      // Link to the actual image, e.g. on Cloud storage
      public String url;
  
      // The coordinates computed for this image (vector embedding)
      public float[] coordinates;
  
  }
  

• Fix incorrect Cursor code getting generated when using @Convert to convert to a String array.

• The io.objectbox.sync plugin now also automatically adds a Sync-enabled JNI library on macOS and Windows (previously on Linux x64 only; still need to add manually for Linux on ARM).

We're hiring! 😎 We believe resource-efficient coding is still cool and are looking for a C / C++ developer who shares our sentiment.

• Fixes writes failing with "error code -30786", which may occur in some corner cases on some devices. #1099
• Add docs to DbSchemaException on how to resolve its typical causes.

We're hiring! 😎 We believe resource-efficient coding is still cool and are looking for a C / C++ developer who shares our sentiment.

This release includes breaking changes to generated code. If you encounter build errors, make sure to clean and build your project (e.g. Build > Rebuild project in Android Studio).

• Add Query.copy() and QueryThreadLocal to obtain a Query instance to use in different threads. Learn more about re-using queries. #1071
• Add relationCount query condition to match objects that have a certain number of related objects pointing to them. E.g. Customer_.orders.relationCount(2) will match all customers with two orders, Customer_.orders.relationCount(0) will match all customers with no associated order. This can be useful to find objects where the relation was dissolved, e.g. after the related object was removed.
• Allow using a relation target ID property with a property query. E.g. query.property(Order_.customerId) will map results to the ID of the customer of an order. #1028
• Add docs on DbFullException about why it occurs and how to handle it.
• Do not fail to transform an entity class that contains a transient relation field when using Android Gradle Plugin 7.1 or lower.
• Restore compatibility for Android projects using Gradle 6.1. The minimum supported version for Gradle is 6.1 and for the Android Gradle Plugin 3.4. This should make it easier for older projects to update to the latest version of ObjectBox.

Using Sync? This release uses a new Sync protocol which improves efficiency. Reach out via your existing contact to check if any actions are required for your setup.

• Add findFirstId() and findUniqueId() to Query which just return the ID of a matching object instead of the full object.
• Experimental support for setting a maximum data size via the maxDataSizeInKByte property when building a Store. This is different from the existing maxSizeInKByte property in that it is possible to remove data after reaching the limit and continue to use the database. See its documentation for more details.
• Fix a crash when querying a value-based index (e.g. @Index(type = IndexType.VALUE)) on Android 32-bit ARM devices. #1105
• Various small improvements to the native libraries.

Using Sync? There is no Sync version for this release, please continue using version 3.2.1.

Note: V3.3.0 contains a bug preventing correct transformation of some classes, please use V3.3.1 instead.

• Gradle plugin: use new transform API with Android Plugin 7.2.0 and newer. Builds should be slightly faster as only entity and cursor classes and only incremental changes are transformed. #1078
• Gradle plugin: improve detection of applied Android plugins, improve registration of byte-code transform for non-Android Java projects, add check for minimum supported version of Gradle.
• Various small improvements to the native libraries.

Using Sync? There is no Sync version for this release, please continue using version 3.2.1.

• Resolve an issue that prevented resources from getting cleaned up after closing BoxStore, causing the reference table to overflow when running many instrumentation tests on Android. #1080
• Plugin: support Kotlin 1.7. #1085

• Query: throw IllegalStateException when query is closed instead of crashing the virtual machine. #1081
• BoxStore and Query now throw IllegalStateException when trying to subscribe but the store or query is closed already.
• Various internal improvements including minor optimizations for binary size and performance.

• Windows: using a database directory path that contains unicode (UTF-8) characters does not longer create an additional, unused, directory with garbled characters.
• Query: when using a negative offset or limit display a helpful error message.
• Processor: do not crash, but error if ToOne/ToMany type arguments are not supplied (e.g. ToOne instead of ToOne<Entity>).
• The Data Browser has been renamed to ObjectBox Admin. Deprecated AndroidObjectBrowser, use Admin instead. AndroidObjectBrowser will be removed in a future release.

This release only contains bug fixes for the Android library when used with ObjectBox for Dart/Flutter.

This release only contains bug fixes.

• Fix incorrect unique constraint violation if an entity contains at least two unique properties with a certain combination of non-unique indexes.
• Data Browser/Admin: improved support when running multiple on the same host, but a different port (e.g. localhost:8090 and localhost:8091).

Read the blog post with more details and code examples for the new flex properties and query conditions.

• Support Flex properties. Expanding on the string and flexible map support in 3.0.0, it is now possible to add a property using Object in Java or Any? in Kotlin. These "flex properties" now allow to store values of various types like integers, floating point values, strings and byte arrays. Or lists and maps (using string keys) of those. Some limitations apply, see the FlexObjectConverter class documentation for details.

  @Entity
  data class Customer(
      @Id var id: Long = 0,
      var tag: Any? = null
  )
  
  val customerStrTag = Customer(tag = "string-tag")
  val customerIntTag = Customer(tag = 1234)
  box.put(customerStrTag, customerIntTag)
  

• The containsElement query condition now matches keys of string map properties. It also matches string or integer elements of a Flex list.
• New containsKeyValue query condition to match key/value combinations of string map and Flex map properties containing strings and integers. Also added matching Query.setParameters overload.

  val customer = Customer(
      properties = mutableMapOf("premium" to "tier-1")
  )
  box.put(customer)
  
  // Query for any customers that have a premium key in their properties map
  val queryPremiumAll = box.query(
      Customer_.properties.containsElement("premium")
  ).build()
  
  // Match only customers with specific key and value map entry
  val queryPremiumTier1 = box.query(
      Customer_.properties.containsKeyValue("premium", "tier-1")
  ).build()
  

• Add ProGuard/R8 rule to not warn about SuppressFBWarnings annotation. #1011
• Add more detailed error message when loading the native library fails on Android. #1024
• Data browser: byte arrays are now correctly displayed in Base64 encoding. #1033

Kotlin

• Add BoxStore.awaitCallInTx suspend function which wraps BoxStore.callInTx.

Gradle plugin

• Do not crash trying to add dependencies to Java desktop projects that only apply the Gradle application plugin.

Read more in the docs

• Fixes the ObjectBox plugin crashing when applied to an Android project that does not use the Kotlin plugin.

See the 3.0.0 release notes for a list of important changes.

All release notes & docs

Note: this version contains a bug that prevents usage with Android Java only projects. Use 3.0.1 instead.

• 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

  // equal AND (less OR oneOf)
  val query = box.query(
        User_.firstName equal "Joe"
                and (User_.age less 12
                or (User_.stamp oneOf longArrayOf(1012))))
        .order(User_.age)
        .build()
  

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

  // Replace String conditions like
  query().equal(User_.firstName, "Joe")
  // With the one accepting a StringOrder
  query().equal(User_.firstName, "Joe", StringOrder.CASE_INSENSITIVE)
  

• The Gradle plugin will now warn when an @Entity class is missing a no-arg (easy to add) or all properties (best for performance) constructor. #900
  Example for an all properties constructor:

  @Entity
  public class Order {
  
      @Id
      private long id;
      private ToOne<Customer> customer;
      private ToMany<Order> relatedOrders;
  
      // All properties constructor for ObjectBox:
      // - make sure type matches exactly,
      // - for ToOne add its virtual ID property instead,
      // - for ToMany add no parameter.
      public Order(long id, long customerId) {
          this.id = id;
          this.customer.setTargetId(customerId);
      }
  
      // TODO getters and setters for properties
  }
  

• 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

  @Entity
  data class Example(
          @Id
          var id: Long = 0,
          @Unique(onConflict = ConflictStrategy.REPLACE)
          var uniqueKey: String? = null
  )
  

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

  @Type(DatabaseType.DateNano)
  var timeInNanos: Long;
  

• 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. #990
• 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>) and lists (Java List<String> and Kotlin MutableList<String>). Using the new containsElement("item") condition, it is also possible to query for entities where "item" is equal to one of the elements.

  @Entity
  data class Example(
          @Id
          var id: Long = 0,
          var stringArray: Array<String>? = null,
          var stringMap: MutableMap<String, String>? = null
  )
  
  // matches [“first”, “second”, “third”]
  box.query(Example_.stringArray.containsElement(“second”)).build()
  

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

All release notes & docs

This is the first release available on the Central repository (Sonatype OSSRH). Make sure to adjust your build.gradle files accordingly:

repositories {
    mavenCentral()
}

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.

All release notes & docs

• 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

Previous release notes & docs