Mobile Database Archives

ObjectBox Database Java 3.1 – Flex type

by Anna | Dec 20, 2021 | Android, Mobile Database, ObjectBox, Release | 0 comments

We are happy to announce version 3.1 of ObjectBox for Java and Kotlin. The major feature of this version is the new Flex type. For a long time, ObjectBox worked on rigid data schemas, and we think that this is a good thing. Knowing what your data looks like is a feature – similar to programming languages that are statically typed. Fixed schemas make data handling more predictable and robust. Nevertheless, sometimes there are use cases which require flexible data structures. ObjectBox 3.1 allows exactly this.

Flex properties

Expanding on the string and flexible map support in 3.0.0, this release adds support for Flex properties where the type must not be known at compile time. To add a Flex property to an entity use Object in Java and Any? in Kotlin. Then at runtime store any of the supported types.

For example, assume a customer entity with a tag property:

// Java
@Entity
public class Customer {

    @Id
    private long id;
    private Object tag;

    // TODO getter and setter
}

// Kotlin
@Entity
data class Customer(
    @Id var id: Long = 0,
    var tag: Any? = null
)

// Java

@Entity

public class Customer {

@Id

private long id;

private Object tag;

// TODO getter and setter

}

// Kotlin

@Entity

data class Customer(

@Id var id: Long = 0,

var tag: Any? = null

)

Then set a String tag on one customer, and an Integer tag on another customer and just put them:

// Java
Customer customerStrTag = new Customer();
customerStrTag.setTag("string-tag");
Customer customerIntTag = new Customer();
customerIntTag.setTag(1234);
box.put(customerStrTag, customerIntTag);

// Kotlin
val customerStrTag = Customer(tag = "string-tag")
val customerIntTag = Customer(tag = 1234)
box.put(customerStrTag, customerIntTag)

// Java

Customer customerStrTag = new Customer();

customerStrTag.setTag("string-tag");

Customer customerIntTag = new Customer();

customerIntTag.setTag(1234);

box.put(customerStrTag, customerIntTag);

// Kotlin

val customerStrTag = Customer(tag = "string-tag")

val customerIntTag = Customer(tag = 1234)

box.put(customerStrTag, customerIntTag)

When getting the customer from its box the original type is restored. For simplicity the below example just casts the tag to the expected type:

// Java
String stringTag = (String) box.get(customerStrTag.getId()).getTag();
Integer intTag = (Integer) box.get(customerIntTag.getId()).getTag();

// Kotlin
val stringTag = box.get(customerStrTag.id).tag as String
val intTag = box.get(customerIntTag.id).tag as Int

// Java

String stringTag = (String) box.get(customerStrTag.getId()).getTag();

Integer intTag = (Integer) box.get(customerIntTag.getId()).getTag();

// Kotlin

val stringTag = box.get(customerStrTag.id).tag as String

val intTag = box.get(customerIntTag.id).tag as Int

A Flex property can be not justString or Integer. Supported types are all integers (Byte, Short, Integer, Long), floating point numbers (Float, Double), String and byte arrays.

It can also hold a List<Object> or a Map<String, Object> of those types. Lists and maps can be nested.

Behind the scenes Flex properties use a FlexBuffer converter to store the property value, so some limitations apply. See the FlexObjectConverter class documentation for details.

Query for map keys and values

If the Flex property contains integers or strings, or a list or map of those types, it’s also possible to do queries. For example, take this customer entity with a properties String to String map:

// Java
@Entity
public class Customer {

    @Id
    private long id;
    private Map<String, String> properties;

    // TODO getter and setter
}

// Kotlin
@Entity
data class Customer(
    @Id var id: Long = 0,
    var properties: MutableMap<String, String>? = null
)

// Java

@Entity

public class Customer {

@Id

private long id;

private Map<String, String> properties;

// TODO getter and setter

}

// Kotlin

@Entity

data class Customer(

@Id var id: Long = 0,

var properties: MutableMap<String, String>? = null

)

Why is properties not of type Object? ObjectBox supports using Map<String, String> (or Map<String, Object>) directly and will still create a Flex property behind the scenes.

Then put a customer with a premium property:

// Java
Customer customer = new Customer();
Map<String, String> properties = new HashMap<>();
properties.put("premium", "tier-1");
customer.setProperties(properties);
box.put(customer);

// Kotlin
val customer = Customer(
    properties = mutableMapOf("premium" to "tier-1")
)
box.put(customer)

// Java

Customer customer = new Customer();

Map<String, String> properties = new HashMap<>();

properties.put("premium", "tier-1");

customer.setProperties(properties);

box.put(customer);

// Kotlin

val customer = Customer(

properties = mutableMapOf("premium" to "tier-1")

)

box.put(customer)

To query for any customers that have a premium key in their properties map, use the containsElement condition:

// Java
Query<customer> queryPremiumAll = box.query(
        Customer_.properties.containsElement("premium")
).build();

// Kotlin
val queryPremiumAll = box.query(
    Customer_.properties.containsElement("premium")
).build()
</customer>

// Java

Query<customer> queryPremiumAll = box.query(

Customer_.properties.containsElement("premium")

).build();

// Kotlin

val queryPremiumAll = box.query(

Customer_.properties.containsElement("premium")

).build()

</customer>

Or to only match customers where the map key has a specific value, here a specific premium tier, use the containsKeyValue condition:

// Java
Query<customer> queryPremiumTier1 = box.query(
        Customer_.properties.containsKeyValue("premium", "tier-1")
).build();

// Kotlin
val queryPremiumTier1 = box.query(
    Customer_.properties.containsKeyValue("premium", "tier-1")
).build()
</customer>

// Java

Query<customer> queryPremiumTier1 = box.query(

Customer_.properties.containsKeyValue("premium", "tier-1")

).build();

// Kotlin

val queryPremiumTier1 = box.query(

Customer_.properties.containsKeyValue("premium", "tier-1")

).build()

</customer>

What’s next?

ObjectBox database is free to use. Check out our docs and this video tutorial to get started today.

We strive to bring joy to mobile developers and appreciate all kinds feedback, both positive and negative. You can always raise an issue on GitHub or post a question on Stackoverflow. Otherwise, star the ObjectBox Java repository and up-vote the features you’d like to see in the next release.

Beginner C++ Database Tutorial: How to use ObjectBox

by Anna | Nov 24, 2021 | Edge Database, Mobile Database, ObjectBox, Tutorial

Introduction

As a direct follow up from the ObjectBox database installation tutorial, today we’ll code a simple C++ example app to show how the database can be used. Before starting to program, let’s briefly overview what we want to achieve with this tutorial and what is the best way to work through it.

Overview of the app we want to build

In short, we will make a console calculator app with an option to save results into memory. These will be stored as objects of the Number class. Every Number will also have an ID for easy reference in future calculations. Apart from the function to make calculations, we will create a function to enter memory. It will list all the database entries and have an option to clear memory. By coding all of this, we will make use of such standard ObjectBox operations as put, get, getAll and removeAll.

Our program will consist of seven files:

the FlatBuffers schema file, that defines the model of a class we want to store in the database
the header file, for class function definitions
the source file, for function implementation
the four files with objectbox binding code that will be created by objectbox-generator

How to use this tutorial

While looking at coding examples is useful in many cases, the best way to learn such a practical skill like programming is to solve problems independently. This is why we included an exercise for each step. You are encouraged to make the effort and do each of them, even if you don’t know the answer straight away. Only move to the next step after you test each part of your program and make sure that everything works as intended. Ideally, you should only use the code snippets presented here to check yourself or look for hints when you feel stuck. Bear in mind that sometimes there might be several different ways to achieve the same results. So if something that we ask you to do in this tutorial doesn’t work for you, try to come up with your own solution.

How to create the FlatBuffers file?

First, we’ll create the FlatBuffers schema (.fbs) for our app. This is required for the objectbox-generator to generate binding code that will allow us to use the ObjectBox library in our project.

The FlatBuffers schema consists of a table, which defines the object we want to store in the database, and the properties of this object. Each property consists of a name and a type. We want to keep our example very simple, so just two properties is enough.

To replicate a calculator’s memory, we want ObjectBox to store some numbers. We can define the Number object by giving the table a corresponding name.
Inside the table, we want to have two properties: id and contents. The contents of each Number object is the number itself (double), while id is an ulong that our program will assign to each of them for easy identification.

Exercise: create a file called numbers.fbs and define the table in the format

table Name {
    property_name: type;
}

table Name {

property_name: type;

}

Reveal code

table Number {
    id: ulong;
    contents: double;
}

table Number {

id: ulong;

contents: double;

}

Generating binding code

Now that the FlatBuffers file is ready, we can generate the binding code. To do this, run the objectbox-generator for our FlatBuffers file:

objectbox-generator -cpp numbers.fbs

1	objectbox-generator -cpp numbers.fbs

The following files will be generated:

objectbox-model.h
objectbox-model.json
numbers.obx.hpp
numbers.obx.cpp

The header file

This is where the main chunk of our code will be. It will contain the Calculator class and all the function definitions.

Start by including the three ObjectBox header files: objectbox.hpp, objectbox-model.h and numbers.obx.hpp. Our whole program will be based on one class, called Calculator. It should only have two private members: Store and Box. Store is a reference to the database and will manage Boxes. Each Box stores objects of a particular class. In this example, we only need one Box. Let’s call it numberBox, as it will store Numbers that we want to save in the memory of our calculator.

Exercise: create a file called calculator.hpp and define the Calculator class with two private members: reference to the obx library member Store and a Box of Numbers.

Reveal code

class Calculator {
    obx::Store& store;
    obx::Box<Number> numberBox;
}

class Calculator {

obx::Store& store;

obx::Box<Number> numberBox;

}

2. After the constructor, we define the run function. It will be responsible for the menu of our program. There should be two main options: to perform calculations and enter memory. As discussed above, we want this app to do two things: perform calculations and show memory. We’ll define these as separate functions, called Calculate and Memory. The first one is quite standard, so we won’t go into a detailed explanation here. The only thing you should keep in mind is that we need to account for the case when the user wants to operate on a memory item. To deal with this, we’ll process input in a function called processInput.

Exercise: define the parametrised constructor which takes a reference to Store as a parameter. Then define the run and Calculate functions.

Reveal code

public:
    Calculator(obx::Store& obxStore)
        : store(obxStore),
          numberBox(obxStore) {}
    int run(){
        std::string input;
        std::cout << "Welcome to the example calculator app." << std::endl;
        while(true) {
            std::cout << std::endl << "Available commands:" << std::endl
                      << "  calc - make a calculation;" << std::endl
                      << "  memory - see stored numbers;" << std::endl
                      << "  exit." << std::endl;
 
            std::getline(std::cin, input);
            if(input == "calc") {
                Calculate();
                continue;
            } else if(input == "memory") {
                Memory();
                continue;
            } else if(input == "exit") {
                std::exit(0);
            } else {
                std::cerr << "Unknown command." << std::endl;
                fflush(stderr);
                continue;
            }
        }
    }
    void Calculate() {
        std::string input;
        double x;
        double y;
        char op;
        double result;
 
        std::cout << "Enter an operation in the format x [+,-,*,/] y: ";
        while (std::getline(std::cin, input)) {
 
            if(input == "back"){ break;}
            bool valid = processInput(input, x, op, y);
            if(valid == false) { continue;}
 
            switch(op) {
                case '+':
                    result = x + y;
                    break;
                case '-':
                    result = x - y;
                    break;
                case '*':
                    result = x * y;
                    break;
                case '/':
                    result = x / y;
                    break;
            }
        }
    }
            std::cout << "Result: " << x << " " << op << " " << y << " = " << result << std::endl;

public:

Calculator(obx::Store& obxStore)

: store(obxStore),

numberBox(obxStore) {}

int run(){

std::string input;

std::cout << "Welcome to the example calculator app." << std::endl;

while(true) {

std::cout << std::endl << "Available commands:" << std::endl

<< " calc - make a calculation;" << std::endl

<< " memory - see stored numbers;" << std::endl

<< " exit." << std::endl;

std::getline(std::cin, input);

if(input == "calc") {

Calculate();

continue;

} else if(input == "memory") {

Memory();

continue;

} else if(input == "exit") {

std::exit(0);

} else {

std::cerr << "Unknown command." << std::endl;

fflush(stderr);

continue;

}

void Calculate() {

std::string input;

double x;

double y;

char op;

double result;

std::cout << "Enter an operation in the format x [+,-,*,/] y: ";

while (std::getline(std::cin, input)) {

if(input == "back"){ break;}

bool valid = processInput(input, x, op, y);

if(valid == false) { continue;}

switch(op) {

case '+':

result = x + y;

break;

case '-':

result = x - y;

break;

case '*':

result = x * y;

break;

case '/':

result = x / y;

break;

}

std::cout << "Result: " << x << " " << op << " " << y << " = " << result << std::endl;

3. The final part of this function is for saving results into memory. We start by asking the user if they want to do that. If the answer is positive, we create a new instance of Number and set the most recent result as a value of its contents. To save our object in the database, we can operate with put(object) on our Box. put is one of the standard ObjectBox operations, which is used for creating new objects and overwriting existing ones.

Exercise: create an option to store the result in memory, making use of the ObjectBox put operation.

Reveal code

std::cout << "Save this number [y/n]? ";
while(true){
    std::getline(std::cin, input);
    if(input == "y"){
        Number object{};
        object.contents = result;
        numberBox.put(object);
        std::cout << "New number in memory: " << object.contents << ", ID: " << object.id << std::endl;
        break;
    } else if (input == "n") {
        break;
    } else {
        std::cerr << "Unknown command. Try again: ";
        fflush(stderr);
        continue;
    }
}

std::cout << "Save this number [y/n]? ";

while(true){

std::getline(std::cin, input);

if(input == "y"){

Number object{};

object.contents = result;

numberBox.put(object);

std::cout << "New number in memory: " << object.contents << ", ID: " << object.id << std::endl;

break;

} else if (input == "n") {

break;

} else {

std::cerr << "Unknown command. Try again: ";

fflush(stderr);

continue;

}

4. Next, we should define processInput, which will read input as a string and check whether it has the right format. Now, to make it recognise the memory items, we have to come up with a standard format for these. Remember, we defined an ID property for our Numbers. Every number in our database has an ID, so we can refer to them as, e.g. m1, m2, m3 etc. To read the numbers from memory, we can make use of the get(obx_id) operation. It returns a unique pointer to the corresponding Number, whose contents we need to access and use as our operand.

Exercise: define the processInput function, which detects when something like m1 was used as an operand and updates x, y, and op according to the input.

Reveal code

bool processInput(const std::string& input, double& x, char& op, double& y) {
    std::vector<std::reference_wrapper<double>> outNumbers;
    outNumbers.push_back(x);
    outNumbers.push_back(y);

    std::vector<std::string> inputStrings;
    std::string strX;
    std::string strY;
    std::istringstream inputStream(input);
    inputStream.str(input);
    inputStream >> strX >> op >> strY;
    inputStrings.push_back(strX);
    inputStrings.push_back(strY);

    //Iterate over the two numbers from input, retrieving them from memory if needed
    for(int i = 0; i < 2; i++) {
        try {
            if(inputStrings[i][0] == 'm') {
                inputStrings[i] = inputStrings[i].substr(1);
                obx_id id = std::stoull(inputStrings[i]);
                std::unique_ptr<Number> num = numberBox.get(id);
                outNumbers[i].get() = num->contents;
            } else {
                outNumbers[i].get() = std::stod(inputStrings[i]);
            }
        }
        catch(std::exception& e) {
            std::cout << "Invalid input. Try again: ";
            return false;
        }
    }
    return true;
}

bool processInput(const std::string& input, double& x, char& op, double& y) {

std::vector<std::reference_wrapper<double>> outNumbers;

outNumbers.push_back(x);

outNumbers.push_back(y);

std::vector<std::string> inputStrings;

std::string strX;

std::string strY;

std::istringstream inputStream(input);

inputStream.str(input);

inputStream >> strX >> op >> strY;

inputStrings.push_back(strX);

inputStrings.push_back(strY);

//Iterate over the two numbers from input, retrieving them from memory if needed

for(int i = 0; i < 2; i++) {

try {

if(inputStrings[i][0] == 'm') {

inputStrings[i] = inputStrings[i].substr(1);

obx_id id = std::stoull(inputStrings[i]);

std::unique_ptr<Number> num = numberBox.get(id);

outNumbers[i].get() = num->contents;

} else {

outNumbers[i].get() = std::stod(inputStrings[i]);

}

catch(std::exception& e) {

std::cout << "Invalid input. Try again: ";

return false;

}

return true;

}

5. The last function in our header file will be Memory. It should list all the numbers contained in the database and have an option to clear data. We can read all the database entries by calling the getAll ObjectBox operator. It returns a vector of unique pointers. To clear memory, you can simply operate with removeAll on our Box.

Exercise: define the Memory function, which lists all the memory items, and can delete all of them by request.

Reveal code

void Memory() {
    std::string input;
    std::vector<std::unique_ptr<Number>> list;
    list = numberBox.getAll();
    for(const auto& number : list) {
        std::cout << number->id << "   " << number->contents << std::endl;
    }
    
    std::cout << "Enter clear to delete all or back to return to menu. " << std::endl;
    while(std::getline(std::cin, input)) {
        if(input == "clear") {
            numberBox.removeAll();
            std::cout << "Data deleted." << std::endl;
            break;
        } else if (input == "back") {
            break;
        } else {
            std::cerr << "Unknown command." << input << std::endl;
            fflush(stderr);
            continue;
        }
    }
}

void Memory() {

std::string input;

std::vector<std::unique_ptr<Number>> list;

list = numberBox.getAll();

for(const auto& number : list) {

std::cout << number->id << " " << number->contents << std::endl;

}

std::cout << "Enter clear to delete all or back to return to menu. " << std::endl;

while(std::getline(std::cin, input)) {

if(input == "clear") {

numberBox.removeAll();

std::cout << "Data deleted." << std::endl;

break;

} else if (input == "back") {

break;

} else {

std::cerr << "Unknown command." << input << std::endl;

fflush(stderr);

continue;

}

The source file

To tie everything together, we create a source (.cpp) file. It should contain only the main function that initialises the objectbox model, creates an instance of the Calculator app, and runs it. To create the ObjectBox model, use

obx::Store::Options options(create_obx_model())

1	obx::Store::Options options(create_obx_model())

then passing options as a parameter when you initialise the Store.

Exercise: create the source file

Reveal code

#include "example.hpp"
 
int main() {
    obx::Store::Options options(create_obx_model());
 
    obx::Store store(options);
    Calculator app(store);
    return app.run();
}

#include "example.hpp"

int main() {

obx::Store::Options options(create_obx_model());

obx::Store store(options);

Calculator app(store);

return app.run();

}

Final notes

Now you can finally compile and run your application. At this point, a good exercise would be to try and add some more functionality to this project. Check out the ObjectBox C++ documentation to learn more about the available operations.

Other than that, if you spot any errors in this tutorial or if anything is unclear, please come back to us. We are happy to hear your thoughts.

Beginner C++ tutorial: ObjectBox installation

by Anna | Oct 26, 2021 | Edge Database, Mobile Database, ObjectBox, Tutorial

This ObjectBox beginner tutorial is for people who have limited knowledge of C++ development (no prior experience with external libraries is required). It will walk you through the installation process of all the development tools needed to get started with ObjectBox on Windows. By the way, ObjectBox is a database with intuitive native APIs, so it won’t take you long to start using it.

Firstly, we will need to set up a Linux subsystem (WSL2) and install such tools as:

CMake, which will generate build files from the ObjectBox source code to work on Linux;
Git, which will download the source code from the ObjectBox repository.

Then, we will install ObjectBox and run a simple example in Visual Studio Code.

Windows Subsystem for Linux (WSL2)

In this section, you will set up a simple Linux subsystem that you can use to build Objectbox in C++.

Install WSL (Note: this requires a reboot; it also configures a limited HyperV that may cause issues with e.g. VirtualBox).
Warning: to paste e.g. a password to the Ubuntu setup console window, right-click the title bar and select Edit → Paste. CTRL + V may not work.
(optional, but recommended) install Windows Terminal from Microsoft Store and use Ubuntu from there (does not have the copy/paste issue, also supports terminal apps better).

3. Within Windows Terminal, open Ubuntu by choosing it from the dropdown menu.

Drop-down menu in Windows Terminal, through which a new tab for Ubuntu can be opened

4. Get the latest packages and upgrade:

sudo apt update
sudo apt upgrade

1 2	sudo apt update sudo apt upgrade

5. Install build tools

sudo apt install build-essential git cmake ccache gdb

# install LLVM / clang
LLVM_VERSION=12
sudo apt install clang-$LLVM_VERSION clang-tools-$LLVM_VERSION clang-format-$LLVM_VERSION lldb-$LLVM_VERSION lld-$LLVM_VERSION clangd-$LLVM_VERSION

# Make clang-LLVM_VERSION the default clang, and clang the default C/C++ compiler
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-$LLVM_VERSION 1000
sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 1000
sudo update-alternatives --config c++
sudo update-alternatives --config clang++
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-$LLVM_VERSION 1000
sudo update-alternatives --install /usr/bin/cc cc /usr/bin/clang 1000
sudo update-alternatives --config cc
sudo update-alternatives --config clang
cc --version
c++ --version

# clang tools
sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-$LLVM_VERSION 1000
sudo update-alternatives --install /usr/bin/scan-build scan-build /usr/bin/scan-build-$LLVM_VERSION 1000

# lld is faster than the standard ld linker
sudo update-alternatives --install /usr/bin/ld ld /usr/bin/ld.lld-$LLVM_VERSION 50
sudo update-alternatives --install /usr/bin/ld ld /usr/bin/ld.bfd 10
sudo update-alternatives --config ld
ld --version

sudo apt install build-essential git cmake ccache gdb

# install LLVM / clang

LLVM_VERSION=12

sudo apt install clang-$LLVM_VERSION clang-tools-$LLVM_VERSION clang-format-$LLVM_VERSION lldb-$LLVM_VERSION lld-$LLVM_VERSION clangd-$LLVM_VERSION

# Make clang-LLVM_VERSION the default clang, and clang the default C/C++ compiler

sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-$LLVM_VERSION 1000

sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 1000

sudo update-alternatives --config c++

sudo update-alternatives --config clang++

sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-$LLVM_VERSION 1000

sudo update-alternatives --install /usr/bin/cc cc /usr/bin/clang 1000

sudo update-alternatives --config cc

sudo update-alternatives --config clang

cc --version

c++ --version

# clang tools

sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-$LLVM_VERSION 1000

sudo update-alternatives --install /usr/bin/scan-build scan-build /usr/bin/scan-build-$LLVM_VERSION 1000

# lld is faster than the standard ld linker

sudo update-alternatives --install /usr/bin/ld ld /usr/bin/ld.lld-$LLVM_VERSION 50

sudo update-alternatives --install /usr/bin/ld ld /usr/bin/ld.bfd 10

sudo update-alternatives --config ld

ld --version

Install ObjectBox using CMake

Now that you have WSL2 and all the packages, we can switch to VS Code and install ObjectBox with the help of CMake.

In Ubuntu, create a new directory and then open it in Visual Studio Code:

mkdir objectbox-ex 
cd objectbox-ex
code .

mkdir objectbox-ex

cd objectbox-ex

code .

2. Install the following extensions:

3. Create a text file called CMakeLists.txt with the following code. It will tell CMake to get the ObjectBox source code from its Git repository and link the library to your project.

include(FetchContent) 

FetchContent_Declare( 
objectbox 
GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git 
GIT_TAG v0.14.0 
) 

FetchContent_MakeAvailable(objectbox) 

add_executable(myapp main.cpp) 
target_link_libraries(myapp objectbox)

include(FetchContent)

FetchContent_Declare(

objectbox

GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git

GIT_TAG v0.14.0

)

FetchContent_MakeAvailable(objectbox)

add_executable(myapp main.cpp)

target_link_libraries(myapp objectbox)

4. Create a simple main.cpp file that will help us verify the setup:

#include "objectbox.hpp" 

int main() { 
printf("Using ObjectBox version %s\n", obx_version_string()); 
}

#include "objectbox.hpp"

int main() {

printf("Using ObjectBox version %s\n", obx_version_string());

}

5. Follow this official guide for VS code and CMake to select Clang as the compiler, configure and build ObjectBox. As a result, .vscode and build folders will be generated. So your directory should now look like this:

Explorer tab in Visual Studio Code, showing the two new folders that were generated after a successful build

Running the tasks-list app example

Finally, we can check that everything works and run a simple example.

1. Click the “Select target to launch” button on the status bar and select “myapp” from the dropdown menu. Then launch it. You should see it output the correct version as in the screenshot.

"Select launch target" menu in Visual Studio Code

2. Before proceeding with the example, you need to download the most recent ObjectBox generator for Linux from releases. Then come back to the Windows Terminal and type

explorer.exe .

1	explorer.exe .

to open the current directory in Windows Explorer. Copy the objectbox-generator file in there.

3. Back in VS Code, you should now run the generator for the example code:

./objectbox-generator -cpp build/_deps/objectbox-src/examples/cpp-gen/tasklist.fbs

1	./objectbox-generator -cpp build/_deps/objectbox-src/examples/cpp-gen/tasklist.fbs

If you get a “permission denied” error, try this to make the generator file executable for your user:

chmod +x objectbox-generator

1	chmod +x objectbox-generator

4. Now choose objectbox-c-examples-tasks-cpp-gen as the target and run it. You should see the menu of a simple to-do list app as shown on the screenshot. It stores your tasks, together with their creation time and status. Try playing around with it and exploring the code of this example app to get a feel of how ObjectBox can be used.

Output of the Objectbox C++ tasks-list app example showing its menu with available commands

Note: if you see a sync error (e.g. Can not modify object of sync-enabled type “Task” because sync has not been activated for this store), please delete the first line from the tasklist.fbs file and run the objectbox generator once again. Or, if you want to try sync, apply for our Early Access Data Sync. There is a separate example (called objectbox-c-examples-tasks-cpp-gen-sync) that you can run after installing the Sync Server.

ObjectBox Database Java / Kotlin 3.0 + CRUD Benchmarks

by Markus | Oct 19, 2021 | Android, Benchmarks, Mobile Database, ObjectBox, Release

The Android database for superfast Java / Kotlin data persistence goes 3.0. Since our first 1.0-release in 2017 (Android-first, Java), we have released C/C++, Go, Flutter/Dart, Swift bindings, as well as Data Sync and we’re thrilled that ObjectBox has been used by over 800,000 developers.

We love our Java / Kotlin community ❤️ who have been with us since day one. So, with today’s post, we’re excited to share a feature-packed new major release for Java and Kotlin alongside CRUD performance benchmarks for MongoDB Realm, Room (SQLite) and ObjectBox.

What is ObjectBox?

ObjectBox is a high performance database and an alternative to SQLite and Room. ObjectBox empowers developers to persist objects locally on Mobile and IoT devices. It’s a NoSQL ACID-compliant object database with an out-of-the-box Data Sync providing fast and easy access to decentralized edge data (Early Access).

New Query API

A new Query API is available that works similar to our existing Dart/Flutter Query API and makes it easier to create nested conditions:

// 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()

// Java
// equal AND (less OR oneOf)
Query<User> query = box.query(
        User_.firstName.equal("Joe")
                .and(User_.age.less(12)
                        .or(User_.stamp.oneOf(new long[]{1012}))))
        .order(User_.age)
        .build();

// 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()

// Java

// equal AND (less OR oneOf)

Query<User> query = box.query(

User_.firstName.equal("Joe")

.and(User_.age.less(12)

.or(User_.stamp.oneOf(new long[]{1012}))))

.order(User_.age)

.build();

In Kotlin, the condition methods are also available as infix functions. This can help make queries easier to read:

val query = box.query(User_.firstName equal "Joe").build()

1	val query = box.query(User_.firstName equal "Joe").build()

Unique on conflict replace strategy

One unique property in an @Entity can now be configured to replace the object in case of a conflict (“onConflict”) when putting a new object.

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

// Java
@Entity
public class Example {
    @Id
    public long id;

    @Unique(onConflict = ConflictStrategy.REPLACE)
    String uniqueKey;
}

// Kotlin

@Entity

data class Example(

@Id

var id: Long = 0,

@Unique(onConflict = ConflictStrategy.REPLACE)

var uniqueKey: String? = null

)

// Java

@Entity

public class Example {

@Id

public long id;

@Unique(onConflict = ConflictStrategy.REPLACE)

String uniqueKey;

}

This can be helpful when updating existing data with a unique ID different from the ObjectBox ID. E.g. assume an app that downloads a list of playlists where each has a modifiable title (e.g. “My Jam”) and a unique String ID (“playlist-1”). When downloading an updated version of the playlists, e.g. if the title of “playlist-1” has changed to “Old Jam”, it is now possible to just do a single put with the new data. The existing object for “playlist-1” is then deleted and replaced by the new version.

Built-in string array and map support

String array or string map properties are now supported as property types out-of-the-box. For string array properties it is now also possible to find objects where the array contains a specific item using the new containsElement condition.

// Kotlin
@Entity
data class Example(
        @Id
        var id: Long = 0,
        var stringArray: Array<String>? = null,
        var stringMap: MutableMap<String, String>? = null
)

// matches [“first”, “second”, “third”]
box.query(Example_.stringArray.containsElement(“second”)).build()

// Java
@Entity
public class Example {
    @Id
    public long id;

    public String[] stringArray;
    public Map<String, String> stringMap;
}

// matches [“first”, “second”, “third”]
box.query(Example_.stringArray.containsElement(“second”)).build();

// Kotlin

@Entity

data class Example(

@Id

var id: Long = 0,

var stringArray: Array<String>? = null,

var stringMap: MutableMap<String, String>? = null

)

// matches [“first”, “second”, “third”]

box.query(Example_.stringArray.containsElement(“second”)).build()

// Java

@Entity

public class Example {

@Id

public long id;

public String[] stringArray;

public Map<String, String> stringMap;

}

// matches [“first”, “second”, “third”]

box.query(Example_.stringArray.containsElement(“second”)).build();

Kotlin Flow, Android 12 and more

Kotlin extension functions were added to obtain a Flow from a BoxStore or Query:

val flow = box.query().subscribe().toFlow()

1	val flow = box.query().subscribe().toFlow()

Data Browser has added support for apps targeting Android 12.

For details on all changes, please check the ObjectBox for Java changelog.

Room (SQLite), Realm & ObjectBox CRUD performance benchmarks

We compared against the Android databases, MongoDB Realm and Room (on top of SQLite) and are happy to share that ObjectBox is still faster across all four major database operations: Create, Read, Update, Delete.

Android database comparative benchmarks for ObjectBox, Realm, and Room

We benchmarked ObjectBox along with Room 2.3.0 using SQLite 3.22.0 and MongoDB Realm 10.6.1 on an Samsung Galaxy S9+ (Exynos) mobile phone with Android 10. All benchmarks were run 10+ times and no outliers were discovered, so we used the average for the results graph above. Find our open source benchmarking code on GitHub and as always: feel free to check them out yourself. More to come soon, follow us on Twitter or sign up to our newsletter to stay tuned (no spam ever!).

Using a fast on-device database matters

A fast local database is more than just a “nice-to-have.” It saves device resources, so you have more resources (CPU, Memory, battery) left for other resource-heavy operations. Also, a faster database allows you to keep more data locally with the device and user, thus improving privacy and data ownership by design. Keeping data locally and reducing data transferal volumes also has a significant impact on sustainability.

Sustainable Data Sync

Some data, however, you might want or need to synchronize to a backend. Reducing overhead and synchronizing data selectively, differentially, and efficiently reduces bandwidth strain, resource consumption, and cloud / Mobile Network usage – lowering the CO2 emissions too. Check out ObjectBox Data Sync, if you are interested in an out-of-the-box solution.

Get Started with ObjectBox for Java / Kotlin Today

ObjectBox is free to use and you can get started right now via this getting-started article, or follow this video.

Already an ObjectBox Android database user and ready to take your application to the next level? Check out ObjectBox Data Sync, which solves data synchronization for edge devices, out-of-the-box. It’s incredibly efficient and (you guessed it) superfast 😎

We ❤️ your Feedback

We believe, ObjectBox is super easy to use. We are on a mission to make developers’ lives better, by building developer tools that are intuitive and fun to code with. Now it’s your turn: let us know what you love, what you don’t, what do you want to see next? Share your feedback with us, or check out GitHub and up-vote the features you’d like to see next in ObjectBox.

What is an Edge Database, and why do you need one?

by Vivien | Jun 23, 2021 | Edge Computing, Insights, IoT, Mobile Database

Edge Databases – from trends to use cases

With the megashift from Cloud Computing to the Edge, a lack of core technologies supporting the needs of the decentralized Edge Computing topology became apparent. Edge Databases are a new type of database addressing these need. To implement edge solutions, developers need fast local data persistence and decentralized data flows (Data Sync). Edge Databases solve these core edge functionalities out-of-the-box, making it easy for application developers to implement edge solutions quickly.

The trends driving the megashift to decentralized Edge Computing
Urgently needed: Software infrastructure for edge computing
What is an edge database?
When do you need an edge database?
Edge Database Use Case Example in Manufacturing
Edge Database Outlook

The trends driving the megashift to decentralized Edge Computing

By 2025, 30+ billion IoT devices will be creating ~4.6 trillion GB of data per day. The growing numbers of devices and data volume, variety, and velocity, as well as bandwidth infrastructure limitations, make it infeasible to store and process all data in a centralized cloud. On top, new use cases come with new requirements, a centralized cloud infrastructure cannot meet. For example, soft and hard response rate requirements, offline-functionality, and security and data protection regulations.

These trends accelerate the shift away from centralized cloud computing to a decentralized edge computing topology. Edge computing refers to decentralized data processing at the “edge” of the network. For example, in a car, on a machine, on a smartphone, or in a building. Hardware specifications do not capture the definition of an “edge device”. The crucial point is rather the decentralized use of data at, or as close as possible to, the data source.

Edge computing itself is not a technology but a topology, and according to McKinsey, one of the top growing trends in tech in 2021. The technologies needed to implement the edge computing topology are at this moment still inadequate. More specifically, there is a gap in basic “core” edge technologies, so-called “software infrastructure”. This gap is one of the main reasons for the failure of edge projects.

Needed: Software infrastructure for Edge Computing

With computing shifting to the edge of the network, the needs of this decentralized topology become clear:

Need for fast local data storage

→ i.e. a machine on the factory floor collects data on stiffness, friction, pressure points. There is limited space on the device, and typically no connection to the Internet. Even with an Internet connection, high data rates quickly push the available bandwidth, as well as associated networking / cloud costs, to the limit. To be able to use this data, it must be persisted in a structured manner at the edge, e.g. stored locally in a database.

Need for reliable on-device data flows

→ i.e. the car is an edge device consisting of many control units. Therefore, data must be stored on multiple control units. In order to access and use the data within several of the control units of the car, the data must be selectively synchronized between the devices. A centralized structure and thus a single point of failure is unthinkable.

Need for edge-to-edge-to-cloud data flows

→ i.e. in a manufacturing hall: Typically, you will find any number of diverse devices from sensors to brownfield to greenfield devices, and no internet connectivity. At the same time, there are diverse employee devices such as tablets or smartphones, as well as central PCs, and a cloud. To extract value from the data, it must be available in raw, aggregated, or summary form, in different places. This means it needs to be synchronized efficiently and selectively, with possible conflicts resolved.

Need for flexible edge data management

→ e.g. with the rise of IoT, time-series data have become common. However, time series data alone is usually not sufficient, and needs to be combined with other data structures (like objects) to add value. At the same time, a push to standardize data formats in industries (e.g. VSS in automotive or Umati in Industrial IoT) requires that the database supports flexible data structures.

Developing solutions without software infrastructure on an individual level is possible, but has many drawbacks:

Custom in-house implementations are cumbersome, slow, costly, and typically scale poorly. Oftentimes, applications or certain feature sets become unfeasible to deliver because of the lack of core software infrastructure. Legacy code and individual workarounds create problems over the lifetime of a product. Instead of a thriving ecosystem, only a few big players are able to implement edge solutions. Innovation and creativity are limited. An edge database is part of the solution and enables the entire edge ecosystem to build edge applications faster, cheaper and more efficiently.

What is an edge database?

An edge database is a new type of database specifically tailored to the unique requirements of the Edge Computing topology. An edge database has specific features that make it easy for application developers to focus on value creation. It remove the burden of implementing underlying functionalities for secure storage and the decentralized synchronization of data.

First, an edge database is optimized for resource efficiency (CPU, memory, …) and performance on resource-constrained devices (embedded devices, IoT, mobile). It has a small footprint of a few megabytes. Traditional databases such as MySQL or MongoDB are too large and cumbersome for typical edge devices, and unsuitable for computing at the edge.

An edge device without data flows to/from other devices is just a data island with very limited utility. Accordingly, an edge database must support the management of decentralized data flows. There is no more efficient way than at the database level. This includes a range of conflict resolution strategies due to the decentralized and multi-directional structure of the Edge.

Data security and protection is an increasingly important issue and can quickly become a showstopper for Edge projects. Edge database need to ensure that data is secured in every state (at rest, in transit, in use).

When do you need an edge database?

Most IoT applications need to store and synchronize data. An edge database is always useful when functions / applications are planned that:

should work offline and independent of an internet connection
need to guarantee fast response times
work with a lot of, possibly high-frequency data
need to serve many devices at the same time
need historical data

In addition, developers also often decide to use an edge database to save time and nerves, or to be able to react quickly and flexibly to future requirements.

Edge Database Use Case Example in Manufacturing

Today, you can find everything from low-frequency brownfield devices to high-frequency greenfield devices on a factory floor. As a rule, the machine controllers in use are not designed to store or transmit data. They usually lack not only the functionality, but also the resources to support this. Therefore, additional edge devices are often needed to collect, analyze and interpret the huge amounts of data that each machine produces on site. For such an edge device, rapid data persistence and ingestion, and efficient data flow from edge-to-edge and edge-to-cloud are at the heart of value creation. The clear separation of machine control and edge data processing unit ensures that there is no risk of unintentional interference with the machine controller. An edge device with a powerful edge database can support multiple use cases on the shop floor today:

1. Operational efficiency

Process optimization along the line to increase quality and reduce damage. When the first machine in a production line uses a new batch of material, i.e. in sheet metal processing, one of the first steps is to cut a sheet to the required size. At this stage, the machine can already detect the differences in the metal compared to a previous batch (deviations are allowed within the DIN standard). With an Edge device this data can be evaluated, and the relevant information passed on to the next machine. With this data machines further down the line can avoid damage / breakpoints of the material.

2. Condition monitoring

Continuous machine condition monitoring reduces downtime and increases maintenance efficiency. A constant stream of high-frequency machine data is compared against the fingerprint of the machine. Any slight deviation is immediately detected and reported. Catching deviations early reduces down-times and costly repairs.

3. Historical Data

Historical data is stored for learning and training to optimize the production line. With an edge database, the data is persisted and thus available in the event of faulty behavior. In case of an error, the data preceding the incident can be analyzed and used to find the causes and predict, or even avoid, such an error in the future. Chances are that “fuzzy expert knowledge” already available at the production site can be translated into deterministic rules when tested with these data sets.

Edge Database and the edge ecosystem – an outlook

Edge computing brings many advantages, and enables many applications and functionalities that can only be realized by computing on the edge. Up to now, however, only a few (usually large) players have been able to create value in edge computing projects, and thus gain competitive advantages. One reason is the lack of basic software for the edge. A thriving edge ecosystem requires edge software infrastructure that solves the basic recurring requirements of edge projects. Edge databases are an important building block on the way to such an ecosystem.

Check out the ObjectBox Edge Database on GitHub

Dart Flutter Database ObjectBox 1.0 Release

by Vivien | May 18, 2021 | Mobile Database, ObjectBox, Release

In 2019 we first introduced the ObjectBox database v0.1 for Flutter/Dart. Our team has loved the engagement and feedback we’ve received from the developer community since, and we’re thrilled to announce the first stable version 1.0 for ObjectBox Dart/Flutter today.

With this release we bring you the fast and easy to use ObjectBox database for Dart objects: optimized for high performance on mobile and desktop devices. ObjectBox persists your Dart objects (null safe, of course) and comes with relations, queries, transactions, and Data Sync. For a feature list and more, please also check the pub.dev page.

ObjectBox by Example

For those of you new to ObjectBox, here is how you can use it (or check the docs if you want to dive deep right away). By annotating a class with @Entity you tell ObjectBox that you want to persist its objects, which is done putting the object in a Box:

@Entity()
class Person {
  int id = 0;
 
  String firstName;
  String lastName;
 
  Person(this.firstName, this.lastName);
}
 
// Open a Store once and keep it open to get type specific Boxes
final store = Store(getObjectBoxModel());
final box = store.box<Person>();
 
// let’s put a new Person in the database
var person = Person("Marty", "McFly");
final id = box.put(person);

@Entity()

class Person {

int id = 0;

String firstName;

String lastName;

Person(this.firstName, this.lastName);

}

// Open a Store once and keep it open to get type specific Boxes

final store = Store(getObjectBoxModel());

final box = store.box<Person>();

// let’s put a new Person in the database

var person = Person("Marty", "McFly");

final id = box.put(person);

What’s new with the 1.0?

Version 1.0 delivers a stabilized API and adds new essential features like async writes and query streams. We’ve also extended support for Flutter desktop. Let’s look at queries and how they can be used depending on the use case:

 // find all people whose name starts with "Mc"; 1. Query variant
Query<Person> query = box.query(Person_.firstName.startsWith("Mc")).build();
List<Person> people = query.find();
 
// 2. variant: "watch" the DB for any changes in the entity, then rerun the query
Stream<Query<Person>> watchedQuery = query.watch();
// You can then .listen(), or for example add the query to a StreamBuilder to show on UI.
_controller.addStream(watchedQuery.map((Query<Person> q) => q.find()));
 
// 3. variant: stream data from (non-trivial) queries:
Stream<User> resultStream = box.query().build().stream();
await stream.forEach((Person person) => print(‘${person.firstName} ${person.lastName}’));

// find all people whose name starts with "Mc"; 1. Query variant

Query<Person> query = box.query(Person_.firstName.startsWith("Mc")).build();

List<Person> people = query.find();

// 2. variant: "watch" the DB for any changes in the entity, then rerun the query

Stream<Query<Person>> watchedQuery = query.watch();

// You can then .listen(), or for example add the query to a StreamBuilder to show on UI.

_controller.addStream(watchedQuery.map((Query<Person> q) => q.find()));

// 3. variant: stream data from (non-trivial) queries:

Stream<User> resultStream = box.query().build().stream();

await stream.forEach((Person person) => print(‘${person.firstName} ${person.lastName}’));

There are two new approaches to do async puts for asynchronous database writes: putAsync() returns a Future to check if the call was successful.

Future<int> idFuture = box.putAsync(person);
...
final id = await idFuture;
userBox.get(id); // after the Future completed, the object is stored in the database

Future<int> idFuture = box.putAsync(person);

...

final id = await idFuture;

userBox.get(id); // after the Future completed, the object is stored in the database

Or you can use a background queue if you don’t need individual Futures, the following code inserts 100 objects and only waits once:

for (int i = 0; i < 100; i++) {
  box.putQueued(Person(...));
}
store.awaitAsyncSubmitted();
// after `awaitAsync*`: objects are inserted
expect(box.count(), equals(100));

for (int i = 0; i < 100; i++) {

box.putQueued(Person(...));

}

store.awaitAsyncSubmitted();

// after `awaitAsync*`: objects are inserted

expect(box.count(), equals(100));

If you are interested in further improvements we made to 1.0, please check out the full changelog.

Dart Flutter Database Benchmarks

ObjectBox Dart v1.0 also comes with considerable optimizations bringing a new level of database performance to Flutter apps. ObjectBox enables data-heavy apps that were not possible on Flutter before. Consider this a first sneak-peek; stay tuned for detailed performance benchmarks to be released including queries (hint: they are really fast) along with updated benchmarking code.

What we tested

We looked at some two popular approaches: sqflite, a SQLite wrapper for Flutter (no Dart Native support), and Hive, a key-value store with Class-adapters which seems still popular although its creator abandoned it for architectural shortcomings (it has memory problems and does not support queries). In the previous benchmark we’ve also had a look at Firestore, but being an online-only database it was thousands of times slower than the rest so we’ve left it to rest this time around. Check our previous benchmark if you’re interested.

To get an overview of the databases, we tested CRUD operations (create, read, update, delete). Each test was run multiple times and executed manually outside of the measured time. Data preparation and evaluation were also done outside of the measured time.

ObjectBox, sqflite, Hive performance comparison across CRUD

Looking at the results, we can see ObjectBox performing significantly faster than sqflite across the board, with up to 100 time speed-up in case of create & update operations. Compared to Hive, the results are a little closer in some cases (read) though ObjectBox still comes out on top in all the metrics. Considering that Hive keeps all Dart objects in memory (!) while ObjectBox does not, should give you a good impression of how fast object persistence with ObjectBox is.

ObjectBox Database for Flutter/Dart Highlights

For those of you new to ObjectBox, here’s a quick summary of what our super-fast embedded database offers, out of the box:

automatic schema migration: adding new classes or fields just works
type-safe APIs, e.g. no interface{} arguments
embedded edge database – no server needed, store all data directly on the device
no ORM, no SQL
relations: to-one, to-many (eager and lazy fetching)
robust query support, including indexes for scalable lookups
Support for implicit (automatic) and explicit (user defined)
transactions: ACID compliant with superfast bulk/batch operations
low memory usage
runs across operating systems: 64-bit Linux, macOS, Windows, small 32-bit ARM-based Linux devices (e.g. Raspberry Pi)
Data Sync: an efficient and easy way to synchronize data between your app and the cloud

Getting Started with ObjectBox for Flutter/Dart Today

ObjectBox is free to use and you can get started right now via the docs, pub.dev or GitHub, or this getting-started video tutorial, or getting-started article.

We ❤️ your Feedback

Now it’s your turn: let us know what you love, what you don’t, what do you want to see next? Share your feedback with us, or check out GitHub and up-vote the features you’d like to see next in ObjectBox.

« Older Entries

ObjectBox Database Java 3.1 – Flex type

Flex properties

Query for map keys and values

What’s next?

Beginner C++ Database Tutorial: How to use ObjectBox

Introduction

Overview of the app we want to build

How to use this tutorial

How to create the FlatBuffers file?

Reveal code

Generating binding code

The header file

Reveal code

Reveal code

Reveal code

Reveal code

Reveal code

The source file

Reveal code

Final notes

Beginner C++ tutorial: ObjectBox installation

Windows Subsystem for Linux (WSL2)

Install ObjectBox using CMake

Running the tasks-list app example

ObjectBox Database Java / Kotlin 3.0 + CRUD Benchmarks

What is ObjectBox?

New Query API

Unique on conflict replace strategy

Built-in string array and map support

Kotlin Flow, Android 12 and more

Room (SQLite), Realm & ObjectBox CRUD performance benchmarks

Using a fast on-device database matters

Sustainable Data Sync

Get Started with ObjectBox for Java / Kotlin Today

We ❤️ your Feedback

What is an Edge Database, and why do you need one?

Edge Databases – from trends to use cases

Table of Contents

The trends driving the megashift to decentralized Edge Computing

Needed: Software infrastructure for Edge Computing

Need for fast local data storage

Need for reliable on-device data flows

Need for edge-to-edge-to-cloud data flows

Need for flexible edge data management

What is an edge database?

When do you need an edge database?

Edge Database Use Case Example in Manufacturing

1. Operational efficiency

2. Condition monitoring

3. Historical Data

Edge Database and the edge ecosystem – an outlook

Dart Flutter Database ObjectBox 1.0 Release

ObjectBox by Example

What’s new with the 1.0?

Dart Flutter Database Benchmarks

What we tested

ObjectBox Database for Flutter/Dart Highlights

Getting Started with ObjectBox for Flutter/Dart Today

We ❤️ your Feedback