A Box offers database operations for objects of a specific type. More...

#include <objectbox.hpp>

Inheritance diagram for obx::Box< EntityT >:

Public Member Functions
	Box (Store &store)

AsyncBox< EntityT >	async ()
	Async operations are available through the AsyncBox class.

QueryBuilder< EntityT >	query ()
	Start building a query this entity.

QueryBuilder< EntityT >	query (const QueryCondition &condition)
	Start building a query this entity.

std::unique_ptr< EntityT >	get (obx_id id)
	Read an object from the database, returning a managed pointer.

bool	get (obx_id id, EntityT &outObject)
	Read an object from the database, replacing the contents of an existing object variable.

std::vector< std::unique_ptr< EntityT > >	get (const std::vector< obx_id > &ids)
	Read multiple objects at once, i.e. in a single read transaction.

std::vector< std::unique_ptr< EntityT > >	getAll ()
	Read all objects from the Box at once, i.e. in a single read transaction.

obx_id	put (EntityT &object, OBXPutMode mode=OBXPutMode_PUT)
	Inserts or updates the given object in the database.

obx_id	put (const EntityT &object, OBXPutMode mode=OBXPutMode_PUT)
	Inserts or updates the given object in the database.

size_t	put (std::vector< EntityT > &objects, std::vector< obx_id > *outIds=nullptr, OBXPutMode mode=OBXPutMode_PUT)
	Puts multiple objects using a single transaction. In case there was an error the transaction is rolled back and none of the changes are persisted.

size_t	put (const std::vector< EntityT > &objects, std::vector< obx_id > *outIds=nullptr, OBXPutMode mode=OBXPutMode_PUT)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

size_t	put (std::vector< std::unique_ptr< EntityT > > &objects, std::vector< obx_id > *outIds=nullptr, OBXPutMode mode=OBXPutMode_PUT)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename SourceEntityT , typename TargetEntityT >
std::vector< obx_id >	backlinkIds (RelationProperty< SourceEntityT, TargetEntityT > toOneRel, obx_id objectId)
	Fetch IDs of all objects in this box that reference the given object (ID) on the given relation property. Note: This method refers to "property based relations" unlike the "stand-alone relations" (Box::standaloneRel*).

template<typename SourceEntityT , typename TargetEntityT >
void	standaloneRelReplace (RelationStandalone< SourceEntityT, TargetEntityT > toManyRel, obx_id sourceObjectId, const std::vector< obx_id > &targetObjectIds)
	Replace the list of standalone relation target objects on the given source object.

template<typename TargetEntityT >
void	standaloneRelPut (RelationStandalone< EntityT, TargetEntityT > toManyRel, obx_id sourceObjectId, obx_id targetObjectId)
	Insert a standalone relation entry between two objects.

template<typename TargetEntityT >
void	standaloneRelRemove (RelationStandalone< EntityT, TargetEntityT > toManyRel, obx_id sourceObjectId, obx_id targetObjectId)
	Remove a standalone relation entry between two objects.

template<typename SourceEntityT >
std::vector< obx_id >	standaloneRelIds (RelationStandalone< SourceEntityT, EntityT > toManyRel, obx_id objectId)
	Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "regular" direction; this Box represents the target of the relation.

template<typename TargetEntityT >
std::vector< obx_id >	standaloneRelBacklinkIds (RelationStandalone< EntityT, TargetEntityT > toManyRel, obx_id objectId)
	Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "backlink" direction; this Box represents the source of the relation.

bool	timeSeriesMinMax (obx_id outMinId, int64_t outMinValue, obx_id outMaxId, int64_t outMaxValue)
	Time series: get the limits (min/max time values) over all objects.

bool	timeSeriesMinMax (int64_t rangeBegin, int64_t rangeEnd, obx_id outMinId, int64_t outMinValue, obx_id outMaxId, int64_t outMaxValue)
	Time series: get the limits (min/max time values) over objects within the given time range.

bool	get (CursorTx &cTx, obx_id id, const void *data, size_t size)
	Low-level API: read an object as FlatBuffers bytes from the database.

Public Member Functions inherited from obx::BoxTypeless
	BoxTypeless (Store &store, obx_schema_id entityTypeId)

OBX_box *	cPtr () const

uint64_t	count (uint64_t limit=0)
	Return the number of objects contained by this box.

bool	isEmpty ()
	Returns true if the box contains no objects.

bool	contains (obx_id id)
	Checks whether this box contains an object with the given ID.

bool	contains (const std::vector< obx_id > &ids)
	Checks whether this box contains all objects matching the given IDs.

bool	get (CursorTx &cTx, obx_id id, const void *data, size_t size)
	Low-level API: read an object as FlatBuffers bytes from the database.

obx_id	putNoThrow (void *data, size_t size, OBXPutMode mode=OBXPutMode_PUT)
	Low-level API: puts the given FlatBuffers object.

obx_id	put (void *data, size_t size, OBXPutMode mode=OBXPutMode_PUT)

bool	remove (obx_id id)
	Remove the object with the given id.

uint64_t	remove (const std::vector< obx_id > &ids)
	Removes all objects matching the given IDs.

uint64_t	removeAll ()
	Removes all objects from the box.

Additional Inherited Members
Protected Attributes inherited from obx::BoxTypeless
Store &	store_

OBX_box *	cBox_

const obx_schema_id	entityTypeId_

Detailed Description

template<typename EntityT>
class obx::Box< EntityT >

A Box offers database operations for objects of a specific type.

Given a Store, you can create Box instances to interact with object data (e.g. get and put operations). A Box instance is associated with a specific object type (data class) and gives you a high level API to interact with data objects of that type.

Box operations automatically start an implicit transaction when accessing the database. And because transactions offered by this API are always reentrant, you can set your own transaction boundary using Store::txRead(), Store::txWrite() or Store::tx(). Using these explicit transactions is very much encouraged for calling multiple write operations that logically belong together for better consistency(ACID) and performance.

Box instances are thread-safe and light-weight wrappers around C-boxes, which are cached internally (see obx_box()).

Constructor & Destructor Documentation

◆ Box()

template<typename EntityT >

obx::Box< EntityT >::Box ( Store & store )

inlineexplicit

Member Function Documentation

◆ async()

template<typename EntityT >

AsyncBox< EntityT > obx::Box< EntityT >::async ( )

inline

Async operations are available through the AsyncBox class.

Returns: a shared AsyncBox instance with the default timeout (1s) for enqueueing. Note: while this looks like it creates a new instance, it's only a thin wrapper and the actual ObjectBox core internal async box really is shared.

◆ backlinkIds()

template<typename EntityT >

template<typename SourceEntityT , typename TargetEntityT >

std::vector< obx_id > obx::Box< EntityT >::backlinkIds	(	RelationProperty< SourceEntityT, TargetEntityT >	toOneRel,
		obx_id	objectId
	)

inline

Fetch IDs of all objects in this box that reference the given object (ID) on the given relation property. Note: This method refers to "property based relations" unlike the "stand-alone relations" (Box::standaloneRel*).

Parameters

toOneRel	the relation property, which must belong to the entity type represented by this box.
objectId	this relation points to - typically ID of an object of another entity type (another box).

Returns: resulting IDs representing objects in this Box, or NULL in case of an error

Example Let's say you have the following two entities with a relation between them (.fbs file format):

     table Customer {
         id:ulong;
         name:string;
         ...
     }
     table Order {
         id:ulong;
         /// objectbox:link=Customer
         customerId:ulong;
         ...
     }
     Now, you can use this method to get all orders for a given customer (e.g. 42):
     obx_id customerId = 42;
     Box<Order_> orderBox(store);
     std::vector<obx_id> customerOrders = orderBox.backlinkIds(Order_.customerId, 42);

◆ get() [1/4]

template<typename EntityT >

std::vector< std::unique_ptr< EntityT > > obx::Box< EntityT >::get ( const std::vector< obx_id > & ids )

inline

Read multiple objects at once, i.e. in a single read transaction.

Returns: a vector of object pointers index-matching the given ids. In case some objects are not found, it's position in the result will be NULL, thus the result will always have the same size as the given ids argument.

◆ get() [2/4]

template<typename EntityT >

bool obx::BoxTypeless::get	(	CursorTx &	cTx,
		obx_id	id,
		const void **	data,
		size_t *	size
	)

inline

Low-level API: read an object as FlatBuffers bytes from the database.

Returns: true on success, false if the ID was not found, in which case outObject is untouched.

◆ get() [3/4]

template<typename EntityT >

std::unique_ptr< EntityT > obx::Box< EntityT >::get ( obx_id id )

inline

Read an object from the database, returning a managed pointer.

Returns: an object pointer or nullptr if an object with the given ID doesn't exist.

◆ get() [4/4]

template<typename EntityT >

bool obx::Box< EntityT >::get	(	obx_id	id,
		EntityT &	outObject
	)

inline

Read an object from the database, replacing the contents of an existing object variable.

Returns: true on success, false if the ID was not found, in which case outObject is untouched.

◆ getAll()

template<typename EntityT >

std::vector< std::unique_ptr< EntityT > > obx::Box< EntityT >::getAll ( )

inline

Read all objects from the Box at once, i.e. in a single read transaction.

◆ put() [1/5]

template<typename EntityT >

obx_id obx::Box< EntityT >::put	(	const EntityT &	object,
		OBXPutMode	mode = `OBXPutMode_PUT`
	)

inline

Inserts or updates the given object in the database.

Returns: newly assigned object ID in case this was an insert, otherwise the original ID from the object param.

◆ put() [2/5]

template<typename EntityT >

size_t obx::Box< EntityT >::put	(	const std::vector< EntityT > &	objects,
		std::vector< obx_id > *	outIds = `nullptr`,
		OBXPutMode	mode = `OBXPutMode_PUT`
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns: the number of put elements (always equal to objects.size() for this overload)

◆ put() [3/5]

template<typename EntityT >

obx_id obx::Box< EntityT >::put	(	EntityT &	object,
		OBXPutMode	mode = `OBXPutMode_PUT`
	)

inline

Inserts or updates the given object in the database.

Parameters

object will be updated with a newly inserted ID if the one specified previously was zero. If an ID was already specified (non-zero), it will remain unchanged.

Returns: object ID from the object param (see object param docs).

◆ put() [4/5]

template<typename EntityT >

size_t obx::Box< EntityT >::put	(	std::vector< EntityT > &	objects,
		std::vector< obx_id > *	outIds = `nullptr`,
		OBXPutMode	mode = `OBXPutMode_PUT`
	)

inline

Puts multiple objects using a single transaction. In case there was an error the transaction is rolled back and none of the changes are persisted.

Parameters

objects objects to insert (if their IDs are zero) or update. ID properties on the newly inserted objects will be updated. If the transaction fails, the assigned IDs on the given objects will be incorrect.

outIds may be provided to collect IDs from the objects. This collects not only new IDs assigned after an insert but also existing IDs if an object isn't new but updated instead. Thus, the outIds vector will always end up with the same number of items as objects argument, with indexes corresponding between the two. Note: outIds content is reset before executing to make sure the indexes match the objects argument even if outIds is reused between multiple calls.

Exceptions

reverts the changes if an error occurs.

Returns: the number of put elements (always equal to objects.size() for this overload)

◆ put() [5/5]

template<typename EntityT >

size_t obx::Box< EntityT >::put	(	std::vector< std::unique_ptr< EntityT > > &	objects,
		std::vector< obx_id > *	outIds = `nullptr`,
		OBXPutMode	mode = `OBXPutMode_PUT`
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns: the number of put elements, i.e. the number of std::unique_ptr != nullptr

◆ query() [1/2]

template<typename EntityT >

QueryBuilder< EntityT > obx::Box< EntityT >::query ( )

inline

Start building a query this entity.

◆ query() [2/2]

template<typename EntityT >

QueryBuilder< EntityT > obx::Box< EntityT >::query ( const QueryCondition & condition )

inline

Start building a query this entity.

◆ standaloneRelBacklinkIds()

template<typename EntityT >

template<typename TargetEntityT >

std::vector< obx_id > obx::Box< EntityT >::standaloneRelBacklinkIds	(	RelationStandalone< EntityT, TargetEntityT >	toManyRel,
		obx_id	objectId
	)

inline

Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "backlink" direction; this Box represents the source of the relation.

Parameters

relationId	ID of a standalone relation, whose source type matches this Box
objectId	object ID of the relation target type (typically from another Box)

Returns: resulting IDs representing objects in this Box

◆ standaloneRelIds()

template<typename EntityT >

template<typename SourceEntityT >

std::vector< obx_id > obx::Box< EntityT >::standaloneRelIds	(	RelationStandalone< SourceEntityT, EntityT >	toManyRel,
		obx_id	objectId
	)

inline

Fetch IDs of all objects in this Box related to the given object (typically from another Box). Used for a stand-alone relation and its "regular" direction; this Box represents the target of the relation.

Parameters

relationId	ID of a standalone relation, whose target type matches this Box
objectId	object ID of the relation source type (typically from another Box)

Returns: resulting IDs representing objects in this Box

Todo:: improve docs by providing an example with a clear distinction between source and target type

◆ standaloneRelPut()

template<typename EntityT >

template<typename TargetEntityT >

void obx::Box< EntityT >::standaloneRelPut	(	RelationStandalone< EntityT, TargetEntityT >	toManyRel,
		obx_id	sourceObjectId,
		obx_id	targetObjectId
	)

inline

Insert a standalone relation entry between two objects.

Parameters

toManyRel	must be a standalone relation ID with source object entity belonging to this box
sourceObjectId	identifies an object from this box
targetObjectId	identifies an object from a target box (as per the relation definition)

◆ standaloneRelRemove()

template<typename EntityT >

template<typename TargetEntityT >

void obx::Box< EntityT >::standaloneRelRemove	(	RelationStandalone< EntityT, TargetEntityT >	toManyRel,
		obx_id	sourceObjectId,
		obx_id	targetObjectId
	)

inline

Remove a standalone relation entry between two objects.

Parameters

toManyRel	must be a standalone relation ID with source object entity belonging to this box
sourceObjectId	identifies an object from this box
targetObjectId	identifies an object from a target box (as per the relation definition)

◆ standaloneRelReplace()

template<typename EntityT >

template<typename SourceEntityT , typename TargetEntityT >

void obx::Box< EntityT >::standaloneRelReplace	(	RelationStandalone< SourceEntityT, TargetEntityT >	toManyRel,
		obx_id	sourceObjectId,
		const std::vector< obx_id > &	targetObjectIds
	)

inline

Replace the list of standalone relation target objects on the given source object.

Parameters

toManyRel	must be a standalone relation ID with source object entity belonging to this box
sourceObjectId	identifies an object from this box
targetObjectIds	identifies objects from a target box (as per the relation definition)

Todo:: consider providing a method similar to the one in Go - inserting target objects with 0 IDs

◆ timeSeriesMinMax() [1/2]

template<typename EntityT >

bool obx::Box< EntityT >::timeSeriesMinMax	(	int64_t	rangeBegin,
		int64_t	rangeEnd,
		obx_id *	outMinId,
		int64_t *	outMinValue,
		obx_id *	outMaxId,
		int64_t *	outMaxValue
	)

inline

Time series: get the limits (min/max time values) over objects within the given time range.

Returns: true if objects were found in the given range (IDs/values are available)

◆ timeSeriesMinMax() [2/2]

template<typename EntityT >

bool obx::Box< EntityT >::timeSeriesMinMax	(	obx_id *	outMinId,
		int64_t *	outMinValue,
		obx_id *	outMaxId,
		int64_t *	outMaxValue
	)

inline

Time series: get the limits (min/max time values) over all objects.

Parameters

outMinId	pointer to receive an output (may be nullptr)
outMinValue	pointer to receive an output (may be nullptr)
outMaxId	pointer to receive an output (may be nullptr)
outMaxValue	pointer to receive an output (may be nullptr)

Returns: true if objects were found (IDs/values are available)

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Box()

Member Function Documentation

◆ async()

◆ backlinkIds()

◆ get() [1/4]

◆ get() [2/4]

◆ get() [3/4]

◆ get() [4/4]

◆ getAll()

◆ put() [1/5]

◆ put() [2/5]

◆ put() [3/5]

◆ put() [4/5]

◆ put() [5/5]

◆ query() [1/2]

◆ query() [2/2]

◆ standaloneRelBacklinkIds()

◆ standaloneRelIds()

◆ standaloneRelPut()

◆ standaloneRelRemove()

◆ standaloneRelReplace()

◆ timeSeriesMinMax() [1/2]

◆ timeSeriesMinMax() [2/2]