{
debug.set(true)
}
```
### Enable DaoCompat mode
ObjectBox can help you migrate from greenDAO by generating classes with a greenDAO-like API.
See the [DaoCompat documentation](http://greenrobot.org/greendao/documentation/objectbox-compat/) on how to enable and use this feature.
## ObjectBox for Flutter/Dart - Advanced Setup
### Change the generated files directory
To customize the directory (relative to the package root) where the files generated by ObjectBox are written, add the following to your `pubspec.yaml`:
```
objectbox:
# Writes objectbox-model.json and objectbox.g.dart to lib/custom (and test/custom).
output_dir: custom
# Or optionally specify the lib and test output folder separately.
# output_dir:
# lib: custom
# test: other
```
# Object IDs
Explanation of Object IDs and how they are used and assigned in ObjectBox.
## ObjectBox - Object IDs
**Objects must have an ID property of type `long`.** You are free to use the wrapper type `java.lang.Long`, but we advise against it in most cases. `long` IDs are enforced to make ObjectBox very efficient internally.
If your application requires other ID types (such as a string UID given by a server), you can model them as standard properties and use [queries](/queries) to look up entities by your application-specific ID.
## Object ID: new vs. persisted entities
When you create new entity objects (on the language level), they are not persisted yet and their ID is (zero). Once an entity is put (persisted), ObjectBox will assign an ID to the entity. You can access the ID property right after the call to `put()`.
Those are also applied the other way round: ObjectBox uses the **ID as a state indication** of whether an entity is new (zero) or already persisted (non-zero). This is used internally, e.g. for relations that heavily rely on IDs.
## Special Object IDs
Object IDs may be any `long` value, with two exceptions:
* **0 (zero):** Objects with an ID of zero (and `null` if the ID is of type `Long`) are considered new (not persisted before). Putting such an object will always insert a new object and assign an unused ID to it.
* **0xFFFFFFFFFFFFFFFF (-1 in Java):** This value is reserved for internal use by ObjectBox and may not be used by the app.
## Object ID assignment (default)
By default, object IDs are assigned by ObjectBox. For each new object, ObjectBox will assign an unused ID that is above the current highest ID value used in a box. For example, if there are two objects with ID 1 and ID 100 in a box the next object that is put will be assigned ID 101.
Also, note that this will mean in some circumstances IDs from deleted objects may be reused. So it is best to not rely on a specific ID getting assigned.
**By default, only ObjectBox may assign IDs.** If you try to put an object with an ID greater than the currently highest ID, ObjectBox will throw an error.
## Manually assigned Object IDs
{% hint style="info" %}
This is not recommended. Check if using a [unique indexed property](/entity-annotations#object-ids-id) is a viable alternative.
{% endhint %}
If your code **needs to assign IDs by itself** you can change the `@Id` annotation to:
{% tabs %}
{% tab title="Java" %}
```java
@Id(assignable = true)
long id;
```
{% endtab %}
{% tab title="Dart" %}
```dart
@Id(assignable: true)
int id = 0;
```
{% endtab %}
{% endtabs %}
This will allow putting an entity with any valid ID (see [#special-object-ids](#special-object-ids "mention")). If the `@Id` field is writable, it can still be set to zero to let ObjectBox auto-assign a new ID.
{% hint style="warning" %}
**Warning:** manually assigning IDs breaks automatic state detection (new vs. persisted entity based on the ID). Therefore, **entities with manually assigned IDs should be put immediately and the Box may have to be attached manually**, especially when working with relations.
For details see the documentation about [updating relations](/relations#updating-relations).
{% endhint %}
## String ID alias (future work)
Check [this issue](https://github.com/objectbox/objectbox-java/issues/167) on Github for status.
# Custom Types
How to store types that are not built-in, recommendations for storing enums, and using property converters.
ObjectBox supports a wide range of [built-in property types](/property-types). For types that aren't directly supported, you can use converters to map them to a built-in type.
## Flex property converters
In ObjectBox for Java/Kotlin, [Flex properties](/property-types#flex-properties) use converters internally. You can exchange converters to fine-tune the conversion process. To **override the default converter**, use `@Convert`. For example to use another built-in `FlexObjectConverter` subclass:
{% tabs %}
{% tab title="Java" %}
// StringLongMapConverter restores any integers always as Long
@Convert(converter = StringLongMapConverter.class, dbType = byte[].class)
@Nullable Map<String, Object> stringMap;
{% endtab %}
{% tab title="Kotlin" %}
```kotlin
// StringLongMapConverter restores any integers always as Long
@Convert(converter = StringLongMapConverter::class, dbType = ByteArray::class)
var stringMap: MutableMap? = null
```
{% endtab %}
{% endtabs %}
You can also write a custom converter like shown below.
## Convert annotation and property converter
To add support for a custom type, you need to provide a conversion to one of the ObjectBox built-in types. For example, you could define a color in your entity using a custom `Color` class and map it to an `Integer`. Or you can map the popular `org.joda.time.DateTime` from Joda Time to a `Long`.
Here is an example mapping an `enum` to an integer:
{% tabs %}
{% tab title="Java" %}
```java
@Entity
public class User {
@Id
public long id;
@Convert(converter = RoleConverter.class, dbType = Integer.class)
public Role role;
public enum Role {
DEFAULT(0), AUTHOR(1), ADMIN(2);
final int id;
Role(int id) {
this.id = id;
}
}
public static class RoleConverter implements PropertyConverter {
@Override
public Role convertToEntityProperty(Integer databaseValue) {
if (databaseValue == null) {
return null;
}
for (Role role : Role.values()) {
if (role.id == databaseValue) {
return role;
}
}
return Role.DEFAULT;
}
@Override
public Integer convertToDatabaseValue(Role entityProperty) {
return entityProperty == null ? null : entityProperty.id;
}
}
}
```
{% endtab %}
{% tab title="Kotlin" %}
```kotlin
@Entity
data class User(
@Id
var id: Long = 0,
@Convert(converter = RoleConverter::class, dbType = Int::class)
var role: Role? = null
)
enum class Role(val id: Int) {
DEFAULT(0), AUTHOR(1), ADMIN(2);
}
class RoleConverter : PropertyConverter {
override fun convertToEntityProperty(databaseValue: Int?): Role? {
if (databaseValue == null) {
return null
}
for (role in Role.values()) {
if (role.id == databaseValue) {
return role
}
}
return Role.DEFAULT
}
override fun convertToDatabaseValue(entityProperty: Role?): Int? {
return entityProperty?.id
}
}
```
{% endtab %}
{% tab title="Dart" %}
```dart
enum Role {
unknown,
author,
admin
}
@Entity()
class User {
int id;
// The Role type is not supported by ObjectBox.
// So ignore this field...
@Transient()
Role? role;
// ...and define a field with a supported type,
// that is backed by the role field.
int? get dbRole {
_ensureStableEnumValues();
return role?.index;
}
set dbRole(int? value) {
_ensureStableEnumValues();
if (value == null) {
role = null;
} else {
role = Role.values[value]; // throws a RangeError if not found
// or if you want to handle unknown values gracefully:
role = value >= 0 && value < Role.values.length
? Role.values[value]
: Role.unknown;
}
}
User(this.id);
void _ensureStableEnumValues() {
assert(Role.unknown.index == 0);
assert(Role.author.index == 1);
assert(Role.admin.index == 2);
}
}
```
{% endtab %}
{% endtabs %}
### Things to look out for
If you define your custom type or converter **inside a Java or Kotlin entity class**, it must be **static or respectively not an inner class**.
Don’t forget to **handle null values** correctly – usually, you should return null if the input is null.
Database types in the sense of the converter are the primitive (built-in) types offered by ObjectBox, as mentioned in the beginning. It is recommended to **use a primitive type that is easily convertible** (int, long, byte array, String, …).
You must **not interact with the database** (such as using `Box` or `BoxStore`) inside the converter. The converter methods are called within a transaction, so for example, getting or putting entities to a box will fail.
{% hint style="info" %}
Note: For optimal performance, **ObjectBox will use a single converter instance** for all conversions. Make sure the converter does not have any other constructor besides the parameter-less default constructor. Also, make it thread-safe, because it might be called concurrently on multiple entities.
{% endhint %}
## List/Array types
You can use a converter with List types. For example, you could convert a List of Strings to a JSON array resulting in a single string for the database. At the moment it is not possible to use an array with converters (you can track this [feature request](https://github.com/greenrobot/ObjectBox/issues/42)).
{% hint style="info" %}
ObjectBox has [built-in support for many list and array types](/property-types#lists-and-arrays), including String lists/arrays and typed numeric arrays.
{% endhint %}
## How to convert Enums correctly
Enums are popular with data objects like entities. When persisting enums, there are a couple of best practices:
* **Do not persist the enum’s ordinal or name:** Both are unstable, and can easily change the next time you edit your enum definitions.
* **Use stable ids:** Define a custom property (integer or string) in your enum that is guaranteed to be stable. Use this for your persistence mapping.
* **Prepare for the unknown:** Define an UNKNOWN enum value. It can serve to handle null or unknown values. This will allow you to handle cases like an old enum value getting removed without crashing your app.
## Custom types in queries
`QueryBuilder` is unaware of custom types. You have to **use the primitive DB type for queries**.
So for the Role example above you would get users with the role of admin with the query condition `.equal(UserProperties.Role, 2)`.
# Entity Inheritance
How to inherit properties from entity super classes.
## ObjectBox - Entity Super Classes
{% hint style="info" %}
Only available for Java/Kotlin at the moment
{% endhint %}
ObjectBox allows entity inheritance to share persisted properties in super classes. The base class can be an entity or non-entity class. For this purpose the `@Entity` annotation is complemented by the `@BaseEntity` annotation. There are three types of super classes, which are defined via annotations:
* **No annotation:** The base class and its properties are not considered for persistence.
* **@BaseEntity:** Properties are considered for persistence in sub classes, but the base class itself cannot be persisted.
* **@Entity:** Properties are considered for persistence in sub classes, and the base class itself is a normally persisted entity.
For example:
{% tabs %}
{% tab title="Java" %}
```java
// Superclass:
@BaseEntity
public abstract class Base {
@Id long id;
String baseString;
public Base() {
}
public Base(long id, String baseString) {
this.id = id;
this.baseString = baseString;
}
}
// Subclass:
@Entity
public class Sub extends Base {
String subString;
public Sub() {
}
public Sub(long id, String baseString, String subString) {
super(id, baseString);
this.subString = subString;
}
}
```
{% endtab %}
{% tab title="Kotlin" %}
```kotlin
// Note: Kotlin data classes do not support inheritance,
// so this example uses regular Kotlin classes.
// Superclass:
@BaseEntity
abstract class Base {
@Id
var id: Long = 0
var baseString: String? = null
constructor()
constructor(id: Long, baseString: String?) {
this.id = id
this.baseString = baseString
}
}
// Subclass:
@Entity
class Sub : Base {
var subString: String? = null
constructor()
constructor(id: Long,
baseString: String?,
subString: String?) : super(id, baseString) {
this.subString = subString
}
}
```
{% endtab %}
{% endtabs %}
The model for Sub, Sub\_, will now include all properties: `id` , `baseString` and `subString` .
It is also possible to inherit properties from another entity:
{% tabs %}
{% tab title="Java" %}
```java
// Entities inherit properties from super entities.
@Entity
public class SubSub extends Sub {
String subSubString;
public SubSub() {
}
public SubSub(long id, String baseString,
String subString, String subSubString) {
super(id, baseString, subString);
this.subSubString = subSubString;
}
}
```
{% endtab %}
{% tab title="Kotlin" %}
```kotlin
// Entities inherit properties from super entities.
@Entity
class SubSub : Sub {
var subSubString: String? = null
constructor()
constructor(id: Long,
baseString: String?,
subString: String?,
subSubString: String?) : super(id, baseString, subString) {
this.subSubString= subSubString
}
}
```
{% endtab %}
{% endtabs %}
## Notes on usage
* It is possible to have classes in the inheritance chain that are not annotated with @BaseEntity. Their properties will be ignored and will not become part of the entity model.
* It is not generally recommend to have a base entity class consisting of an ID property only. E.g. Java imposes an additional overhead to construct objects with a sub class.
* Depending on your use case using interfaces may be more straightforward.
## Restrictions
* Superclasses annotated with **@BaseEntity can not be part of a library**.
* There are **no polymorphic queries** (e.g. you cannot query for a base class and expect results from sub classes).
* Currently any superclass, whether it is an @Entity or @BaseEntity, **can not have any relations** (like a ToOne or ToMany property).
{% tabs %}
{% tab title="Java" %}
```java
// THIS DOES NOT WORK
@BaseEntity
public abstract class Base {
@Id long id;
ToOne other;
ToMany others;
}
```
{% endtab %}
{% tab title="Kotlin" %}
```kotlin
// THIS DOES NOT WORK
@BaseEntity
abstract class Base {
@Id
var id: Long = 0
lateinit var other: ToOne
lateinit var others: ToMany
}
```
{% endtab %}
{% endtabs %}
# Data Model Updates
How to rename entities and properties, change property types in ObjectBox.
## ObjectBox - Data Model Updates
ObjectBox manages its data model (schema) mostly automatically. The data model is defined by the entity classes you define. When you **add or remove** entities or properties of your entities, **ObjectBox takes care** of those changes without any further action from you.
For other changes like **renaming or changing the type**, ObjectBox needs **extra information** to make things unambiguous. This is done by setting a unique ID (UIDs) as an annotation, as we will see below.
## UIDs
ObjectBox keeps track of entities and properties by assigning them unique IDs (UIDs). All those UIDs are stored in a file `objectbox-models/default.json` (Java, Kotlin) or `lib/objectbox-model.json` (Dart) which you should add to your version control system (e.g. git). If you are interested, we have [in-depth documentation on UIDs and concepts](/advanced/meta-model-ids-and-uids). But let’s continue with how to rename entities or properties.
**In short:** To make UID-related changes, put an `@Uid` annotation (Java, Kotlin) or `@Entity(uid: 0)/@Property(uid: 0)` (Dart) on the entity or property and build the project to get further instructions. Repeat for each entity or property to change.
## Renaming Entities and Properties
So why do we need that UID annotation? If you simply rename an entity class, ObjectBox only sees that the old entity is gone and a new entity is available. This can be interpreted in two ways:
* The old entity is removed and a new entity should be added, the old data is discarded. This is the **default behavior** of ObjectBox.
* The entity was renamed, the old data should be re-used.
So to tell ObjectBox to do a rename instead of discarding your old entity and data, you need to make sure it knows that this is the same entity and not a new one. You do that by attaching the internal UID to the entity.
The same is true for properties.
Now let’s walk through how to do that. The process works the same if you want to rename a property:
### How-to and Example (Java/Kotlin and Dart)
**Step 1:** Add an empty UID to the entity/property you want to rename:
{% tabs %}
{% tab title="Java/Kotlin" %}
```java
@Entity
@Uid
public class MyName { ... }
```
{% endtab %}
{% tab title="Dart" %}
```dart
@Entity(uid: 0)
class MyName { ... }
```
{% endtab %}
{% endtabs %}
**Step 2:** Build the project (in Dart, run `pub run build_runner build`). The build will fail with an error message that gives you the current UID of the entity/property:
{% tabs %}
{% tab title="Java/Kotlin" %}
```
error: [ObjectBox] UID operations for entity "MyName":
[Rename] apply the current UID using @Uid(6645479796472661392L) -
[Change/reset] apply a new UID using @Uid(4385203238808477712L)
```
{% endtab %}
{% tab title="Dart" %}
```
@Entity(uid: 0) found on "MyName" - you can choose one of the following actions:
[Rename] apply the current UID using @Entity(uid: 6645479796472661392)
[Change/reset] apply a new UID using @Entity(uid: 4385203238808477712)
```
{% endtab %}
{% endtabs %}
**Step 3:** Apply the UID from the \[Rename] section of the error message to your entity/property:
{% tabs %}
{% tab title="Java/Kotlin" %}
```java
@Entity
@Uid(6645479796472661392L)
public class MyName { ... }
```
{% endtab %}
{% tab title="Dart" %}
```dart
@Entity(uid: 6645479796472661392)
class MyName { ... }
```
{% endtab %}
{% endtabs %}
**Step 4:** The last thing to do is the actual rename on the language level (Java, Kotlin, etc.):
{% tabs %}
{% tab title="Java/Kotlin" %}
```java
@Entity
@Uid(6645479796472661392L)
public class MyNewName { ... }
```
{% endtab %}
{% tab title="Dart" %}
```dart
@Entity(uid: 6645479796472661392)
class MyNewName { ... }
```
{% endtab %}
{% endtabs %}
**Step 5:** Build the project again, it should now succeed. You can now use your renamed entity/property as expected and all existing data will still be there.
**Repeat** the steps above to rename another entity or property.
{% hint style="info" %}
Note: Instead of the above you can also find the UID of the entity/property in the model JSON mentioned in the introduction. You can add the UID value to the annotation yourself, before renaming the entity/property, and skip the intermediate error where ObjectBox just prints it for you. This can be **faster when renaming multiple properties**.
{% endhint %}
### How-to and Example (Python)
Since in Python there isn't a build step, the steps for renaming an Entity are different. Say we want to rename the Entity `MyName` to `MyNewName`:
```python
@Entity()
class MyName:
id = Id
some_property = Int
```
**Step 1**: Find out the UID of the entity `MyName`:
print(MyName._uid)
# 6645479796472661392
**Step 2**: Rename `MyName` to `MyNewName` and explicitly specify the old UID:
```python
@Entity(uid=6645479796472661392)
class MyNewName:
id = Id
some_property = Int
```
This makes possible for Objectbox to associate the old entity to the new one, and retain persisted data. If you don't specify the old UID, Objectbox will discard the old data and add a fresh new entity called `MyNameName` to the schema.
## Changing Property Types
{% hint style="warning" %}
ObjectBox does not support migrating existing property data to a new type. You will have to take care of this yourself, e.g. by keeping the old property and adding some migration logic.
{% endhint %}
There are two solutions to changing the type of a property:
* Add a new property with a different name (this only works if the property has no @Uid annotation already):
```java
// old:
String year;
// new:
int yearInt;
```
* Set a new UID for the property so ObjectBox treats it as a new property. Let’s walk through how to do that:
### How-to and Example
**Step 1:** Add the `@Uid` annotation to the property where you want to change the type:
{% tabs %}
{% tab title="Java/Kotlin" %}
```java
@Uid
String year;
```
{% endtab %}
{% tab title="Dart" %}
```dart
@Property(uid: 0)
String year;
```
{% endtab %}
{% endtabs %}
**Step 2:** Build the project. The build will fail with an error message that gives you a newly created UID value:
{% tabs %}
{% tab title="Java/Kotlin" %}
```
error: [ObjectBox] UID operations for property "MyEntity.year":
[Rename] apply the current UID using @Uid(6707341922395832766L) -
[Change/reset] apply a new UID using @Uid(9204131405652381067L)
```
{% endtab %}
{% tab title="Dart" %}
```
@Property(uid: 0) found on "year" - you can choose one of the following actions:
[Rename] apply the current UID using @Property(uid: 6707341922395832766)
[Change/reset] apply a new UID using @Property(uid: 9204131405652381067)
```
{% endtab %}
{% endtabs %}
**Step 3:** Apply the UID from the \[Change/reset] section to your property:
{% tabs %}
{% tab title="Java/Kotlin" %}
```java
@Uid(9204131405652381067L)
int year;
```
{% endtab %}
{% tab title="Dart" %}
```dart
@Property(uid: 9204131405652381067)
String year;
```
{% endtab %}
{% endtabs %}
**Step 4:** Build the project again, it should now succeed. You can now use the property in your entity as if it were a new one.
**Repeat** the steps above to change the type of another property.
# Meta Model, IDs, and UIDs
Explaining the ObjectBox meta model file and how to resolve model file conflicts.
Unlike relational databases like SQLite, ObjectBox does not require you to create a database schema. That does not mean ObjectBox is schema-less. For efficiency reasons, ObjectBox manages a **meta model** of the data stored. This meta model is actually ObjectBox’s equivalent of a schema. It includes known object types including all properties, indexes, etc. A key difference to relational schemas is that ObjectBox tries to manage its meta model automatically. In some cases it needs your help. That’s why we will look at some details.
## IDs
In the ObjectBox meta model, everything has an ID and a UID. IDs are used internally in ObjectBox to reference entities, properties, and indexes. For example, you have an entity “User” with the properties “id” and “name”. In the meta model the entity (type) could have the ID 42, and the properties the IDs 1 and 2. Property IDs must only be unique within their entity.
{% hint style="info" %}
Note: do not confuse object IDs with meta model IDs: object IDs are the values of the @Id property (see Object IDs in [basics](/getting-started)). In contrast, all objects are instances of the entity type associated with a single meta model ID.
{% endhint %}
ObjectBox assigns meta model IDs sequentially (1, 2, 3, 4, …) and keeps track of the last used ID to prevent ID collisions.
## UIDs
As a rule of thumb, for each meta model ID there’s a corresponding UID. They complement IDs and are often used in combination (e.g. in the JSON file). While IDs are assigned sequentially, UIDs are a random long value. The job of UIDs is detecting and resolving concurrent modifications of the meta model.
A UID is unique across entities, properties, indexes, etc. Thus unlike IDs, an UID already used for an entity may not be used for a property. As a precaution to avoid side effects, ObjectBox keeps track of “retired” UIDs to ensure previously used but now abandoned UIDs are not used for new artifacts.
## JSON for consistent IDs
ObjectBox stores a part of its meta model in a JSON file. This file should be available to every developer and thus checked into a source version control system (e.g. git). The main purpose of this JSON file is to ensure consistent IDs and UIDs in the meta model across devices.
This JSON file is stored in
* `objectbox-models/default.json` for Android or Java projects,
* `lib/objectbox-model.json` for Dart or Flutter projects.
For example, look at a file from the [ObjectBox example project](https://github.com/objectbox/objectbox-examples):
```java
{
"_note1": "KEEP THIS FILE! Check it into a version control system (VCS) like git.",
"_note2": "ObjectBox manages crucial IDs for your object model. See docs for details.",
"_note3": "If you have VCS merge conflicts, you must resolve them according to ObjectBox docs.",
"entities": [
{
"id": "1:6645479796472661392",
"lastPropertyId": "5:8452815412120793251",
"name": "Note",
"properties": [
{
"id": "1:9211738071025439652",
"name": "id",
"type": 6,
"flags": 1
},
{
"id": "2:8804670454579230281",
"name": "text",
"type": 9
},
{
"id": "4:1260602348787983453",
"name": "date",
"indexId": "1:9194998581973594219",
"type": 10,
"flags": 8
},
{
"id": "5:8452815412120793251",
"name": "authorId",
"indexId": "2:5206397068544851461",
"type": 11,
"flags": 520,
"relationTarget": "Author"
}
],
"relations": []
},
{
"id": "2:8096888707432154961",
"lastPropertyId": "2:388290850215565763",
"name": "Author",
"properties": [
{
"id": "1:2456363380762264329",
"name": "id",
"type": 6,
"flags": 1
},
{
"id": "2:388290850215565763",
"name": "name",
"type": 9
}
],
"relations": []
}
],
"lastEntityId": "2:8096888707432154961",
"lastIndexId": "2:5206397068544851461",
"lastRelationId": "0:0",
"lastSequenceId": "0:0",
"modelVersion": 5,
"modelVersionParserMinimum": 5,
"retiredEntityUids": [],
"retiredIndexUids": [],
"retiredPropertyUids": [],
"retiredRelationUids": [],
"version": 1
}
```
As you can see, the “id” attributes combine the ID and UID using a colon. This protects against faulty merges. When applying the meta model to the database, ObjectBox will check for consistent IDs and UIDs.
## Meta Model Synchronization
At build time, ObjectBox gathers meta model information from the entities (@Entity classes) and the JSON file. The complete meta model information is written into the generated class `MyObjectBox`.
Then, at runtime, the meta model assembled in MyObjectBox is synchronized with the meta model inside the ObjectBox database (file). UIDs are the primary keys to synchronize the meta model with the database. The synchronization involves a couple of consistency checks that may fail when you try to apply illegal meta data.
## Stable Renames using UIDs
At some point you may want to rename an entity class or just a property. Without further information, ObjectBox will remove the old entity/property and add a new one with the new name. This is actually a valid scenario by itself: removing one property and adding another. To tell ObjectBox it should do a rename instead, you need to supply the property's previous UID.
Add an `@Uid` annotation without any value to the entity or property you want to rename and trigger a project build. The build will fail with a message containing the UID you need to apply to the `@Uid` annotation.
Also check out this [how-to guide](/advanced/data-model-updates) for hands-on information on renaming and resetting.
## Resolving Meta Model Conflicts
In the section on UIDs, we already hinted at the possibility of meta model conflicts. This means the meta model defined in the `objectbox-models/default.json` file conflicts with the model of the existing database file.
When creating a Store the meta model is passed and verified against the database file. If a conflict exists an exception or error is thrown, for example:
```
// If lastEntityId in the model file is incorrect:
io.objectbox.exception.DbSchemaException:
DB's last entity ID 4 is higher than 3 from model
// If the UID of an entity in the model file has changed:
io.objectbox.exception.DbSchemaException:
Incoming entity ID 1:6645479796472661392 does not match existing UID 8096888707432154961
```
Such a conflict can be caused by
* developers changing the meta model at the same time (e.g. in different version control system branches), typically by adding entity classes or properties.
* the `objectbox-models/default.json` model file getting accidentally deleted, it is then generated on the next build with a new set of UIDs.
* a database file with a different model getting restored by [Android Auto Backup](https://developer.android.com/guide/topics/data/autobackup) or getting [supplied as the initial database file](https://objectbox.io/docfiles/java/current/io/objectbox/BoxStoreBuilder.html#initialDbFile\(java.io.File\)).
There are basically two ways to resolve this:
* Resolve conflicts in or reconstruct the `default.json` meta model file to match the model of an existing database file.
* Keep or create a fresh `default.json` model file and delete the database file. However, this will lose all existing data.
The two options are explained in detail below.
### Manual conflict resolution
Usually, it is preferred to edit the JSON file to resolve conflicts and fix the meta model. This involves the following steps:
* **Ensure IDs are unique:** in the JSON file the id attribute has values in the format “ID:UID”. If you have duplicate IDs after a VCS merge, you should assign a new ID (keep the UID part!) to one of the two. Typically, the new ID would be “last used ID + 1”.
* **Update last ID values:** for entities, update the attribute `lastEntityId`; for properties, update the attribute `lastPropertyId` of the enclosing entity back to the ID:UID with the ID indicated by the error message.
* **Check for other ID references:** do a text search for the UID and check if the ID part is correct for all UID occurrences
To illustrate this with an example, let's assume the last assigned entity ID was 41. Thus the next entity ID will be 42. Now, the developers Alice and Bob add a new entity without knowing of each other. Alice adds a new entity “Ant” which is assigned the entity ID 42. At the same time, Bob adds the entity “Bear” which is also assigned the ID 42. After both developers committed their code, the ID 42 does not unique identify an entity type (“Ant” or “Bear”?). Furthermore, in Alice’s ObjectBox the entity ID 42 is already wired to “Ant” while Bob’s ObjectBox maps 42 to “Bear”. UIDs make this situation resolvable. Let’s say the UID is 12345 for “Ant” and 9876 for “Bear”. Now, when Bob pulls Alice’s changes, he is able to resolve the conflict. He manually assigns the entity ID 43 to “Bear” and updates the lastEntityId attribute accordingly to “43:9876” (ID:UID). After Bob commits his changes, both developers are able to continue with their ObjectBox files.
### The Nuke Option
During initial development, it may be an option to just delete the meta model and all databases. This will cause a fresh start for the meta model, e.g. all UIDs will be regenerated. Follow these steps:
* Delete the JSON file (objectbox-models/default.json)
* Build the project to generate a new JSON file from scratch
* Commit the recreated JSON file to your VCS (e.g. git)
* **Delete all previously created ObjectBox databases** (e.g. for Android, delete the app’s data or uninstall the app)
While this is a simple approach, it has its obvious disadvantages. For example for a published app, all existing data would be lost.
# Changelogs
The changelogs for each programming language are available at GitHub:
* [Java changelog (GitHub releases)](https://github.com/objectbox/objectbox-java/releases)
* [Dart changelog](https://github.com/objectbox/objectbox-dart/blob/main/objectbox/CHANGELOG.md)
* [Python changelog (GitHub releases)](https://github.com/objectbox/objectbox-python/releases)
For other languages, please check there respective doc pages:
* [C and C++](https://cpp.objectbox.io/)
* [Swift](https://swift.objectbox.io/)
* [Go](https://golang.objectbox.io/)
## Changelog History before 4.0.3
Older entries (4.0.2 and earlier) are available in the [release history](/release-history).
# FAQ
Answers to questions specific to ObjectBox for Java and Dart
## **Does ObjectBox support Kotlin? RxJava?**
ObjectBox comes with full [Kotlin support](https://docs.objectbox.io/kotlin-support) including data classes. And yes, it supports [RxJava and reactive queries without RxJava](https://docs.objectbox.io/data-observers-and-rx).
## **Does ObjectBox support object relations?**
Yes. ObjectBox comes with strong relation support and offers features like “eager loading” for optimal performance.
## **Does ObjectBox support multi-module projects? Can entities be spread across modules?**
The ObjectBox Gradle plugin only looks for entities in the current module, it does not search library modules. However, you can have a separate database (`MyObjectBox` file) for each module. Just make sure to pass different database names when building your BoxStore.
## **Is ObjectBox a “zero copy” database? Are properties fetched lazily?**
It depends. Internally and in [the C API](https://github.com/objectbox/objectbox-c), ObjectBox does zero-copy reads. Java objects require a single copy only. However, copying data is only a minor factor in overall performance. In ObjectBox, objects are POJOs (plain objects), and all properties will be properly initialized. Thus, there is no run time penalty for accessing properties and values do not change in unexpected ways when the database updates.
## **Are there any threading constrictions?**
No. The objects you get from ObjectBox are POJOs (plain objects). You are safe to pass them around in threads.
## Should I use ObjectBox on the main thread (or UI thread)?
It depends. In most cases no IO operations (which is what ObjectBox does) should be run on the main thread. This avoids (even rare) hangs of your app.
However, in some cases it might be alright. While ObjectBox and the underlying OS and file system can give no hard guarantees, reading (e.g. Box.get(id)) small amounts of data is typically very fast and should have no notable impact on observed performance of your app. This is because in ObjectBox reads, unlike writes, are not blocked by other operations.
## **On which platforms does ObjectBox run?**
ObjectBox supports **Android 5.0 (API level 21)** or newer and works on most device architectures (armeabi-v7a, arm64-v8a, x86 and x86\_64). An Android library is available for Java (also Kotlin) and Flutter projects.
ObjectBox supports **iOS 12** or newer on **64-bit devices** only. An iOS library is available for [Flutter](https://pub.dev/packages/objectbox) or [Swift](https://objectbox.io/swift-database-for-ios/) projects.
ObjectBox also runs on Linux (x86\_64, arm64, armv7), Windows (x86\_64) and macOS 10.15 or newer (x86\_64, Apple M1) with support for [Kotlin, Java, Dart, Flutter, Go, C, Swift and Python](https://objectbox.io/offline-first-mobile-database/).
## **Can I use ObjectBox on the desktop/server?**
Yes, you can ObjectBox on the desktop/server side. Contact us for details if you are interested in running ObjectBox in client/server mode or containerized!
## **Can I use ObjectBox on smart IoT devices?**
Yes. You can run the ObjectBox database on any IoT device that runs Linux. We also offer Go and C APIs. Check our [cross-platform tutorial](https://objectbox.io/cross-platform-sync-example/) and see how easy it is to sync data across platforms in real time with ObjectBox.
## **How do I rename object properties or classes?**
If you only do a rename on the language level, ObjectBox will by default remove the old and add a new entity/property. [To do a rename, you must specify the UID](https://docs.objectbox.io/advanced/data-model-updates).
## **How much does ObjectBox add to my APK size?**
The Google Play **download size** increases by around 2.3 MB (checked for ObjectBox 3.0.0) as a native library for each [supported architecture](#on-which-platforms-does-objectbox-run) is packaged. If you [build multiple APKs](https://developer.android.com/studio/build/configure-apk-splits) split by ABI or use [Android App Bundle](https://developer.android.com/guide/app-bundle/) it only increases around 0.6 MB.
{% hint style="info" %}
Tip: Open your APK or AAB in Android Studio and have a look at the lib folder to see the raw file size and download size added.
{% endhint %}
When building with minimum API level 23 (Android 6.0), the **raw file (APK or AAB) size** increases more, by around 6.1 MB. This is because the Android Plugin adds `extractNativeLibs="false"` to your `AndroidManifest.xml` [as recommended by Google](https://developer.android.com/topic/performance/reduce-apk-size#extract-false). This turns off compression. However, this allows Google Play to optimally compress APKs before downloading them to each device (see download size above) and reduces the size of your app updates (on Android 6.0 or newer). [Read this Android developers post for details](https://medium.com/androiddevelopers/smallerapk-part-8-native-libraries-open-from-apk-fc22713861ff). It also avoids issues that might occur when extracting the libraries.
If you rather have a smaller APK/App Bundle instead of smaller app downloads and updates (e.g. when distributing in other stores) you can override the flag in your `AndroidManifest.xml`:
{% hint style="info" %}
This is also [currently recommended](https://docs.flutter.dev/deployment/android#building-the-app-for-release) in any case **when building a Flutter** app with minimum API level 23 (Android 6.0).
{% endhint %}
```
```
More importantly, ObjectBox adds little to the APK method count since it’s mostly written in native code.
## **Can I ship my app with a pre-built database?**
Yes. ObjectBox stores all data in a single database file. Thus, you just need to prepare a database file and copy it to the correct location on the first start of your app (before you touch ObjectBox’s API).
{% hint style="info" %}
For Java, there is an **experimental** `initialDbFile()` method when building BoxStore. [Let us know](https://github.com/objectbox/objectbox-java/issues/310) if this is useful!
{% endhint %}
The database file is called `data.mdb` and is typically located in a subdirectory called `objectbox` (or any name you passed to BoxStoreBuilder). On Android, the DB file is located inside the app’s files directory inside `objectbox/objectbox/`. Or `objectbox/` if you assigned the custom name `` using BoxStoreBuilder.
## How does ObjectBox use disk space? And, can I reclaim disk space?
In most cases, ObjectBox uses disk space quite optimally. Only once you add more data, the database file grows as required. When you delete data, file areas are marked as unused internally and will be reused by ObjectBox. Note that re-using existing file areas is much more efficient than shrinking and growing the file. In practice, once used file storage will be used again in the future; especially considering that stored data has the tendency to get more over time.
ObjectBox relies on multi-version concurrency storage based on "copy on write". This allows e.g. to read the previous state while a write transaction is active. A counter-intuitive consequence is that deleting data can actually increase disk usage because the old data is still referenced. But of course, forthcoming transactions can reuse the internally reclaimed space.
{% hint style="info" %}
The storage layout on disk is optimized for performance. Database structures and concepts like B+ trees, multi-version concurrency and indexes use more space than storing data e.g. in a text file. Advantages like scalable data operations easily make up for it. Also keep in mind that in many cases data stored in a database is a small proportion compared to media files.
{% endhint %}
Non-standard use cases may require a temporary peak in data storage space that is followed by a permanent drop of storage space. To reclaim disk space for those cases, you need to delete the database files and restore them later; e.g. from the cloud or from a second store, which you set up to put the objects you want to keep.
{% hint style="warning" %}
Deleting the database files deletes the contained data permanently. If you want to restore old data, it's your responsibility to backup and restore.
{% endhint %}
While we don't recommend deleting the entire database, the API offers some methods to do so: first, `close()` the `BoxStore` and then delete the database files using `BoxStore.deleteAllFiles(objectBoxDirectory)`. To avoid having to close `BoxStore` delete files before building it, e.g. during app start-up.
```java
// If BoxStore is in use, close it first.
store.close();
BoxStore.deleteAllFiles(new File(BoxStoreBuilder.DEFAULT_NAME));
// TODO Build a new BoxStore instance.
```
{% hint style="info" %}
`BoxStore.removeAllObjects()` does not reclaim disk space. It keeps the allocated disk space so it returns fast and to avoid the performance hit of having to allocate the same disk space when data is put again.
{% endhint %}
## **Answers to other questions**
{% content-ref url="/pages/-LStL89QLKScKNmzP29c" %}
[Troubleshooting](/troubleshooting)
{% endcontent-ref %}
Questions that apply to all supported platforms and languages are answered in the [general ObjectBox FAQ](https://objectbox.io/faq/).
If you believe to have found a bug or missing feature, please create an issue.
For Java/Kotlin:
For Flutter/Dart:
If you have a usage question regarding ObjectBox, please post on Stack Overflow.
# Troubleshooting
Solutions for common issues with ObjectBox for Java and Dart
## **Unresolved reference: MyObjectBox (class not found, etc.)**
MyObjectBox is a generated class, so make sure the project builds successfully. Resolve any other build errors.
Check that the [project is configured correctly](/getting-started#adding-objectbox-to-your-android-project). E.g. for Kotlin, check that the kapt plugin is applied (`apply plugin: 'kotlin-kapt'`) before the ObjectBox plugin.
`android-apt` is known to cause problems, try to remove it.
## **Merge conflict or** DbSchemaException **after concurrent data model modifications**
If your team makes concurrent modifications to the data model (e.g. adding/removing entities or properties) it may clash with your changes. Read the [meta model docs](/advanced/meta-model-ids-and-uids#resolving-meta-model-conflicts) on how to resolve the conflicts.
## DbSchemaException: incoming ID does not match existing UID
Creating a Store throws a `DbSchemaException` and a message like
* Incoming *entity* ID does not match existing UID
* Incoming *property* ID does not match existing UID
* Incoming *index* ID does not match existing UID
This means there is a conflict between the data model defined in your code (using `@Entity` classes) and the data model of the existing database file.
For example for an entity, this message indicates the unique identifier (UID) of an entity is not the same as before. Entity UIDs are auto-assigned by ObjectBox and stored in `objectbox-models/default.json` for Java or `lib/objectbox-model.json` for Dart. Look for the `id` property which contains the UID in the second part, the first part is the ID (the format is `ID:UID`).
Read the [meta model docs](/advanced/meta-model-ids-and-uids#resolving-meta-model-conflicts) on why this can happen and how to resolve such conflicts.
## DbSchemaException **after switching git branch (no concurrent data model modifications)**
See below.
## DbSchemaException: DB's last ID is higher
Creating a Store throws a `DbSchemaException` and a message like
* DB's last *entity* ID is higher than from model
* DB's last *property* ID is higher than the incoming one
* DB's last *index* ID is higher than from model
* DB's last *relation* ID is higher than from model
This means, there is a conflict between the data model defined in your code (using `@Entity` classes) and the data model of the existing database file.
For example for an entity, this message indicates that the database already contains one or more entities with IDs higher than the lowest one of the model in your code. Entity IDs are auto-assigned by ObjectBox and stored in `objectbox-models/default.json` for Java or `lib/objectbox-model.json` for Dart. Look for the `lastEntityId` value, the highest used entity ID is contained in the first part, the second part is the UID (the format is `ID:UID`).
Read the [meta model docs](/advanced/meta-model-ids-and-uids#resolving-meta-model-conflicts) on why this can happen and how to resolve such conflicts.
## DbFullException: Could not put
This is thrown when applying a transaction (e.g. putting an object) would exceed the [maxSizeInKByte](https://objectbox.io/docfiles/java/current/io/objectbox/BoxStoreBuilder.html#maxSizeInKByte\(long\)) (Java)/[maxDBSizeInKB](https://pub.dev/documentation/objectbox/latest/objectbox/Store/Store.html) (Dart) configured for the store.
By default, this is 1 GB, which should be sufficient for most applications. In general, a maximum size prevents the database from growing indefinitely when something goes wrong (for example data is put in an infinite loop).
This value can be changed, so increased or also decreased, each time when opening a store:
{% tabs %}
{% tab title="Java" %}
```kotlin
MyObjectBox.builder()
.androidContext(context)
.maxSizeInKByte(1024 * 1024 /* 1 GB */)
.build()
```
{% endtab %}
{% tab title="Dart" %}
```dart
Store(getObjectBoxModel(), maxDBSizeInKB: 1024 * 1024 /* 1 GB */);
```
{% endtab %}
{% endtabs %}
## **Couldn’t find “libobjectbox.so”**
This can have various reasons. In general **check your ABI filter setup** [or add one](https://google.github.io/android-gradle-dsl/current/com.android.build.gradle.internal.dsl.NdkOptions.html#com.android.build.gradle.internal.dsl.NdkOptions:abiFilters) in your Gradle build file.
If your app explicitly **ships code for "armeabi"**: For Android, ObjectBox comes with binaries for “armeabi-v7a” and “arm64-v8a” ABIs. We consider “armeabi” to be outdated and thus do not support it. Check if you have a Gradle config like abiFilters "armeabi", which is causing the problem (e.g. remove it or change it to “armeabi-v7a”).
If your app uses **split APKs or App Bundle**: some users might have sideloaded your APK that includes the library for a platform that is incompatible with the one of their device. See [App Bundle, split APKs and Multidex](/android/app-bundle-and-split-apk) for workarounds.
## **Version conflict with ‘com.google.code.findbugs:jsr305’**
If you are doing Android instrumentation (especially with Espresso), you may get a warning like this:\
`Error:Conflict with dependency ‘com.google.code.findbugs:jsr305’ in project ‘:app’. Resolved versions for app (3.0.2) and test app (2.0.1) differ. See` [`http://g.co/androidstudio/app-test-app-conflict`](http://g.co/androidstudio/app-test-app-conflict) `for details.`
You can easily resolve the version conflict by adding this Gradle dependency: `androidTestCompile 'com.google.code.findbugs:jsr305:3.0.2'`
[Background info](https://github.com/objectbox/objectbox-java/issues/73).
## **Incompatible property type**
Check the[ data model migration guide](https://docs.objectbox.io/advanced/data-model-updates) if you get an exception like:\
`io.objectbox.exception.DbException: Property […] is not compatible to its previous definition. Check its type.`
or
`Cannot change the following flags for Property`
## Flutter iOS builds for armv7 fail with "ObjectBox does not contain that architecture"
[Only 64-bit iOS devices are supported.](/faq#on-which-platforms-does-objectbox-run) To resolve the build error, configure Architectures in your Xcode project like described in [Getting Started](/getting-started) for Flutter.
## **Error Codes**
Sometimes you might get an error code along with a error message. Typically, you will find error codes in parenthesis. Example:
`Could not prepare directory: objectbox (30)`
This error code comes from the OS, and gives you additional information; e.g. 30 tells that you tried to init a database in a read-only location of the file system, which cannot work.
Here's the list of typical OS errors:
| Error code | Errno | Description |
| :--------: | ------- | ----------------------------------- |
| 1 | EPERM | Operation not permitted |
| 2 | ENOENT | No such file or directory |
| 3 | ESRCH | No such process |
| 4 | EINTR | Interrupted system call |
| 5 | EIO | I/O error |
| 6 | ENXIO | No such device or address |
| 7 | E2BIG | Argument list too long |
| 8 | ENOEXEC | Exec format error |
| 9 | EBADF | Bad file number |
| 10 | ECHILD | No child processes |
| 11 | EAGAIN | Try again |
| 12 | ENOMEM | Out of memory |
| 13 | EACCES | Permission denied |
| 14 | EFAULT | Bad address |
| 15 | ENOTBLK | Block device required |
| 16 | EBUSY | Device or resource busy |
| 17 | EEXIST | File exists |
| 18 | EXDEV | Cross-device link |
| 19 | ENODEV | No such device |
| 20 | ENOTDIR | Not a directory |
| 21 | EISDIR | Is a directory |
| 22 | EINVAL | Invalid argument |
| 23 | ENFILE | File table overflow |
| 24 | EMFILE | Too many open files |
| 25 | ENOTTY | Not a typewriter |
| 26 | ETXTBSY | Text file busy |
| 27 | EFBIG | File too large |
| 28 | ENOSPC | No space left on device |
| 29 | ESPIPE | Illegal seek |
| 30 | EROFS | Read-only file system |
| 31 | EMLINK | Too many links |
| 32 | EPIPE | Broken pipe |
| 33 | EDOM | Math argument out of domain of func |
| 34 | ERANGE | Math result not representable |
## **Help with other issues**
{% content-ref url="/pages/-LSagCKqcUJYSop2Sfxf" %}
[FAQ](/faq)
{% endcontent-ref %}
If you believe to have found a bug or missing feature, please create an issue.
For Java/Kotlin:
For Flutter/Dart:
If you have a usage question regarding ObjectBox, please post on Stack Overflow.
# Java Release History (<= v1.5)
Release notes for ObjectBox 1.5.0 and older.
Although this is technically the changelog for Java, this is also a good reference of what changed in the ObjectBox C++ core.
### 4.0.2 - 2024-08-20
* Add convenience `oneOf` and `notOneOf` conditions that accept `Date` to avoid manual conversion using `getTime()`.
* When `BoxStore` is closing, briefly wait on active transactions to finish.
* Guard against crashes when `BoxStore` was closed, but database operations do still occur concurrently (transactions are still active).
### 4.0.1 - 2024-06-03
* Examples: added [Vector Search example](https://github.com/objectbox/objectbox-examples/tree/main/java-main-vector-search) that demonstrates how to perform on-device [approximate nearest neighbor (ANN) search](https://docs.objectbox.io/on-device-vector-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](https://docs.objectbox.io/queries) instead.
* Update and expand documentation on `ToOne` and `ToMany`.
### 4.0.0 - Vector Search - 2024-05-16
**ObjectBox now supports** [**Vector Search**](https://docs.objectbox.io/ann-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:
```java
@Entity
public class City {
@HnswIndex(dimensions = 2)
float[] location;
}
```
Perform a nearest neighbor search using the new `nearestNeighbors(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:
```java
final float[] madrid = {40.416775F, -3.703790F};
final Query 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](https://docs.objectbox.io/ann-vector-search).
* BoxStore: deprecated `BoxStore.sizeOnDisk()`. Instead use one of the new APIs to determine the size of a database:
* `BoxStore.getDbSize()` which for a file-based database returns the file size and for an in-memory database returns the approximately used memory,
* `BoxStore.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](https://github.com/objectbox/objectbox-java-generator) has changed to the GNU Affero General Public License (AGPL).
### V3.8.0 - 2024-02-13
* Support creating file-less in-memory databases, e.g. for caching and testing. To create one use `inMemory()` when building a `BoxStore`:
```java
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 [Custom types](/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.
### V3.7.1 - 2023/11/07
* Throw an exception instead of crashing when trying to create a query on a closed store. [#1154](https://github.com/objectbox/objectbox-java/issues/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.
### V3.7.0 - 2023/08/22
* 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](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-dart/issues/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](https://github.com/objectbox/objectbox-dart/issues/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.
### V3.6.0 - 2023/05/16
* **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:
```java
@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 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.:
```java
@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](https://sync.objectbox.io/sync-client#objectbox-sync-enabled-library)).
### V3.5.1 - 2023/01/31
* Fixes writes failing with "error code -30786", which may occur in some corner cases on some devices. [#1099](https://github.com/objectbox/objectbox-java/issues/1099)
* Add docs to `DbSchemaException` on how to resolve its typical causes.
### V3.5.0 - 2022/12/05
**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](https://docs.objectbox.io/queries#reusing-queries-and-parameters). [#1071](https://github.com/objectbox/objectbox-java/issues/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](https://docs.objectbox.io/queries#propertyquery). E.g. `query.property(Order_.customerId)` will map results to the ID of the customer of an order. [#1028](https://github.com/objectbox/objectbox-java/issues/1028)
* Add docs on `DbFullException` about [why it occurs and how to handle it](https://docs.objectbox.io/troubleshooting#dbfullexception-could-not-put).
* 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.
### V3.4.0 - 2022/10/18
* **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](https://github.com/objectbox/objectbox-java/issues/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.
### V3.3.1 - 2022/09/05
**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](https://github.com/objectbox/objectbox-java/issues/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.
**Using Sync?** There is no Sync version for this release, please continue using version 3.2.1.
### V3.2.1 - 2022/07/05
* 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](https://github.com/objectbox/objectbox-java/issues/1080)
* Plugin: support Kotlin 1.7. [#1085](https://github.com/objectbox/objectbox-java/issues/1085)
### V3.2.0 - 2022/06/20
* Query: throw `IllegalStateException` when query is closed instead of crashing the virtual machine. [#1081](https://github.com/objectbox/objectbox-java/issues/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.
### V3.1.3 - 2022/05/10
* **The Data Browser has been renamed to** [**ObjectBox Admin**](https://docs.objectbox.io/data-browser)**.** Deprecated `AndroidObjectBrowser`, use `Admin` instead. `AndroidObjectBrowser` will be removed in a future release.
* 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`).
### V3.1.2 - 2022/02/21
This release only contains bug fixes for the Android library when used with ObjectBox for Dart/Flutter.
### V3.1.1 - 2022/01/26
* 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`).
### V3.1.0 - 2021/12/15
[Read the blog post with more details](https://objectbox.io/objectbox-java-database-flex-type/) and code examples for the new flex properties and query conditions.
* [**Support Flex properties**](/advanced/custom-types#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" 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.
* **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.
* 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.
### V3.0.0 - 2021/10/19
{% hint style="info" %}
**2021/10/19: Released version 3.0.1**, which contains a fix for Android Java projects.
{% endhint %}
* [**A new Query API**](https://docs.objectbox.io/queries#new-query-api) is available that works similar to the [ObjectBox for Dart/Flutter](https://pub.dev/packages/objectbox) Query API and makes it **easier to create nested conditions**. #201
```kotlin
// 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`](https://objectbox.io/docfiles/java/current/io/objectbox/query/QueryBuilder.StringOrder.html) for which one to choose (typically `StringOrder.CASE_INSENSITIVE`).
```kotlin
// Replace String conditions like
query().equal(User_.firstName, "Joe")
// With the one accepting a StringOrder
query().equal(User_.firstName, "Joe", StringOrder.CASE_INSENSITIVE)
```
* **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
```kotlin
@Entity
data class Example(
@Id
var id: Long = 0,
@Unique(onConflict = ConflictStrategy.REPLACE)
var uniqueKey: String? = null
)
```
* Support [`@Unsigned`](https://objectbox.io/docfiles/java/current/io/objectbox/annotation/Unsigned.html) 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 for compatibility with other ObjectBox language bindings:
```kotlin
@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`.** #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`) **and lists** (Java `List` and Kotlin `MutableList`). Using the new `containsElement("item")` condition, it is also possible to query for entities where "item" is equal to one of the elements.
```kotlin
@Entity
data class Example(
@Id
var id: Long = 0,
var stringArray: Array? = null,
var stringMap: MutableMap? = null
)
// matches [“first”, “second”, “third”]
box.query(Example_.stringArray.containsElement(“second”)).build()
```
* **String maps** (Java `Map` or Kotlin `MutableMap`). 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](/queries#new-query-api) provides support for nested AND and OR conditions. [#201](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-java/issues/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](https://docs.objectbox.io/entity-annotations#object-ids-id).
* Support annotating a single property with `@Unique(onConflict = ConflictStrategy.REPLACE)` to replace an existing Object if a conflict occurs when doing a put. [#509](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-java/issues/894)
* Kotlin: add Flow extension functions for BoxStore and Query. [#900](https://github.com/objectbox/objectbox-java/pull/990)
* Data browser: display query results if a property has a NaN value. [#984](https://github.com/objectbox/objectbox-java/issues/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`). 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` or Kotlin `MutableMap`). 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:
```
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`.
### 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](https://github.com/objectbox/objectbox-java/issues/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](https://docs.objectbox.io/java-desktop-apps#add-libraries-for-distribution).
* Resolve rare `ClassNotFoundException: kotlin.text.Charsets` when running processor. [#946](https://github.com/objectbox/objectbox-java/issues/946)
* Ensure Query setParameters works if running the x86 library on x64 devices (which could happen if ABI filters were set up incorrectly). [#927](https://github.com/objectbox/objectbox-java/issues/927)
### V2.8.1 - 2020/11/10
* Minor improvements to [Sync](https://objectbox.io/sync/) tooling.
See the 2.8.0 release notes below for the latest changes.
### **V2.8.0 - 2020/11/05**
* Added [Sync](https://objectbox.io/sync/) API.
* Fixed "illegal reflective access" warning in the plugin.
* The data browser notification is now silent by default, for quieter testing. [#903](https://github.com/objectbox/objectbox-java/issues/903)
* Updated and improved API documentation in various places (e.g. on how `Query.findLazy()` and `Query.findLazyCached()` work with `LazyList` [#906](https://github.com/objectbox/objectbox-java/issues/906)).
* Print full name and link to element for `@Index` and `@Id` errors. [#902](https://github.com/objectbox/objectbox-java/issues/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 for`BoxStore` 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](https://github.com/objectbox/objectbox-java/issues/857)
* Fixes for one-to-many relations, e.g. allow removing both entity classes of a one-to-many relation. [GitHub #859](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-java/issues/157)
* [**RxJava 3 support library**](https://github.com/objectbox/objectbox-java/tree/master/objectbox-rxjava3) `objectbox-rxjava3`. Also includes Kotlin extension functions to more easily obtain Rx types, e.g. use `query.observable()` to get an `Observable`. [GH#83](https://github.com/objectbox/objectbox-java/issues/839)
* The annotation processor is incremental by default. [GH#620](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-java/issues/834)
* Turn on incremental annotation processing by default. [GH#620](https://github.com/objectbox/objectbox-java/issues/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](https://docs.objectbox.io/entity-annotations#object-ids-id).
* 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](/queries#new-query-api). See [the documentation](/queries#new-query-api) for examples.
* The old Query API now also supports setting an alias after combining conditions using `and()` or `or()`. [GH#834](https://github.com/objectbox/objectbox-java/issues/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](https://docs.objectbox.io/entity-annotations#object-ids-id).
* Java's `String[]` and Kotlin's `Array` 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](https://github.com/objectbox/objectbox-java/tree/release-3.0.0-alpha2/objectbox-rxjava3), `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](https://github.com/objectbox/objectbox-java/issues/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.
```groovy
buildscript {
dependencies {
classpath "io.objectbox:objectbox-gradle-plugin:3.0.0-alpha2"
}
}
dependencies {
// Artifacts with native code remain at 2.5.1.
implementation "io.objectbox:objectbox-android:2.5.1"
}
```
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](/queries#new-query-api) provides support for nested AND and OR conditions. See [the documentation](/queries#new-query-api) for examples and notable changes. [GH#201](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-java/issues/793)
* Turn on incremental annotation processing by default. [GH#620](https://github.com/objectbox/objectbox-java/issues/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`.
```groovy
buildscript {
dependencies {
classpath "io.objectbox:objectbox-gradle-plugin:3.0.0-alpha1"
}
}
dependencies {
implementation "io.objectbox:objectbox-java:3.0.0-alpha1"
// Artifacts with native code remain at 2.5.1.
implementation "io.objectbox:objectbox-android:2.5.1"
}
```
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](https://github.com/objectbox/objectbox-java/issues/817)
* Support for incremental annotation processing. [GH#620](https://github.com/objectbox/objectbox-java/issues/620) It is off by default. To turn it on set `objectbox.incremental` to `true` in `build.gradle` :
```groovy
android {
defaultConfig {
javaCompileOptions {
annotationProcessorOptions {
arguments = [ "objectbox.incremental" : "true" ]
}
}
}
}
```
### **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](/android/livedata-architecture-components) and [Paging integration](/android/paging-architecture-components) 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](https://developer.android.com/jetpack/androidx/migrate).
* 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](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-java/issues/490)
* Resolved issue to enable query conditions on the target ID property of a ToOne relation. [GH#537](https://github.com/objectbox/objectbox-java/issues/537)
* Box.getAll always returns a mutable list. [GH#685](https://github.com/objectbox/objectbox-java/pull/685)
* Do not overwrite existing objectbox-java or objectbox-kotlin dependency. [GH#693](https://github.com/objectbox/objectbox-java/issues/693)
* Resolved a corner case build time crash when parsing package elements. [GH#698](https://github.com/objectbox/objectbox-java/issues/698)
* When trying to find an appropriate get-method for a property, also check if the return type matches the property type. [GH#720](https://github.com/objectbox/objectbox-java/issues/720)
* Explicitly display an error if two entities with the same name are detected. [GH#744](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-java/issues/750)
* Query: improved performance for ordered results with a limit. [GH#769](https://github.com/objectbox/objectbox-java/issues/769)
* Query: throw if a filter is used incorrectly with count or remove. [GH#771](https://github.com/objectbox/objectbox-java/issues/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](https://github.com/objectbox/objectbox-c) 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](/entity-annotations#index-types-string) 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](/entity-annotations#unique-constraints)
* Support for char type (16 bit)
* [RX lib](/data-observers-and-rx#objectbox-rxjava-extension-library) 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](/queries#aggregating-values): 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](/queries#add-query-conditions-for-related-entities-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](/relations#access-many-to-many-in-the-reverse-direction): 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](/android/paging-architecture-components) (architecture components)
* [Kotlin extensions](/kotlin-support#using-the-provided-extension-functions): more Kotlin fun with ObjectBox KTX
* [Query parameters aliases](/queries#reusing-queries-and-parameters): 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.0** – 2018/04/17
#### New Features/Improvements
* Full support for [Android local tests](/android/android-local-unit-tests): use full ObjectBox features in local tests
* New count method optimized for a given maximum count
* Gradle option to [define the package for MyObjectBox](/advanced/advanced-setup#change-the-myobjectbox-package) explicitly
* Query condition startsWith now uses index if available for better performance
#### Fixes
* Fixed some static methods in BoxStore to ensure that the native lib is loaded
* Internal optimizations for 64 bit devices
* Some fixes for entities in the default package
* Entity can be named `Property`, no longer conflicts with ObjectBox Property class
* Property queries for strings crashed on some Android devices if there were more than 512 results
* Object Browser uses less threads
* Object Browser now displays negative int/long values correctly
* Changes to relations object in constructors were overwritten when constructors delegated to other constructors
### **V1.4.4** – 2018/03/08
#### New Features/Improvements
* Supply an initial database file using BoxStoreBuilder
* Gradle plugin detects [plain Java projects](/java-desktop-apps#objectbox-embedded-database-for-java-desktop-apps) and configures dependencies
* Improved Box.removeAll() performance for entities that have indexes or relations
#### Fixes
* Fixed converting from arrays in entities
* Fixed @NameInDb
* Fixed Gradle “androidTestCompile is obsolete” warning
### **V1.4.3** – 2018/03/01
#### New Features
* macOS support: with Linux, Windows, and macOS, ObjectBox now supports all major desktop/server platforms. Use it for local unit tests or standalone Java applications.
#### Fixes
* Fixed BoxStore.close being stuck in rare scenarios
* Fixed an issue with char properties in entities
### **V1.4.2** – 2018/02/25
**Note: This release requires the** [**Android Gradle Plugin 3.0.0**](https://developer.android.com/studio/releases/gradle-plugin.html#3-0-0) **or higher.**
#### Improvements
* JCenter: we’ve moved the ObjectBox artifacts to the JCenter repository. This simplifies set up and improves accessibility (e.g. JCenter is not blocked from China).
* Instant App support (only with Android Gradle Plugin 3.0.0 or higher)
### **V1.4.1** – 2018/01/23
#### Improvements
* Added DbExceptionListener as a central place to listen for DB related exceptions
* Minor improvements for ToMany and generated Cursor classes
#### Fixes
* ToMany: fixed handling of duplicate entries (e.g. fixes swap and reverse operations)
* ToMany: fixed removal of non-persisted element for standalone relations
### **V1.4.0** – 2018/01/11
#### New Features
* Property queries that return individual properties only (including distinct values, unique, null values, primitive result arrays or scalars)
* Entity inheritance (non-polymorphic)
* 50% size reduction of native libraries
### **V1.3.4** – 2017/12/07
#### Improvements
* ToOne now implements equals() and hashCode() based on the targetId property
* Android ABI x86\_64 was added to the aar
#### Fixes
* ID verification does not complain about “resurrected” objects that were loaded, removed, and put again
* Fixed setting Query parameters for Date type
* Fixes for ObjectBox browser
### **V1.3.3 (1.3.x)** – 2017/12/04
Please update to the latest version. We made important changes and fixes under the hood to make ObjectBox perform better, generally, and especially in concurrent scenarios. In addition, 1.3.x comes with several improvements for developers.
#### Improvements
* [Flag for query parameter logging](http://objectbox.io/files/objectbox-java/current/io/objectbox/DebugFlags.html)
* Object browser lets you download all entities as JSON
* Object browser efficiency improvements: introduced streamed processing to reduce memory consumption and increase performance for large data sets
* Improved transaction logging, e.g. numbered transactions and waiting times for write transactions
* Closing the store (e.g. for tests, an app should just leave it open) will wait for any ongoing write transaction to finish
* Two additional [overloads for static BoxStore.deleteAllFiles()](http://objectbox.io/files/objectbox-java/current/io/objectbox/BoxStore.html#deleteAllFiles-java.io.File-)
* Added automatic retries for read transactions; also configurable for queries
#### Fixes
* Fixes for concurrent setups (multi threaded, in live apps with up to 100 threads); internally we improved our testing automation and CI infrastructure significantly
* Fix for sumDouble throwing an exception
* Fixed ProGuard rule for ToOne
### **V1.2.1** – 2017/11/10
#### Improvements
* Improved debug logging for transactions and queries: enable this using BoxStoreBuilder.debugFlags(…) with values from the [DebugFlags](http://objectbox.io/files/objectbox-java/current/io/objectbox/DebugFlags.html) class
* Improved package selection for MyObjectBox if you use entities in multiple packages (please check if you need to adjust your imports after the update)
* ObjectBox Browser’s UI is more compact and thus better usable on mobile devices
#### Fixes
* Fix for ObjectBoxLiveData firing twice
### **V1.2.0** – 2017/10/31
Compatibility note: We removed some Box.find methods, which were all tagged as @Temporary. Only the Property based ones remain (for now, also @Temporary).
#### New Features
* [ObjectBoxLiveData](/android/livedata-architecture-components#objectbox-livedata-with-android-architecture-components): Implements LiveData from Android Architecture Components
* Object ID based methods for [ToMany](http://objectbox.io/files/objectbox-java/current/io/objectbox/relation/ToMany.html): getById, indexOfId, removeById
* More robust Android app directory detection that works around Android bugs
* Using the new official FlatBuffers Maven dependency (FlatBuffer is not anymore embedded in the artifact)
* UI improvements for ObjectBox browser
* Other minor improvements
#### Fixes
* Fixed query order by float and double
* Fixed an missing import if to-many relations referenced a entity in another package
* Other minor fixes
### **V1.1.0** – 2017/10/03
#### New Features
* Object Browser to view DB contents (Android)
* Plain Java support to run ObjectBox on Windows and Linux
* Added ToMany.hasA()/hasAll() to simplify query filters in Java
* Sort query result via Comparator
* Improved error messages on build errors
* Internal clean up, dropping legacy plugin
#### Fixes
* Annotation processor detects boolean getters starting with “is”
* Fixed a NPE with eager and findFirst() when there is no result
### **V1.0.1** – 2017/09/10
First bug fix release for [ObjectBox 1.0](http://objectbox.io/objectbox-1-0/).
#### New Features
* ToMany allows setting a Comparator to order the List (experimental)
#### Fixes
* Fix UID assignment process: use @Uid without value to see options (pin UID, reset/change)
* Fix relation code generation for entities in different packages
* Fix Kotlin extension functions in transformed (library) project
* Fix ToOne access if field is inaccessible (e.g. in Kotlin data classes if they are part of constructor – lateinit were OK)
### **V1.0.0** – 2017/09/04
ObjectBox is out of beta! See our [announcement blog post](http://objectbox.io/objectbox-1-0/) for details.
#### New Features
* Eager loading of relations via query builder
* Java filters as query post-processing
* Minor improvements like a new callInReadTx method and making Query.forEach breakable
#### Fixes
* Fixed two corner cases with queries
### V0.9.15 (beta) 2017/08/21 Hotfixes
#### Fixes
* Fixed: Android flavors in caused the model file (default.json) to be written into the wrong folder (inside the build folder) causing the build to fail
* Fixed: failed builds if entity constructor parameters are of specific types
### V0.9.14 (beta) 2017/08/14 Standalone relations, new build tools
For upgrade notes, please check the [announcement post](http://objectbox.io/objectbox-db-0-9-14/).
#### New Features
* No more in-place code generation: Java source code is all yours now. This is based on the new build tool chain introduced in 0.9.13. Thus Kotlin and Java share the same build system. The old Java-based plugin is still available (plugin ID “io.objectbox.legacy”) in this version.
* “Standalone” to-many relations (without backing to-one properties/relations)
* Gradle plugin tries to automatically add runtime dependencies (also (k)apt, but this does not always work!?)
* Improved error reporting
#### Fixes
* Fixed the issue causing a “Illegal state: Tx destroyed/inactive, writeable cursor still available” error log
### V0.9.13 (beta) 2017/07/12 Kotlin Support
#### New Features
* Kotlin support (based on a new annotation processor)
* Started “object-kotlin”, a sub-project for Kotlin extensions (tiny yet, let us know your ideas!)
* BoxStoreBuilder: added maxReaders configuration
* Get multiple entities by their IDs via Box methods (see get/getMap(Iterable))
* ToOne and ToMany are now serializable (which does not imply serializing is a good idea)
* ObjectBox may now opt to construct entities using the no-args constructor if the all-args constructor is absent
* Prevents opening two BoxStores for the same DB file, which may have side effects that are hard to debug
* Various minor and internal improvements and fixes
#### Fixes
* Fixed ToOne without an explicit target ID property
* Fixed type check of properties to allow ToMany (instead of List)
* Fixed @Convert in combination with List
* Fixed a race condition with cursor deletion when Java’s finalizer kicked in potentially resulting in a SIGSEGV
* Fixed a leak with potentially occurring with indexes
### V0.9.12 (beta) 2017/05/08 ToMany class
* **Update 2017/05/19:** We just released 0.9.12.1 for the Gradle plugin (only), which fixes two problems with parsing of to-many relations.
* Added the new list type ToMany which represents a to-many relation. A ToMany object will be automatically assigned to List types in the entity, eliminating a lot of generated code in the entity.
* ToMany comes with change tracking: all changes (add/remove) are automatically applied to the DB when its hosting entity is persisted via put(). Thus, the list content is synced to the DB, e.g. their relationship status is updated and new entities are put.
* Streamlined annotations (breaking API changes):\
@Generated(hash = 123) becomes @Generated(123),\
@Property was removed,\
@NameInDb replaces attributes in @Entity and the former @Property,\
Backlinking to-many relations require @Backlink (only),\
@Relation is now only used for to-one relations (and is subject to change in the next version)
### V0.9.11 (beta) 2017/04/25: Various improvements
* Smarter to-one relations: if you put a new object that also has a new to-one relation object, the latter will also be put automatically.
* Getters and setters for properties are now only generated if no direct field access is possible
* JSR-305 annotations (@Nullable and others) to help the IDE find problems in your code
* @Uid(-1) will reassign IDs to simplify some migrations (docs will follow soon)
* No more getter for ToOne objects in favor of direct field access
* Quite a few internal improvements (evolved EntityInfo meta info object, etc.)
### V0.9.10 (beta) 2017/04/10: Bug Fixes and minor improvements
#### New features and improvements
* Breaking API: Replaced “uid” attribute of @Entity and @Property with @Uid annotation
* An empty @Uid will retrieve the current UID automatically
* Some minor efficency improvements for read transactions
* Better DB resources clean up for internal thread pool
#### Bug fixes
* Better compatibility with Android Gradle plugin
* Fixes for multithreaded reads of relation and index data
* Fixed compilation error in generated sources for Entities without non-ID properties
### V0.9.9 (beta) 2017/03/07: Bug Fixes
#### New features
* Query.forEach() to iterate efficiently over query result objects
#### Bug fixes
* Various bug fixes
### V0.9.8 (beta) 2017/02/22: Going Reactive
#### New features
* Data observers with reactive extensions for transformations, thread scheduling, etc.
* Optional RxJava 2 library
* OR conditions for QueryBuilder allow more powerful queries
#### Bug fixes
* Fixed: Changing the order of an entity’s properties could cause errors in some cases
* Fixed: Querying using relation IDs
### V0.9.7 (beta) 2017/02/10
#### New features
* LazyList returned by Query: another query option to defer getting actual objects until actually accessing them. This enables memory efficient iterations over large results. Also minimizes the time for a query to return. Note: LazyList cannot be combined with order specifications just yet.
* QueryBuilder and Query now support Date and boolean types directly
* QueryBuilder supports now a notIn opperator
* put() now uses entity fields directly unless they are private (can be more efficient than calling getters)
#### Breaking internal changes
At this early point in the beta we decided to break backward compatibility. This allowed us to make important improvements without worrying about rather complex migrations of previous versions. We believe this was a special situation and future versions will likely be backward compatible although we cannot make promises. If you intend to publish an app with ObjectBox it’s a good idea to contact us before.
* The internal data format was optimized to store data more compact. Previous database files are not compatible and should be deleted.
* We improved some details how IDs are used in the meta model. This affects the model file, which is stored in your project directory (objectbox-models/default.json). Files created by previous versions should be deleted.
### V0.9.6 (first public beta release) 2017/01/24
See [ObjectBox Announcement](http://greenrobot.org/announcement/introducing-objectbox-beta/)