Queries

ObjectBox queries return persisted objects that match user-defined criteria. You use QueryBuilder to specify criteria and create a Query which actually executes the query and returns matching objects. 
Building queries
The QueryBuilder<T>/OBX_query_builder class lets you build custom queries for your entities. Create an instance via box.query() (C++) or obx_query_builder() (C). 
The generated code contains entity and property meta-information in an enum (C) or a struct (C++). These provide a way to define query conditions safely, without literal entity and property IDs spread throughout the code. Let's have a look at a fragment of the generated code for a User entity (its unique Entity ID is 6 and it has three properties: id, name surname) and the examples below.
C++
C
1
struct User_ {
2
    static constexpr obx_schema_id entityId() { return 6; }
3
    
4
    static const obx::Property<User, OBXPropertyType_Long> id;
5
    static const obx::Property<User, OBXPropertyType_String> name;
6
    static const obx::Property<User, OBXPropertyType_String> surname;
7
};
Copied!
1
enum User_ {
2
    User_ENTITY_ID = 6,
3
    
4
    User_PROP_ID_id = 1,
5
    User_PROP_ID_name = 2,
6
    User_PROP_ID_surname = 3,
7
};
Copied!
Here's how we could query for all users with the first name “Joe” (case insensitive) and their surname starting with a capital "O". First, we initialize the QueryBuilder, next we add one or more conditions (combined with AND operator by default), then we build the query and finally execute it using find.
C++
C
1
QueryBuilder<User> qb = box.query(
2
        User_::name.equals("Joe", false) && User_::surname.startsWith("O")
3
        );
4
Query<User> query = qb.build();
5
std::vector<std::unique_ptr<User>> joes = query.find();
Copied!
1
OBX_query_builder* qb = obx_query_builder(store, User_ENTITY_ID);
2
obx_qb_string_equal(qb, User_PROP_ID_name, "Joe", false);
3
obx_qb_string_starts_with(qb, User_PROP_ID_surname, "O", true);
4
OBX_query* query = obx_query(qb);
5
OBX_bytes_array* bytes_array = obx_query_find(query, 0, 0);
6
​
7
... flatbuffers deserialization
Copied!
obx_query_find() needs to be executed inside an explicit read transaction to avoid data copy while preserving its validity (so that concurrent threads won't change the data while you read it). We're omitting this in the examples to keep them simple, see Transactions for more details.
Reusing queries and parameters
If you frequently run a Query you should cache the Query object and re-use it. To make a Query more reusable you can change the values, or query parameters, of each condition you added even after the Query is built. Let's see how.
Assume we want to find a list of User with specific name values. First, we build a regular Query with an equal condition for name. Because we have to pass an initial parameter value to equal() but plan to override it before running the Query later, we just pass an empty string:
C++
C
1
Query<User> query = box.query(User::name.equals("")).build();
Copied!
1
obx_qb_string_equal(qb, User_PROP_ID_name, "", true);
2
...
3
OBX_query* query = obx_query(qb);
Copied!
Now at some later point, we want to actually run the Query. To set a value for the name parameter on the Query and pass the name property and the new parameter value:
C++
C
1
// Change name param to "Joe", get results
2
auto joes = query.setParameter(User_::name, "Joe").find();
3
​
4
...
5
​
6
// Change name param to "Jake", get results
7
// Note: setting a parameter updates the query object so no need to do it inline
8
query.setParameter(User_::name, "Jake"); 
9
auto jakes = query.find();
Copied!
1
// Change name param to "Joe", get results
2
obx_query_string_param(query, User_ENTITY_ID, User_PROP_ID_name, "Joe")
3
// call obx_query_find(query, 0, 0); and read data from flatbuffers
4
​
5
...
6
​
7
// Change name param to "Jake", get results
8
obx_query_string_param(query, User_ENTITY_ID, User_PROP_ID_name, "Jake")
9
// call obx_query_find(query, 0, 0); and read data from flatbuffers
Copied!
Aliases
So you might already be wondering, what happens if you have more than one condition using the same property? For this purpose, you can assign each condition an alias by calling Alias() right after specifying the condition:
C++
C
1
obx_qb_int_greater(qb.cPtr(), User_::age, 0);
2
obx_qb_param_alias(qb.cPtr(), "min age");
3
obx_qb_int_less(qb.cPtr(), User_::age, 0);
4
obx_qb_param_alias(qb.cPtr(), "max age");
Copied!
1
obx_qb_int_greater(qb, User_PROP_ID_age, 0);
2
obx_qb_param_alias(qb, "min age");
3
obx_qb_int_less(qb, User_PROP_ID_age, 0);
4
obx_qb_param_alias(qb, "max age");
Copied!
Then you'll pass the alias when setting a new parameter value:
C++
C
1
obx_query_int_param_alias(query.cPtr(), "min age", 50);
2
obx_query_int_param_alias(query.cPtr(), "max age", 100);
Copied!
1
obx_query_int_param_alias(query, "min age", 50);
2
obx_query_int_param_alias(query, "max age", 100);
Copied!
Limit, Offset, and Pagination
Sometimes you only need a subset of a query, for example, the first 10 elements. This is especially helpful (and frugal) when you have a high number of entities and you cannot limit the result using query conditions only. The built query has  offset and limit methods to help you do that.
C++
C
1
auto users = query.offset(10).limit(5).find();
2
// users.size() <= 5
3
​
4
// same result on later calls, offset and limit are persisted on the C++ query
5
users = query.find(); 
Copied!
1
uint64_t offset = 10;
2
uint64_t limit = 5;
3
OBX_bytes_array* bytes_array = obx_query_find(query, offset, limit);
Copied!
Reading a single property
If you only want to return the values of certain property and not a list of full objects you can use a PropertyQuery:
C++
C
1
Query<User> query = qb.build();
2
OBX_query_prop* propQuery = obx_query_prop(query.cPtr(), User_::age);
3
OBX_int64_array* ages = obx_query_prop_int64_find(propQuery, nullptr);
Copied!
1
OBX_query* query = obx_query(qb);
2
OBX_query_prop* prop_query = obx_query_prop(query, User_PROP_ID_age);
3
OBX_int64_array* ages = obx_query_prop_int64_find(prop_query, NULL);
Copied!
Note: the returned array of property values is not in any particular order, even if you did specify an order when building the query.
Handling null values
By default, null values are not returned (they're skipped). However, you can specify a replacement value to return if a property is null as the second argument to obx_query_prop_*_find().
Other query features
There are many more features, such as property aggregate functions, distinct, removal of all data matching a query. Be sure to check out the objectbox.h and objectbox.hpp or API docs to discover more.
Transactions in ObjectBox
Time Series Data
Last modified 1yr ago
Copy link
Contents
Building queries
Reusing queries and parameters
Aliases
Limit, Offset, and Pagination
Reading a single property
Handling null values
Other query features