ObjectBox - Database Persistence with Entity Annotations

ObjectBox is a database that persists objects. For a clear distinction, we sometimes call those persistable objects entities. To let ObjectBox know which classes are entities you can either make them implement the ObjectBox.Entity protocol, or add annotations to them. Then ObjectBox can do its magic with your entities.

Here is an example:

// objectbox: Entity
class User {
    // objectbox: entityId
    var id: Id<User> = 0
​
    var name: String
​
    // objectbox: transient
    private var tempUsageCount: Int // not persisted
​
    // ...
}

The Entity annotation identifies the Swift class User as a persistable entity. This will trigger ObjectBox to generate persistence code tailored for this class, even if it does not conform to the Entity protocol..

Object IDs: objectId

In ObjectBox, every object has an ID of type Id<> to efficiently get or reference objects. Usually ObjectBox will just find that property in your entity based on its type and "do the right thing", but if you have several properties of the same Id<> type, you can use an annotation to mark a particular property as the ID of your entity:

class User: Entity {
​
    // objectbox: objectId
    var id: Id<User> = 0
​
    // ...
}

Basic annotations for entity properties

class User: Entity {
​
    // objectbox: nameInDb = "USERNAME"
    var name: String
​
    // objectbox: transient
    var tempUsageCount: Int
​
    ...
}

The nameInDb annotation lets you define a name on the database level for a property. This allows you to rename the Swift field without affecting the property name on the database level.

The transient annotation marks properties that should not be persisted, like the temporary counter above. As far as ObjectBox is concerned, transient properties simply do not exist. static properties are always ignored by ObjectBox and do not need to be marked as transient.

Property Indexes with Index

Annotate a property with // objectbox: index to create a database index for the corresponding database column. This can improve performance when querying for that property.

// objectbox: index
var name: String

An index stores additional information in the database to make look ups faster. As an analogy we could look at how you store objects in an Array<>. For example you could store persons using an Array<Person>. Now, you want to search for all persons with a specific name so you would iterate through the list and check for the name property of each object. This is an O(N) operation and thus does don't scale well with an increasing number of objects.

To make this more scalable you can introduce a second data structure Dictionary<String, Person> with the name as a key. This will give you a constant lookup time (O(1)). The downside of this is that it needs more resources (here: RAM) and slows down add/remove operations on the list a bit. These principles can be transferred to database indexes, just that the primary resource consumed is disk space.

Index types (String)

Because String properties typicall typically take more space than scalar values, ObjectBox uses a hash for indexing strings by default. For any other type, the property value is used for all index look-ups.

You can instruct ObjectBox to use a value-based index for a String property by specifying an index type:

// objectbox: index = value 
var name: String

Keep in mind that for String, depending on the length of your values, a value-based index may require more storage space than the default hash-based index.

ObjectBox supports these index types:

• Not specified Uses best index based on property type (hash for String, value for others).

• value Uses property values to build index. For String, this may require more storage than a hash-based index.

• hash Uses 32-bit hashes of property values to build the index. Occasional collisions may occur which should not have any performance impact in practice. Usually a better choice than hash64, as it requires less storage.

• hash64 Uses 64-bit hashes of property values to build the index. Requires more storage than hash and thus should not be the first choice in most cases.

Unique constraints

Annotate a property with unique to enforce that values are unique before an entity is put:

// objectbox: unique
var name: String

A put() operation will abort and throw an OBXErrorUniqueViolation error:

try {
    box.put(User("Sam Flynn"))
} catch let error as OBXErrorUniqueViolation {
    // A user with that name already exists.
}

Relations

Creating to-one and to-many relations between objects is possible as well, see the Relations documentation for details.

Triggering generation

You usually should not need to do anything special to trigger code generation once your entity classes are properly annotated. The setup.rb script should have automatically configured your project to run the code generator when you compile your project, for example using Product > Build in Xcode.