ObjectBox C API

Classes
struct	OBX_id_score
	Object ID with its associated query score, which is used for special query results. More...
struct	OBX_bytes
	This bytes struct is an input/output wrapper used for a single data object (represented as FlatBuffers). More...
struct	OBX_bytes_array
	This bytes array struct is an input/output wrapper for multiple data objects (represented as FlatBuffers). More...
struct	OBX_bytes_score
	This bytes score struct is an input/output wrapper used for a single data object (represented as FlatBuffers) with its associated query score, which is used for special query results. More...
struct	OBX_bytes_score_array
	This bytes score array struct is an input/output wrapper pointing to multiple OBX_bytes_score instances. If count is zero, bytes_scores is allowed to be invalid. More...
struct	OBX_id_array
	ID array struct is an input/output wrapper for an array of object IDs. More...
struct	OBX_id_score_array
	ID score array struct is an input/output wrapper for an array of OBX_id_score structs. If count is zero, bytes_scores is allowed to be invalid. More...
struct	OBX_string_array
	String array struct is an input/output wrapper for an array of character strings. More...
struct	OBX_int64_array
	Int64 array struct is an input/output wrapper for an array of int64 numbers. More...
struct	OBX_int32_array
	Int32 array struct is an input/output wrapper for an array of int32 numbers. More...
struct	OBX_int16_array
	Int16 array struct is an input/output wrapper for an array of int16 numbers. More...
struct	OBX_int8_array
	Int8 array struct is an input/output wrapper for an array of int8 numbers. More...
struct	OBX_double_array
	Double array struct is an input/output wrapper for an array of double precision floating point numbers. More...
struct	OBX_float_array
	Float array struct is an input/output wrapper for an array of single precision floating point numbers. More...

Macros
#define	OBX_C_API
#define	OBX_VERSION_MAJOR   4
	When using ObjectBox as a dynamic library, you should verify that a compatible version was linked using obx_version() or obx_version_is_at_least(). More...
#define	OBX_VERSION_MINOR   0
#define	OBX_VERSION_PATCH   3
#define	OBX_ID_NEW   0xFFFFFFFFFFFFFFFF
	To be used for putting objects with prepared ID slots, e.g. obx_cursor_put_object(). More...
#define	OBX_SUCCESS   0
	Value returned when no error occurred (0) More...
#define	OBX_NOT_FOUND   404
	Returned by, e.g., get operations if nothing was found for a specific ID. This is NOT an error condition, and thus no "last error" info (code/text) is set. More...
#define	OBX_NO_SUCCESS   1001
	Indicates that a function had "no success", which is typically a likely outcome and not a "hard error". This is NOT an error condition, and thus no "last error" info is set. More...
#define	OBX_TIMEOUT   1002
	Indicates that a function reached a time out, which is typically a likely outcome and not a "hard error". This is NOT an error condition, and thus no "last error" info is set. More...
#define	OBX_ERROR_ILLEGAL_STATE   10001
	A request does not make sense in the current state. For example, doing actions on a closed object. More...
#define	OBX_ERROR_ILLEGAL_ARGUMENT   10002
	The passed arguments were illegal; e.g. passed null to a non-null argument. More...
#define	OBX_ERROR_ALLOCATION   10003
	A resource could not be allocated. This usually indicates a severe system status, e.g running out of memory. More...
#define	OBX_ERROR_NUMERIC_OVERFLOW   10004
	Thrown when a numeric value did overflow/underflow, e.g. an addition would result in a value of the type's limits. More...
#define	OBX_ERROR_FEATURE_NOT_AVAILABLE   10005
	Tried to use a special feature that is not part of this lib edition. The ObjectBox library comes in different flavors, and may not contain all features. More...
#define	OBX_ERROR_SHUTTING_DOWN   10006
	A required resource (e.g. a store or some internal queue) is shutting down, and thus, the current request could not be fulfilled. Typically occurs in asynchronous operations. More...
#define	OBX_ERROR_IO   10007
	An I/O operation failed, e.g. a file was not found, could not be written or read. More...
#define	OBX_ERROR_BACKUP_FILE_INVALID   10008
	A given backup file has invalid content and thus cannot be restored. More...
#define	OBX_ERROR_NO_ERROR_INFO   10097
	An error occurred but error information could not be extracted. This falls in the "should not happen" category and should be very rare; please report if you ever encounter this in a reproducible fashion. More...
#define	OBX_ERROR_GENERAL   10098
	A general error occurred that did not fit in a more specific category. More...
#define	OBX_ERROR_UNKNOWN   10099
	An error of unknown type occurred. This falls in the "should not happen" category and should be very rare; please report if you ever encounter this in a reproducible fashion. More...
#define	OBX_ERROR_DB_FULL   10101
	The database has reached its given storage limit. Note that is limit is user defined and thus you can set it as an option when opening a database via obx_opt_max_db_size_in_kb(). Further note that this limit is in place to protect the system from unreasonable storage consumption due to unexpected usage and user errors (e.g. inserting data in an infinite loop). More...
#define	OBX_ERROR_MAX_READERS_EXCEEDED   10102
	Thrown when the maximum of readers (read transactions) was exceeded. Verify that you run a reasonable amount of threads only. If you actually intend to work with a very high number of threads (>100), consider increasing the number of maximum readers via obx_opt_max_readers(). More...
#define	OBX_ERROR_STORE_MUST_SHUTDOWN   10103
	Can not continue, ObjectBox store must be closed. This falls in the "should not happen" category and should be very rare; please report if you ever encounter this in a reproducible fashion. More...
#define	OBX_ERROR_MAX_DATA_SIZE_EXCEEDED   10104
	Occurs when a transaction is about to commit but it would exceed the user-defined data size limit. See obx_opt_max_data_size_in_kb() for details. More...
#define	OBX_ERROR_DB_GENERAL   10198
	A general database related error occurred that did not fit in a more specific category. No secondary error code is available. More...
#define	OBX_ERROR_STORAGE_GENERAL   10199
	A storage error occurred that did not fit in a more specific (storage) category. A secondary error code is available via obx_last_error_secondary(). More...
#define	OBX_ERROR_UNIQUE_VIOLATED   10201
	A unique constraint of was violated when trying to put. More...
#define	OBX_ERROR_NON_UNIQUE_RESULT   10202
	A result was supposed to be unique, but was not. E.g. a query results in multiple results where one one is expected. More...
#define	OBX_ERROR_PROPERTY_TYPE_MISMATCH   10203
	A Property did not match an expected type; e.g. when defining a string-based query condition for an integer type. More...
#define	OBX_ERROR_ID_ALREADY_EXISTS   10210
	A given ID already existed, e.g. when trying to insert with a pre-existing ID. Should happen only with user assigned IDs. More...
#define	OBX_ERROR_ID_NOT_FOUND   10211
	A given ID was not found (does not exist), e.g. when trying to update an object that does not exist. Typically happens when an object was removed before while trying to update it. More...
#define	OBX_ERROR_TIME_SERIES   10212
	A Time Series operation failed, e.g. a time value was out of range. More...
#define	OBX_ERROR_CONSTRAINT_VIOLATED   10299
	A constraint violation occurred that did not fit in a more specific (constraint violation) category. More...
#define	OBX_ERROR_STD_ILLEGAL_ARGUMENT   10301
#define	OBX_ERROR_STD_OUT_OF_RANGE   10302
#define	OBX_ERROR_STD_LENGTH   10303
#define	OBX_ERROR_STD_BAD_ALLOC   10304
#define	OBX_ERROR_STD_RANGE   10305
#define	OBX_ERROR_STD_OVERFLOW   10306
#define	OBX_ERROR_STD_OTHER   10399
#define	OBX_ERROR_SCHEMA   10501
	Data schema (aka data model) related error; typically when a provided schema is inconsistent/incompatible to an existing one (on disk). More...
#define	OBX_ERROR_FILE_CORRUPT   10502
	DB file has errors, e.g. illegal values or structural inconsistencies were detected. More...
#define	OBX_ERROR_FILE_PAGES_CORRUPT   10503
	DB file has errors related to pages, e.g. bad page refs outside of the file. More...
#define	OBX_ERROR_SCHEMA_OBJECT_NOT_FOUND   10504
	A requested schema object (e.g. an entity or a property) was not found in the schema. More...
#define	OBX_ERROR_TREE_MODEL_INVALID   10601
	Could not setup tree because the data model (schema) of the database does not contain all required tree types/properties. More...
#define	OBX_ERROR_TREE_VALUE_TYPE_MISMATCH   10602
	Accessing a tree value failed because the stored value was put using a different value type. More...
#define	OBX_ERROR_TREE_PATH_NON_UNIQUE   10603
	At a given path, a leaf was expected but a branch node was found; e.g. values can only be stored in leaves. More...
#define	OBX_ERROR_TREE_PATH_ILLEGAL   10604
	When trying to put or get using an illegal tree path. Examples for illegal paths with delimiter '/': "", "/", "a", "/a", "a/", "a//b", " ", " / ", "a/ /b", " a/b", "a/b ". More...
#define	OBX_ERROR_TREE_OTHER   10699
	An error related to tree functionality was detected; please check the error message for details (see obx_last_error_message()). More...

Typedefs
typedef uint32_t	obx_schema_id
	Schema entity & property identifiers. More...
typedef uint64_t	obx_uid
	Universal identifier used in schema for entities & properties. More...
typedef uint64_t	obx_id
	ID of a single Object stored in the database. More...
typedef struct OBX_id_score	OBX_id_score
	Object ID with its associated query score, which is used for special query results. More...
typedef int	obx_err
	Error/success code returned by an obx_* function; see defines OBX_SUCCESS, OBX_NOT_FOUND, and OBX_ERROR_*. More...
typedef bool	obx_data_visitor(const void *data, size_t size, void *user_data)
	The callback for reading data (i.e. object bytes) one-by-one. More...
typedef bool	obx_data_score_visitor(const struct OBX_bytes_score *data, void *user_data)
	The callback for reading data (i.e. object bytes) with a search score one-by-one. More...
typedef void	obx_log_callback(OBXLogLevel log_level, const char *message, size_t message_size, void *user_data)
	Callback for logging, which can be provided to store creation via options. More...
typedef struct OBX_model	OBX_model
	Model represents a database schema and must be provided when opening the store. Model initialization is usually done by language bindings, which automatically build the model based on parsed source code (for examples, see ObjectBox Go or Swift, which also use this C API). More...
typedef struct OBX_store	OBX_store
	A ObjectBox store represents a database storing data in a given directory on a local file system or in-memory using "memory:" directory prefix. More...
typedef struct OBX_store_options	OBX_store_options
	Store options customize the behavior of ObjectBox before opening a store. Options can't be changed once the store is open but of course you can close the store and open it again with the changed options. Some of the notable options are obx_opt_directory() and obx_opt_max_db_size_in_kb(). More...
typedef struct OBX_bytes	OBX_bytes
	This bytes struct is an input/output wrapper used for a single data object (represented as FlatBuffers). More...
typedef struct OBX_bytes_array	OBX_bytes_array
	This bytes array struct is an input/output wrapper for multiple data objects (represented as FlatBuffers). More...
typedef struct OBX_bytes_score	OBX_bytes_score
	This bytes score struct is an input/output wrapper used for a single data object (represented as FlatBuffers) with its associated query score, which is used for special query results. More...
typedef struct OBX_bytes_score_array	OBX_bytes_score_array
	This bytes score array struct is an input/output wrapper pointing to multiple OBX_bytes_score instances. If count is zero, bytes_scores is allowed to be invalid. More...
typedef struct OBX_bytes_lazy	OBX_bytes_lazy
	Bytes, which must be resolved "lazily" via obx_bytes_lazy_get() and released via obx_bytes_lazy_free(). Unlike OBX_bytes, this may represent allocated resources and/or bytes that are only produced on demand. More...
typedef struct OBX_id_array	OBX_id_array
	ID array struct is an input/output wrapper for an array of object IDs. More...
typedef struct OBX_id_score_array	OBX_id_score_array
	ID score array struct is an input/output wrapper for an array of OBX_id_score structs. If count is zero, bytes_scores is allowed to be invalid. More...
typedef struct OBX_string_array	OBX_string_array
	String array struct is an input/output wrapper for an array of character strings. More...
typedef struct OBX_int64_array	OBX_int64_array
	Int64 array struct is an input/output wrapper for an array of int64 numbers. More...
typedef struct OBX_int32_array	OBX_int32_array
	Int32 array struct is an input/output wrapper for an array of int32 numbers. More...
typedef struct OBX_int16_array	OBX_int16_array
	Int16 array struct is an input/output wrapper for an array of int16 numbers. More...
typedef struct OBX_int8_array	OBX_int8_array
	Int8 array struct is an input/output wrapper for an array of int8 numbers. More...
typedef struct OBX_double_array	OBX_double_array
	Double array struct is an input/output wrapper for an array of double precision floating point numbers. More...
typedef struct OBX_float_array	OBX_float_array
	Float array struct is an input/output wrapper for an array of single precision floating point numbers. More...
typedef struct OBX_txn	OBX_txn
	Transaction provides the mean to use explicit database transactions, grouping several operations into a single unit of work that either executes completely or not at all. If you are looking for a more detailed introduction to transactions in general, please consult other resources, e.g., https://en.wikipedia.org/wiki/Database_transaction. More...
typedef struct OBX_cursor	OBX_cursor
	Cursor provides fine-grained (lower level API) access to the stored objects. Check also the more convenient Box API. More...
typedef struct OBX_box	OBX_box
	A Box offers database operations for objects of a specific type. More...
typedef void	obx_status_callback(obx_err status, void *user_data)
	Callback for simple async functions that only deliver a obx_err status. More...
typedef struct OBX_async	OBX_async
	Created by obx_box_async, used for async operations like obx_async_put. More...
typedef struct OBX_query_builder	OBX_query_builder
	You use QueryBuilder to specify criteria and create a Query which actually executes the query and returns matching objects. More...
typedef int	obx_qb_cond
	Query Builder condition identifier. More...
typedef struct OBX_query	OBX_query
	Query holds the information necessary to execute a database query. It's prepared by QueryBuilder and may be reused any number of times. It also supports parametrization before executing, further improving the reusability. Query is NOT thread safe and must only be used from a single thread at the same time. If you prefer to avoid locks, you may want to create clonse using obx_query_clone(). More...
typedef struct OBX_query_prop	OBX_query_prop
	PropertyQuery - getting a single property instead of whole objects. Also provides aggregation over properties. More...
typedef struct OBX_observer	OBX_observer
	Observers are called back when data has changed in the database. See obx_observe(), or obx_observe_single_type() to listen to a changes that affect a single entity type. More...
typedef void	obx_observer(const obx_schema_id *type_ids, size_t type_ids_count, void *user_data)
	Callback for obx_observe() More...
typedef void	obx_observer_single_type(void *user_data)
	Callback for obx_observe_single_type() More...
typedef struct OBX_tree_options	OBX_tree_options
	Structural/behavioral options for a tree passed during tree creation. More...
typedef struct OBX_tree	OBX_tree
	Top level tree API representing a tree structure/schema associated with a store. More...
typedef struct OBX_tree_cursor	OBX_tree_cursor
typedef struct OBX_tree_leaves_info	OBX_tree_leaves_info
	Extended information about leaf nodes. More...
typedef void	obx_tree_async_get_callback(obx_err status, obx_id id, const char *path, const void *leaf_data, size_t leaf_data_size, const void *leaf_metadata, size_t leaf_metadata_size, void *user_data)
	Callback for obx_tree_async_get_raw(). More...
typedef void	obx_tree_async_put_callback(obx_err status, obx_id id, void *user_data)
	Callback for obx_tree_async_put_raw(). More...
typedef struct OBX_weak_store	OBX_weak_store
	A "weak store" is a weakly referenced store. More...
typedef struct OBX_admin_options	OBX_admin_options
	Options to configure the OBX_admin to be created. More...
typedef struct OBX_admin	OBX_admin
	The admin web UI is an optional feature consisting of an embedded http server, that comes with an object (data) browser and an administration UI. More...

Enumerations
enum	OBXFeature {   OBXFeature_ResultArray = 1 , OBXFeature_TimeSeries = 2 , OBXFeature_Sync = 3 , OBXFeature_DebugLog = 4 ,   OBXFeature_Admin = 5 , OBXFeature_Tree = 6 , OBXFeature_SyncServer = 7 , OBXFeature_WebSockets = 8 ,   OBXFeature_Cluster = 9 , OBXFeature_HttpServer = 10 , OBXFeature_GraphQL = 11 , OBXFeature_Backup = 12 ,   OBXFeature_Lmdb = 13 , OBXFeature_VectorSearch = 14 , OBXFeature_Wal = 15 , OBXFeature_SyncMongoDb = 16 }
enum	OBXLogLevel {   OBXLogLevel_Verbose = 10 , OBXLogLevel_Debug = 20 , OBXLogLevel_Info = 30 , OBXLogLevel_Warn = 40 ,   OBXLogLevel_Error = 50 }
	Log level as passed to obx_log_callback. More...
enum	OBXPropertyType {   OBXPropertyType_Unknown = 0 , OBXPropertyType_Bool = 1 , OBXPropertyType_Byte = 2 , OBXPropertyType_Short = 3 ,   OBXPropertyType_Char = 4 , OBXPropertyType_Int = 5 , OBXPropertyType_Long = 6 , OBXPropertyType_Float = 7 ,   OBXPropertyType_Double = 8 , OBXPropertyType_String = 9 , OBXPropertyType_Date = 10 , OBXPropertyType_Relation = 11 ,   OBXPropertyType_DateNano = 12 , OBXPropertyType_Flex = 13 , OBXPropertyType_BoolVector = 22 , OBXPropertyType_ByteVector = 23 ,   OBXPropertyType_ShortVector = 24 , OBXPropertyType_CharVector = 25 , OBXPropertyType_IntVector = 26 , OBXPropertyType_LongVector = 27 ,   OBXPropertyType_FloatVector = 28 , OBXPropertyType_DoubleVector = 29 , OBXPropertyType_StringVector = 30 , OBXPropertyType_DateVector = 31 ,   OBXPropertyType_DateNanoVector = 32 }
enum	OBXVectorDistanceType {   OBXVectorDistanceType_Unknown = 0 , OBXVectorDistanceType_Euclidean = 1 , OBXVectorDistanceType_Cosine = 2 , OBXVectorDistanceType_DotProduct = 3 ,   OBXVectorDistanceType_Manhattan = 4 , OBXVectorDistanceType_Hamming = 5 , OBXVectorDistanceType_DotProductNonNormalized = 10 }
	The vector distance algorithm used by an HNSW index (vector search). More...
enum	OBXHnswFlags {   OBXHnswFlags_None = 0 , OBXHnswFlags_DebugLogs = 1 , OBXHnswFlags_DebugLogsDetailed = 2 , OBXHnswFlags_VectorCacheSimdPaddingOff = 4 ,   OBXHnswFlags_ReparationLimitCandidates = 8 }
	Bit-flags to influence the behavior of HNSW index (vector search). More...
enum	OBXEntityFlags { OBXEntityFlags_SYNC_ENABLED = 2 , OBXEntityFlags_SHARED_GLOBAL_IDS = 4 }
	Bit-flags defining the behavior of entities. Note: Numbers indicate the bit position. More...
enum	OBXPropertyFlags {   OBXPropertyFlags_ID = 1 , OBXPropertyFlags_NON_PRIMITIVE_TYPE = 2 , OBXPropertyFlags_NOT_NULL = 4 , OBXPropertyFlags_INDEXED = 8 ,   OBXPropertyFlags_RESERVED = 16 , OBXPropertyFlags_UNIQUE = 32 , OBXPropertyFlags_ID_MONOTONIC_SEQUENCE = 64 , OBXPropertyFlags_ID_SELF_ASSIGNABLE = 128 ,   OBXPropertyFlags_INDEX_PARTIAL_SKIP_NULL = 256 , OBXPropertyFlags_INDEX_PARTIAL_SKIP_ZERO = 512 , OBXPropertyFlags_VIRTUAL = 1024 , OBXPropertyFlags_INDEX_HASH = 2048 ,   OBXPropertyFlags_INDEX_HASH64 = 4096 , OBXPropertyFlags_UNSIGNED = 8192 , OBXPropertyFlags_ID_COMPANION = 16384 , OBXPropertyFlags_UNIQUE_ON_CONFLICT_REPLACE = 32768 ,   OBXPropertyFlags_EXPIRATION_TIME = 65536 }
	Bit-flags defining the behavior of properties. Note: Numbers indicate the bit position. More...
enum	OBXDebugFlags {   OBXDebugFlags_LOG_TRANSACTIONS_READ = 1 , OBXDebugFlags_LOG_TRANSACTIONS_WRITE = 2 , OBXDebugFlags_LOG_QUERIES = 4 , OBXDebugFlags_LOG_QUERY_PARAMETERS = 8 ,   OBXDebugFlags_LOG_ASYNC_QUEUE = 16 , OBXDebugFlags_LOG_CACHE_HITS = 32 , OBXDebugFlags_LOG_CACHE_ALL = 64 , OBXDebugFlags_LOG_TREE = 128 ,   OBXDebugFlags_LOG_EXCEPTION_STACK_TRACE = 256 , OBXDebugFlags_RUN_THREADING_SELF_TEST = 512 }
	Debug flags typically enable additional "debug logging" that can be helpful to better understand what is going on internally. These are intended for the development process only; typically one does not enable them for releases. More...
enum	OBXValidateOnOpenPagesFlags { OBXValidateOnOpenPagesFlags_None = 0 , OBXValidateOnOpenPagesFlags_VisitLeafPages = 1 }
	Flags used to control pages validation options when opening the store. More...
enum	OBXValidateOnOpenKvFlags { OBXValidateOnOpenKvFlags_None = 0 }
	Flags used to control key/value pairs validation options when opening the store. Note: this enum does not contain any actual values besides "None" yet; it's only used to future proof the API. More...
enum	OBXPutPaddingMode { OBXPutPaddingMode_PaddingAutomatic = 1 , OBXPutPaddingMode_PaddingAllowedByBuffer = 2 , OBXPutPaddingMode_PaddingByCaller = 3 }
	Defines a padding mode for putting data bytes. Depending on how that data is created, this mode may optimize data handling by avoiding copying memory. Internal background: data buffers used by put operations are required to have a size divisible by 4 for an efficient data layout. More...
enum	OBXBackupFlags { OBXBackupFlags_ExcludeTimestamp = 0x1 , OBXBackupFlags_ExcludeSalt = 0x2 }
	Backup flags control how the store creates backup files. E.g. when you want "deterministic" file content, you can exclude timestamp and salt. More...
enum	OBXWalFlags { OBXWalFlags_EnableWal = 0x1 , OBXWalFlags_NoSyncFile = 0x2 }
	WAL flags control how the store handles WAL files. More...
enum	OBXBackupRestoreFlags { OBXBackupRestoreFlags_OverwriteExistingData = 1 }
	Backup restore flags control how backups are restored to the database. More...
enum	OBXStoreTypeId { OBXStoreTypeId_LMDB = 1 , OBXStoreTypeId_InMemory = 2 , OBXStoreTypeId_InMemoryWal = 3 }
	Store type to be registered with obx_store_type_id_register_default(). More...
enum	OBXPutMode { OBXPutMode_PUT = 1 , OBXPutMode_INSERT = 2 , OBXPutMode_UPDATE = 3 }
enum	OBXOrderFlags {   OBXOrderFlags_DESCENDING = 1 , OBXOrderFlags_CASE_SENSITIVE = 2 , OBXOrderFlags_UNSIGNED = 4 , OBXOrderFlags_NULLS_LAST = 8 ,   OBXOrderFlags_NULLS_ZERO = 16 }
	Not really an enum, but binary flags to use across languages. More...
enum	OBXTreeOptionFlags {   OBXTreeOptionFlags_DebugLogsDisable = 1 , OBXTreeOptionFlags_DebugLogsEnable = 2 , OBXTreeOptionFlags_EnforceUniquePath = 4 , OBXTreeOptionFlags_AllowNonUniqueNodes = 8 ,   OBXTreeOptionFlags_DetectNonUniqueNodes = 16 , OBXTreeOptionFlags_AutoConsolidateNonUniqueNodes = 32 }

Functions
OBX_C_API void	obx_version (int *major, int *minor, int *patch)
	Return the (runtime) version of the library as ints. Pointers may be null. More...
OBX_C_API bool	obx_version_is_at_least (int major, int minor, int patch)
	Check if the (runtime) version of the library is equal to or higher than the given version ints. More...
OBX_C_API const char *	obx_version_string (void)
	Return the (runtime) version of the library to be printed. The current format is "major.minor.patch" (e.g. "1.0.0") but may change in any future release. Thus, only use for information purposes. More...
OBX_C_API const char *	obx_version_core_string (void)
	Return the version of the ObjectBox core to be printed (currently also contains a version date and features). The format may change in any future release; only use for information purposes. More...
OBX_C_API bool	obx_has_feature (OBXFeature feature)
	Checks whether the given feature is available in the currently loaded library. More...
OBX_C_API obx_err	obx_remove_db_files (char const *directory)
	Delete the store files from the given directory. More...
OBX_C_API size_t	obx_db_file_size (char const *directory)
OBX_C_API obx_err	obx_debug_log (bool enabled)
	Enable (or disable) debug logging for ObjectBox internals. This requires a version of the library with the DebugLog feature. You can check if the feature is available with obx_has_feature(OBXFeature_DebugLog). More...
OBX_C_API bool	obx_debug_log_enabled ()
	Checks if debug logs are enabled for ObjectBox internals. This depends on the availability of the DebugLog feature. If the feature is available, it returns the current state, which is adjustable via obx_debug_log(). Otherwise, it always returns false for standard release builds (or true if you are having a special debug version). More...
OBX_C_API int	obx_thread_number ()
	Gets the number, as used by ObjectBox, of the current thread. This e.g. allows to "associate" the thread with ObjectBox logs (each log entry contains the thread number). More...
OBX_C_API bool	obx_last_error_pop (obx_err *out_error, const char **out_message)
	Return the error status on the current thread and clear the error state. The buffer returned in out_message is valid only until the next call into ObjectBox. More...
OBX_C_API obx_err	obx_last_error_code (void)
	The last error raised by an ObjectBox API call on the current thread, or OBX_SUCCESS if no error occurred yet. Note that API calls do not clear this error code (also true for this method). Thus, if you receive an error from this, it's usually a good idea to call obx_last_error_clear() to clear the error state (or use obx_last_error_pop()) for future API calls. More...
OBX_C_API const char *	obx_last_error_message (void)
	The error message string attached to the error returned by obx_last_error_code(). Like obx_last_error_code(), this is bound to the current thread, and this call does not clear the error state. The buffer returned is valid only until the next call into ObjectBox. More...
OBX_C_API obx_err	obx_last_error_secondary (void)
	The underlying error for the error returned by obx_last_error_code(). Where obx_last_error_code() may be a generic error like OBX_ERROR_STORAGE_GENERAL, this will give a further underlying and possibly platform-specific error code. More...
OBX_C_API void	obx_last_error_clear (void)
	Clear the error state on the current thread; e.g. obx_last_error_code() will now return OBX_SUCCESS. Note that clearing the error state does not happen automatically; API calls set the error state when they produce an error, but do not clear it on success. See also: obx_last_error_pop() to retrieve the error state and clear it. More...
OBX_C_API bool	obx_last_error_set (obx_err code, obx_err secondary, const char *message)
	Set the last error code and test - reserved for internal use from generated code. More...
OBX_C_API float	obx_vector_distance_float32 (OBXVectorDistanceType type, const float *vector1, const float *vector2, size_t dimension)
	Utility function to calculate the distance of two given vectors. Note: the memory of the two vectors may not overlap! More...
OBX_C_API float	obx_vector_distance_to_relevance (OBXVectorDistanceType type, float distance)
	Utility function to convert a vector distance (e.g. scores from query results) to a relevance score. The relevance score is a value between 0.0 and 1.0, with 1.0 indicating the most relevant. Note: the higher a distance (score), the lower the relevance score. Note: while the distance (score) is potentially unbound (e.g. Euclidean and dot product) and dependent on the type, relevance score always has fixed range (0.0 to 1.0). More...
OBX_C_API OBX_model *	obx_model (void)
	Create an (empty) data meta model which is to be consumed by obx_opt_model(). More...
OBX_C_API obx_err	obx_model_free (OBX_model *model)
	Only call when not calling obx_store_open() (which will free it internally) More...
OBX_C_API obx_err	obx_model_error_code (OBX_model *model)
	To minimise the amount of error handling code required when building a model, the first error is stored and can be obtained here. All the obx_model_XXX functions are null operations after the first model error has occurred. More...
OBX_C_API const char *	obx_model_error_message (OBX_model *model)
	To minimise the amount of error handling code required when building a model, the first error is stored and can be obtained here. All the obx_model_XXX functions are null operations after the first model error has occurred. More...
OBX_C_API obx_err	obx_model_entity (OBX_model *model, const char *name, obx_schema_id entity_id, obx_uid entity_uid)
	Starts the definition of a new entity type for the meta data model. After this, call obx_model_property() to add properties to the entity type. More...
OBX_C_API obx_err	obx_model_entity_flags (OBX_model *model, uint32_t flags)
	Refine the definition of the entity declared by the most recent obx_model_entity() call, specifying flags. More...
OBX_C_API obx_err	obx_model_property (OBX_model *model, const char *name, OBXPropertyType type, obx_schema_id property_id, obx_uid property_uid)
	Starts the definition of a new property for the entity type of the last obx_model_entity() call. More...
OBX_C_API obx_err	obx_model_property_flags (OBX_model *model, uint32_t flags)
	Refine the definition of the property declared by the most recent obx_model_property() call, specifying flags. More...
OBX_C_API obx_err	obx_model_property_relation (OBX_model *model, const char *target_entity, obx_schema_id index_id, obx_uid index_uid)
	Refine the definition of the property declared by the most recent obx_model_property() call, declaring it a relation. More...
OBX_C_API obx_err	obx_model_property_index_id (OBX_model *model, obx_schema_id index_id, obx_uid index_uid)
	Refine the definition of the property declared by the most recent obx_model_property() call, adding an index. More...
OBX_C_API obx_err	obx_model_property_index_hnsw_dimensions (OBX_model *model, size_t value)
	Sets the vector dimensionality for the HNSW index of the latest property (must be of a supported vector type). This a mandatory option for all HNSW indexes. Note 1: vectors with higher dimensions than this value are also indexed (ignoring the higher elements). Note 2: vectors with lower dimensions than this value are completely ignored for indexing. More...
OBX_C_API obx_err	obx_model_property_index_hnsw_neighbors_per_node (OBX_model *model, uint32_t value)
	Sets the max number of neighbors per node (aka "M") for the HNSW index of the latest property. Higher number increases the graph connectivity which can lead to better results, but higher resources usage. If no value is set, a default value taken (currently 30). Try e.g. 16 for faster but less accurate results, or 64 for more accurate results. More...
OBX_C_API obx_err	obx_model_property_index_hnsw_indexing_search_count (OBX_model *model, uint32_t value)
	Sets the max number of neighbors searched while indexing (aka "efConstruction") for the HNSW index of the latest property. If no value is set, a default value taken (currently 100, which can change in future version). The default value serves as a starting point that can likely be optimized for specific datasets and use cases. The higher the value, the more accurate the search, but the longer the indexing will take. If indexing time is not a major concern, a value of at least 200 is recommended to improve search quality. More...
OBX_C_API obx_err	obx_model_property_index_hnsw_flags (OBX_model *model, uint32_t flags)
	Sets flags for the HNSW index of the latest property (). For details see OBXHnswFlags and its individual values. More...
OBX_C_API obx_err	obx_model_property_index_hnsw_distance_type (OBX_model *model, OBXVectorDistanceType value)
	Sets the distance type for the HNSW index of the latest property. More...
OBX_C_API obx_err	obx_model_property_index_hnsw_reparation_backlink_probability (OBX_model *model, float value)
	Sets the reparation backlink probability, for the HNSW index of the latest property. When repairing the graph after a node was removed, this gives the probability of adding backlinks to the repaired neighbors. The default is 1.0 (aka "always") as this should be worth a bit of extra costs as it improves the graph's quality. More...
OBX_C_API obx_err	obx_model_property_index_hnsw_vector_cache_hint_size_kb (OBX_model *model, size_t value)
	Sets the vector cache hint size for the HNSW index of the latest property. This is a non-binding hint of the maximum size of the vector cache in KB (default: 2097152 or 2 GB/GiB). More...
OBX_C_API obx_err	obx_model_relation (OBX_model *model, obx_schema_id relation_id, obx_uid relation_uid, obx_schema_id target_id, obx_uid target_uid)
	Add a standalone relation between the active entity and the target entity to the model. More...
OBX_C_API void	obx_model_last_entity_id (OBX_model *, obx_schema_id entity_id, obx_uid entity_uid)
	Set the highest ever known entity id in the model. Should always be equal to or higher than the last entity id of the previous version of the model. More...
OBX_C_API void	obx_model_last_index_id (OBX_model *model, obx_schema_id index_id, obx_uid index_uid)
	Set the highest ever known index id in the model. Should always be equal to or higher than the last index id of the previous version of the model. More...
OBX_C_API void	obx_model_last_relation_id (OBX_model *model, obx_schema_id relation_id, obx_uid relation_uid)
	Set the highest every known relation id in the model. Should always be equal to or higher than the last relation id of the previous version of the model. More...
OBX_C_API obx_err	obx_model_entity_last_property_id (OBX_model *model, obx_schema_id property_id, obx_uid property_uid)
	Set the highest ever known property id in the entity. Should always be equal to or higher than the last property id of the previous version of the entity. More...
OBX_C_API obx_err	obx_bytes_lazy_get (OBX_bytes_lazy *bytes, const void **out_bytes, size_t *out_size)
	Get the actual bytes from the given OBX_bytes_lazy. Because of the potential lazy creation of bytes, the given bytes are not const as it may be resolved internally. For the same reason, this function is not thread-safe, at least for the first call on a OBX_bytes_lazy instance. More...
OBX_C_API void	obx_bytes_lazy_free (OBX_bytes_lazy *bytes)
	Releases any resources associated with the given OBX_bytes_lazy. More...
OBX_C_API OBX_store_options *	obx_opt ()
	Create a default set of store options. More...
OBX_C_API obx_err	obx_opt_directory (OBX_store_options *opt, const char *dir)
	Set the store directory on the options. The default is "objectbox". Use prefix "memory:" to open an in-memory database, e.g. "memory:myApp" (see docs for details). More...
OBX_C_API void	obx_opt_max_db_size_in_kb (OBX_store_options *opt, uint64_t size_in_kb)
	Set the maximum db size on the options. The default is 1Gb. More...
OBX_C_API void	obx_opt_max_data_size_in_kb (OBX_store_options *opt, uint64_t size_in_kb)
	Data size tracking is more involved than DB size tracking, e.g. it stores an internal counter. Thus only use it if a stricter, more accurate limit is required (it's off by default). It tracks the size of actual data bytes of objects (system and metadata is not considered). On the upside, reaching the data limit still allows data to be removed (assuming DB limit is not reached). Max data and DB sizes can be combined; data size must be below the DB size. More...
OBX_C_API void	obx_opt_file_mode (OBX_store_options *opt, unsigned int file_mode)
	Set the file mode on the options. The default is 0644 (unix-style). More...
OBX_C_API void	obx_opt_max_readers (OBX_store_options *opt, unsigned int max_readers)
	Set the maximum number of readers (related to read transactions) on the given options. "Readers" are an finite resource for which we need to define a maximum number upfront. The default value is enough for most apps and usually you can ignore it completely. However, if you get the OBX_ERROR_MAX_READERS_EXCEEDED error, you should verify your threading. For each thread, ObjectBox uses multiple readers. Their number (per thread) depends on number of types, relations, and usage patterns. Thus, if you are working with many threads (e.g. in a server-like scenario), it can make sense to increase the maximum number of readers. More...
OBX_C_API void	obx_opt_no_reader_thread_locals (OBX_store_options *opt, bool flag)
	Disables the usage of thread locals for "readers" related to read transactions. This can make sense if you are using a lot of threads that are kept alive. More...
OBX_C_API obx_err	obx_opt_model (OBX_store_options *opt, OBX_model *model)
	Set the model on the options. The default is no model. NOTE: the model is always freed by this function, including when an error occurs. More...
OBX_C_API obx_err	obx_opt_model_bytes (OBX_store_options *opt, const void *bytes, size_t size)
	Set the model on the options copying the given bytes. The default is no model. More...
OBX_C_API obx_err	obx_opt_model_bytes_direct (OBX_store_options *opt, const void *bytes, size_t size)
	Like obx_opt_model_bytes BUT WITHOUT copying the given bytes. Thus, you must keep the bytes available until after the store is created. More...
OBX_C_API void	obx_opt_validate_on_open_pages (OBX_store_options *opt, size_t page_limit, uint32_t flags)
	When the DB is opened initially, ObjectBox can do a consistency check on the given amount of pages. Reliable file systems already guarantee consistency, so this is primarily meant to deal with unreliable OSes, file systems, or hardware. Thus, usually a low number (e.g. 1-20) is sufficient and does not impact startup performance significantly. To completely disable this you can pass 0, but we recommend a setting of at least 1. Note: ObjectBox builds upon ACID storage, which guarantees consistency given that the file system is working correctly (in particular fsync). More...
OBX_C_API void	obx_opt_validate_on_open_kv (OBX_store_options *opt, uint32_t flags)
	When the DB is opened initially, ObjectBox can do a validation over the key/value pairs to check, for example, whether they're consistent towards our internal specification. More...
OBX_C_API void	obx_opt_put_padding_mode (OBX_store_options *opt, OBXPutPaddingMode mode)
	Don't touch unless you know exactly what you are doing: Advanced setting typically meant for language bindings (not end users). See OBXPutPaddingMode description. More...
OBX_C_API void	obx_opt_read_schema (OBX_store_options *opt, bool value)
	Advanced setting meant only for special scenarios: setting to false causes opening the database in a limited, schema-less mode. If you don't know what this means exactly: ignore this flag. Defaults to true. More...
OBX_C_API void	obx_opt_use_previous_commit (OBX_store_options *opt, bool value)
	Advanced setting recommended to be used together with read-only mode to ensure no data is lost. Ignores the latest data snapshot (committed transaction state) and uses the previous snapshot instead. When used with care (e.g. backup the DB files first), this option may also recover data removed by the latest transaction. Defaults to false. More...
OBX_C_API void	obx_opt_read_only (OBX_store_options *opt, bool value)
	Open store in read-only mode: no schema update, no write transactions. Defaults to false. More...
OBX_C_API void	obx_opt_debug_flags (OBX_store_options *opt, uint32_t flags)
	Configure debug flags (OBXDebugFlags); e.g. to influence logging. Defaults to NONE. Combine multiple flags using bitwise OR. More...
OBX_C_API void	obx_opt_add_debug_flags (OBX_store_options *opt, uint32_t flags)
	Adds debug flags (OBXDebugFlags) to potentially existing ones. Combine multiple flags using bitwise OR. More...
OBX_C_API void	obx_opt_async_max_queue_length (OBX_store_options *opt, size_t value)
	Maximum of async elements in the queue before new elements will be rejected. Hitting this limit usually hints that async processing cannot keep up; data is produced at a faster rate than it can be persisted in the background. In that case, increasing this value is not the only alternative; other values might also optimize throughput. For example, increasing maxInTxDurationMicros may help too. More...
OBX_C_API void	obx_opt_async_throttle_at_queue_length (OBX_store_options *opt, size_t value)
	Producers (AsyncTx submitter) is throttled when the queue size hits this. More...
OBX_C_API void	obx_opt_async_throttle_micros (OBX_store_options *opt, uint32_t value)
	Sleeping time for throttled producers on each submission. More...
OBX_C_API void	obx_opt_async_max_in_tx_duration (OBX_store_options *opt, uint32_t micros)
	Maximum duration spent in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate. More...
OBX_C_API void	obx_opt_async_max_in_tx_operations (OBX_store_options *opt, uint32_t value)
	Maximum operations performed in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate. More...
OBX_C_API void	obx_opt_async_pre_txn_delay (OBX_store_options *opt, uint32_t delay_micros)
	Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations. More...
OBX_C_API void	obx_opt_async_pre_txn_delay4 (OBX_store_options *opt, uint32_t delay_micros, uint32_t delay2_micros, size_t min_queue_length_for_delay2)
	Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations. More...
OBX_C_API void	obx_opt_async_post_txn_delay (OBX_store_options *opt, uint32_t delay_micros)
	Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around. More...
OBX_C_API void	obx_opt_async_post_txn_delay5 (OBX_store_options *opt, uint32_t delay_micros, uint32_t delay2_micros, size_t min_queue_length_for_delay2, bool subtract_processing_time)
	Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around. More...
OBX_C_API void	obx_opt_async_minor_refill_threshold (OBX_store_options *opt, size_t queue_length)
	Numbers of operations below this value are considered "minor refills". More...
OBX_C_API void	obx_opt_async_minor_refill_max_count (OBX_store_options *opt, uint32_t value)
	If non-zero, this allows "minor refills" with small batches that came in (off by default). More...
OBX_C_API void	obx_opt_async_max_tx_pool_size (OBX_store_options *opt, size_t value)
	Default value: 10000, set to 0 to deactivate pooling. More...
OBX_C_API void	obx_opt_async_object_bytes_max_cache_size (OBX_store_options *opt, uint64_t value)
	Total cache size; default: ~ 0.5 MB. More...
OBX_C_API void	obx_opt_async_object_bytes_max_size_to_cache (OBX_store_options *opt, uint64_t value)
	Maximal size for an object to be cached (only cache smaller ones) More...
OBX_C_API void	obx_opt_log_callback (OBX_store_options *opt, obx_log_callback *callback, void *user_data)
	Registers a log callback, which is called for a selection of log events. Note: this does not replace the default logging, which is much more extensive (at least at this point). More...
OBX_C_API void	obx_opt_backup_restore (OBX_store_options *opt, const char *backup_file, uint32_t flags)
	Before opening the database, this options instructs to restore the database content from the given backup file. Note: backup is a server-only feature. By default, actually restoring the backup is only performed if no database already exists (database does not contain data). More...
OBX_C_API void	obx_opt_wal (OBX_store_options *opt, uint32_t flags)
	Enables Write-ahead logging (WAL) if OBXWalFlags_EnableWal is given. For now this is only supported for in-memory DBs. More...
OBX_C_API void	obx_opt_wal_max_file_size_on_open_in_kb (OBX_store_options *opt, uint64_t size_in_kb)
	The WAL file gets consolidated when it reached this size limit when opening the database. This setting is meant for applications that prefer to consolidate on startup, which may avoid consolidations on commits while the application is running. The default is 4096 (4 MB). More...
OBX_C_API void	obx_opt_wal_max_file_size_in_kb (OBX_store_options *opt, uint64_t size_in_kb)
	The WAL file gets consolidated when it reaches this size limit after a commit. As consolidation takes some time, it is a trade-off between accumulating enough data and the time the consolidation takes (longer with more data). The default is 16384 (16 MB). More...
OBX_C_API const char *	obx_opt_get_directory (OBX_store_options *opt)
	Gets the option for "directory"; this is either the default, or, the value set by obx_opt_directory(). The returned value must not be modified and is only valid for the lifetime of the options or until the value is changed. More...
OBX_C_API uint64_t	obx_opt_get_max_db_size_in_kb (OBX_store_options *opt)
	Gets the option for "max DB size"; this is either the default, or, the value set by obx_opt_max_db_size_in_kb(). More...
OBX_C_API uint64_t	obx_opt_get_max_data_size_in_kb (OBX_store_options *opt)
	Gets the option for "max data size"; this is either the default, or, the value set by obx_opt_max_data_size_in_kb(). More...
OBX_C_API uint32_t	obx_opt_get_debug_flags (OBX_store_options *opt)
	Gets the option for "debug flags"; this is either the default, or, the value set by obx_opt_debug_flags(). More...
OBX_C_API void	obx_opt_free (OBX_store_options *opt)
	Free the options. Note: Only free unused options, obx_store_open() frees the options internally. More...
OBX_C_API OBX_store *	obx_store_open (OBX_store_options *opt)
	Opens (creates) a "store", which represents an ObjectBox database instance in a given directory. The store is an entry point to data access APIs such as box (obx_box_*), query (obx_qb_* and obx_query_*), and transaction (obx_txn_*). It's possible to open multiple stores in different directories, e.g. at the same time. See also obx_store_close() to close a previously opened store. Note: the given options are always freed by this function, including when an error occurs. More...
OBX_C_API bool	obx_store_is_open (const char *path)
	Check if an open store was found for the given path (i.e. opened before and not yet closed). More...
OBX_C_API OBX_store *	obx_store_attach (const char *path)
	Attach to a previously opened store matching the path of the DB directory, which was used for opening the store. The returned store is a new instance (e.g. different pointer value) and must also be closed via obx_store_close(). The actual underlying store is only closed when the last store OBX_store instance is closed. More...
OBX_C_API OBX_store *	obx_store_attach_id (uint64_t store_id)
	Attach to a previously opened store matching the given store ID. The returned store is a new instance (e.g. different pointer value) and must also be closed via obx_store_close(). The actual underlying store is only closed when the last store OBX_store instance is closed. More...
OBX_C_API OBX_store *	obx_store_attach_or_open (OBX_store_options *opt, bool check_matching_options, bool *out_attached)
	Combines the functionality of obx_store_attach() and obx_store_open() in a thread-safe way. More...
OBX_C_API uint64_t	obx_store_id (OBX_store *store)
	Store IDs can be used to attach to a store later. The IDs are stable and unique during the lifetime of the process. E.g. these IDs can be shared across threads efficiently and can serve a similar purpose as weak pointers do. More...
OBX_C_API uint64_t	obx_store_size (OBX_store *store)
	Get the size of the store. For a disk-based store type, this corresponds to the size on disk, and for the in-memory store type, this is roughly the used memory bytes occupied by the data. More...
OBX_C_API uint64_t	obx_store_size_on_disk (OBX_store *store)
	The size in bytes occupied by the database on disk (if any). More...
OBX_C_API uint32_t	obx_store_type_id (OBX_store *store)
	Gives the store type ID for the given store. More...
OBX_C_API OBX_store *	obx_store_clone (OBX_store *store)
	Clone a previously opened store; while a store instance is usable from multiple threads, situations may exist in which cloning a store simplifies the overall lifecycle. E.g. when a store is used for multiple threads and it may only be fully released once the last thread completes. The returned store is a new instance (e.g. different pointer value) and must also be closed via obx_store_close(). The actual underlying store is only closed when the last store OBX_store instance is closed. More...
OBX_C_API OBX_store *	obx_store_wrap (void *core_store)
	For stores created outside of this C API, e.g. via C++ or Java, this is how you can use it via C too. Like this, it is OK to use the same store instance (same database) from multiple languages in parallel. Note: the store's life time will still be managed outside of the C API; thus ensure that store is not closed while calling any C function on it. Once you are done with the C specific OBX_store, call obx_store_close() to free any C related resources. This, however, will not close the "core store". More...
OBX_C_API obx_schema_id	obx_store_entity_id (OBX_store *store, const char *entity_name)
	Look for an entity with the given name in the model and return its Entity ID. More...
OBX_C_API obx_schema_id	obx_store_entity_property_id (OBX_store *store, obx_schema_id entity_id, const char *property_name)
	Return the property id from the property name or 0 if the name is not found. More...
OBX_C_API bool	obx_store_await_async_completion (OBX_store *store)
	Await for all (including future) async submissions to be completed (the async queue becomes empty). More...
OBX_C_API bool	obx_store_await_async_submitted (OBX_store *store)
	Await async operations that have been submitted up to this point to be completed (the async queue may still contain elements). More...
OBX_C_API obx_err	obx_store_back_up_to_file (OBX_store *store, const char *backup_file, uint32_t backup_flags)
	Backs up the store DB to the given backup-file, using the given flags. Note: backup is a server-only feature. More...
OBX_C_API obx_err	obx_store_debug_flags (OBX_store *store, uint32_t flags)
	Configure debug logging. More...
OBX_C_API bool	obx_store_opened_with_previous_commit (OBX_store *store)
OBX_C_API obx_err	obx_store_prepare_to_close (OBX_store *store)
	Prepares the store to close by setting its internal state to "closing". Functions relying on the store will result in OBX_ERROR_SHUTTING_DOWN status once closing is initiated. Unlike obx_store_close(), this method will return immediately and does not free resources just yet. This is typically used in a multi-threaded context to allow an orderly shutdown in stages which go through a "not accepting new requests" state. More...
OBX_C_API obx_err	obx_store_close (OBX_store *store)
	Closes a previously opened store and thus freeing all resources associated with the store. More...
OBX_C_API int	obx_store_type_id_register_default (uint32_t storeTypeId)
	Registers the default DB type, which is used if no other types matched a path prefix. More...
OBX_C_API OBX_txn *	obx_txn_write (OBX_store *store)
	Create a write transaction (read and write). Transaction creation can be nested (recursive), however only the outermost transaction is relevant on the DB level. Once you are done tithe the transaction, you must call obx_txn_success() or obx_txn_close(). More...
OBX_C_API OBX_txn *	obx_txn_read (OBX_store *store)
	Create a read transaction (read only). Transaction creation can be nested (recursive), however only the outermost transaction is relevant on the DB level. Once you are done tithe the transaction, you must call obx_txn_close(). More...
OBX_C_API obx_err	obx_txn_success (OBX_txn *txn)
	"Finish" this write transaction successfully and close it, performing a commit if this is the top level transaction and all inner transactions (if any) were also successful (obx_txn_success() was called on them). Because this also closes the given transaction along with all resources, the given OBX_txn pointer becomes invalid. Thus, the OBX_txn pointer must not be used afterwards; do not even call obx_txn_close(). More...
OBX_C_API obx_err	obx_txn_close (OBX_txn *txn)
	Close the transaction (read or write) and free all of its resources; the given OBX_txn pointer must not be used afterwards. If the given transaction is a write transaction, it is aborted (not committed) right away (without waiting for the top level transaction). If an error is returned (e.g., a commit failed because DB is full), you can assume that the transaction was closed. More...
OBX_C_API obx_err	obx_txn_abort (OBX_txn *txn)
	Note: At the moment, you typically want to use only obx_txn_close() instead. Abort the underlying transaction immediately and thus frees DB resources. Only obx_txn_close() is allowed to be called on the transaction after calling this. More...
OBX_C_API obx_err	obx_txn_data_size (OBX_txn *txn, uint64_t *out_committed_size, int64_t *out_size_change)
OBX_C_API OBX_cursor *	obx_cursor (OBX_txn *txn, obx_schema_id entity_id)
OBX_C_API obx_err	obx_cursor_close (OBX_cursor *cursor)
OBX_C_API obx_id	obx_cursor_id_for_put (OBX_cursor *cursor, obx_id id_or_zero)
	Call this when putting an object to generate/prepare an ID for it. More...
OBX_C_API obx_err	obx_cursor_put (OBX_cursor *cursor, obx_id id, const void *data, size_t size)
	Puts the given object data using the given ID. A "put" in ObjectBox follows "insert or update" semantics; New objects (no pre-existing object for given ID) are inserted while existing objects are replaced/updated. More...
OBX_C_API obx_err	obx_cursor_put4 (OBX_cursor *cursor, obx_id id, const void *data, size_t size, OBXPutMode mode)
	Like put obx_cursor_put(), but takes an additional parameter (4th parameter) for choosing a put mode. More...
OBX_C_API obx_err	obx_cursor_put_new (OBX_cursor *cursor, obx_id id, const void *data, size_t size)
	An optimized version of obx_cursor_put() if you can ensure that the given ID is not used yet. Typically used right after getting a new ID via obx_cursor_id_for_put(). WARNING: using this incorrectly (an object with the given ID already exists) may result in inconsistent data (e.g. indexes do not get updated). More...
OBX_C_API obx_err	obx_cursor_insert (OBX_cursor *cursor, obx_id id, const void *data, size_t size)
	Convenience for obx_cursor_put4() with OBXPutMode_INSERT. More...
OBX_C_API obx_err	obx_cursor_update (OBX_cursor *cursor, obx_id id, const void *data, size_t size)
	Convenience for obx_cursor_put4() with OBXPutMode_UPDATE. More...
OBX_C_API obx_id	obx_cursor_put_object (OBX_cursor *cursor, void *data, size_t size)
	FB ID slot must be present; new entities must prepare the slot using the special value OBX_ID_NEW. Alternatively, you may also pass 0 to indicate a new entity if you are aware that FlatBuffers builders typically skip zero values by default. Thus, you have to "force" writing the zero in FlatBuffers. More...
OBX_C_API obx_id	obx_cursor_put_object4 (OBX_cursor *cursor, void *data, size_t size, OBXPutMode mode)
OBX_C_API obx_err	obx_cursor_get (OBX_cursor *cursor, obx_id id, const void **data, size_t *size)
OBX_C_API OBX_bytes_array *	obx_cursor_get_all (OBX_cursor *cursor)
	Get all objects as bytes. For larger quantities, it's recommended to iterate using obx_cursor_first and obx_cursor_next. However, if the calling overhead is high (e.g., for language bindings), this method helps. More...
OBX_C_API obx_err	obx_cursor_first (OBX_cursor *cursor, const void **data, size_t *size)
OBX_C_API obx_err	obx_cursor_next (OBX_cursor *cursor, const void **data, size_t *size)
OBX_C_API obx_err	obx_cursor_seek (OBX_cursor *cursor, obx_id id)
OBX_C_API obx_err	obx_cursor_current (OBX_cursor *cursor, const void **data, size_t *size)
OBX_C_API obx_err	obx_cursor_remove (OBX_cursor *cursor, obx_id id)
OBX_C_API obx_err	obx_cursor_remove_all (OBX_cursor *cursor)
OBX_C_API obx_err	obx_cursor_count (OBX_cursor *cursor, uint64_t *count)
	Count the number of available objects. More...
OBX_C_API obx_err	obx_cursor_count_max (OBX_cursor *cursor, uint64_t max_count, uint64_t *out_count)
	Count the number of available objects up to the specified maximum. More...
OBX_C_API obx_err	obx_cursor_is_empty (OBX_cursor *cursor, bool *out_is_empty)
	Return true if there is no object available (false if at least one object is available) More...
OBX_C_API OBX_bytes_array *	obx_cursor_backlinks (OBX_cursor *cursor, obx_schema_id entity_id, obx_schema_id property_id, obx_id id)
OBX_C_API OBX_id_array *	obx_cursor_backlink_ids (OBX_cursor *cursor, obx_schema_id entity_id, obx_schema_id property_id, obx_id id)
OBX_C_API obx_err	obx_cursor_rel_put (OBX_cursor *cursor, obx_schema_id relation_id, obx_id source_id, obx_id target_id)
OBX_C_API obx_err	obx_cursor_rel_remove (OBX_cursor *cursor, obx_schema_id relation_id, obx_id source_id, obx_id target_id)
OBX_C_API OBX_id_array *	obx_cursor_rel_ids (OBX_cursor *cursor, obx_schema_id relation_id, obx_id source_id)
OBX_C_API obx_err	obx_cursor_seek_first_id (OBX_cursor *cursor, obx_id *out_id)
	Gets the first object ID or zero if there was no object. More...
OBX_C_API obx_err	obx_cursor_seek_next_id (OBX_cursor *cursor, obx_id *out_id)
	Gets the next object ID or zero if there was no next object. More...
OBX_C_API obx_err	obx_cursor_current_id (OBX_cursor *cursor, obx_id *out_id)
	Gets the object ID at the current position; ensures being up-to-date by verifying against database. More...
OBX_C_API obx_err	obx_cursor_ts_min_max (OBX_cursor *cursor, obx_id *out_min_id, int64_t *out_min_value, obx_id *out_max_id, int64_t *out_max_value)
	Time series: get the limits (min/max time values) over all objects. More...
OBX_C_API obx_err	obx_cursor_ts_min_max_range (OBX_cursor *cursor, int64_t range_begin, int64_t range_end, obx_id *out_min_id, int64_t *out_min_value, obx_id *out_max_id, int64_t *out_max_value)
	Time series: get the limits (min/max time values) over objects within the given time range. More...
OBX_C_API OBX_box *	obx_box (OBX_store *store, obx_schema_id entity_id)
	Get access to the box for the given entity. A box may be used across threads. Boxes are shared instances and managed by the store so there's no need to close/free them manually. More...
OBX_C_API OBX_store *	obx_box_store (OBX_box *box)
	Get access to the store this box belongs to - utility for when you only have access to the box variable but need some store method, such as starting a transaction. This doesn't produce a new instance of OBX_store, just gives you back the same pointer you've created this box with. In other words, don't close the returned store separately. More...
OBX_C_API obx_err	obx_box_contains (OBX_box *box, obx_id id, bool *out_contains)
	Check whether a given object exists in the box. More...
OBX_C_API obx_err	obx_box_contains_many (OBX_box *box, const OBX_id_array *ids, bool *out_contains)
	Check whether this box contains objects with all of the IDs given. More...
OBX_C_API obx_err	obx_box_get (OBX_box *box, obx_id id, const void **data, size_t *size)
	Fetch a single object from the box; must be called inside a (reentrant) transaction. The exposed data comes directly from the OS to allow zero-copy access, which limits the data lifetime: More...
OBX_C_API OBX_bytes_array *	obx_box_get_many (OBX_box *box, const OBX_id_array *ids)
	Fetch multiple objects for the given IDs from the box; must be called inside a (reentrant) transaction. More...
OBX_C_API OBX_bytes_array *	obx_box_get_all (OBX_box *box)
	Fetch all objects from the box; must be called inside a (reentrant) transaction. NOTE: don't call this in 32 bit mode! Use obx_box_visit_all() instead. More...
OBX_C_API obx_err	obx_box_visit_many (OBX_box *box, const OBX_id_array *ids, obx_data_visitor *visitor, void *user_data)
	Read given objects from the database in a single transaction. Call the visitor() on each object, passing user_data, object data & size as arguments. The given visitor must return true to keep receiving results, false to cancel. If an object is not found, the visitor() is still called, passing NULL as data and a 0 as size. More...
OBX_C_API obx_err	obx_box_visit_all (OBX_box *box, obx_data_visitor *visitor, void *user_data)
	Read all objects in a single transaction. Calls the visitor() on each object, passing visitor_arg, object data & size as arguments. The given visitor must return true to keep receiving results, false to cancel. More...
OBX_C_API obx_id	obx_box_id_for_put (OBX_box *box, obx_id id_or_zero)
	Prepares an ID for insertion: pass in 0 (zero) to reserve a new ID or an existing ID to check/prepare it. More...
OBX_C_API obx_err	obx_box_ids_for_put (OBX_box *box, uint64_t count, obx_id *out_first_id)
	Reserve the given number of (new) IDs for insertion; a bulk version of obx_box_id_for_put(). More...
OBX_C_API obx_err	obx_box_put (OBX_box *box, obx_id id, const void *data, size_t size)
	Put the given object using the given ID synchronously; note that the ID also must match the one present in data. More...
OBX_C_API obx_err	obx_box_insert (OBX_box *box, obx_id id, const void *data, size_t size)
	Convenience for obx_box_put5() with OBXPutMode_INSERT. More...
OBX_C_API obx_err	obx_box_update (OBX_box *box, obx_id id, const void *data, size_t size)
	Convenience for obx_cursor_put4() with OBXPutMode_UPDATE. More...
OBX_C_API obx_err	obx_box_put5 (OBX_box *box, obx_id id, const void *data, size_t size, OBXPutMode mode)
	Put the given object using the given ID synchronously; note that the ID also must match the one present in data. More...
OBX_C_API obx_id	obx_box_put_object (OBX_box *box, void *data, size_t size)
	FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW. More...
OBX_C_API obx_id	obx_box_put_object4 (OBX_box *box, void *data, size_t size, OBXPutMode mode)
	FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW. More...
OBX_C_API obx_err	obx_box_put_many (OBX_box *box, const OBX_bytes_array *objects, const obx_id *ids, OBXPutMode mode)
	Put all given objects in the database in a single transaction. If any of the individual objects failed to put, none are put and an error is returned, equivalent to calling obx_box_put_many5() with fail_on_id_failure=true. More...
OBX_C_API obx_err	obx_box_put_many5 (OBX_box *box, const OBX_bytes_array *objects, const obx_id *ids, OBXPutMode mode, bool fail_on_id_failure)
	Like obx_box_put_many(), but with an additional flag indicating how to treat ID failures with OBXPutMode_INSERT and OBXPutMode_UPDATE. More...
OBX_C_API obx_err	obx_box_remove (OBX_box *box, obx_id id)
	Remove a single object will return OBX_NOT_FOUND if an object with the given ID doesn't exist. More...
OBX_C_API obx_err	obx_box_remove_many (OBX_box *box, const OBX_id_array *ids, uint64_t *out_count)
	Remove all given objects from the database in a single transaction. Note that this method will not fail if the object is not found (e.g. already removed). In case you need to strictly check whether all of the objects exist before removing them, execute obx_box_contains_ids() and obx_box_remove_ids() inside a single write transaction. More...
OBX_C_API obx_err	obx_box_remove_all (OBX_box *box, uint64_t *out_count)
	Remove all objects and set the out_count the the number of removed objects. More...
OBX_C_API obx_err	obx_box_is_empty (OBX_box *box, bool *out_is_empty)
	Check whether there are any objects for this entity and updates the out_is_empty accordingly. More...
OBX_C_API obx_err	obx_box_count (OBX_box *box, uint64_t limit, uint64_t *out_count)
	Count the number of objects in the box, up to the given maximum. You can pass limit=0 to count all objects without any limitation. More...
OBX_C_API OBX_id_array *	obx_box_get_backlink_ids (OBX_box *box, obx_schema_id property_id, obx_id id)
	Fetch IDs of all objects that link back to the given object (ID) using the given relation property (ID). Note: This method refers to "property based relations" unlike the "stand-alone relations" (see obx_box_rel_*). More...
OBX_C_API obx_err	obx_box_rel_put (OBX_box *box, obx_schema_id relation_id, obx_id source_id, obx_id target_id)
	Insert a standalone relation entry between two objects. More...
OBX_C_API obx_err	obx_box_rel_remove (OBX_box *box, obx_schema_id relation_id, obx_id source_id, obx_id target_id)
	Remove a standalone relation entry between two objects. See obx_box_rel_put() for parameters documentation. More...
OBX_C_API OBX_id_array *	obx_box_rel_get_ids (OBX_box *box, obx_schema_id relation_id, obx_id id)
	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. More...
OBX_C_API OBX_id_array *	obx_box_rel_get_backlink_ids (OBX_box *box, obx_schema_id relation_id, obx_id id)
	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. More...
OBX_C_API obx_err	obx_expired_objects_remove (OBX_txn *txn, obx_schema_id entity_id, size_t *out_removed_count)
	Removes expired objects of one or all entity types. More...
OBX_C_API obx_err	obx_expired_objects_remove_async (OBX_store *store, obx_schema_id entity_id, obx_status_callback *callback, void *user_data)
	Asynchronously removes expired objects of one or all entity types. More...
OBX_C_API obx_err	obx_box_ts_min_max (OBX_box *box, obx_id *out_min_id, int64_t *out_min_value, obx_id *out_max_id, int64_t *out_max_value)
	Time series: get the limits (min/max time values) over all objects. More...
OBX_C_API obx_err	obx_box_ts_min_max_range (OBX_box *box, int64_t range_begin, int64_t range_end, obx_id *out_min_id, int64_t *out_min_value, obx_id *out_max_id, int64_t *out_max_value)
	Time series: get the limits (min/max time values) over objects within the given time range. More...
OBX_C_API OBX_async *	obx_async (OBX_box *box)
	Note: DO NOT close this OBX_async; its lifetime is tied to the OBX_box instance. More...
OBX_C_API obx_err	obx_async_put (OBX_async *async, obx_id id, const void *data, size_t size)
	Put asynchronously with standard put semantics (insert or update). More...
OBX_C_API obx_err	obx_async_put5 (OBX_async *async, obx_id id, const void *data, size_t size, OBXPutMode mode)
	Put asynchronously using the given mode. More...
OBX_C_API obx_err	obx_async_insert (OBX_async *async, obx_id id, const void *data, size_t size)
	Put asynchronously with inserts semantics (won't put if object already exists). More...
OBX_C_API obx_err	obx_async_update (OBX_async *async, obx_id id, const void *data, size_t size)
	Put asynchronously with update semantics (won't put if object is not yet present). More...
OBX_C_API obx_id	obx_async_put_object (OBX_async *async, void *data, size_t size)
	Reserve an ID, which is returned immediately for future reference, and put asynchronously. Note: of course, it can NOT be guaranteed that the entity will actually be put successfully in the DB. More...
OBX_C_API obx_id	obx_async_put_object4 (OBX_async *async, void *data, size_t size, OBXPutMode mode)
	FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW. More...
OBX_C_API obx_id	obx_async_insert_object (OBX_async *async, void *data, size_t size)
	Reserve an ID, which is returned immediately for future reference, and insert asynchronously. Note: of course, it can NOT be guaranteed that the entity will actually be inserted successfully in the DB. More...
OBX_C_API obx_err	obx_async_remove (OBX_async *async, obx_id id)
	Remove asynchronously. More...
OBX_C_API OBX_async *	obx_async_create (OBX_box *box, uint64_t enqueue_timeout_millis)
	Create a custom OBX_async instance that has to be closed using obx_async_close(). Note: for standard tasks, prefer obx_box_async() giving you a shared instance that does not have to be closed. More...
OBX_C_API obx_err	obx_async_close (OBX_async *async)
	Close a custom OBX_async instance created with obx_async_create(). More...
OBX_C_API OBX_query_builder *	obx_query_builder (OBX_store *store, obx_schema_id entity_id)
	Create a query builder which is used to collect conditions using the obx_qb_* functions. Once all conditions are applied, use obx_query() to build a OBX_query that is used to actually retrieve data. Use obx_qb_close() to close (free) the query builder. More...
OBX_C_API obx_err	obx_qb_close (OBX_query_builder *builder)
	Close the query builder; note that OBX_query objects outlive their builder and thus are not affected by this call. More...
OBX_C_API obx_schema_id	obx_qb_type_id (OBX_query_builder *builder)
OBX_C_API obx_err	obx_qb_error_code (OBX_query_builder *builder)
	To minimise the amount of error handling code required when building a query, the first error is stored in the query and can be obtained here. All the obx_qb_XXX functions are null operations after the first query error has occurred. More...
OBX_C_API const char *	obx_qb_error_message (OBX_query_builder *builder)
	To minimise the amount of error handling code required when building a query, the first error is stored in the query and can be obtained here. All the obx_qb_XXX functions are null operations after the first query error has occurred. More...
OBX_C_API obx_qb_cond	obx_qb_null (OBX_query_builder *builder, obx_schema_id property_id)
	Add null check to the query. More...
OBX_C_API obx_qb_cond	obx_qb_not_null (OBX_query_builder *builder, obx_schema_id property_id)
	Add not-null check to the query. More...
OBX_C_API obx_qb_cond	obx_qb_equals_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
	For string and flex properties, this looks for a value equal to the given one. More...
OBX_C_API obx_qb_cond	obx_qb_not_equals_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
OBX_C_API obx_qb_cond	obx_qb_contains_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
OBX_C_API obx_qb_cond	obx_qb_contains_element_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
	For container types (e.g. string vector or flex), this looks for a element that equals the given string. More...
OBX_C_API obx_qb_cond	obx_qb_contains_key_value_string (OBX_query_builder *builder, obx_schema_id property_id, const char *key, const char *value, bool case_sensitive)
	For flex properties that have a map as root value, this looks for matching key/value pair. More...
OBX_C_API obx_qb_cond	obx_qb_starts_with_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
OBX_C_API obx_qb_cond	obx_qb_ends_with_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
OBX_C_API obx_qb_cond	obx_qb_greater_than_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
OBX_C_API obx_qb_cond	obx_qb_greater_or_equal_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
OBX_C_API obx_qb_cond	obx_qb_less_than_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
OBX_C_API obx_qb_cond	obx_qb_less_or_equal_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
OBX_C_API obx_qb_cond	obx_qb_in_strings (OBX_query_builder *builder, obx_schema_id property_id, const char *const values[], size_t count, bool case_sensitive)
	Note that all string values are copied and thus do not need to be maintained by the calling code. More...
OBX_C_API obx_qb_cond	obx_qb_any_equals_string (OBX_query_builder *builder, obx_schema_id property_id, const char *value, bool case_sensitive)
	For OBXPropertyType_StringVector - matches if at least one vector item equals the given value. More...
OBX_C_API obx_qb_cond	obx_qb_equals_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
OBX_C_API obx_qb_cond	obx_qb_not_equals_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
OBX_C_API obx_qb_cond	obx_qb_greater_than_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
OBX_C_API obx_qb_cond	obx_qb_greater_or_equal_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
OBX_C_API obx_qb_cond	obx_qb_less_than_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
OBX_C_API obx_qb_cond	obx_qb_less_or_equal_int (OBX_query_builder *builder, obx_schema_id property_id, int64_t value)
OBX_C_API obx_qb_cond	obx_qb_between_2ints (OBX_query_builder *builder, obx_schema_id property_id, int64_t value_a, int64_t value_b)
OBX_C_API obx_qb_cond	obx_qb_in_int64s (OBX_query_builder *builder, obx_schema_id property_id, const int64_t values[], size_t count)
	Note that all values are copied and thus do not need to be maintained by the calling code. More...
OBX_C_API obx_qb_cond	obx_qb_not_in_int64s (OBX_query_builder *builder, obx_schema_id property_id, const int64_t values[], size_t count)
	Note that all values are copied and thus do not need to be maintained by the calling code. More...
OBX_C_API obx_qb_cond	obx_qb_in_int32s (OBX_query_builder *builder, obx_schema_id property_id, const int32_t values[], size_t count)
	Note that all values are copied and thus do not need to be maintained by the calling code. More...
OBX_C_API obx_qb_cond	obx_qb_not_in_int32s (OBX_query_builder *builder, obx_schema_id property_id, const int32_t values[], size_t count)
	Note that all values are copied and thus do not need to be maintained by the calling code. More...
OBX_C_API obx_qb_cond	obx_qb_greater_than_double (OBX_query_builder *builder, obx_schema_id property_id, double value)
OBX_C_API obx_qb_cond	obx_qb_greater_or_equal_double (OBX_query_builder *builder, obx_schema_id property_id, double value)
OBX_C_API obx_qb_cond	obx_qb_less_than_double (OBX_query_builder *builder, obx_schema_id property_id, double value)
OBX_C_API obx_qb_cond	obx_qb_less_or_equal_double (OBX_query_builder *builder, obx_schema_id property_id, double value)
OBX_C_API obx_qb_cond	obx_qb_between_2doubles (OBX_query_builder *builder, obx_schema_id property_id, double value_a, double value_b)
OBX_C_API obx_qb_cond	obx_qb_equals_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
OBX_C_API obx_qb_cond	obx_qb_greater_than_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
OBX_C_API obx_qb_cond	obx_qb_greater_or_equal_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
OBX_C_API obx_qb_cond	obx_qb_less_than_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
OBX_C_API obx_qb_cond	obx_qb_less_or_equal_bytes (OBX_query_builder *builder, obx_schema_id property_id, const void *value, size_t size)
OBX_C_API obx_qb_cond	obx_qb_relation_count_property (OBX_query_builder *builder, obx_schema_id relation_entity_id, obx_schema_id relation_property_id, uint32_t relation_count)
	An object matches, if it has a given number of related objects pointing to it. At this point, there are a couple of limitations (later version may improve on that): 1) 1:N relations only, 2) the complexity is O(n * (relationCount + 1)) and cannot be improved via indexes, 3) The relation count cannot be set as an parameter. More...
OBX_C_API obx_qb_cond	obx_qb_all (OBX_query_builder *builder, const obx_qb_cond conditions[], size_t count)
	Combine conditions[] to a new condition using operator AND (all). More...
OBX_C_API obx_qb_cond	obx_qb_any (OBX_query_builder *builder, const obx_qb_cond conditions[], size_t count)
	Combine conditions[] to a new condition using operator OR (any). More...
OBX_C_API obx_err	obx_qb_param_alias (OBX_query_builder *builder, const char *alias)
	Create an alias for the previous condition (the one added just before calling this function). This is useful when you have a query with multiple conditions of the same property (e.g. height < 20 or height > 50) and you want to use obx_query_param_* to change the values. Consider the following simplified example. More...
OBX_C_API obx_err	obx_qb_order (OBX_query_builder *builder, obx_schema_id property_id, uint32_t flags)
	Configures an order of results in the query. More...
OBX_C_API OBX_query_builder *	obx_qb_link_property (OBX_query_builder *builder, obx_schema_id property_id)
	Create a link based on a property-relation (many-to-one) More...
OBX_C_API OBX_query_builder *	obx_qb_backlink_property (OBX_query_builder *builder, obx_schema_id source_entity_id, obx_schema_id source_property_id)
	Create a backlink based on a property-relation used in reverse (one-to-many) More...
OBX_C_API OBX_query_builder *	obx_qb_link_standalone (OBX_query_builder *builder, obx_schema_id relation_id)
	Create a link based on a standalone relation (many-to-many) More...
OBX_C_API OBX_query_builder *	obx_qb_backlink_standalone (OBX_query_builder *builder, obx_schema_id relation_id)
	Create a backlink based on a standalone relation (many-to-many, reverse direction) More...
OBX_C_API OBX_query_builder *	obx_qb_link_time (OBX_query_builder *builder, obx_schema_id linked_entity_id, obx_schema_id begin_property_id, obx_schema_id end_property_id)
	Link the (time series) entity type to another entity space using a time point or range defined in the given linked entity type and properties. Note: time series functionality must be available to use this. More...
OBX_C_API obx_qb_cond	obx_qb_nearest_neighbors_f32 (OBX_query_builder *builder, obx_schema_id vector_property_id, const float *query_vector, size_t max_result_count)
	Performs an approximate nearest neighbor (ANN) search to find objects near to the given query_vector. This requires the vector property to have a HNSW index. More...
OBX_C_API OBX_query *	obx_query (OBX_query_builder *builder)
OBX_C_API obx_err	obx_query_close (OBX_query *query)
	Close the query and free resources. More...
OBX_C_API OBX_query *	obx_query_clone (OBX_query *query)
	Create a clone of the given query such that it can be run on a separate thread. More...
OBX_C_API obx_err	obx_query_offset (OBX_query *query, size_t offset)
	Configure an offset for this query - all methods that support offset will return/process objects starting at this offset. Example use case: use together with limit to get a slice of the whole result, e.g. for "result paging". Call with offset=0 to reset to the default behavior, i.e. starting from the first element. More...
OBX_C_API obx_err	obx_query_offset_limit (OBX_query *query, size_t offset, size_t limit)
	Configure an offset and a limit for this query - all methods that support an offset/limit will return/process objects starting at this offset and up to the given limit. Example use case: get a slice of the whole result, e.g. for "result paging". Call with offset/limit=0 to reset to the default behavior, i.e. starting from the first element without limit. More...
OBX_C_API obx_err	obx_query_limit (OBX_query *query, size_t limit)
	Configure a limit for this query - all methods that support limit will return/process only the given number of objects. Example use case: use together with offset to get a slice of the whole result, e.g. for "result paging". Call with limit=0 to reset to the default behavior - zero limit means no limit applied. More...
OBX_C_API OBX_bytes_array *	obx_query_find (OBX_query *query)
	Find objects matching the query. NOTE: You must use an explicit transaction and the returned data is only valid as long the transaction is active! Note: if no order conditions is present, the order is arbitrary (sometimes ordered by ID, but never guaranteed to). More...
OBX_C_API OBX_bytes_score_array *	obx_query_find_with_scores (OBX_query *query)
	Find objects matching the query associated to their query score (e.g. distance in NN search). The resulting array is sorted by score in ascending order (unlike obx_query_find()). More...
OBX_C_API OBX_id_score_array *	obx_query_find_ids_with_scores (OBX_query *query)
	Find object IDs matching the query associated to their query score (e.g. distance in NN search). The resulting array is sorted by score in ascending order (unlike obx_query_find_ids()). More...
OBX_C_API OBX_id_array *	obx_query_find_ids_by_score (OBX_query *query)
	Find object IDs matching the query ordered by their query score (e.g. distance in NN search). The resulting array is sorted by score in ascending order (unlike obx_query_find_ids()). Unlike obx_query_find_ids_with_scores(), this method returns a simple array of IDs without scores. More...
OBX_C_API obx_err	obx_query_find_first (OBX_query *query, const void **data, size_t *size)
	Find the first object matching the query. More...
OBX_C_API obx_err	obx_query_find_unique (OBX_query *query, const void **data, size_t *size)
	Find the only object matching the query. More...
OBX_C_API obx_err	obx_query_visit (OBX_query *query, obx_data_visitor *visitor, void *user_data)
	Walk over matching objects one-by-one using the given data visitor (a callback function). Note: if no order conditions is present, the order is arbitrary (sometimes ordered by ID, but never guaranteed to). More...
OBX_C_API obx_err	obx_query_visit_with_score (OBX_query *query, obx_data_score_visitor *visitor, void *user_data)
	Walk over matching objects with their query score one-by-one using the given data visitor (a callback function). Note: the elements are ordered by the score (ascending). More...
OBX_C_API OBX_id_array *	obx_query_find_ids (OBX_query *query)
	Return the IDs of all matching objects. Note: if no order conditions is present, the order is arbitrary (sometimes ordered by ID, but never guaranteed to). More...
OBX_C_API obx_err	obx_query_count (OBX_query *query, uint64_t *out_count)
	Return the number of matching objects. More...
OBX_C_API obx_err	obx_query_remove (OBX_query *query, uint64_t *out_count)
	Remove all matching objects from the database & return the number of deleted objects. More...
OBX_C_API const char *	obx_query_describe (OBX_query *query)
	The returned char* is valid until another call to describe() is made on the query or until the query is freed. More...
OBX_C_API const char *	obx_query_describe_params (OBX_query *query)
	The returned char* is valid until another call to describe_params() is made on the query or until the query is freed. More...
OBX_C_API obx_err	obx_query_cursor_visit (OBX_query *query, OBX_cursor *cursor, obx_data_visitor *visitor, void *user_data)
OBX_C_API OBX_bytes_array *	obx_query_cursor_find (OBX_query *query, OBX_cursor *cursor)
	Find entities matching the query; NOTE: the returned data is only valid as long the transaction is active! More...
OBX_C_API OBX_id_array *	obx_query_cursor_find_ids (OBX_query *query, OBX_cursor *cursor)
OBX_C_API obx_err	obx_query_cursor_count (OBX_query *query, OBX_cursor *cursor, uint64_t *out_count)
OBX_C_API obx_err	obx_query_cursor_remove (OBX_query *query, OBX_cursor *cursor, uint64_t *out_count)
	Remove (delete!) all matching objects. More...
OBX_C_API obx_err	obx_query_param_string (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const char *value)
OBX_C_API obx_err	obx_query_param_2strings (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const char *value, const char *value2)
OBX_C_API obx_err	obx_query_param_strings (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const char *const values[], size_t count)
OBX_C_API obx_err	obx_query_param_int (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, int64_t value)
OBX_C_API obx_err	obx_query_param_2ints (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, int64_t value_a, int64_t value_b)
OBX_C_API obx_err	obx_query_param_int64s (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const int64_t values[], size_t count)
OBX_C_API obx_err	obx_query_param_int32s (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const int32_t values[], size_t count)
OBX_C_API obx_err	obx_query_param_double (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, double value)
OBX_C_API obx_err	obx_query_param_2doubles (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, double value_a, double value_b)
OBX_C_API obx_err	obx_query_param_bytes (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const void *value, size_t size)
OBX_C_API obx_err	obx_query_param_vector_float32 (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id, const float *value, size_t element_count)
OBX_C_API size_t	obx_query_param_get_type_size (OBX_query *query, obx_schema_id entity_id, obx_schema_id property_id)
	Gets the size of the property type used in a query condition. A typical use case of this is to allow language bindings (e.g. Swift) use the right type (e.g. 32 bit ints) even if the language has a bias towards another type (e.g. 64 bit ints). More...
OBX_C_API obx_err	obx_query_param_alias_string (OBX_query *query, const char *alias, const char *value)
OBX_C_API obx_err	obx_query_param_alias_strings (OBX_query *query, const char *alias, const char *const values[], size_t count)
OBX_C_API obx_err	obx_query_param_alias_int (OBX_query *query, const char *alias, int64_t value)
OBX_C_API obx_err	obx_query_param_alias_2ints (OBX_query *query, const char *alias, int64_t value_a, int64_t value_b)
OBX_C_API obx_err	obx_query_param_alias_int64s (OBX_query *query, const char *alias, const int64_t values[], size_t count)
OBX_C_API obx_err	obx_query_param_alias_int32s (OBX_query *query, const char *alias, const int32_t values[], size_t count)
OBX_C_API obx_err	obx_query_param_alias_double (OBX_query *query, const char *alias, double value)
OBX_C_API obx_err	obx_query_param_alias_2doubles (OBX_query *query, const char *alias, double value_a, double value_b)
OBX_C_API obx_err	obx_query_param_alias_bytes (OBX_query *query, const char *alias, const void *value, size_t size)
OBX_C_API obx_err	obx_query_param_alias_vector_float32 (OBX_query *query, const char *alias, const float *value, size_t element_count)
OBX_C_API size_t	obx_query_param_alias_get_type_size (OBX_query *query, const char *alias)
	Gets the size of the property type used in a query condition. A typical use case of this is to allow language bindings (e.g. Swift) use the right type (e.g. 32 bit ints) even if the language has a bias towards another type (e.g. 64 bit ints). More...
OBX_C_API OBX_query_prop *	obx_query_prop (OBX_query *query, obx_schema_id property_id)
	Create a "property query" with results referring to single property (not complete objects). Also provides aggregates like for example obx_query_prop_avg(). More...
OBX_C_API obx_err	obx_query_prop_close (OBX_query_prop *query)
	Close the property query and release resources. More...
OBX_C_API obx_err	obx_query_prop_distinct (OBX_query_prop *query, bool distinct)
	Configure the property query to work only on distinct values. More...
OBX_C_API obx_err	obx_query_prop_distinct_case (OBX_query_prop *query, bool distinct, bool case_sensitive)
	Configure the property query to work only on distinct values. This version is reserved for string properties and defines the case sensitivity for distinctness. More...
OBX_C_API obx_err	obx_query_prop_count (OBX_query_prop *query, uint64_t *out_count)
	Count the number of non-NULL values of the given property across all objects matching the query. More...
OBX_C_API obx_err	obx_query_prop_avg (OBX_query_prop *query, double *out_average, int64_t *out_count)
	Calculate an average value for the given numeric property across all objects matching the query. More...
OBX_C_API obx_err	obx_query_prop_avg_int (OBX_query_prop *query, int64_t *out_average, int64_t *out_count)
	Calculate an average value for the given numeric property across all objects matching the query. More...
OBX_C_API obx_err	obx_query_prop_min (OBX_query_prop *query, double *out_minimum, int64_t *out_count)
	Find the minimum value of the given floating-point property across all objects matching the query. More...
OBX_C_API obx_err	obx_query_prop_max (OBX_query_prop *query, double *out_maximum, int64_t *out_count)
	Find the maximum value of the given floating-point property across all objects matching the query. More...
OBX_C_API obx_err	obx_query_prop_sum (OBX_query_prop *query, double *out_sum, int64_t *out_count)
	Calculate the sum of the given floating-point property across all objects matching the query. More...
OBX_C_API obx_err	obx_query_prop_min_int (OBX_query_prop *query, int64_t *out_minimum, int64_t *out_count)
	Find the minimum value of the given property across all objects matching the query. More...
OBX_C_API obx_err	obx_query_prop_max_int (OBX_query_prop *query, int64_t *out_maximum, int64_t *out_count)
	Find the maximum value of the given property across all objects matching the query. More...
OBX_C_API obx_err	obx_query_prop_sum_int (OBX_query_prop *query, int64_t *out_sum, int64_t *out_count)
	Calculate the sum of the given property across all objects matching the query. More...
OBX_C_API OBX_string_array *	obx_query_prop_find_strings (OBX_query_prop *query, const char *value_if_null)
	Return an array of strings stored as the given property across all objects matching the query. More...
OBX_C_API OBX_int64_array *	obx_query_prop_find_int64s (OBX_query_prop *query, const int64_t *value_if_null)
	Return an array of ints stored as the given property across all objects matching the query. More...
OBX_C_API OBX_int32_array *	obx_query_prop_find_int32s (OBX_query_prop *query, const int32_t *value_if_null)
	Return an array of ints stored as the given property across all objects matching the query. More...
OBX_C_API OBX_int16_array *	obx_query_prop_find_int16s (OBX_query_prop *query, const int16_t *value_if_null)
	Return an array of ints stored as the given property across all objects matching the query. More...
OBX_C_API OBX_int8_array *	obx_query_prop_find_int8s (OBX_query_prop *query, const int8_t *value_if_null)
	Return an array of ints stored as the given property across all objects matching the query. More...
OBX_C_API OBX_double_array *	obx_query_prop_find_doubles (OBX_query_prop *query, const double *value_if_null)
	Return an array of doubles stored as the given property across all objects matching the query. More...
OBX_C_API OBX_float_array *	obx_query_prop_find_floats (OBX_query_prop *query, const float *value_if_null)
	Return an array of int stored as the given property across all objects matching the query. More...
OBX_C_API OBX_observer *	obx_observe (OBX_store *store, obx_observer *callback, void *user_data)
	Create an observer (callback) to be notified about all data changes (for all object types). The callback is invoked right after a successful commit. More...
OBX_C_API OBX_observer *	obx_observe_single_type (OBX_store *store, obx_schema_id type_id, obx_observer_single_type *callback, void *user_data)
	Create an observer (callback) to be notified about data changes for a given object type. The callback is invoked right after a successful commit. More...
OBX_C_API obx_err	obx_observer_close (OBX_observer *observer)
	Free the memory used by the given observer and unsubscribe it from its box or query. More...
OBX_C_API OBX_tree_options *	obx_tree_options ()
	Creates a options object that is passed to tree creation via obx_tree(). More...
OBX_C_API void	obx_tree_options_free (OBX_tree_options *options)
	Free the tree options if they were not used (and "consumed") by obx_tree(). Note: Only free unused options, obx_tree() frees the options internally. More...
OBX_C_API obx_err	obx_tree_opt_path_delimiter (OBX_tree_options *options, char path_delimiter)
	Adjusts the path delimiter character, which is by default "/". More...
OBX_C_API obx_err	obx_tree_opt_flags (OBX_tree_options *options, uint32_t flags)
	Sets the given OBXTreeOptionFlags at the tree options. Combine multiple flags using bitwise OR. More...
OBX_C_API OBX_tree *	obx_tree (OBX_store *store, OBX_tree_options *options)
	Creates a tree for the given store. More...
OBX_C_API void	obx_tree_close (OBX_tree *tree)
OBX_C_API OBX_tree_cursor *	obx_tree_cursor (OBX_tree *tree, OBX_txn *txn)
	To get/put data from tree, you need to create a tree cursor using this method. More...
OBX_C_API size_t	obx_tree_node_conflict_count (OBX_tree *tree)
	Gets the number of currently tracked node conflicts (non-unique nodes at the same path). This count gets resent when conflicts get consolidated. Only tracked if OBXTreeOptionFlags_DetectNonUniqueNodes (or OBXTreeOptionFlags_AutoConsolidateNonUniqueNodes) is set. More...
OBX_C_API void	obx_tree_cursor_close (OBX_tree_cursor *cursor)
	Closes the tree cursor, e.g. before a transaction is ending. The cursor cannot be used afterwards (consider obx_tree_cursor_reset() if you want to keep using it). More...
OBX_C_API obx_err	obx_tree_cursor_txn (OBX_tree_cursor *cursor, OBX_txn *txn)
	Sets or clears a transaction from the tree cursor. More...
OBX_C_API obx_err	obx_tree_cursor_get_raw (OBX_tree_cursor *cursor, const char *path, const void **data, size_t *size, const void **metadata, size_t *metadata_size)
	A "low-level" get operation to access a tree leaf using the raw FlatBuffer bytes stored in the database. As usual, the data is only valid during the lifetime of the transaction and before the first write to the DB. An advantage of using "raw" operations is that custom properties can be passed in the FlatBuffer. More...
OBX_C_API const char *	obx_tree_cursor_get_leaf_path (OBX_tree_cursor *cursor, obx_id leaf_id)
	Gets the full path (from the root) of the given leaf ID. More...
OBX_C_API obx_err	obx_tree_cursor_put_raw (OBX_tree_cursor *cursor, const char *path, void *leaf_data, size_t leaf_data_size, OBXPropertyType type, obx_id *out_id, void *leaf_metadata, size_t leaf_metadata_size, OBXPutMode leaf_put_mode)
	A "low-level" put operation for a tree leaf using given raw FlatBuffer bytes. Any non-existing branches and meta nodes are put on the fly if an optional meta-leaf FlatBuffers is given. A typical usage pattern is to first try without the meta-leaf, and if it does not work, create the meta-leaf and call again with the meta leaf. This approach takes into account that meta-leaves typically exist, and thus no resources are wasted for meta-leaf creation if it's not required. An advantage of using "raw" operations is that custom properties can be passed in the FlatBuffers. More...
OBX_C_API obx_err	obx_tree_cursor_consolidate_node_conflicts (OBX_tree_cursor *cursor, size_t *out_consolidated_count)
	Explicitly consolidates tree node conflicts (non unique nodes sharing a common path). See also obx_tree_async_consolidate_node_conflicts() for an asynchronous version. More...
OBX_C_API OBX_tree_leaves_info *	obx_tree_cursor_get_child_leaves_info (OBX_tree_cursor *cursor, const char *path)
	Given an existing path, return all existing leaves with their paths. As this traverses the data tree (i.e. not the meta tree), it will only return nodes that exist (obviously). Thus, the meta tree may contain additional paths, but these are unused by the data tree (currently at least). More...
OBX_C_API size_t	obx_tree_leaves_info_size (OBX_tree_leaves_info *leaves_info)
	Gets the number of leaves from the given leaves info. More...
OBX_C_API const char *	obx_tree_leaves_info_path (OBX_tree_leaves_info *leaves_info, size_t index)
	Gets the path of a given leaf (by index). More...
OBX_C_API OBXPropertyType	obx_tree_leaves_info_type (OBX_tree_leaves_info *leaves_info, size_t index)
	Gets the property type (as OBXPropertyType) of a given leaf (by index). More...
OBX_C_API obx_id	obx_tree_leaves_info_id (OBX_tree_leaves_info *leaves_info, size_t index)
	Gets the id of a given leaf (by index). More...
OBX_C_API void	obx_tree_leaves_info_free (OBX_tree_leaves_info *leaves_info)
	Frees a leaves info reference. More...
OBX_C_API obx_err	obx_tree_async_get_raw (OBX_tree *tree, const char *path, bool with_metadata, obx_tree_async_get_callback *callback, void *callback_user_data)
	Like obx_tree_cursor_get_raw(), but asynchronous. More...
OBX_C_API obx_err	obx_tree_async_put_raw (OBX_tree *tree, const char *path, void *leaf_data, size_t leaf_data_size, OBXPropertyType type, void *leaf_metadata, size_t leaf_metadata_size, OBXPutMode leaf_put_mode, obx_tree_async_put_callback *callback, void *callback_user_data)
	Like obx_tree_cursor_put_raw(), but asynchronous. More...
OBX_C_API obx_err	obx_tree_async_consolidate_node_conflicts (OBX_tree *tree)
	Explicitly consolidates tree node conflicts (non unique nodes sharing a common path) asynchronously. See also obx_tree_cursor_consolidate_node_conflicts() for a synchronous version. More...
OBX_C_API OBX_weak_store *	obx_weak_store (OBX_store *store)
	Creates a weak reference to the given store. More...
OBX_C_API void	obx_weak_store_free (OBX_weak_store *weak_store)
	Frees a weak store reference. More...
OBX_C_API OBX_weak_store *	obx_weak_store_by_id (uint64_t store_id)
	Tries to get a weak reference to the store with the given ID. More...
OBX_C_API OBX_store *	obx_weak_store_lock (OBX_weak_store *weak_store)
	Tries to create a regular store instance for the given weak reference. More...
OBX_C_API void	obx_bytes_free (OBX_bytes *bytes)
OBX_C_API void	obx_bytes_score_array_free (OBX_bytes_score_array *array)
	Free the array struct. More...
OBX_C_API OBX_bytes_array *	obx_bytes_array (size_t count)
	Allocate a bytes array struct of the given size, ready for the data to be pushed. More...
OBX_C_API obx_err	obx_bytes_array_set (OBX_bytes_array *array, size_t index, const void *data, size_t size)
	Set the given data as the index in the bytes array. The data is not copied, just referenced through the pointer. More...
OBX_C_API void	obx_bytes_array_free (OBX_bytes_array *array)
	Free the bytes array struct. More...
OBX_C_API OBX_id_array *	obx_id_array (const obx_id *ids, size_t count)
	Create an ID array struct, copying the given IDs as the contents. More...
OBX_C_API void	obx_id_array_free (OBX_id_array *array)
	Free the array struct. More...
OBX_C_API void	obx_string_array_free (OBX_string_array *array)
	Free the array struct. More...
OBX_C_API void	obx_id_score_array_free (OBX_id_score_array *array)
	Free the array struct. More...
OBX_C_API void	obx_int64_array_free (OBX_int64_array *array)
	Free the array struct. More...
OBX_C_API void	obx_int32_array_free (OBX_int32_array *array)
	Free the array struct. More...
OBX_C_API void	obx_int16_array_free (OBX_int16_array *array)
	Free the array struct. More...
OBX_C_API void	obx_int8_array_free (OBX_int8_array *array)
	Free the array struct. More...
OBX_C_API void	obx_double_array_free (OBX_double_array *array)
	Free the array struct. More...
OBX_C_API void	obx_float_array_free (OBX_float_array *array)
	Free the array struct. More...
OBX_C_API obx_err	obx_posix_sem_prefix_set (const char *prefix)
	Only for Apple platforms: set the prefix to use for mutexes based on POSIX semaphores. You must supply the application group identifier for sand-boxed macOS apps here; see also: https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW24. More...
OBX_C_API OBX_admin_options *	obx_admin_opt ()
	Create a default set of admin options. More...
OBX_C_API obx_err	obx_admin_opt_store (OBX_admin_options *opt, OBX_store *store)
	Configure admin with an existing, open OBX_store*. More...
OBX_C_API obx_err	obx_admin_opt_store_path (OBX_admin_options *opt, const char *directory)
	Configure admin with an existing, open OBX_store*. More...
OBX_C_API obx_err	obx_admin_opt_bind (OBX_admin_options *opt, const char *uri)
	Set the address and port on which the underlying http-server should server the admin web UI. Defaults to "http://127.0.0.1:8081". More...
OBX_C_API obx_err	obx_admin_opt_ssl_cert (OBX_admin_options *opt, const char *cert_path)
	Configure the server to use SSL, with the given certificate. More...
OBX_C_API obx_err	obx_admin_opt_num_threads (OBX_admin_options *opt, size_t num_threads)
	Sets the number of worker threads the http-server uses to serve requests. Default: 4. More...
OBX_C_API obx_err	obx_admin_opt_unsecured_no_authentication (OBX_admin_options *opt, bool value)
	Disables authentication to make the web app accessible to anyone, e.g. to allow recovery if users have locked themselves out. Otherwise, if users have been defined, authentication is enforced. More...
OBX_C_API obx_err	obx_admin_opt_user_management (OBX_admin_options *opt, bool value)
	Disable user management in the database - this is usually only done during development, with local-only access. More...
OBX_C_API obx_err	obx_admin_opt_log_requests (OBX_admin_options *opt, bool value)
	Logs request info, e.g. timing for serving a request. More...
OBX_C_API obx_err	obx_admin_opt_free (OBX_admin_options *opt)
	Free the options. Note: Only free unused options, obx_admin() frees the options internally. More...
OBX_C_API OBX_admin *	obx_admin (OBX_admin_options *options)
	Initialize the http-server with the given options. Note: the given options are always freed by this function, including when an error occurs. More...
OBX_C_API uint16_t	obx_admin_port (OBX_admin *admin)
	Returns a port this server listens on. This is especially useful if the port was assigned arbitrarily (a "0" port was used in the URL given to obx_admin_opt_bind()). More...
OBX_C_API obx_err	obx_admin_close (OBX_admin *admin)
	Stop the http-server and free all the resources. More...

Detailed Description

Macro Definition Documentation

OBX_C_API

#define OBX_C_API

OBX_ERROR_ALLOCATION

#define OBX_ERROR_ALLOCATION   10003

A resource could not be allocated. This usually indicates a severe system status, e.g running out of memory.

OBX_ERROR_BACKUP_FILE_INVALID

#define OBX_ERROR_BACKUP_FILE_INVALID   10008

A given backup file has invalid content and thus cannot be restored.

OBX_ERROR_CONSTRAINT_VIOLATED

#define OBX_ERROR_CONSTRAINT_VIOLATED   10299

A constraint violation occurred that did not fit in a more specific (constraint violation) category.

OBX_ERROR_DB_FULL

#define OBX_ERROR_DB_FULL   10101

The database has reached its given storage limit. Note that is limit is user defined and thus you can set it as an option when opening a database via obx_opt_max_db_size_in_kb(). Further note that this limit is in place to protect the system from unreasonable storage consumption due to unexpected usage and user errors (e.g. inserting data in an infinite loop).

OBX_ERROR_DB_GENERAL

#define OBX_ERROR_DB_GENERAL   10198

A general database related error occurred that did not fit in a more specific category. No secondary error code is available.

OBX_ERROR_FEATURE_NOT_AVAILABLE

#define OBX_ERROR_FEATURE_NOT_AVAILABLE   10005

Tried to use a special feature that is not part of this lib edition. The ObjectBox library comes in different flavors, and may not contain all features.

OBX_ERROR_FILE_CORRUPT

#define OBX_ERROR_FILE_CORRUPT   10502

DB file has errors, e.g. illegal values or structural inconsistencies were detected.

OBX_ERROR_FILE_PAGES_CORRUPT

#define OBX_ERROR_FILE_PAGES_CORRUPT   10503

DB file has errors related to pages, e.g. bad page refs outside of the file.

OBX_ERROR_GENERAL

#define OBX_ERROR_GENERAL   10098

A general error occurred that did not fit in a more specific category.

OBX_ERROR_ID_ALREADY_EXISTS

#define OBX_ERROR_ID_ALREADY_EXISTS   10210

A given ID already existed, e.g. when trying to insert with a pre-existing ID. Should happen only with user assigned IDs.

OBX_ERROR_ID_NOT_FOUND

#define OBX_ERROR_ID_NOT_FOUND   10211

A given ID was not found (does not exist), e.g. when trying to update an object that does not exist. Typically happens when an object was removed before while trying to update it.

OBX_ERROR_ILLEGAL_ARGUMENT

#define OBX_ERROR_ILLEGAL_ARGUMENT   10002

The passed arguments were illegal; e.g. passed null to a non-null argument.

OBX_ERROR_ILLEGAL_STATE

#define OBX_ERROR_ILLEGAL_STATE   10001

A request does not make sense in the current state. For example, doing actions on a closed object.

OBX_ERROR_IO

#define OBX_ERROR_IO   10007

An I/O operation failed, e.g. a file was not found, could not be written or read.

OBX_ERROR_MAX_DATA_SIZE_EXCEEDED

#define OBX_ERROR_MAX_DATA_SIZE_EXCEEDED   10104

Occurs when a transaction is about to commit but it would exceed the user-defined data size limit. See obx_opt_max_data_size_in_kb() for details.

OBX_ERROR_MAX_READERS_EXCEEDED

#define OBX_ERROR_MAX_READERS_EXCEEDED   10102

Thrown when the maximum of readers (read transactions) was exceeded. Verify that you run a reasonable amount of threads only. If you actually intend to work with a very high number of threads (>100), consider increasing the number of maximum readers via obx_opt_max_readers().

OBX_ERROR_NO_ERROR_INFO

#define OBX_ERROR_NO_ERROR_INFO   10097

An error occurred but error information could not be extracted. This falls in the "should not happen" category and should be very rare; please report if you ever encounter this in a reproducible fashion.

OBX_ERROR_NON_UNIQUE_RESULT

#define OBX_ERROR_NON_UNIQUE_RESULT   10202

A result was supposed to be unique, but was not. E.g. a query results in multiple results where one one is expected.

OBX_ERROR_NUMERIC_OVERFLOW

#define OBX_ERROR_NUMERIC_OVERFLOW   10004

Thrown when a numeric value did overflow/underflow, e.g. an addition would result in a value of the type's limits.

OBX_ERROR_PROPERTY_TYPE_MISMATCH

#define OBX_ERROR_PROPERTY_TYPE_MISMATCH   10203

A Property did not match an expected type; e.g. when defining a string-based query condition for an integer type.

OBX_ERROR_SCHEMA

#define OBX_ERROR_SCHEMA   10501

Data schema (aka data model) related error; typically when a provided schema is inconsistent/incompatible to an existing one (on disk).

OBX_ERROR_SCHEMA_OBJECT_NOT_FOUND

#define OBX_ERROR_SCHEMA_OBJECT_NOT_FOUND   10504

A requested schema object (e.g. an entity or a property) was not found in the schema.

OBX_ERROR_SHUTTING_DOWN

#define OBX_ERROR_SHUTTING_DOWN   10006

A required resource (e.g. a store or some internal queue) is shutting down, and thus, the current request could not be fulfilled. Typically occurs in asynchronous operations.

OBX_ERROR_STD_BAD_ALLOC

#define OBX_ERROR_STD_BAD_ALLOC   10304

OBX_ERROR_STD_ILLEGAL_ARGUMENT

#define OBX_ERROR_STD_ILLEGAL_ARGUMENT   10301

OBX_ERROR_STD_LENGTH

#define OBX_ERROR_STD_LENGTH   10303

OBX_ERROR_STD_OTHER

#define OBX_ERROR_STD_OTHER   10399

OBX_ERROR_STD_OUT_OF_RANGE

#define OBX_ERROR_STD_OUT_OF_RANGE   10302

OBX_ERROR_STD_OVERFLOW

#define OBX_ERROR_STD_OVERFLOW   10306

OBX_ERROR_STD_RANGE

#define OBX_ERROR_STD_RANGE   10305

OBX_ERROR_STORAGE_GENERAL

#define OBX_ERROR_STORAGE_GENERAL   10199

A storage error occurred that did not fit in a more specific (storage) category. A secondary error code is available via obx_last_error_secondary().

OBX_ERROR_STORE_MUST_SHUTDOWN

#define OBX_ERROR_STORE_MUST_SHUTDOWN   10103

Can not continue, ObjectBox store must be closed. This falls in the "should not happen" category and should be very rare; please report if you ever encounter this in a reproducible fashion.

OBX_ERROR_TIME_SERIES

#define OBX_ERROR_TIME_SERIES   10212

A Time Series operation failed, e.g. a time value was out of range.

OBX_ERROR_TREE_MODEL_INVALID

#define OBX_ERROR_TREE_MODEL_INVALID   10601

Could not setup tree because the data model (schema) of the database does not contain all required tree types/properties.

OBX_ERROR_TREE_OTHER

#define OBX_ERROR_TREE_OTHER   10699

An error related to tree functionality was detected; please check the error message for details (see obx_last_error_message()).

OBX_ERROR_TREE_PATH_ILLEGAL

#define OBX_ERROR_TREE_PATH_ILLEGAL   10604

When trying to put or get using an illegal tree path. Examples for illegal paths with delimiter '/': "", "/", "a", "/a", "a/", "a//b", " ", " / ", "a/ /b", " a/b", "a/b ".

OBX_ERROR_TREE_PATH_NON_UNIQUE

#define OBX_ERROR_TREE_PATH_NON_UNIQUE   10603

At a given path, a leaf was expected but a branch node was found; e.g. values can only be stored in leaves.

OBX_ERROR_TREE_VALUE_TYPE_MISMATCH

#define OBX_ERROR_TREE_VALUE_TYPE_MISMATCH   10602

Accessing a tree value failed because the stored value was put using a different value type.

OBX_ERROR_UNIQUE_VIOLATED

#define OBX_ERROR_UNIQUE_VIOLATED   10201

A unique constraint of was violated when trying to put.

OBX_ERROR_UNKNOWN

#define OBX_ERROR_UNKNOWN   10099

An error of unknown type occurred. This falls in the "should not happen" category and should be very rare; please report if you ever encounter this in a reproducible fashion.

OBX_ID_NEW

#define OBX_ID_NEW   0xFFFFFFFFFFFFFFFF

To be used for putting objects with prepared ID slots, e.g. obx_cursor_put_object().

OBX_NO_SUCCESS

#define OBX_NO_SUCCESS   1001

Indicates that a function had "no success", which is typically a likely outcome and not a "hard error". This is NOT an error condition, and thus no "last error" info is set.

OBX_NOT_FOUND

#define OBX_NOT_FOUND   404

Returned by, e.g., get operations if nothing was found for a specific ID. This is NOT an error condition, and thus no "last error" info (code/text) is set.

OBX_SUCCESS

#define OBX_SUCCESS   0

Value returned when no error occurred (0)

OBX_TIMEOUT

#define OBX_TIMEOUT   1002

Indicates that a function reached a time out, which is typically a likely outcome and not a "hard error". This is NOT an error condition, and thus no "last error" info is set.

OBX_VERSION_MAJOR

#define OBX_VERSION_MAJOR   4

When using ObjectBox as a dynamic library, you should verify that a compatible version was linked using obx_version() or obx_version_is_at_least().

OBX_VERSION_MINOR

#define OBX_VERSION_MINOR   0

OBX_VERSION_PATCH

#define OBX_VERSION_PATCH   3

Typedef Documentation

OBX_admin

typedef struct OBX_admin OBX_admin

The admin web UI is an optional feature consisting of an embedded http server, that comes with an object (data) browser and an administration UI.

OBX_admin_options

typedef struct OBX_admin_options OBX_admin_options

Options to configure the OBX_admin to be created.

OBX_async

typedef struct OBX_async OBX_async

Created by obx_box_async, used for async operations like obx_async_put.

OBX_box

typedef struct OBX_box OBX_box

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

Given an OBX_store, obx_box() gives you 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 C API are always reentrant, you can set your own transaction boundary using obx_txn_read() or obx_txn_write(). 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 cached internally (see obx_box()).

OBX_bytes

typedef struct OBX_bytes OBX_bytes

This bytes struct is an input/output wrapper used for a single data object (represented as FlatBuffers).

OBX_bytes_array

typedef struct OBX_bytes_array OBX_bytes_array

This bytes array struct is an input/output wrapper for multiple data objects (represented as FlatBuffers).

OBX_bytes_lazy

typedef struct OBX_bytes_lazy OBX_bytes_lazy

Bytes, which must be resolved "lazily" via obx_bytes_lazy_get() and released via obx_bytes_lazy_free(). Unlike OBX_bytes, this may represent allocated resources and/or bytes that are only produced on demand.

OBX_bytes_score

typedef struct OBX_bytes_score OBX_bytes_score

This bytes score struct is an input/output wrapper used for a single data object (represented as FlatBuffers) with its associated query score, which is used for special query results.

OBX_bytes_score_array

typedef struct OBX_bytes_score_array OBX_bytes_score_array

This bytes score array struct is an input/output wrapper pointing to multiple OBX_bytes_score instances. If count is zero, bytes_scores is allowed to be invalid.

OBX_cursor

typedef struct OBX_cursor OBX_cursor

Cursor provides fine-grained (lower level API) access to the stored objects. Check also the more convenient Box API.

obx_data_score_visitor

typedef bool obx_data_score_visitor(const struct OBX_bytes_score *data, void *user_data)

The callback for reading data (i.e. object bytes) with a search score one-by-one.

Parameters

data	contains the current data with score element
user_data	is a pass-through argument passed to the called API

Returns

The visitor returns true to keep going or false to cancel.

obx_data_visitor

typedef bool obx_data_visitor(const void *data, size_t size, void *user_data)

The callback for reading data (i.e. object bytes) one-by-one.

Parameters

data	is the read data buffer
size	specifies the length of the read data
user_data	is a pass-through argument passed to the called API

Returns

The visitor returns true to keep going or false to cancel.

OBX_double_array

typedef struct OBX_double_array OBX_double_array

Double array struct is an input/output wrapper for an array of double precision floating point numbers.

obx_err

typedef int obx_err

Error/success code returned by an obx_* function; see defines OBX_SUCCESS, OBX_NOT_FOUND, and OBX_ERROR_*.

OBX_float_array

typedef struct OBX_float_array OBX_float_array

Float array struct is an input/output wrapper for an array of single precision floating point numbers.

obx_id

typedef uint64_t obx_id

ID of a single Object stored in the database.

OBX_id_array

typedef struct OBX_id_array OBX_id_array

ID array struct is an input/output wrapper for an array of object IDs.

OBX_id_score

typedef struct OBX_id_score OBX_id_score

Object ID with its associated query score, which is used for special query results.

OBX_id_score_array

typedef struct OBX_id_score_array OBX_id_score_array

ID score array struct is an input/output wrapper for an array of OBX_id_score structs. If count is zero, bytes_scores is allowed to be invalid.

OBX_int16_array

typedef struct OBX_int16_array OBX_int16_array

Int16 array struct is an input/output wrapper for an array of int16 numbers.

OBX_int32_array

typedef struct OBX_int32_array OBX_int32_array

Int32 array struct is an input/output wrapper for an array of int32 numbers.

OBX_int64_array

typedef struct OBX_int64_array OBX_int64_array

Int64 array struct is an input/output wrapper for an array of int64 numbers.

OBX_int8_array

typedef struct OBX_int8_array OBX_int8_array

Int8 array struct is an input/output wrapper for an array of int8 numbers.

obx_log_callback

typedef void obx_log_callback(OBXLogLevel log_level, const char *message, size_t message_size, void *user_data)

Callback for logging, which can be provided to store creation via options.

OBX_model

typedef struct OBX_model OBX_model

Model represents a database schema and must be provided when opening the store. Model initialization is usually done by language bindings, which automatically build the model based on parsed source code (for examples, see ObjectBox Go or Swift, which also use this C API).

For manual creation, these are the basic steps:

• define entity types using obx_model_entity() and obx_model_property()
• Pass the last ever used IDs with obx_model_last_entity_id(), obx_model_last_index_id(), obx_model_last_relation_id()

OBX_observer

typedef struct OBX_observer OBX_observer

Observers are called back when data has changed in the database. See obx_observe(), or obx_observe_single_type() to listen to a changes that affect a single entity type.

obx_observer

typedef void obx_observer(const obx_schema_id *type_ids, size_t type_ids_count, void *user_data)

Callback for obx_observe()

Parameters

user_data	user data given to obx_observe()
type_ids	array of object type IDs that had changes
type_ids_count	number of IDs of type_ids

obx_observer_single_type

typedef void obx_observer_single_type(void *user_data)

Callback for obx_observe_single_type()

obx_qb_cond

typedef int obx_qb_cond

Query Builder condition identifier.

• returned by condition creating functions,
• used to combine conditions with any/all, thus building more complex conditions

OBX_query

typedef struct OBX_query OBX_query

Query holds the information necessary to execute a database query. It's prepared by QueryBuilder and may be reused any number of times. It also supports parametrization before executing, further improving the reusability. Query is NOT thread safe and must only be used from a single thread at the same time. If you prefer to avoid locks, you may want to create clonse using obx_query_clone().

OBX_query_builder

typedef struct OBX_query_builder OBX_query_builder

You use QueryBuilder to specify criteria and create a Query which actually executes the query and returns matching objects.

OBX_query_prop

typedef struct OBX_query_prop OBX_query_prop

PropertyQuery - getting a single property instead of whole objects. Also provides aggregation over properties.

obx_schema_id

typedef uint32_t obx_schema_id

Schema entity & property identifiers.

obx_status_callback

typedef void obx_status_callback(obx_err status, void *user_data)

Callback for simple async functions that only deliver a obx_err status.

Parameters

status	The result status of the async operation
user_data	The data initially passed to the async function call is passed back.

OBX_store

typedef struct OBX_store OBX_store

A ObjectBox store represents a database storing data in a given directory on a local file system or in-memory using "memory:" directory prefix.

Once opened using obx_store_open(), it's an entry point to data access APIs such as box, query, cursor, transaction. After your work is done, you must close obx_store_close() to safely release all the handles and avoid data loss.

It's possible open multiple stores in different directories.

OBX_store_options

typedef struct OBX_store_options OBX_store_options

Store options customize the behavior of ObjectBox before opening a store. Options can't be changed once the store is open but of course you can close the store and open it again with the changed options. Some of the notable options are obx_opt_directory() and obx_opt_max_db_size_in_kb().

OBX_string_array

typedef struct OBX_string_array OBX_string_array

String array struct is an input/output wrapper for an array of character strings.

OBX_tree

typedef struct OBX_tree OBX_tree

Top level tree API representing a tree structure/schema associated with a store.

Data is accessed via "tree cursors" that can be created using obx_tree_cursor().

obx_tree_async_get_callback

typedef void obx_tree_async_get_callback(obx_err status, obx_id id, const char *path, const void *leaf_data, size_t leaf_data_size, const void *leaf_metadata, size_t leaf_metadata_size, void *user_data)

Callback for obx_tree_async_get_raw().

Note

If the given status is an error, you can use functions like obx_last_error_message() to gather more info during this callback (error state is thread bound and the callback uses an internal thread).

Parameters

status	The result status of the async operation
id	If the operation was successful, the ID of the leaf, which was get (otherwise zero).
path	The leafs path as string.
leaf_data	The leafs data flatbuffer pointer.
leaf_data_size	The leafs data flatbuffer size.
leaf_metadata	The leafs metadata flatbuffer pointer.
leaf_metadata_size	The leafs meatdata flatbuffer size.
user_data	The data initially passed to the async function call is passed back.

obx_tree_async_put_callback

typedef void obx_tree_async_put_callback(obx_err status, obx_id id, void *user_data)

Callback for obx_tree_async_put_raw().

Note

If the given status is an error, you can use functions like obx_last_error_message() to gather more info during this callback (error state is thread bound and the callback uses an internal thread).

Parameters

status	The result status of the async operation
id	If the operation was successful, the ID of the leaf, which was put (otherwise zero).
user_data	The data initially passed to the async function call is passed back.

OBX_tree_cursor

typedef struct OBX_tree_cursor OBX_tree_cursor

OBX_tree_leaves_info

typedef struct OBX_tree_leaves_info OBX_tree_leaves_info

Extended information about leaf nodes.

OBX_tree_options

typedef struct OBX_tree_options OBX_tree_options

Structural/behavioral options for a tree passed during tree creation.

OBX_txn

typedef struct OBX_txn OBX_txn

Transaction provides the mean to use explicit database transactions, grouping several operations into a single unit of work that either executes completely or not at all. If you are looking for a more detailed introduction to transactions in general, please consult other resources, e.g., https://en.wikipedia.org/wiki/Database_transaction.

You may not notice it, but almost all interactions with ObjectBox involve transactions. For example, if you call obx_box_put() a write transaction is used. Also if you call obx_box_count(), a read transaction is used. All of this is done under the hood and transparent to you. However, there are situations where an explicit read transaction is necessary, e.g. obx_box_get(). Also, it’s usually worth learning transaction basics to make your app more consistent and efficient, especially for writes.

obx_uid

typedef uint64_t obx_uid

Universal identifier used in schema for entities & properties.

OBX_weak_store

typedef struct OBX_weak_store OBX_weak_store

A "weak store" is a weakly referenced store.

While you can "attach" to a store multiple time; each instance will keep the store open. Alternatively for "secondary stores" (e.g. used in a background thread), a weakly referenced store does not keep the store open by itself. Only strong references (e.g. the store created and attached stores) do. A weak store needs to be "locked" to get a regular store (strong reference) in order to actually use it.

Enumeration Type Documentation

OBXBackupFlags

enum OBXBackupFlags

Backup flags control how the store creates backup files. E.g. when you want "deterministic" file content, you can exclude timestamp and salt.

Enumerator
OBXBackupFlags_ExcludeTimestamp	Do not include a timestamp in the backup file (time when the backup file is generated).
OBXBackupFlags_ExcludeSalt	Do not include a random salt in the backup file.

OBXBackupRestoreFlags

enum OBXBackupRestoreFlags

Backup restore flags control how backups are restored to the database.

Enumerator
OBXBackupRestoreFlags_OverwriteExistingData	Overwrite any existing database with the content of the backup file.

OBXDebugFlags

enum OBXDebugFlags

Debug flags typically enable additional "debug logging" that can be helpful to better understand what is going on internally. These are intended for the development process only; typically one does not enable them for releases.

Enumerator
OBXDebugFlags_LOG_TRANSACTIONS_READ
OBXDebugFlags_LOG_TRANSACTIONS_WRITE
OBXDebugFlags_LOG_QUERIES
OBXDebugFlags_LOG_QUERY_PARAMETERS
OBXDebugFlags_LOG_ASYNC_QUEUE
OBXDebugFlags_LOG_CACHE_HITS
OBXDebugFlags_LOG_CACHE_ALL
OBXDebugFlags_LOG_TREE
OBXDebugFlags_LOG_EXCEPTION_STACK_TRACE	For a limited number of error conditions, this will try to print stack traces. Note: this is Linux-only, experimental, and has several limitations: The usefulness of these stack traces depends on several factors and might not be helpful at all.
OBXDebugFlags_RUN_THREADING_SELF_TEST	Run a quick self-test to verify basic threading; somewhat paranoia to check the platform and the library setup.

OBXEntityFlags

enum OBXEntityFlags

Bit-flags defining the behavior of entities. Note: Numbers indicate the bit position.

Enumerator
OBXEntityFlags_SYNC_ENABLED	Enable "data synchronization" for this entity type: objects will be synced with other stores over the network. It's possible to have local-only (non-synced) types and synced types in the same store (schema/data model).
OBXEntityFlags_SHARED_GLOBAL_IDS	Makes object IDs for a synced types (SYNC_ENABLED is set) global. By default (not using this flag), the 64 bit object IDs have a local scope and are not unique globally. This flag tells ObjectBox to treat object IDs globally and thus no ID mapping (local <-> global) is performed. Often this is used with assignable IDs (ID_SELF_ASSIGNABLE property flag is set) and some special ID scheme. Note: typically you won't do this with automatically assigned IDs, set by the local ObjectBox store. Two devices would likely overwrite each other's object during sync as object IDs are prone to collide. It might be OK if you can somehow ensure that only a single device will create new IDs.

OBXFeature

enum OBXFeature

Enumerator
OBXFeature_ResultArray	Functions that are returning multiple results (e.g. multiple objects) can be only used if this is available. This is only available for 64-bit OSes and is the opposite of "chunked mode", which forces to consume results in chunks (e.g. one by one). Since chunked mode consumes a bit less RAM, ResultArray style functions are typically only preferable if there's an additional overhead per call, e.g. caused by a higher level language abstraction like CGo.
OBXFeature_TimeSeries	TimeSeries support (date/date-nano companion ID and other time-series functionality).
OBXFeature_Sync	Sync client availability. Visit https://objectbox.io/sync for more details.
OBXFeature_DebugLog	Check whether debug log can be enabled during runtime.
OBXFeature_Admin	Admin UI including a database browser, user management, and more. Depends on HttpServer (if Admin is available HttpServer is too).
OBXFeature_Tree	Tree with special GraphQL support.
OBXFeature_SyncServer	Sync server availability. Visit https://objectbox.io/sync for more details.
OBXFeature_WebSockets	Implicitly added by Sync or SyncServer; disable via NoWebSockets.
OBXFeature_Cluster	Sync Server has cluster functionality. Implicitly added by SyncServer; disable via NoCluster.
OBXFeature_HttpServer	Embedded HTTP server.
OBXFeature_GraphQL	Embedded GraphQL server (via HTTP). Depends on HttpServer (if GraphQL is available HttpServer is too).
OBXFeature_Backup	Database Backup functionality; typically only enabled in Sync Server builds.
OBXFeature_Lmdb	The default database "provider"; writes data persistently to disk (ACID).
OBXFeature_VectorSearch	Vector search functionality; enables indexing for nearest neighbor search.
OBXFeature_Wal	WAL (write-ahead logging).
OBXFeature_SyncMongoDb	Sync connector to integrate MongoDB with SyncServer.

OBXHnswFlags

enum OBXHnswFlags

Bit-flags to influence the behavior of HNSW index (vector search).

Enumerator
OBXHnswFlags_None
OBXHnswFlags_DebugLogs	Enables debug logs.
OBXHnswFlags_DebugLogsDetailed	Enables "high volume" debug logs, e.g. individual gets/puts.
OBXHnswFlags_VectorCacheSimdPaddingOff	Padding for SIMD is enabled by default, which uses more memory but may be faster. This flag turns it off.
OBXHnswFlags_ReparationLimitCandidates	If the speed of removing nodes becomes a concern in your use case, you can speed it up by setting this flag. By default, repairing the graph after node removals creates more connections to improve the graph's quality. The extra costs for this are relatively low (e.g. vs. regular indexing), and thus the default is recommended.

OBXLogLevel

enum OBXLogLevel

Log level as passed to obx_log_callback.

Enumerator
OBXLogLevel_Verbose	Log level for verbose messages (not emitted at the moment)
OBXLogLevel_Debug	Log level for debug messages (may be limited to special debug builds)
OBXLogLevel_Info	Log level for info messages.
OBXLogLevel_Warn	Log level for warning messages.
OBXLogLevel_Error	Log level for error messages.

OBXOrderFlags

enum OBXOrderFlags

Not really an enum, but binary flags to use across languages.

Enumerator
OBXOrderFlags_DESCENDING	Reverse the order from ascending (default) to descending.
OBXOrderFlags_CASE_SENSITIVE	Sort upper case letters (e.g. "Z") before lower case letters (e.g. "a"). If not specified, the default is case insensitive for ASCII characters.
OBXOrderFlags_UNSIGNED	For scalars only: change the comparison to unsigned (default is signed).
OBXOrderFlags_NULLS_LAST	null values will be put last. If not specified, by default null values will be put first.
OBXOrderFlags_NULLS_ZERO	null values should be treated equal to zero (scalars only).

OBXPropertyFlags

enum OBXPropertyFlags

Bit-flags defining the behavior of properties. Note: Numbers indicate the bit position.

Enumerator
OBXPropertyFlags_ID	64 bit long property (internally unsigned) representing the ID of the entity. May be combined with: NON_PRIMITIVE_TYPE, ID_MONOTONIC_SEQUENCE, ID_SELF_ASSIGNABLE.
OBXPropertyFlags_NON_PRIMITIVE_TYPE	On languages like Java, a non-primitive type is used (aka wrapper types, allowing null)
OBXPropertyFlags_NOT_NULL	Unused yet.
OBXPropertyFlags_INDEXED
OBXPropertyFlags_RESERVED	Unused yet.
OBXPropertyFlags_UNIQUE	Unique index.
OBXPropertyFlags_ID_MONOTONIC_SEQUENCE	Unused yet: Use a persisted sequence to enforce ID to rise monotonic (no ID reuse)
OBXPropertyFlags_ID_SELF_ASSIGNABLE	Allow IDs to be assigned by the developer.
OBXPropertyFlags_INDEX_PARTIAL_SKIP_NULL	Unused yet.
OBXPropertyFlags_INDEX_PARTIAL_SKIP_ZERO	Used by References for 1) back-references and 2) to clear references to deleted objects (required for ID reuse)
OBXPropertyFlags_VIRTUAL	Virtual properties may not have a dedicated field in their entity class, e.g. target IDs of to-one relations.
OBXPropertyFlags_INDEX_HASH	Index uses a 32 bit hash instead of the value 32 bits is shorter on disk, runs well on 32 bit systems, and should be OK even with a few collisions.
OBXPropertyFlags_INDEX_HASH64	Index uses a 64 bit hash instead of the value recommended mostly for 64 bit machines with values longer >200 bytes; small values are faster with a 32 bit hash.
OBXPropertyFlags_UNSIGNED	The actual type of the variable is unsigned (used in combination with numeric OBXPropertyType_*). While our default are signed ints, queries & indexes need do know signing info. Note: Don't combine with ID (IDs are always unsigned internally).
OBXPropertyFlags_ID_COMPANION	By defining an ID companion property, a special ID encoding scheme is activated involving this property. For Time Series IDs, a companion property of type Date or DateNano represents the exact timestamp.
OBXPropertyFlags_UNIQUE_ON_CONFLICT_REPLACE	Unique on-conflict strategy: the object being put replaces any existing conflicting object (deletes it).
OBXPropertyFlags_EXPIRATION_TIME	If a date property has this flag (max. one per entity type), the date value specifies the time by which the object expires, at which point it MAY be removed (deleted), which can be triggered by an API call.

OBXPropertyType

enum OBXPropertyType

Enumerator
OBXPropertyType_Unknown	Not a actual type; represents an uninitialized or invalid type.
OBXPropertyType_Bool	A boolean (flag)
OBXPropertyType_Byte	8-bit integer
OBXPropertyType_Short	16-bit integer
OBXPropertyType_Char	16-bit character
OBXPropertyType_Int	32-bit integer
OBXPropertyType_Long	64-bit integer
OBXPropertyType_Float	32-bit floating point number
OBXPropertyType_Double	64-bit floating point number
OBXPropertyType_String	UTF-8 encoded string (variable length)
OBXPropertyType_Date	64-bit (integer) timestamp; milliseconds since 1970-01-01 (unix epoch)
OBXPropertyType_Relation	Relation to another entity.
OBXPropertyType_DateNano	High precision 64-bit timestamp; nanoseconds since 1970-01-01 (unix epoch)
OBXPropertyType_Flex	Flexible" type, which may contain scalars (integers, floating points), strings or containers (lists and maps). Note: a flex map must use string keys.
OBXPropertyType_BoolVector	Variable sized vector of Bool values (note: each value is one byte)
OBXPropertyType_ByteVector	Variable sized vector of Byte values (8-bit integers)
OBXPropertyType_ShortVector	Variable sized vector of Short values (16-bit integers)
OBXPropertyType_CharVector	Variable sized vector of Char values (16-bit characters)
OBXPropertyType_IntVector	Variable sized vector of Int values (32-bit integers)
OBXPropertyType_LongVector	Variable sized vector of Long values (64-bit integers)
OBXPropertyType_FloatVector	Variable sized vector of Float values (32-bit floating point numbers)
OBXPropertyType_DoubleVector	Variable sized vector of Double values (64-bit floating point numbers)
OBXPropertyType_StringVector	Variable sized vector of String values (UTF-8 encoded strings).
OBXPropertyType_DateVector	Variable sized vector of Date values (64-bit timestamp).
OBXPropertyType_DateNanoVector	Variable sized vector of Date values (high precision 64-bit timestamp).

OBXPutMode

enum OBXPutMode

Enumerator
OBXPutMode_PUT	Standard put ("insert or update")
OBXPutMode_INSERT	Put succeeds only if the entity does not exist yet.
OBXPutMode_UPDATE	Put succeeds only if the entity already exist.

OBXPutPaddingMode

enum OBXPutPaddingMode

Defines a padding mode for putting data bytes. Depending on how that data is created, this mode may optimize data handling by avoiding copying memory. Internal background: data buffers used by put operations are required to have a size divisible by 4 for an efficient data layout.

Enumerator
OBXPutPaddingMode_PaddingAutomatic	Adds a padding when needed (may require a memory copy): this is the safe option and also the default. The extra memory copy may impact performance, however this is usually not noticeable.
OBXPutPaddingMode_PaddingAllowedByBuffer	Indicates that data buffers are safe to be extended for padding (adding up to 3 bytes to size is OK). Typically, it depends on the used FlatBuffers builder; e.g. the official C++ seems to ensure it, but flatcc (3rd party implementation for plain C) may not.
OBXPutPaddingMode_PaddingByCaller	The caller ensures that all data bytes are already padded. ObjectBox will verify the buffer size and returns an error if it's not divisible by 4.

OBXStoreTypeId

enum OBXStoreTypeId

Store type to be registered with obx_store_type_id_register_default().

Enumerator
OBXStoreTypeId_LMDB	Default store type: persistent data storage (based on LMDB)
OBXStoreTypeId_InMemory	Store type ID for in-memory database (non-persistent)
OBXStoreTypeId_InMemoryWal	Store type ID for in-memory WAL-enabled (persistent)

OBXTreeOptionFlags

enum OBXTreeOptionFlags

Enumerator
OBXTreeOptionFlags_DebugLogsDisable	If true, debug logs are always disabled for this tree regardless of the store's debug flags.
OBXTreeOptionFlags_DebugLogsEnable	If true, debug logs are always enabled for this tree regardless of the store's debug flags.
OBXTreeOptionFlags_EnforceUniquePath	By default, a path such as "a/b/c" can address a branch and a leaf at the same time. E.g. under the common parent path "a/b", a branch "c" and a "c" leaf may exist. To disable this, set this flag to true. This will enable an additional check when inserting new leafs and new branches for the existence of the other.
OBXTreeOptionFlags_AllowNonUniqueNodes	In some scenarios, e.g. when using Sync, multiple node objects of the same type (e.g. branch or leaf) at the same path may exist temporarily. By enabling this flag, this is not considered an error situation. Instead, the first node is picked.
OBXTreeOptionFlags_DetectNonUniqueNodes	Nodes described in AllowNonUniqueNodes will be automatically detected to consolidate them (manually).
OBXTreeOptionFlags_AutoConsolidateNonUniqueNodes	Nodes described in AllowNonUniqueNodes will be automatically consolidated to make them unique. This consolidation happens e.g. on put/remove operations. Using this value implies DetectNonUniqueNodes.

OBXValidateOnOpenKvFlags

enum OBXValidateOnOpenKvFlags

Flags used to control key/value pairs validation options when opening the store. Note: this enum does not contain any actual values besides "None" yet; it's only used to future proof the API.

Enumerator
OBXValidateOnOpenKvFlags_None	No special flags.

OBXValidateOnOpenPagesFlags

enum OBXValidateOnOpenPagesFlags

Flags used to control pages validation options when opening the store.

Enumerator
OBXValidateOnOpenPagesFlags_None	No special flags.
OBXValidateOnOpenPagesFlags_VisitLeafPages	Enable validation of leaf pages (by default only branch pages are validated)

OBXVectorDistanceType

enum OBXVectorDistanceType

The vector distance algorithm used by an HNSW index (vector search).

Enumerator
OBXVectorDistanceType_Unknown	Not a real type, just best practice (e.g. forward compatibility)
OBXVectorDistanceType_Euclidean	The default; typically "Euclidean squared" internally.
OBXVectorDistanceType_Cosine	Cosine similarity compares two vectors irrespective of their magnitude (compares the angle of two vectors). Often used for document or semantic similarity. Value range: 0.0 - 2.0 (0.0: same direction, 1.0: orthogonal, 2.0: opposite direction)
OBXVectorDistanceType_DotProduct	For normalized vectors (vector length == 1.0), the dot product is equivalent to the cosine similarity. Because of this, the dot product is often preferred as it performs better. Value range (normalized vectors): 0.0 - 2.0 (0.0: same direction, 1.0: orthogonal, 2.0: opposite direction)
OBXVectorDistanceType_Manhattan
OBXVectorDistanceType_Hamming
OBXVectorDistanceType_DotProductNonNormalized	A custom dot product similarity measure that does not require the vectors to be normalized. Note: this is no replacement for cosine similarity (like DotProduct for normalized vectors is). The non-linear conversion provides a high precision over the entire float range (for the raw dot product). The higher the dot product, the lower the distance is (the nearer the vectors are). The more negative the dot product, the higher the distance is (the farther the vectors are). Value range: 0.0 - 2.0 (nonlinear; 0.0: nearest, 1.0: orthogonal, 2.0: farthest)

OBXWalFlags

enum OBXWalFlags

WAL flags control how the store handles WAL files.

Enumerator
OBXWalFlags_EnableWal	Enable Wal.
OBXWalFlags_NoSyncFile	Does not wait for the disk to acknowledge; faster but not ACID compliant (not generally recommended).

Function Documentation

obx_admin()

OBX_C_API OBX_admin* obx_admin

(

OBX_admin_options *

options

)

Initialize the http-server with the given options. Note: the given options are always freed by this function, including when an error occurs.

Parameters

options

required parameter holding the options (see obx_admin_opt_*())

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_admin_close()

OBX_C_API obx_err obx_admin_close

(

OBX_admin *

admin

)

Stop the http-server and free all the resources.

Parameters

admin

may be NULL

obx_admin_opt()

OBX_C_API OBX_admin_options* obx_admin_opt

(

)

Create a default set of admin options.

Returns

NULL on failure, a default set of options on success

obx_admin_opt_bind()

OBX_C_API obx_err obx_admin_opt_bind	(	OBX_admin_options *	opt,
		const char *	uri
	)

Set the address and port on which the underlying http-server should server the admin web UI. Defaults to "http://127.0.0.1:8081".

Note

: you can use for e.g. "http://127.0.0.1:0" for automatic free port assignment - see obx_admin_port().

obx_admin_opt_free()

OBX_C_API obx_err obx_admin_opt_free

(

OBX_admin_options *

opt

)

Free the options. Note: Only free unused options, obx_admin() frees the options internally.

obx_admin_opt_log_requests()

OBX_C_API obx_err obx_admin_opt_log_requests	(	OBX_admin_options *	opt,
		bool	value
	)

Logs request info, e.g. timing for serving a request.

obx_admin_opt_num_threads()

OBX_C_API obx_err obx_admin_opt_num_threads	(	OBX_admin_options *	opt,
		size_t	num_threads
	)

Sets the number of worker threads the http-server uses to serve requests. Default: 4.

obx_admin_opt_ssl_cert()

OBX_C_API obx_err obx_admin_opt_ssl_cert	(	OBX_admin_options *	opt,
		const char *	cert_path
	)

Configure the server to use SSL, with the given certificate.

Parameters

cert_path

- the file must be in PEM format, and it must have both private key and certificate (public key).

obx_admin_opt_store()

OBX_C_API obx_err obx_admin_opt_store	(	OBX_admin_options *	opt,
		OBX_store *	store
	)

Configure admin with an existing, open OBX_store*.

See also

also obx_admin_opt_store_path() as an alternative.

obx_admin_opt_store_path()

OBX_C_API obx_err obx_admin_opt_store_path	(	OBX_admin_options *	opt,
		const char *	directory
	)

Configure admin with an existing, open OBX_store*.

See also

also obx_admin_opt_store() as an alternative.

obx_admin_opt_unsecured_no_authentication()

OBX_C_API obx_err obx_admin_opt_unsecured_no_authentication	(	OBX_admin_options *	opt,
		bool	value
	)

Disables authentication to make the web app accessible to anyone, e.g. to allow recovery if users have locked themselves out. Otherwise, if users have been defined, authentication is enforced.

obx_admin_opt_user_management()

OBX_C_API obx_err obx_admin_opt_user_management	(	OBX_admin_options *	opt,
		bool	value
	)

Disable user management in the database - this is usually only done during development, with local-only access.

obx_admin_port()

OBX_C_API uint16_t obx_admin_port

(

OBX_admin *

admin

)

Returns a port this server listens on. This is especially useful if the port was assigned arbitrarily (a "0" port was used in the URL given to obx_admin_opt_bind()).

obx_async()

OBX_C_API OBX_async* obx_async

(

OBX_box *

box

)

Note: DO NOT close this OBX_async; its lifetime is tied to the OBX_box instance.

obx_async_close()

OBX_C_API obx_err obx_async_close

(

OBX_async *

async

)

Close a custom OBX_async instance created with obx_async_create().

Returns

OBX_ERROR_ILLEGAL_ARGUMENT if you pass the shared instance from obx_box_async()

obx_async_create()

OBX_C_API OBX_async* obx_async_create	(	OBX_box *	box,
		uint64_t	enqueue_timeout_millis
	)

Create a custom OBX_async instance that has to be closed using obx_async_close(). Note: for standard tasks, prefer obx_box_async() giving you a shared instance that does not have to be closed.

obx_async_insert()

OBX_C_API obx_err obx_async_insert	(	OBX_async *	async,
		obx_id	id,
		const void *	data,
		size_t	size
	)

Put asynchronously with inserts semantics (won't put if object already exists).

obx_async_insert_object()

OBX_C_API obx_id obx_async_insert_object	(	OBX_async *	async,
		void *	data,
		size_t	size
	)

Reserve an ID, which is returned immediately for future reference, and insert asynchronously. Note: of course, it can NOT be guaranteed that the entity will actually be inserted successfully in the DB.

Parameters

data	the given bytes are mutated to update the contained ID data.

Returns

id of the new object, 0 on error

obx_async_put()

OBX_C_API obx_err obx_async_put	(	OBX_async *	async,
		obx_id	id,
		const void *	data,
		size_t	size
	)

Put asynchronously with standard put semantics (insert or update).

obx_async_put5()

OBX_C_API obx_err obx_async_put5	(	OBX_async *	async,
		obx_id	id,
		const void *	data,
		size_t	size,
		OBXPutMode	mode
	)

Put asynchronously using the given mode.

obx_async_put_object()

OBX_C_API obx_id obx_async_put_object	(	OBX_async *	async,
		void *	data,
		size_t	size
	)

Reserve an ID, which is returned immediately for future reference, and put asynchronously. Note: of course, it can NOT be guaranteed that the entity will actually be put successfully in the DB.

Parameters

data	the given bytes are mutated to update the contained ID data.

Returns

id of the new object, 0 on error

obx_async_put_object4()

OBX_C_API obx_id obx_async_put_object4	(	OBX_async *	async,
		void *	data,
		size_t	size,
		OBXPutMode	mode
	)

FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW.

Parameters

data	writable data buffer, which may be updated for the ID

Returns

id of the new object, 0 on error, e.g. the entity can't be put according to OBXPutMode

obx_async_remove()

OBX_C_API obx_err obx_async_remove	(	OBX_async *	async,
		obx_id	id
	)

Remove asynchronously.

obx_async_update()

OBX_C_API obx_err obx_async_update	(	OBX_async *	async,
		obx_id	id,
		const void *	data,
		size_t	size
	)

Put asynchronously with update semantics (won't put if object is not yet present).

obx_box()

OBX_C_API OBX_box* obx_box	(	OBX_store *	store,
		obx_schema_id	entity_id
	)

Get access to the box for the given entity. A box may be used across threads. Boxes are shared instances and managed by the store so there's no need to close/free them manually.

obx_box_contains()

OBX_C_API obx_err obx_box_contains	(	OBX_box *	box,
		obx_id	id,
		bool *	out_contains
	)

Check whether a given object exists in the box.

obx_box_contains_many()

OBX_C_API obx_err obx_box_contains_many	(	OBX_box *	box,
		const OBX_id_array *	ids,
		bool *	out_contains
	)

Check whether this box contains objects with all of the IDs given.

Parameters

out_contains

is set to true if all of the IDs are present, otherwise false

obx_box_count()

OBX_C_API obx_err obx_box_count	(	OBX_box *	box,
		uint64_t	limit,
		uint64_t *	out_count
	)

Count the number of objects in the box, up to the given maximum. You can pass limit=0 to count all objects without any limitation.

obx_box_get()

OBX_C_API obx_err obx_box_get	(	OBX_box *	box,
		obx_id	id,
		const void **	data,
		size_t *	size
	)

Fetch a single object from the box; must be called inside a (reentrant) transaction. The exposed data comes directly from the OS to allow zero-copy access, which limits the data lifetime:

Attention

The exposed data is only valid as long as the (top) transaction is still active and no write

operation (e.g. put/remove) was executed. Accessing data after this is undefined behavior.

Returns

OBX_ERROR_ILLEGAL_STATE if not inside of an active transaction (see obx_txn_read() and obx_txn_write())

obx_box_get_all()

OBX_C_API OBX_bytes_array* obx_box_get_all

(

OBX_box *

box

)

Fetch all objects from the box; must be called inside a (reentrant) transaction. NOTE: don't call this in 32 bit mode! Use obx_box_visit_all() instead.

Attention

See obx_box_get() for important notes on the limited lifetime of the exposed data.

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details; e.g. code OBX_ERROR_ILLEGAL_STATE will be set if not inside of an active transaction (see obx_txn_read() and obx_txn_write())

obx_box_get_backlink_ids()

OBX_C_API OBX_id_array* obx_box_get_backlink_ids	(	OBX_box *	box,
		obx_schema_id	property_id,
		obx_id	id
	)

Fetch IDs of all objects that link back to the given object (ID) using the given relation property (ID). Note: This method refers to "property based relations" unlike the "stand-alone relations" (see obx_box_rel_*).

Parameters

property_id	the relation property, which must belong to the entity type represented by this box
id	object ID; the object's type is the target of the relation property (typically from another Box)

Returns

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

obx_box_get_many()

OBX_C_API OBX_bytes_array* obx_box_get_many	(	OBX_box *	box,
		const OBX_id_array *	ids
	)

Fetch multiple objects for the given IDs from the box; must be called inside a (reentrant) transaction.

Attention

See obx_box_get() for important notes on the limited lifetime of the exposed data.

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details; e.g. code OBX_ERROR_ILLEGAL_STATE will be set if not inside of an active transaction (see obx_txn_read() and obx_txn_write())

obx_box_id_for_put()

OBX_C_API obx_id obx_box_id_for_put	(	OBX_box *	box,
		obx_id	id_or_zero
	)

Prepares an ID for insertion: pass in 0 (zero) to reserve a new ID or an existing ID to check/prepare it.

Parameters

id_or_zero

The ID of the entity. If you pass 0, this will generate a new one. @seealso obx_cursor_id_for_put()

obx_box_ids_for_put()

OBX_C_API obx_err obx_box_ids_for_put	(	OBX_box *	box,
		uint64_t	count,
		obx_id *	out_first_id
	)

Reserve the given number of (new) IDs for insertion; a bulk version of obx_box_id_for_put().

Parameters

count	number of IDs to reserve, max 10000
out_first_id	the first ID of the sequence as

Returns

an error in case the required number of IDs could not be reserved.

obx_box_insert()

OBX_C_API obx_err obx_box_insert	(	OBX_box *	box,
		obx_id	id,
		const void *	data,
		size_t	size
	)

Convenience for obx_box_put5() with OBXPutMode_INSERT.

Parameters

id

non-zero

Returns

OBX_ERROR_ID_ALREADY_EXISTS if an insert fails because of a colliding ID

obx_box_is_empty()

OBX_C_API obx_err obx_box_is_empty	(	OBX_box *	box,
		bool *	out_is_empty
	)

Check whether there are any objects for this entity and updates the out_is_empty accordingly.

obx_box_put()

OBX_C_API obx_err obx_box_put	(	OBX_box *	box,
		obx_id	id,
		const void *	data,
		size_t	size
	)

Put the given object using the given ID synchronously; note that the ID also must match the one present in data.

Parameters

id	An ID usually reserved via obx_box_id_for_put().

See also

obx_box_put5() to additionally provide a put mode

obx_box_put_object() for a variant not requiring reserving IDs

obx_box_put5()

OBX_C_API obx_err obx_box_put5	(	OBX_box *	box,
		obx_id	id,
		const void *	data,
		size_t	size,
		OBXPutMode	mode
	)

Put the given object using the given ID synchronously; note that the ID also must match the one present in data.

Parameters

id	An ID usually reserved via obx_box_id_for_put().

See also

obx_box_put() for standard put mode

obx_box_put_object() for a variant not requiring reserving IDs

obx_box_put_many()

OBX_C_API obx_err obx_box_put_many	(	OBX_box *	box,
		const OBX_bytes_array *	objects,
		const obx_id *	ids,
		OBXPutMode	mode
	)

Put all given objects in the database in a single transaction. If any of the individual objects failed to put, none are put and an error is returned, equivalent to calling obx_box_put_many5() with fail_on_id_failure=true.

Parameters

ids	Previously allocated IDs for the given given objects (e.g. using obx_box_ids_for_put)

obx_box_put_many5()

OBX_C_API obx_err obx_box_put_many5	(	OBX_box *	box,
		const OBX_bytes_array *	objects,
		const obx_id *	ids,
		OBXPutMode	mode,
		bool	fail_on_id_failure
	)

Like obx_box_put_many(), but with an additional flag indicating how to treat ID failures with OBXPutMode_INSERT and OBXPutMode_UPDATE.

Parameters

fail_on_id_failure

if set to true, an ID failure (OBX_ERROR_ID_ALREADY_EXISTS and OBX_ERROR_ID_NOT_FOUND) will fail the transaction, and none of the objects are put/inserted/updated. Note 1: If this function is run inside a managed TX (created by obx_txn_write()) with fail_on_id_failure=true and a failure occurs, the whole outer TX is also aborted. Note 2: ID failure errors are returned even if fail_on_id_failure=false and the TX wasn't aborted.

obx_box_put_object()

OBX_C_API obx_id obx_box_put_object	(	OBX_box *	box,
		void *	data,
		size_t	size
	)

FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW.

Parameters

data	writable data buffer, which may be updated for the ID

Returns

id if the object could be put, or 0 in case of an error

obx_box_put_object4()

OBX_C_API obx_id obx_box_put_object4	(	OBX_box *	box,
		void *	data,
		size_t	size,
		OBXPutMode	mode
	)

FB ID slot must be present in the given data; new entities must have an ID value of zero or OBX_ID_NEW.

Parameters

data	writable data buffer, which may be updated for the ID

Returns

id if the object, or 0 in case of an error, e.g. the entity was not put according to OBXPutMode

obx_box_rel_get_backlink_ids()

OBX_C_API OBX_id_array* obx_box_rel_get_backlink_ids	(	OBX_box *	box,
		obx_schema_id	relation_id,
		obx_id	id
	)

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

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

Returns

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

obx_box_rel_get_ids()

OBX_C_API OBX_id_array* obx_box_rel_get_ids	(	OBX_box *	box,
		obx_schema_id	relation_id,
		obx_id	id
	)

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

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

Returns

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

obx_box_rel_put()

OBX_C_API obx_err obx_box_rel_put	(	OBX_box *	box,
		obx_schema_id	relation_id,
		obx_id	source_id,
		obx_id	target_id
	)

Insert a standalone relation entry between two objects.

Parameters

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

obx_box_rel_remove()

OBX_C_API obx_err obx_box_rel_remove	(	OBX_box *	box,
		obx_schema_id	relation_id,
		obx_id	source_id,
		obx_id	target_id
	)

Remove a standalone relation entry between two objects. See obx_box_rel_put() for parameters documentation.

obx_box_remove()

OBX_C_API obx_err obx_box_remove	(	OBX_box *	box,
		obx_id	id
	)

Remove a single object will return OBX_NOT_FOUND if an object with the given ID doesn't exist.

obx_box_remove_all()

OBX_C_API obx_err obx_box_remove_all	(	OBX_box *	box,
		uint64_t *	out_count
	)

Remove all objects and set the out_count the the number of removed objects.

Parameters

out_count

Pointer to retrieve the number of removed objects; optional: may be NULL.

obx_box_remove_many()

OBX_C_API obx_err obx_box_remove_many	(	OBX_box *	box,
		const OBX_id_array *	ids,
		uint64_t *	out_count
	)

Remove all given objects from the database in a single transaction. Note that this method will not fail if the object is not found (e.g. already removed). In case you need to strictly check whether all of the objects exist before removing them, execute obx_box_contains_ids() and obx_box_remove_ids() inside a single write transaction.

Parameters

out_count

Pointer to retrieve the number of removed objects; optional: may be NULL.

obx_box_store()

OBX_C_API OBX_store* obx_box_store

(

OBX_box *

box

)

Get access to the store this box belongs to - utility for when you only have access to the box variable but need some store method, such as starting a transaction. This doesn't produce a new instance of OBX_store, just gives you back the same pointer you've created this box with. In other words, don't close the returned store separately.

obx_box_ts_min_max()

OBX_C_API obx_err obx_box_ts_min_max	(	OBX_box *	box,
		obx_id *	out_min_id,
		int64_t *	out_min_value,
		obx_id *	out_max_id,
		int64_t *	out_max_value
	)

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

Parameters

out_min_id	pointer to receive an output (may be NULL)
out_min_value	pointer to receive an output (may be NULL)
out_max_id	pointer to receive an output (may be NULL)
out_max_value	pointer to receive an output (may be NULL)

Returns

OBX_NOT_FOUND if no objects are stored

obx_box_ts_min_max_range()

OBX_C_API obx_err obx_box_ts_min_max_range	(	OBX_box *	box,
		int64_t	range_begin,
		int64_t	range_end,
		obx_id *	out_min_id,
		int64_t *	out_min_value,
		obx_id *	out_max_id,
		int64_t *	out_max_value
	)

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

Parameters

out_min_id	pointer to receive an output (may be NULL)
out_min_value	pointer to receive an output (may be NULL)
out_max_id	pointer to receive an output (may be NULL)
out_max_value	pointer to receive an output (may be NULL)

Returns

OBX_NOT_FOUND if no objects are stored in the given range

obx_box_update()

OBX_C_API obx_err obx_box_update	(	OBX_box *	box,
		obx_id	id,
		const void *	data,
		size_t	size
	)

Convenience for obx_cursor_put4() with OBXPutMode_UPDATE.

Parameters

id

non-zero

Returns

OBX_ERROR_ID_NOT_FOUND if an update fails because the given ID does not represent any object

obx_box_visit_all()

OBX_C_API obx_err obx_box_visit_all	(	OBX_box *	box,
		obx_data_visitor *	visitor,
		void *	user_data
	)

Read all objects in a single transaction. Calls the visitor() on each object, passing visitor_arg, object data & size as arguments. The given visitor must return true to keep receiving results, false to cancel.

obx_box_visit_many()

OBX_C_API obx_err obx_box_visit_many	(	OBX_box *	box,
		const OBX_id_array *	ids,
		obx_data_visitor *	visitor,
		void *	user_data
	)

Read given objects from the database in a single transaction. Call the visitor() on each object, passing user_data, object data & size as arguments. The given visitor must return true to keep receiving results, false to cancel. If an object is not found, the visitor() is still called, passing NULL as data and a 0 as size.

obx_bytes_array()

OBX_C_API OBX_bytes_array* obx_bytes_array

(

size_t

count

)

Allocate a bytes array struct of the given size, ready for the data to be pushed.

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_bytes_array_free()

OBX_C_API void obx_bytes_array_free

(

OBX_bytes_array *

array

)

Free the bytes array struct.

obx_bytes_array_set()

OBX_C_API obx_err obx_bytes_array_set	(	OBX_bytes_array *	array,
		size_t	index,
		const void *	data,
		size_t	size
	)

Set the given data as the index in the bytes array. The data is not copied, just referenced through the pointer.

obx_bytes_free()

OBX_C_API void obx_bytes_free

(

OBX_bytes *

bytes

)

obx_bytes_lazy_free()

OBX_C_API void obx_bytes_lazy_free

(

OBX_bytes_lazy *

bytes

)

Releases any resources associated with the given OBX_bytes_lazy.

obx_bytes_lazy_get()

OBX_C_API obx_err obx_bytes_lazy_get	(	OBX_bytes_lazy *	bytes,
		const void **	out_bytes,
		size_t *	out_size
	)

Get the actual bytes from the given OBX_bytes_lazy. Because of the potential lazy creation of bytes, the given bytes are not const as it may be resolved internally. For the same reason, this function is not thread-safe, at least for the first call on a OBX_bytes_lazy instance.

Parameters

out_bytes

The pointer to a data pointer may be null, e.g. if you are only interested in the size.

obx_bytes_score_array_free()

OBX_C_API void obx_bytes_score_array_free

(

OBX_bytes_score_array *

array

)

Free the array struct.

obx_cursor()

OBX_C_API OBX_cursor* obx_cursor	(	OBX_txn *	txn,
		obx_schema_id	entity_id
	)

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_cursor_backlink_ids()

OBX_C_API OBX_id_array* obx_cursor_backlink_ids	(	OBX_cursor *	cursor,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		obx_id	id
	)

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_cursor_backlinks()

OBX_C_API OBX_bytes_array* obx_cursor_backlinks	(	OBX_cursor *	cursor,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		obx_id	id
	)

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_cursor_close()

OBX_C_API obx_err obx_cursor_close

(

OBX_cursor *

cursor

)

Parameters

cursor

may be NULL

obx_cursor_count()

OBX_C_API obx_err obx_cursor_count	(	OBX_cursor *	cursor,
		uint64_t *	count
	)

Count the number of available objects.

obx_cursor_count_max()

OBX_C_API obx_err obx_cursor_count_max	(	OBX_cursor *	cursor,
		uint64_t	max_count,
		uint64_t *	out_count
	)

Count the number of available objects up to the specified maximum.

obx_cursor_current()

OBX_C_API obx_err obx_cursor_current	(	OBX_cursor *	cursor,
		const void **	data,
		size_t *	size
	)

obx_cursor_current_id()

OBX_C_API obx_err obx_cursor_current_id	(	OBX_cursor *	cursor,
		obx_id *	out_id
	)

Gets the object ID at the current position; ensures being up-to-date by verifying against database.

Parameters

out_id

pointer to receive an output. If the cursor is not positioned at an actual object, it receives one of two special IDs: 0 (OBJECT_ID_BEFORE_START) if the cursor was not yet moved or reached the end (going backwards). 0xFFFFFFFFFFFFFFFF (OBJECT_ID_BEYOND_END) if the cursor reached the end (going forwards).

obx_cursor_first()

OBX_C_API obx_err obx_cursor_first	(	OBX_cursor *	cursor,
		const void **	data,
		size_t *	size
	)

obx_cursor_get()

OBX_C_API obx_err obx_cursor_get	(	OBX_cursor *	cursor,
		obx_id	id,
		const void **	data,
		size_t *	size
	)

obx_cursor_get_all()

OBX_C_API OBX_bytes_array* obx_cursor_get_all

(

OBX_cursor *

cursor

)

Get all objects as bytes. For larger quantities, it's recommended to iterate using obx_cursor_first and obx_cursor_next. However, if the calling overhead is high (e.g., for language bindings), this method helps.

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_cursor_id_for_put()

OBX_C_API obx_id obx_cursor_id_for_put	(	OBX_cursor *	cursor,
		obx_id	id_or_zero
	)

Call this when putting an object to generate/prepare an ID for it.

Parameters

id_or_zero

The ID of the entity. If you pass 0, this will generate a new one. @seealso obx_box_id_for_put()

obx_cursor_insert()

OBX_C_API obx_err obx_cursor_insert	(	OBX_cursor *	cursor,
		obx_id	id,
		const void *	data,
		size_t	size
	)

Convenience for obx_cursor_put4() with OBXPutMode_INSERT.

Parameters

id

non-zero

Returns

OBX_ERROR_ID_ALREADY_EXISTS if an insert fails because of a colliding ID

obx_cursor_is_empty()

OBX_C_API obx_err obx_cursor_is_empty	(	OBX_cursor *	cursor,
		bool *	out_is_empty
	)

Return true if there is no object available (false if at least one object is available)

obx_cursor_next()

OBX_C_API obx_err obx_cursor_next	(	OBX_cursor *	cursor,
		const void **	data,
		size_t *	size
	)

obx_cursor_put()

OBX_C_API obx_err obx_cursor_put	(	OBX_cursor *	cursor,
		obx_id	id,
		const void *	data,
		size_t	size
	)

Puts the given object data using the given ID. A "put" in ObjectBox follows "insert or update" semantics; New objects (no pre-existing object for given ID) are inserted while existing objects are replaced/updated.

Parameters

id

non-zero

obx_cursor_put4()

OBX_C_API obx_err obx_cursor_put4	(	OBX_cursor *	cursor,
		obx_id	id,
		const void *	data,
		size_t	size,
		OBXPutMode	mode
	)

Like put obx_cursor_put(), but takes an additional parameter (4th parameter) for choosing a put mode.

Parameters

id	non-zero
mode	Changes the put semantics to the given mode, e.g. OBXPutMode_INSERT or OBXPutMode_UPDATE.

Returns

OBX_SUCCESS if the put operation was successful

OBX_ERROR_ID_ALREADY_EXISTS OBXPutMode_INSERT was used, but an existing object was found using the given ID

OBX_ERROR_ID_NOT_FOUND OBXPutMode_UPDATE was used, but no object was found for the given ID

obx_cursor_put_new()

OBX_C_API obx_err obx_cursor_put_new	(	OBX_cursor *	cursor,
		obx_id	id,
		const void *	data,
		size_t	size
	)

An optimized version of obx_cursor_put() if you can ensure that the given ID is not used yet. Typically used right after getting a new ID via obx_cursor_id_for_put(). WARNING: using this incorrectly (an object with the given ID already exists) may result in inconsistent data (e.g. indexes do not get updated).

Parameters

id

non-zero

obx_cursor_put_object()

obx_id obx_cursor_put_object	(	OBX_cursor *	cursor,
		void *	data,
		size_t	size
	)

FB ID slot must be present; new entities must prepare the slot using the special value OBX_ID_NEW. Alternatively, you may also pass 0 to indicate a new entity if you are aware that FlatBuffers builders typically skip zero values by default. Thus, you have to "force" writing the zero in FlatBuffers.

Parameters

data	object data, non-const because the ID slot will be written (mutated) for new entites (see above)

Returns

id if the object could be put, or 0 in case of an error

obx_cursor_put_object4()

OBX_C_API obx_id obx_cursor_put_object4	(	OBX_cursor *	cursor,
		void *	data,
		size_t	size,
		OBXPutMode	mode
	)

obx_cursor_rel_ids()

OBX_C_API OBX_id_array* obx_cursor_rel_ids	(	OBX_cursor *	cursor,
		obx_schema_id	relation_id,
		obx_id	source_id
	)

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_cursor_rel_put()

OBX_C_API obx_err obx_cursor_rel_put	(	OBX_cursor *	cursor,
		obx_schema_id	relation_id,
		obx_id	source_id,
		obx_id	target_id
	)

obx_cursor_rel_remove()

OBX_C_API obx_err obx_cursor_rel_remove	(	OBX_cursor *	cursor,
		obx_schema_id	relation_id,
		obx_id	source_id,
		obx_id	target_id
	)

obx_cursor_remove()

OBX_C_API obx_err obx_cursor_remove	(	OBX_cursor *	cursor,
		obx_id	id
	)

obx_cursor_remove_all()

OBX_C_API obx_err obx_cursor_remove_all

(

OBX_cursor *

cursor

)

obx_cursor_seek()

OBX_C_API obx_err obx_cursor_seek	(	OBX_cursor *	cursor,
		obx_id	id
	)

obx_cursor_seek_first_id()

OBX_C_API obx_err obx_cursor_seek_first_id	(	OBX_cursor *	cursor,
		obx_id *	out_id
	)

Gets the first object ID or zero if there was no object.

obx_cursor_seek_next_id()

OBX_C_API obx_err obx_cursor_seek_next_id	(	OBX_cursor *	cursor,
		obx_id *	out_id
	)

Gets the next object ID or zero if there was no next object.

obx_cursor_ts_min_max()

OBX_C_API obx_err obx_cursor_ts_min_max	(	OBX_cursor *	cursor,
		obx_id *	out_min_id,
		int64_t *	out_min_value,
		obx_id *	out_max_id,
		int64_t *	out_max_value
	)

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

Parameters

out_min_id	pointer to receive an output (may be NULL)
out_min_value	pointer to receive an output (may be NULL)
out_max_id	pointer to receive an output (may be NULL)
out_max_value	pointer to receive an output (may be NULL)

Returns

OBX_NOT_FOUND if no objects are stored

obx_cursor_ts_min_max_range()

OBX_C_API obx_err obx_cursor_ts_min_max_range	(	OBX_cursor *	cursor,
		int64_t	range_begin,
		int64_t	range_end,
		obx_id *	out_min_id,
		int64_t *	out_min_value,
		obx_id *	out_max_id,
		int64_t *	out_max_value
	)

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

Parameters

out_min_id	pointer to receive an output (may be NULL)
out_min_value	pointer to receive an output (may be NULL)
out_max_id	pointer to receive an output (may be NULL)
out_max_value	pointer to receive an output (may be NULL)

Returns

OBX_NOT_FOUND if no objects are stored in the given range

obx_cursor_update()

OBX_C_API obx_err obx_cursor_update	(	OBX_cursor *	cursor,
		obx_id	id,
		const void *	data,
		size_t	size
	)

Convenience for obx_cursor_put4() with OBXPutMode_UPDATE.

Parameters

id

non-zero

Returns

OBX_ERROR_ID_NOT_FOUND if an update fails because the given ID does not represent any object

obx_db_file_size()

OBX_C_API size_t obx_db_file_size

(

char const *

directory

)

Returns

the file size of the main database file, or 0 if the file does not exist or some error occurred.

obx_debug_log()

OBX_C_API obx_err obx_debug_log

(

bool

enabled

)

Enable (or disable) debug logging for ObjectBox internals. This requires a version of the library with the DebugLog feature. You can check if the feature is available with obx_has_feature(OBXFeature_DebugLog).

obx_debug_log_enabled()

OBX_C_API bool obx_debug_log_enabled

(

)

Checks if debug logs are enabled for ObjectBox internals. This depends on the availability of the DebugLog feature. If the feature is available, it returns the current state, which is adjustable via obx_debug_log(). Otherwise, it always returns false for standard release builds (or true if you are having a special debug version).

obx_double_array_free()

OBX_C_API void obx_double_array_free

(

OBX_double_array *

array

)

Free the array struct.

obx_expired_objects_remove()

OBX_C_API obx_err obx_expired_objects_remove	(	OBX_txn *	txn,
		obx_schema_id	entity_id,
		size_t *	out_removed_count
	)

Removes expired objects of one or all entity types.

Parameters

entity_id	Type of the objects to be remove; if zero, all types are included. Hint: if you only have the entity type's name, use obx_store_entity_id() to get the ID.
out_removed_count	If given (non-null), it will receive the count of removed objects.

See also

OBXPropertyFlags_EXPIRATION_TIME to define a property for the expiration time.

obx_expired_objects_remove_async()

OBX_C_API obx_err obx_expired_objects_remove_async	(	OBX_store *	store,
		obx_schema_id	entity_id,
		obx_status_callback *	callback,
		void *	user_data
	)

Asynchronously removes expired objects of one or all entity types.

Parameters

entity_id

Type of the objects to be remove; if zero, all types are included. Hint: if you only have the entity type's name, use obx_store_entity_id() to get the ID.

See also

OBXPropertyFlags_EXPIRATION_TIME to define a property for the expiration time.

obx_float_array_free()

OBX_C_API void obx_float_array_free

(

OBX_float_array *

array

)

Free the array struct.

obx_has_feature()

OBX_C_API bool obx_has_feature

(

OBXFeature

feature

)

Checks whether the given feature is available in the currently loaded library.

obx_id_array()

OBX_C_API OBX_id_array* obx_id_array	(	const obx_id *	ids,
		size_t	count
	)

Create an ID array struct, copying the given IDs as the contents.

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_id_array_free()

OBX_C_API void obx_id_array_free

(

OBX_id_array *

array

)

Free the array struct.

obx_id_score_array_free()

OBX_C_API void obx_id_score_array_free

(

OBX_id_score_array *

array

)

Free the array struct.

obx_int16_array_free()

OBX_C_API void obx_int16_array_free

(

OBX_int16_array *

array

)

Free the array struct.

obx_int32_array_free()

OBX_C_API void obx_int32_array_free

(

OBX_int32_array *

array

)

Free the array struct.

obx_int64_array_free()

OBX_C_API void obx_int64_array_free

(

OBX_int64_array *

array

)

Free the array struct.

obx_int8_array_free()

OBX_C_API void obx_int8_array_free

(

OBX_int8_array *

array

)

Free the array struct.

obx_last_error_clear()

OBX_C_API void obx_last_error_clear

(

void

)

Clear the error state on the current thread; e.g. obx_last_error_code() will now return OBX_SUCCESS. Note that clearing the error state does not happen automatically; API calls set the error state when they produce an error, but do not clear it on success. See also: obx_last_error_pop() to retrieve the error state and clear it.

obx_last_error_code()

OBX_C_API obx_err obx_last_error_code

(

void

)

The last error raised by an ObjectBox API call on the current thread, or OBX_SUCCESS if no error occurred yet. Note that API calls do not clear this error code (also true for this method). Thus, if you receive an error from this, it's usually a good idea to call obx_last_error_clear() to clear the error state (or use obx_last_error_pop()) for future API calls.

obx_last_error_message()

OBX_C_API const char* obx_last_error_message

(

void

)

The error message string attached to the error returned by obx_last_error_code(). Like obx_last_error_code(), this is bound to the current thread, and this call does not clear the error state. The buffer returned is valid only until the next call into ObjectBox.

obx_last_error_pop()

OBX_C_API bool obx_last_error_pop	(	obx_err *	out_error,
		const char **	out_message
	)

Return the error status on the current thread and clear the error state. The buffer returned in out_message is valid only until the next call into ObjectBox.

Parameters

out_error	receives the error code; optional: may be NULL
out_message	receives the pointer to the error messages; optional: may be NULL

Returns

true if an error was pending

obx_last_error_secondary()

OBX_C_API obx_err obx_last_error_secondary

(

void

)

The underlying error for the error returned by obx_last_error_code(). Where obx_last_error_code() may be a generic error like OBX_ERROR_STORAGE_GENERAL, this will give a further underlying and possibly platform-specific error code.

obx_last_error_set()

OBX_C_API bool obx_last_error_set	(	obx_err	code,
		obx_err	secondary,
		const char *	message
	)

Set the last error code and test - reserved for internal use from generated code.

obx_model()

OBX_C_API OBX_model* obx_model

(

void

)

Create an (empty) data meta model which is to be consumed by obx_opt_model().

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details. Note that obx_model_* functions handle OBX_model NULL pointers (will indicate an error but not crash).

obx_model_entity()

OBX_C_API obx_err obx_model_entity	(	OBX_model *	model,
		const char *	name,
		obx_schema_id	entity_id,
		obx_uid	entity_uid
	)

Starts the definition of a new entity type for the meta data model. After this, call obx_model_property() to add properties to the entity type.

Parameters

name	A human readable name for the entity. Must be unique within the model
entity_id	Must be unique within this version of the model
entity_uid	Used to identify entities between versions of the model. Must be globally unique.

obx_model_entity_flags()

OBX_C_API obx_err obx_model_entity_flags	(	OBX_model *	model,
		uint32_t	flags
	)

Refine the definition of the entity declared by the most recent obx_model_entity() call, specifying flags.

Parameters

flags

See OBXEntityFlags for values (use bitwise OR to combine multiple flags)

obx_model_entity_last_property_id()

OBX_C_API obx_err obx_model_entity_last_property_id	(	OBX_model *	model,
		obx_schema_id	property_id,
		obx_uid	property_uid
	)

Set the highest ever known property id in the entity. Should always be equal to or higher than the last property id of the previous version of the entity.

obx_model_error_code()

OBX_C_API obx_err obx_model_error_code

(

OBX_model *

model

)

To minimise the amount of error handling code required when building a model, the first error is stored and can be obtained here. All the obx_model_XXX functions are null operations after the first model error has occurred.

Parameters

model

NULL-able; returns OBX_ERROR_ILLEGAL_ARGUMENT if model is NULL

obx_model_error_message()

OBX_C_API const char* obx_model_error_message

(

OBX_model *

model

)

To minimise the amount of error handling code required when building a model, the first error is stored and can be obtained here. All the obx_model_XXX functions are null operations after the first model error has occurred.

Parameters

model

NULL-able; returns NULL if model is NULL

obx_model_free()

OBX_C_API obx_err obx_model_free

(

OBX_model *

model

)

Only call when not calling obx_store_open() (which will free it internally)

Parameters

model

NULL-able; returns OBX_SUCCESS if model is NULL

obx_model_last_entity_id()

OBX_C_API void obx_model_last_entity_id	(	OBX_model *	,
		obx_schema_id	entity_id,
		obx_uid	entity_uid
	)

Set the highest ever known entity id in the model. Should always be equal to or higher than the last entity id of the previous version of the model.

obx_model_last_index_id()

OBX_C_API void obx_model_last_index_id	(	OBX_model *	model,
		obx_schema_id	index_id,
		obx_uid	index_uid
	)

Set the highest ever known index id in the model. Should always be equal to or higher than the last index id of the previous version of the model.

obx_model_last_relation_id()

OBX_C_API void obx_model_last_relation_id	(	OBX_model *	model,
		obx_schema_id	relation_id,
		obx_uid	relation_uid
	)

Set the highest every known relation id in the model. Should always be equal to or higher than the last relation id of the previous version of the model.

obx_model_property()

OBX_C_API obx_err obx_model_property	(	OBX_model *	model,
		const char *	name,
		OBXPropertyType	type,
		obx_schema_id	property_id,
		obx_uid	property_uid
	)

Starts the definition of a new property for the entity type of the last obx_model_entity() call.

Parameters

name	A human readable name for the property. Must be unique within the entity
type	The type of property required
property_id	Must be unique within the entity
property_uid	Used to identify properties between versions of the entity. Must be global unique.

obx_model_property_flags()

OBX_C_API obx_err obx_model_property_flags	(	OBX_model *	model,
		uint32_t	flags
	)

Refine the definition of the property declared by the most recent obx_model_property() call, specifying flags.

Parameters

flags

See OBXPropertyFlags for values (use bitwise OR to combine multiple flags)

obx_model_property_index_hnsw_dimensions()

OBX_C_API obx_err obx_model_property_index_hnsw_dimensions	(	OBX_model *	model,
		size_t	value
	)

Sets the vector dimensionality for the HNSW index of the latest property (must be of a supported vector type). This a mandatory option for all HNSW indexes. Note 1: vectors with higher dimensions than this value are also indexed (ignoring the higher elements). Note 2: vectors with lower dimensions than this value are completely ignored for indexing.

obx_model_property_index_hnsw_distance_type()

OBX_C_API obx_err obx_model_property_index_hnsw_distance_type	(	OBX_model *	model,
		OBXVectorDistanceType	value
	)

Sets the distance type for the HNSW index of the latest property.

obx_model_property_index_hnsw_flags()

OBX_C_API obx_err obx_model_property_index_hnsw_flags	(	OBX_model *	model,
		uint32_t	flags
	)

Sets flags for the HNSW index of the latest property (). For details see OBXHnswFlags and its individual values.

Parameters

flags

See OBXHnswFlags for values (use bitwise OR to combine multiple flags)

obx_model_property_index_hnsw_indexing_search_count()

OBX_C_API obx_err obx_model_property_index_hnsw_indexing_search_count	(	OBX_model *	model,
		uint32_t	value
	)

Sets the max number of neighbors searched while indexing (aka "efConstruction") for the HNSW index of the latest property. If no value is set, a default value taken (currently 100, which can change in future version). The default value serves as a starting point that can likely be optimized for specific datasets and use cases. The higher the value, the more accurate the search, but the longer the indexing will take. If indexing time is not a major concern, a value of at least 200 is recommended to improve search quality.

obx_model_property_index_hnsw_neighbors_per_node()

OBX_C_API obx_err obx_model_property_index_hnsw_neighbors_per_node	(	OBX_model *	model,
		uint32_t	value
	)

Sets the max number of neighbors per node (aka "M") for the HNSW index of the latest property. Higher number increases the graph connectivity which can lead to better results, but higher resources usage. If no value is set, a default value taken (currently 30). Try e.g. 16 for faster but less accurate results, or 64 for more accurate results.

obx_model_property_index_hnsw_reparation_backlink_probability()

OBX_C_API obx_err obx_model_property_index_hnsw_reparation_backlink_probability	(	OBX_model *	model,
		float	value
	)

Sets the reparation backlink probability, for the HNSW index of the latest property. When repairing the graph after a node was removed, this gives the probability of adding backlinks to the repaired neighbors. The default is 1.0 (aka "always") as this should be worth a bit of extra costs as it improves the graph's quality.

obx_model_property_index_hnsw_vector_cache_hint_size_kb()

OBX_C_API obx_err obx_model_property_index_hnsw_vector_cache_hint_size_kb	(	OBX_model *	model,
		size_t	value
	)

Sets the vector cache hint size for the HNSW index of the latest property. This is a non-binding hint of the maximum size of the vector cache in KB (default: 2097152 or 2 GB/GiB).

obx_model_property_index_id()

OBX_C_API obx_err obx_model_property_index_id	(	OBX_model *	model,
		obx_schema_id	index_id,
		obx_uid	index_uid
	)

Refine the definition of the property declared by the most recent obx_model_property() call, adding an index.

Parameters

index_id	Must be unique within this version of the model
index_uid	Used to identify relations between versions of the model. Must be globally unique.

obx_model_property_relation()

OBX_C_API obx_err obx_model_property_relation	(	OBX_model *	model,
		const char *	target_entity,
		obx_schema_id	index_id,
		obx_uid	index_uid
	)

Refine the definition of the property declared by the most recent obx_model_property() call, declaring it a relation.

Parameters

target_entity	The name of the entity linked to by the relation
index_id	Must be unique within this version of the model
index_uid	Used to identify relations between versions of the model. Must be globally unique.

obx_model_relation()

OBX_C_API obx_err obx_model_relation	(	OBX_model *	model,
		obx_schema_id	relation_id,
		obx_uid	relation_uid,
		obx_schema_id	target_id,
		obx_uid	target_uid
	)

Add a standalone relation between the active entity and the target entity to the model.

Parameters

relation_id	Must be unique within this version of the model
relation_uid	Used to identify relations between versions of the model. Must be globally unique.
target_id	The id of the target entity of the relation
target_uid	The uid of the target entity of the relation

obx_observe()

OBX_C_API OBX_observer* obx_observe	(	OBX_store *	store,
		obx_observer *	callback,
		void *	user_data
	)

Create an observer (callback) to be notified about all data changes (for all object types). The callback is invoked right after a successful commit.

Threading note

The given callback is called on the thread issuing the commit for the data change, e.g. via obx_txn_success(). Future versions might change that to a background thread, so be careful with threading assumptions. Also, it's a usually good idea to make the callback return quickly to let the calling thread continue.

Attention

Currently, you can not call any data operations from inside the call back.

More accurately, no transaction may be strated. (This restriction may be removed in a later version.)

Parameters

user_data	any value you want to be forwarded to the given observer callback (usually some context info).
callback	pointer to be called when the observed data changes.

Returns

NULL if a illegal locking situation was detected, e.g. called from an observer itself or a timeout/deadlock was detected (OBX_ERROR_ILLEGAL_STATE).

obx_observe_single_type()

OBX_C_API OBX_observer* obx_observe_single_type	(	OBX_store *	store,
		obx_schema_id	type_id,
		obx_observer_single_type *	callback,
		void *	user_data
	)

Create an observer (callback) to be notified about data changes for a given object type. The callback is invoked right after a successful commit.

Note

If you intend to observe more than one type, it is more efficient to use obx_observe().

Threading note

The given callback is called on the thread issuing the commit for the data change, e.g. via obx_txn_success(). Future versions might change that to a background thread, so be careful with threading assumptions. Also, it's a usually good idea to make the callback return quickly to let the calling thread continue.

Attention

Currently, you can not call any data operations from inside the call back.

More accurately, no transaction may be started. (This restriction may be removed in a later version.)

Parameters

type_id	ID of the object type to be observer.
user_data	any value you want to be forwarded to the given observer callback (usually some context info).
callback	pointer to be called when the observed data changes.

Returns

NULL if a illegal locking situation was detected, e.g. called from an observer itself or a timeout/deadlock was detected (OBX_ERROR_ILLEGAL_STATE).

obx_observer_close()

OBX_C_API obx_err obx_observer_close

(

OBX_observer *

observer

)

Free the memory used by the given observer and unsubscribe it from its box or query.

Returns

OBX_ERROR_ILLEGAL_STATE if a illegal locking situation was detected, e.g. called from an observer itself or a timeout/deadlock was detected. In that case, the caller must try to close again in a valid situation not causing lock failures.

obx_opt()

OBX_C_API OBX_store_options* obx_opt

(

)

Create a default set of store options.

Returns

NULL on failure, a default set of options on success

obx_opt_add_debug_flags()

OBX_C_API void obx_opt_add_debug_flags	(	OBX_store_options *	opt,
		uint32_t	flags
	)

Adds debug flags (OBXDebugFlags) to potentially existing ones. Combine multiple flags using bitwise OR.

obx_opt_async_max_in_tx_duration()

OBX_C_API void obx_opt_async_max_in_tx_duration	(	OBX_store_options *	opt,
		uint32_t	micros
	)

Maximum duration spent in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate.

obx_opt_async_max_in_tx_operations()

OBX_C_API void obx_opt_async_max_in_tx_operations	(	OBX_store_options *	opt,
		uint32_t	value
	)

Maximum operations performed in a transaction before AsyncQ enforces a commit. This becomes relevant if the queue is constantly populated at a high rate.

obx_opt_async_max_queue_length()

OBX_C_API void obx_opt_async_max_queue_length	(	OBX_store_options *	opt,
		size_t	value
	)

Maximum of async elements in the queue before new elements will be rejected. Hitting this limit usually hints that async processing cannot keep up; data is produced at a faster rate than it can be persisted in the background. In that case, increasing this value is not the only alternative; other values might also optimize throughput. For example, increasing maxInTxDurationMicros may help too.

obx_opt_async_max_tx_pool_size()

OBX_C_API void obx_opt_async_max_tx_pool_size	(	OBX_store_options *	opt,
		size_t	value
	)

Default value: 10000, set to 0 to deactivate pooling.

obx_opt_async_minor_refill_max_count()

OBX_C_API void obx_opt_async_minor_refill_max_count	(	OBX_store_options *	opt,
		uint32_t	value
	)

If non-zero, this allows "minor refills" with small batches that came in (off by default).

obx_opt_async_minor_refill_threshold()

OBX_C_API void obx_opt_async_minor_refill_threshold	(	OBX_store_options *	opt,
		size_t	queue_length
	)

Numbers of operations below this value are considered "minor refills".

obx_opt_async_object_bytes_max_cache_size()

OBX_C_API void obx_opt_async_object_bytes_max_cache_size	(	OBX_store_options *	opt,
		uint64_t	value
	)

Total cache size; default: ~ 0.5 MB.

obx_opt_async_object_bytes_max_size_to_cache()

OBX_C_API void obx_opt_async_object_bytes_max_size_to_cache	(	OBX_store_options *	opt,
		uint64_t	value
	)

Maximal size for an object to be cached (only cache smaller ones)

obx_opt_async_post_txn_delay()

OBX_C_API void obx_opt_async_post_txn_delay	(	OBX_store_options *	opt,
		uint32_t	delay_micros
	)

Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around.

obx_opt_async_post_txn_delay5()

OBX_C_API void obx_opt_async_post_txn_delay5	(	OBX_store_options *	opt,
		uint32_t	delay_micros,
		uint32_t	delay2_micros,
		size_t	min_queue_length_for_delay2,
		bool	subtract_processing_time
	)

Similar to preTxDelay but after a transaction was committed. One of the purposes is to give other transactions some time to execute. In combination with preTxDelay this can prolong non-TX batching time if only a few operations are around.

Parameters

subtract_processing_time

If set, delay_micros is interpreted from the start of TX processing. In other words, the actual delay is delay_micros minus the TX processing time including the commit. This can make timings more accurate (e.g. when fixed batching interval are given).

obx_opt_async_pre_txn_delay()

OBX_C_API void obx_opt_async_pre_txn_delay	(	OBX_store_options *	opt,
		uint32_t	delay_micros
	)

Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations.

obx_opt_async_pre_txn_delay4()

OBX_C_API void obx_opt_async_pre_txn_delay4	(	OBX_store_options *	opt,
		uint32_t	delay_micros,
		uint32_t	delay2_micros,
		size_t	min_queue_length_for_delay2
	)

Before the AsyncQ is triggered by a new element in queue to starts a new run, it delays actually starting the transaction by this value. This gives a newly starting producer some time to produce more than one a single operation before AsyncQ starts. Note: this value should typically be low to keep latency low and prevent accumulating too much operations.

obx_opt_async_throttle_at_queue_length()

OBX_C_API void obx_opt_async_throttle_at_queue_length	(	OBX_store_options *	opt,
		size_t	value
	)

Producers (AsyncTx submitter) is throttled when the queue size hits this.

obx_opt_async_throttle_micros()

OBX_C_API void obx_opt_async_throttle_micros	(	OBX_store_options *	opt,
		uint32_t	value
	)

Sleeping time for throttled producers on each submission.

obx_opt_backup_restore()

OBX_C_API void obx_opt_backup_restore	(	OBX_store_options *	opt,
		const char *	backup_file,
		uint32_t	flags
	)

Before opening the database, this options instructs to restore the database content from the given backup file. Note: backup is a server-only feature. By default, actually restoring the backup is only performed if no database already exists (database does not contain data).

Parameters

flags

For default behavior pass 0, or adjust defaults using OBXBackupRestoreFlags bit flags, e.g., to overwrite all existing data in the database.

obx_opt_debug_flags()

OBX_C_API void obx_opt_debug_flags	(	OBX_store_options *	opt,
		uint32_t	flags
	)

Configure debug flags (OBXDebugFlags); e.g. to influence logging. Defaults to NONE. Combine multiple flags using bitwise OR.

obx_opt_directory()

OBX_C_API obx_err obx_opt_directory	(	OBX_store_options *	opt,
		const char *	dir
	)

Set the store directory on the options. The default is "objectbox". Use prefix "memory:" to open an in-memory database, e.g. "memory:myApp" (see docs for details).

obx_opt_file_mode()

OBX_C_API void obx_opt_file_mode	(	OBX_store_options *	opt,
		unsigned int	file_mode
	)

Set the file mode on the options. The default is 0644 (unix-style).

obx_opt_free()

OBX_C_API void obx_opt_free

(

OBX_store_options *

opt

)

Free the options. Note: Only free unused options, obx_store_open() frees the options internally.

obx_opt_get_debug_flags()

OBX_C_API uint32_t obx_opt_get_debug_flags

(

OBX_store_options *

opt

)

Gets the option for "debug flags"; this is either the default, or, the value set by obx_opt_debug_flags().

Returns

0 if an error occurred, e.g. the given options were null.

obx_opt_get_directory()

OBX_C_API const char* obx_opt_get_directory

(

OBX_store_options *

opt

)

Gets the option for "directory"; this is either the default, or, the value set by obx_opt_directory(). The returned value must not be modified and is only valid for the lifetime of the options or until the value is changed.

Returns

null if an error occurred, e.g. the given options were null.

obx_opt_get_max_data_size_in_kb()

OBX_C_API uint64_t obx_opt_get_max_data_size_in_kb

(

OBX_store_options *

opt

)

Gets the option for "max data size"; this is either the default, or, the value set by obx_opt_max_data_size_in_kb().

Returns

0 if an error occurred, e.g. the given options were null.

obx_opt_get_max_db_size_in_kb()

OBX_C_API uint64_t obx_opt_get_max_db_size_in_kb

(

OBX_store_options *

opt

)

Gets the option for "max DB size"; this is either the default, or, the value set by obx_opt_max_db_size_in_kb().

Returns

0 if an error occurred, e.g. the given options were null.

obx_opt_log_callback()

OBX_C_API void obx_opt_log_callback	(	OBX_store_options *	opt,
		obx_log_callback *	callback,
		void *	user_data
	)

Registers a log callback, which is called for a selection of log events. Note: this does not replace the default logging, which is much more extensive (at least at this point).

obx_opt_max_data_size_in_kb()

OBX_C_API void obx_opt_max_data_size_in_kb	(	OBX_store_options *	opt,
		uint64_t	size_in_kb
	)

Data size tracking is more involved than DB size tracking, e.g. it stores an internal counter. Thus only use it if a stricter, more accurate limit is required (it's off by default). It tracks the size of actual data bytes of objects (system and metadata is not considered). On the upside, reaching the data limit still allows data to be removed (assuming DB limit is not reached). Max data and DB sizes can be combined; data size must be below the DB size.

obx_opt_max_db_size_in_kb()

OBX_C_API void obx_opt_max_db_size_in_kb	(	OBX_store_options *	opt,
		uint64_t	size_in_kb
	)

Set the maximum db size on the options. The default is 1Gb.

obx_opt_max_readers()

OBX_C_API void obx_opt_max_readers	(	OBX_store_options *	opt,
		unsigned int	max_readers
	)

Set the maximum number of readers (related to read transactions) on the given options. "Readers" are an finite resource for which we need to define a maximum number upfront. The default value is enough for most apps and usually you can ignore it completely. However, if you get the OBX_ERROR_MAX_READERS_EXCEEDED error, you should verify your threading. For each thread, ObjectBox uses multiple readers. Their number (per thread) depends on number of types, relations, and usage patterns. Thus, if you are working with many threads (e.g. in a server-like scenario), it can make sense to increase the maximum number of readers.

Note

The internal default is currently 126. So when hitting this limit, try values around 200-500.

Attention

Each thread that performed a read transaction and is still alive holds on to a reader slot. These slots only get vacated when the thread ends. Thus be mindful with the number of active threads. Alternatively, you can opt to try the experimental noReaderThreadLocals option flag.

obx_opt_model()

OBX_C_API obx_err obx_opt_model	(	OBX_store_options *	opt,
		OBX_model *	model
	)

Set the model on the options. The default is no model. NOTE: the model is always freed by this function, including when an error occurs.

obx_opt_model_bytes()

OBX_C_API obx_err obx_opt_model_bytes	(	OBX_store_options *	opt,
		const void *	bytes,
		size_t	size
	)

Set the model on the options copying the given bytes. The default is no model.

obx_opt_model_bytes_direct()

OBX_C_API obx_err obx_opt_model_bytes_direct	(	OBX_store_options *	opt,
		const void *	bytes,
		size_t	size
	)

Like obx_opt_model_bytes BUT WITHOUT copying the given bytes. Thus, you must keep the bytes available until after the store is created.

obx_opt_no_reader_thread_locals()

OBX_C_API void obx_opt_no_reader_thread_locals	(	OBX_store_options *	opt,
		bool	flag
	)

Disables the usage of thread locals for "readers" related to read transactions. This can make sense if you are using a lot of threads that are kept alive.

Note

This is still experimental, as it comes with subtle behavior changes at a low level and may affect corner cases with e.g. transactions, which may not be fully tested at the moment.

obx_opt_put_padding_mode()

OBX_C_API void obx_opt_put_padding_mode	(	OBX_store_options *	opt,
		OBXPutPaddingMode	mode
	)

Don't touch unless you know exactly what you are doing: Advanced setting typically meant for language bindings (not end users). See OBXPutPaddingMode description.

obx_opt_read_only()

OBX_C_API void obx_opt_read_only	(	OBX_store_options *	opt,
		bool	value
	)

Open store in read-only mode: no schema update, no write transactions. Defaults to false.

obx_opt_read_schema()

OBX_C_API void obx_opt_read_schema	(	OBX_store_options *	opt,
		bool	value
	)

Advanced setting meant only for special scenarios: setting to false causes opening the database in a limited, schema-less mode. If you don't know what this means exactly: ignore this flag. Defaults to true.

obx_opt_use_previous_commit()

OBX_C_API void obx_opt_use_previous_commit	(	OBX_store_options *	opt,
		bool	value
	)

Advanced setting recommended to be used together with read-only mode to ensure no data is lost. Ignores the latest data snapshot (committed transaction state) and uses the previous snapshot instead. When used with care (e.g. backup the DB files first), this option may also recover data removed by the latest transaction. Defaults to false.

obx_opt_validate_on_open_kv()

OBX_C_API void obx_opt_validate_on_open_kv	(	OBX_store_options *	opt,
		uint32_t	flags
	)

When the DB is opened initially, ObjectBox can do a validation over the key/value pairs to check, for example, whether they're consistent towards our internal specification.

Parameters

flags

flags used to influence how the validation checks are performed; see OBXValidateOnOpenKvFlags for values (use bitwise OR to combine multiple flags)

obx_opt_validate_on_open_pages()

OBX_C_API void obx_opt_validate_on_open_pages	(	OBX_store_options *	opt,
		size_t	page_limit,
		uint32_t	flags
	)

When the DB is opened initially, ObjectBox can do a consistency check on the given amount of pages. Reliable file systems already guarantee consistency, so this is primarily meant to deal with unreliable OSes, file systems, or hardware. Thus, usually a low number (e.g. 1-20) is sufficient and does not impact startup performance significantly. To completely disable this you can pass 0, but we recommend a setting of at least 1. Note: ObjectBox builds upon ACID storage, which guarantees consistency given that the file system is working correctly (in particular fsync).

Parameters

page_limit	limits the number of checked pages (currently defaults to 0, but will be increased in the future)
flags	flags used to influence how the validation checks are performed; see OBXValidateOnOpenPagesFlags for values (use bitwise OR to combine multiple flags)

obx_opt_wal()

OBX_C_API void obx_opt_wal	(	OBX_store_options *	opt,
		uint32_t	flags
	)

Enables Write-ahead logging (WAL) if OBXWalFlags_EnableWal is given. For now this is only supported for in-memory DBs.

Parameters

flags

OBXWalFlags_EnableWal with optional other flags (bitwise OR).

obx_opt_wal_max_file_size_in_kb()

OBX_C_API void obx_opt_wal_max_file_size_in_kb	(	OBX_store_options *	opt,
		uint64_t	size_in_kb
	)

The WAL file gets consolidated when it reaches this size limit after a commit. As consolidation takes some time, it is a trade-off between accumulating enough data and the time the consolidation takes (longer with more data). The default is 16384 (16 MB).

obx_opt_wal_max_file_size_on_open_in_kb()

OBX_C_API void obx_opt_wal_max_file_size_on_open_in_kb	(	OBX_store_options *	opt,
		uint64_t	size_in_kb
	)

The WAL file gets consolidated when it reached this size limit when opening the database. This setting is meant for applications that prefer to consolidate on startup, which may avoid consolidations on commits while the application is running. The default is 4096 (4 MB).

obx_posix_sem_prefix_set()

OBX_C_API obx_err obx_posix_sem_prefix_set

(

const char *

prefix

)

Only for Apple platforms: set the prefix to use for mutexes based on POSIX semaphores. You must supply the application group identifier for sand-boxed macOS apps here; see also: https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW24.

Parameters

prefix

must be at most 20 characters long and end with a forward slash '/'.

obx_qb_all()

OBX_C_API obx_qb_cond obx_qb_all	(	OBX_query_builder *	builder,
		const obx_qb_cond	conditions[],
		size_t	count
	)

Combine conditions[] to a new condition using operator AND (all).

obx_qb_any()

OBX_C_API obx_qb_cond obx_qb_any	(	OBX_query_builder *	builder,
		const obx_qb_cond	conditions[],
		size_t	count
	)

Combine conditions[] to a new condition using operator OR (any).

obx_qb_any_equals_string()

OBX_C_API obx_qb_cond obx_qb_any_equals_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

For OBXPropertyType_StringVector - matches if at least one vector item equals the given value.

obx_qb_backlink_property()

OBX_C_API OBX_query_builder* obx_qb_backlink_property	(	OBX_query_builder *	builder,
		obx_schema_id	source_entity_id,
		obx_schema_id	source_property_id
	)

Create a backlink based on a property-relation used in reverse (one-to-many)

obx_qb_backlink_standalone()

OBX_C_API OBX_query_builder* obx_qb_backlink_standalone	(	OBX_query_builder *	builder,
		obx_schema_id	relation_id
	)

Create a backlink based on a standalone relation (many-to-many, reverse direction)

obx_qb_between_2doubles()

OBX_C_API obx_qb_cond obx_qb_between_2doubles	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		double	value_a,
		double	value_b
	)

obx_qb_between_2ints()

OBX_C_API obx_qb_cond obx_qb_between_2ints	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		int64_t	value_a,
		int64_t	value_b
	)

obx_qb_close()

OBX_C_API obx_err obx_qb_close

(

OBX_query_builder *

builder

)

Close the query builder; note that OBX_query objects outlive their builder and thus are not affected by this call.

Parameters

builder

may be NULL

obx_qb_contains_element_string()

OBX_C_API obx_qb_cond obx_qb_contains_element_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

For container types (e.g. string vector or flex), this looks for a element that equals the given string.

obx_qb_contains_key_value_string()

OBX_C_API obx_qb_cond obx_qb_contains_key_value_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	key,
		const char *	value,
		bool	case_sensitive
	)

For flex properties that have a map as root value, this looks for matching key/value pair.

obx_qb_contains_string()

OBX_C_API obx_qb_cond obx_qb_contains_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

obx_qb_ends_with_string()

OBX_C_API obx_qb_cond obx_qb_ends_with_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

obx_qb_equals_bytes()

OBX_C_API obx_qb_cond obx_qb_equals_bytes	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const void *	value,
		size_t	size
	)

obx_qb_equals_int()

OBX_C_API obx_qb_cond obx_qb_equals_int	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		int64_t	value
	)

obx_qb_equals_string()

OBX_C_API obx_qb_cond obx_qb_equals_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

For string and flex properties, this looks for a value equal to the given one.

obx_qb_error_code()

OBX_C_API obx_err obx_qb_error_code

(

OBX_query_builder *

builder

)

To minimise the amount of error handling code required when building a query, the first error is stored in the query and can be obtained here. All the obx_qb_XXX functions are null operations after the first query error has occurred.

obx_qb_error_message()

OBX_C_API const char* obx_qb_error_message

(

OBX_query_builder *

builder

)

To minimise the amount of error handling code required when building a query, the first error is stored in the query and can be obtained here. All the obx_qb_XXX functions are null operations after the first query error has occurred.

obx_qb_greater_or_equal_bytes()

OBX_C_API obx_qb_cond obx_qb_greater_or_equal_bytes	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const void *	value,
		size_t	size
	)

obx_qb_greater_or_equal_double()

OBX_C_API obx_qb_cond obx_qb_greater_or_equal_double	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		double	value
	)

obx_qb_greater_or_equal_int()

OBX_C_API obx_qb_cond obx_qb_greater_or_equal_int	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		int64_t	value
	)

obx_qb_greater_or_equal_string()

OBX_C_API obx_qb_cond obx_qb_greater_or_equal_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

obx_qb_greater_than_bytes()

OBX_C_API obx_qb_cond obx_qb_greater_than_bytes	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const void *	value,
		size_t	size
	)

obx_qb_greater_than_double()

OBX_C_API obx_qb_cond obx_qb_greater_than_double	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		double	value
	)

obx_qb_greater_than_int()

OBX_C_API obx_qb_cond obx_qb_greater_than_int	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		int64_t	value
	)

obx_qb_greater_than_string()

OBX_C_API obx_qb_cond obx_qb_greater_than_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

obx_qb_in_int32s()

OBX_C_API obx_qb_cond obx_qb_in_int32s	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const int32_t	values[],
		size_t	count
	)

Note that all values are copied and thus do not need to be maintained by the calling code.

obx_qb_in_int64s()

OBX_C_API obx_qb_cond obx_qb_in_int64s	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const int64_t	values[],
		size_t	count
	)

Note that all values are copied and thus do not need to be maintained by the calling code.

obx_qb_in_strings()

OBX_C_API obx_qb_cond obx_qb_in_strings	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *const	values[],
		size_t	count,
		bool	case_sensitive
	)

Note that all string values are copied and thus do not need to be maintained by the calling code.

obx_qb_less_or_equal_bytes()

OBX_C_API obx_qb_cond obx_qb_less_or_equal_bytes	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const void *	value,
		size_t	size
	)

obx_qb_less_or_equal_double()

OBX_C_API obx_qb_cond obx_qb_less_or_equal_double	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		double	value
	)

obx_qb_less_or_equal_int()

OBX_C_API obx_qb_cond obx_qb_less_or_equal_int	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		int64_t	value
	)

obx_qb_less_or_equal_string()

OBX_C_API obx_qb_cond obx_qb_less_or_equal_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

obx_qb_less_than_bytes()

OBX_C_API obx_qb_cond obx_qb_less_than_bytes	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const void *	value,
		size_t	size
	)

obx_qb_less_than_double()

OBX_C_API obx_qb_cond obx_qb_less_than_double	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		double	value
	)

obx_qb_less_than_int()

OBX_C_API obx_qb_cond obx_qb_less_than_int	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		int64_t	value
	)

obx_qb_less_than_string()

OBX_C_API obx_qb_cond obx_qb_less_than_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

obx_qb_link_property()

OBX_C_API OBX_query_builder* obx_qb_link_property	(	OBX_query_builder *	builder,
		obx_schema_id	property_id
	)

Create a link based on a property-relation (many-to-one)

obx_qb_link_standalone()

OBX_C_API OBX_query_builder* obx_qb_link_standalone	(	OBX_query_builder *	builder,
		obx_schema_id	relation_id
	)

Create a link based on a standalone relation (many-to-many)

obx_qb_link_time()

OBX_C_API OBX_query_builder* obx_qb_link_time	(	OBX_query_builder *	builder,
		obx_schema_id	linked_entity_id,
		obx_schema_id	begin_property_id,
		obx_schema_id	end_property_id
	)

Link the (time series) entity type to another entity space using a time point or range defined in the given linked entity type and properties. Note: time series functionality must be available to use this.

Parameters

linked_entity_id	Entity type that defines a time point or range
begin_property_id	Property of the linked entity defining a time point or the begin of a time range. Must be a date type (e.g. PropertyType_Date or PropertyType_DateNano).
end_property_id	Optional property of the linked entity defining the end of a time range. Pass zero to only define a time point (begin_property_id). Must be a date type (e.g. PropertyType_Date or PropertyType_DateNano).

obx_qb_nearest_neighbors_f32()

OBX_C_API obx_qb_cond obx_qb_nearest_neighbors_f32	(	OBX_query_builder *	builder,
		obx_schema_id	vector_property_id,
		const float *	query_vector,
		size_t	max_result_count
	)

Performs an approximate nearest neighbor (ANN) search to find objects near to the given query_vector. This requires the vector property to have a HNSW index.

Parameters

vector_property_id	the vector property ID of the entity
query_vector	the query vector; its dimensions should be at least the dimensions of the vector property.
max_result_count	maximum number of objects to return by the ANN condition. Hint: it can also be used as the "ef" HNSW parameter to increase the search quality in combination with a query limit. For example, use 100 here with a query limit of 10 to have 10 results that are of potentially better quality than just passing in 10 here (quality/performance tradeoff).

obx_qb_not_equals_int()

OBX_C_API obx_qb_cond obx_qb_not_equals_int	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		int64_t	value
	)

obx_qb_not_equals_string()

OBX_C_API obx_qb_cond obx_qb_not_equals_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

obx_qb_not_in_int32s()

OBX_C_API obx_qb_cond obx_qb_not_in_int32s	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const int32_t	values[],
		size_t	count
	)

Note that all values are copied and thus do not need to be maintained by the calling code.

obx_qb_not_in_int64s()

OBX_C_API obx_qb_cond obx_qb_not_in_int64s	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const int64_t	values[],
		size_t	count
	)

Note that all values are copied and thus do not need to be maintained by the calling code.

obx_qb_not_null()

OBX_C_API obx_qb_cond obx_qb_not_null	(	OBX_query_builder *	builder,
		obx_schema_id	property_id
	)

Add not-null check to the query.

obx_qb_null()

OBX_C_API obx_qb_cond obx_qb_null	(	OBX_query_builder *	builder,
		obx_schema_id	property_id
	)

Add null check to the query.

obx_qb_order()

OBX_C_API obx_err obx_qb_order	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		uint32_t	flags
	)

Configures an order of results in the query.

obx_qb_param_alias()

OBX_C_API obx_err obx_qb_param_alias	(	OBX_query_builder *	builder,
		const char *	alias
	)

Create an alias for the previous condition (the one added just before calling this function). This is useful when you have a query with multiple conditions of the same property (e.g. height < 20 or height > 50) and you want to use obx_query_param_* to change the values. Consider the following simplified example.

Example: Create a query with two aliased params and set their values later during query execution:

     OBX_query_builder* qb = obx_query_builder(store, entity_id);
     obx_qb_less_than_int(qb, height_prop_id, 0)
     obx_qb_param_alias(qb, "height-lt")
     obx_qb_greater_than_int(qb, height_prop_id, 0)
     obx_qb_param_alias(qb, "height-gt")
     OBX_query* query = obx_query(OBX_query_builder* qb);
     ...
     obx_query_param_alias_int(query, "height-lt", 20)
     obx_query_param_alias_int(query, "height-gt", 50)
     OBX_bytes_array* results = obx_query_find(query)
     obx_query_param_alias_int(query, "height-lt", 100)
     obx_query_param_alias_int(query, "height-gt", 500)
     OBX_bytes_array* results2 = obx_query_find(query)

Parameters

alias

any non-empty string

obx_qb_relation_count_property()

OBX_C_API obx_qb_cond obx_qb_relation_count_property	(	OBX_query_builder *	builder,
		obx_schema_id	relation_entity_id,
		obx_schema_id	relation_property_id,
		uint32_t	relation_count
	)

An object matches, if it has a given number of related objects pointing to it. At this point, there are a couple of limitations (later version may improve on that): 1) 1:N relations only, 2) the complexity is O(n * (relationCount + 1)) and cannot be improved via indexes, 3) The relation count cannot be set as an parameter.

Parameters

relation_entity_id	ID of the entity type the relation comes from.
relation_property_id	ID of the property in the related entity type representing the relation.
relation_count	Number of related object an object must have to match. May be 0 if objects shall be matched that do not have related objects. (Typically low numbers are used for the count.)

obx_qb_starts_with_string()

OBX_C_API obx_qb_cond obx_qb_starts_with_string	(	OBX_query_builder *	builder,
		obx_schema_id	property_id,
		const char *	value,
		bool	case_sensitive
	)

obx_qb_type_id()

OBX_C_API obx_schema_id obx_qb_type_id

(

OBX_query_builder *

builder

)

Returns

the entity type ID that was used to construct the query builder.

obx_query()

OBX_C_API OBX_query* obx_query

(

OBX_query_builder *

builder

)

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_query_builder()

OBX_C_API OBX_query_builder* obx_query_builder	(	OBX_store *	store,
		obx_schema_id	entity_id
	)

Create a query builder which is used to collect conditions using the obx_qb_* functions. Once all conditions are applied, use obx_query() to build a OBX_query that is used to actually retrieve data. Use obx_qb_close() to close (free) the query builder.

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_query_clone()

OBX_C_API OBX_query* obx_query_clone

(

OBX_query *

query

)

Create a clone of the given query such that it can be run on a separate thread.

obx_query_close()

OBX_C_API obx_err obx_query_close

(

OBX_query *

query

)

Close the query and free resources.

obx_query_count()

OBX_C_API obx_err obx_query_count	(	OBX_query *	query,
		uint64_t *	out_count
	)

Return the number of matching objects.

obx_query_cursor_count()

OBX_C_API obx_err obx_query_cursor_count	(	OBX_query *	query,
		OBX_cursor *	cursor,
		uint64_t *	out_count
	)

obx_query_cursor_find()

OBX_C_API OBX_bytes_array* obx_query_cursor_find	(	OBX_query *	query,
		OBX_cursor *	cursor
	)

Find entities matching the query; NOTE: the returned data is only valid as long the transaction is active!

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_query_cursor_find_ids()

OBX_C_API OBX_id_array* obx_query_cursor_find_ids	(	OBX_query *	query,
		OBX_cursor *	cursor
	)

obx_query_cursor_remove()

OBX_C_API obx_err obx_query_cursor_remove	(	OBX_query *	query,
		OBX_cursor *	cursor,
		uint64_t *	out_count
	)

Remove (delete!) all matching objects.

obx_query_cursor_visit()

OBX_C_API obx_err obx_query_cursor_visit	(	OBX_query *	query,
		OBX_cursor *	cursor,
		obx_data_visitor *	visitor,
		void *	user_data
	)

obx_query_describe()

OBX_C_API const char* obx_query_describe

(

OBX_query *

query

)

The returned char* is valid until another call to describe() is made on the query or until the query is freed.

obx_query_describe_params()

OBX_C_API const char* obx_query_describe_params

(

OBX_query *

query

)

The returned char* is valid until another call to describe_params() is made on the query or until the query is freed.

obx_query_find()

OBX_C_API OBX_bytes_array* obx_query_find

(

OBX_query *

query

)

Find objects matching the query. NOTE: You must use an explicit transaction and the returned data is only valid as long the transaction is active! Note: if no order conditions is present, the order is arbitrary (sometimes ordered by ID, but never guaranteed to).

obx_query_find_first()

OBX_C_API obx_err obx_query_find_first	(	OBX_query *	query,
		const void **	data,
		size_t *	size
	)

Find the first object matching the query.

Returns

OBX_NOT_FOUND if no object matches. The exposed data comes directly from the OS to allow zero-copy access, which limits the data lifetime:

Warning

Currently ignores offset, taking the the first matching element.

Attention

The exposed data is only valid as long as the (top) transaction is still active and no write operation (e.g. put/remove) was executed. Accessing data after this is undefined behavior.

obx_query_find_ids()

OBX_C_API OBX_id_array* obx_query_find_ids

(

OBX_query *

query

)

Return the IDs of all matching objects. Note: if no order conditions is present, the order is arbitrary (sometimes ordered by ID, but never guaranteed to).

obx_query_find_ids_by_score()

OBX_C_API OBX_id_array* obx_query_find_ids_by_score

(

OBX_query *

query

)

Find object IDs matching the query ordered by their query score (e.g. distance in NN search). The resulting array is sorted by score in ascending order (unlike obx_query_find_ids()). Unlike obx_query_find_ids_with_scores(), this method returns a simple array of IDs without scores.

obx_query_find_ids_with_scores()

OBX_C_API OBX_id_score_array* obx_query_find_ids_with_scores

(

OBX_query *

query

)

Find object IDs matching the query associated to their query score (e.g. distance in NN search). The resulting array is sorted by score in ascending order (unlike obx_query_find_ids()).

obx_query_find_unique()

OBX_C_API obx_err obx_query_find_unique	(	OBX_query *	query,
		const void **	data,
		size_t *	size
	)

Find the only object matching the query.

Returns

OBX_NOT_FOUND if no object matches, an error if there are multiple objects matching the query. The exposed data comes directly from the OS to allow zero-copy access, which limits the data lifetime:

Warning

Currently ignores offset and limit, considering all matching elements.

Attention

The exposed data is only valid as long as the (top) transaction is still active and no write operation (e.g. put/remove) was executed. Accessing data after this is undefined behavior.

obx_query_find_with_scores()

OBX_C_API OBX_bytes_score_array* obx_query_find_with_scores

(

OBX_query *

query

)

Find objects matching the query associated to their query score (e.g. distance in NN search). The resulting array is sorted by score in ascending order (unlike obx_query_find()).

obx_query_limit()

OBX_C_API obx_err obx_query_limit	(	OBX_query *	query,
		size_t	limit
	)

Configure a limit for this query - all methods that support limit will return/process only the given number of objects. Example use case: use together with offset to get a slice of the whole result, e.g. for "result paging". Call with limit=0 to reset to the default behavior - zero limit means no limit applied.

obx_query_offset()

OBX_C_API obx_err obx_query_offset	(	OBX_query *	query,
		size_t	offset
	)

Configure an offset for this query - all methods that support offset will return/process objects starting at this offset. Example use case: use together with limit to get a slice of the whole result, e.g. for "result paging". Call with offset=0 to reset to the default behavior, i.e. starting from the first element.

obx_query_offset_limit()

OBX_C_API obx_err obx_query_offset_limit	(	OBX_query *	query,
		size_t	offset,
		size_t	limit
	)

Configure an offset and a limit for this query - all methods that support an offset/limit will return/process objects starting at this offset and up to the given limit. Example use case: get a slice of the whole result, e.g. for "result paging". Call with offset/limit=0 to reset to the default behavior, i.e. starting from the first element without limit.

obx_query_param_2doubles()

OBX_C_API obx_err obx_query_param_2doubles	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		double	value_a,
		double	value_b
	)

obx_query_param_2ints()

OBX_C_API obx_err obx_query_param_2ints	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		int64_t	value_a,
		int64_t	value_b
	)

obx_query_param_2strings()

OBX_C_API obx_err obx_query_param_2strings	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		const char *	value,
		const char *	value2
	)

obx_query_param_alias_2doubles()

OBX_C_API obx_err obx_query_param_alias_2doubles	(	OBX_query *	query,
		const char *	alias,
		double	value_a,
		double	value_b
	)

obx_query_param_alias_2ints()

OBX_C_API obx_err obx_query_param_alias_2ints	(	OBX_query *	query,
		const char *	alias,
		int64_t	value_a,
		int64_t	value_b
	)

obx_query_param_alias_bytes()

OBX_C_API obx_err obx_query_param_alias_bytes	(	OBX_query *	query,
		const char *	alias,
		const void *	value,
		size_t	size
	)

obx_query_param_alias_double()

OBX_C_API obx_err obx_query_param_alias_double	(	OBX_query *	query,
		const char *	alias,
		double	value
	)

obx_query_param_alias_get_type_size()

OBX_C_API size_t obx_query_param_alias_get_type_size	(	OBX_query *	query,
		const char *	alias
	)

Gets the size of the property type used in a query condition. A typical use case of this is to allow language bindings (e.g. Swift) use the right type (e.g. 32 bit ints) even if the language has a bias towards another type (e.g. 64 bit ints).

Returns

the size of the underlying property

0 if it does not have a fixed size (e.g. strings, vectors) or an error occurred

obx_query_param_alias_int()

OBX_C_API obx_err obx_query_param_alias_int	(	OBX_query *	query,
		const char *	alias,
		int64_t	value
	)

obx_query_param_alias_int32s()

OBX_C_API obx_err obx_query_param_alias_int32s	(	OBX_query *	query,
		const char *	alias,
		const int32_t	values[],
		size_t	count
	)

obx_query_param_alias_int64s()

OBX_C_API obx_err obx_query_param_alias_int64s	(	OBX_query *	query,
		const char *	alias,
		const int64_t	values[],
		size_t	count
	)

obx_query_param_alias_string()

OBX_C_API obx_err obx_query_param_alias_string	(	OBX_query *	query,
		const char *	alias,
		const char *	value
	)

obx_query_param_alias_strings()

OBX_C_API obx_err obx_query_param_alias_strings	(	OBX_query *	query,
		const char *	alias,
		const char *const	values[],
		size_t	count
	)

obx_query_param_alias_vector_float32()

OBX_C_API obx_err obx_query_param_alias_vector_float32	(	OBX_query *	query,
		const char *	alias,
		const float *	value,
		size_t	element_count
	)

obx_query_param_bytes()

OBX_C_API obx_err obx_query_param_bytes	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		const void *	value,
		size_t	size
	)

obx_query_param_double()

OBX_C_API obx_err obx_query_param_double	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		double	value
	)

obx_query_param_get_type_size()

OBX_C_API size_t obx_query_param_get_type_size	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id
	)

Gets the size of the property type used in a query condition. A typical use case of this is to allow language bindings (e.g. Swift) use the right type (e.g. 32 bit ints) even if the language has a bias towards another type (e.g. 64 bit ints).

Returns

the size of the underlying property

0 if it does not have a fixed size (e.g. strings, vectors) or an error occurred

obx_query_param_int()

OBX_C_API obx_err obx_query_param_int	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		int64_t	value
	)

obx_query_param_int32s()

OBX_C_API obx_err obx_query_param_int32s	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		const int32_t	values[],
		size_t	count
	)

obx_query_param_int64s()

OBX_C_API obx_err obx_query_param_int64s	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		const int64_t	values[],
		size_t	count
	)

obx_query_param_string()

OBX_C_API obx_err obx_query_param_string	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		const char *	value
	)

obx_query_param_strings()

OBX_C_API obx_err obx_query_param_strings	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		const char *const	values[],
		size_t	count
	)

obx_query_param_vector_float32()

OBX_C_API obx_err obx_query_param_vector_float32	(	OBX_query *	query,
		obx_schema_id	entity_id,
		obx_schema_id	property_id,
		const float *	value,
		size_t	element_count
	)

obx_query_prop()

OBX_C_API OBX_query_prop* obx_query_prop	(	OBX_query *	query,
		obx_schema_id	property_id
	)

Create a "property query" with results referring to single property (not complete objects). Also provides aggregates like for example obx_query_prop_avg().

obx_query_prop_avg()

OBX_C_API obx_err obx_query_prop_avg	(	OBX_query_prop *	query,
		double *	out_average,
		int64_t *	out_count
	)

Calculate an average value for the given numeric property across all objects matching the query.

Parameters

query	the query to run
out_average	the result of the query
out_count	(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. a floating point NaN value will trigger the short cut as the average will be a NaN no matter what values will follow.

obx_query_prop_avg_int()

OBX_C_API obx_err obx_query_prop_avg_int	(	OBX_query_prop *	query,
		int64_t *	out_average,
		int64_t *	out_count
	)

Calculate an average value for the given numeric property across all objects matching the query.

Parameters

query	the query to run
out_average	the result of the query
out_count	(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete.

Returns

OBX_ERROR_NUMERIC_OVERFLOW if the result does not fit into an int64_t

obx_query_prop_close()

OBX_C_API obx_err obx_query_prop_close

(

OBX_query_prop *

query

)

Close the property query and release resources.

obx_query_prop_count()

OBX_C_API obx_err obx_query_prop_count	(	OBX_query_prop *	query,
		uint64_t *	out_count
	)

Count the number of non-NULL values of the given property across all objects matching the query.

obx_query_prop_distinct()

OBX_C_API obx_err obx_query_prop_distinct	(	OBX_query_prop *	query,
		bool	distinct
	)

Configure the property query to work only on distinct values.

Note

not all methods support distinct, those that don't will return an error

obx_query_prop_distinct_case()

OBX_C_API obx_err obx_query_prop_distinct_case	(	OBX_query_prop *	query,
		bool	distinct,
		bool	case_sensitive
	)

Configure the property query to work only on distinct values. This version is reserved for string properties and defines the case sensitivity for distinctness.

Note

not all methods support distinct, those that don't will return an error

obx_query_prop_find_doubles()

OBX_C_API OBX_double_array* obx_query_prop_find_doubles	(	OBX_query_prop *	query,
		const double *	value_if_null
	)

Return an array of doubles stored as the given property across all objects matching the query.

Parameters

value_if_null

value that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_query_prop_find_floats()

OBX_C_API OBX_float_array* obx_query_prop_find_floats	(	OBX_query_prop *	query,
		const float *	value_if_null
	)

Return an array of int stored as the given property across all objects matching the query.

Parameters

value_if_null

value that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_query_prop_find_int16s()

OBX_C_API OBX_int16_array* obx_query_prop_find_int16s	(	OBX_query_prop *	query,
		const int16_t *	value_if_null
	)

Return an array of ints stored as the given property across all objects matching the query.

Parameters

value_if_null

value that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_query_prop_find_int32s()

OBX_C_API OBX_int32_array* obx_query_prop_find_int32s	(	OBX_query_prop *	query,
		const int32_t *	value_if_null
	)

Return an array of ints stored as the given property across all objects matching the query.

Parameters

value_if_null

value that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_query_prop_find_int64s()

OBX_C_API OBX_int64_array* obx_query_prop_find_int64s	(	OBX_query_prop *	query,
		const int64_t *	value_if_null
	)

Return an array of ints stored as the given property across all objects matching the query.

Parameters

value_if_null

value that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_query_prop_find_int8s()

OBX_C_API OBX_int8_array* obx_query_prop_find_int8s	(	OBX_query_prop *	query,
		const int8_t *	value_if_null
	)

Return an array of ints stored as the given property across all objects matching the query.

Parameters

value_if_null

value that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified are skipped

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_query_prop_find_strings()

OBX_C_API OBX_string_array* obx_query_prop_find_strings	(	OBX_query_prop *	query,
		const char *	value_if_null
	)

Return an array of strings stored as the given property across all objects matching the query.

Parameters

value_if_null

value that should be used in place of NULL values on object fields; if value_if_null=NULL is given, objects with NULL values of the specified field are skipped

obx_query_prop_max()

OBX_C_API obx_err obx_query_prop_max	(	OBX_query_prop *	query,
		double *	out_maximum,
		int64_t *	out_count
	)

Find the maximum value of the given floating-point property across all objects matching the query.

Parameters

query	the query to run
out_maximum	the result of the query
out_count	(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. if an index is used, it will be set to 0 or -1, instead of the actual count of objects.

obx_query_prop_max_int()

OBX_C_API obx_err obx_query_prop_max_int	(	OBX_query_prop *	query,
		int64_t *	out_maximum,
		int64_t *	out_count
	)

Find the maximum value of the given property across all objects matching the query.

Parameters

query	the query to run
out_maximum	the result of the query
out_count	(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. if an index is used, it will be set to 0 or -1, instead of the actual count of objects.

obx_query_prop_min()

OBX_C_API obx_err obx_query_prop_min	(	OBX_query_prop *	query,
		double *	out_minimum,
		int64_t *	out_count
	)

Find the minimum value of the given floating-point property across all objects matching the query.

Parameters

query	the query to run
out_minimum	the result of the query
out_count	(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. if an index is used, it will be set to 0 or -1, instead of the actual count of objects.

obx_query_prop_min_int()

OBX_C_API obx_err obx_query_prop_min_int	(	OBX_query_prop *	query,
		int64_t *	out_minimum,
		int64_t *	out_count
	)

Find the minimum value of the given property across all objects matching the query.

Parameters

query	the query to run
out_minimum	the result of the query
out_count	(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. if an index is used, it will be set to 0 or -1, instead of the actual count of objects.

obx_query_prop_sum()

OBX_C_API obx_err obx_query_prop_sum	(	OBX_query_prop *	query,
		double *	out_sum,
		int64_t *	out_count
	)

Calculate the sum of the given floating-point property across all objects matching the query.

Parameters

query	the query to run
out_sum	the result of the query
out_count	(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete. E.g. a floating point NaN value will trigger the short cut as the average will be a NaN no matter what values will follow.

obx_query_prop_sum_int()

OBX_C_API obx_err obx_query_prop_sum_int	(	OBX_query_prop *	query,
		int64_t *	out_sum,
		int64_t *	out_count
	)

Calculate the sum of the given property across all objects matching the query.

Parameters

query	the query to run
out_sum	the result of the query
out_count	(optional, may be NULL) number of objects contributing to the result (counted on the fly). A negative count indicates that the computation used a short cut and thus the count is incomplete.

Returns

OBX_ERROR_NUMERIC_OVERFLOW if the result does not fit into an int64_t

obx_query_remove()

OBX_C_API obx_err obx_query_remove	(	OBX_query *	query,
		uint64_t *	out_count
	)

Remove all matching objects from the database & return the number of deleted objects.

obx_query_visit()

OBX_C_API obx_err obx_query_visit	(	OBX_query *	query,
		obx_data_visitor *	visitor,
		void *	user_data
	)

Walk over matching objects one-by-one using the given data visitor (a callback function). Note: if no order conditions is present, the order is arbitrary (sometimes ordered by ID, but never guaranteed to).

obx_query_visit_with_score()

OBX_C_API obx_err obx_query_visit_with_score	(	OBX_query *	query,
		obx_data_score_visitor *	visitor,
		void *	user_data
	)

Walk over matching objects with their query score one-by-one using the given data visitor (a callback function). Note: the elements are ordered by the score (ascending).

obx_remove_db_files()

OBX_C_API obx_err obx_remove_db_files

(

char const *

directory

)

Delete the store files from the given directory.

obx_store_attach()

OBX_C_API OBX_store* obx_store_attach

(

const char *

path

)

Attach to a previously opened store matching the path of the DB directory, which was used for opening the store. The returned store is a new instance (e.g. different pointer value) and must also be closed via obx_store_close(). The actual underlying store is only closed when the last store OBX_store instance is closed.

Returns

nullptr if no open store was found (i.e. not opened before or already closed)

See also

obx_store_clone() for "attaching" to a available store instance.

obx_store_attach_id()

OBX_C_API OBX_store* obx_store_attach_id

(

uint64_t

store_id

)

Attach to a previously opened store matching the given store ID. The returned store is a new instance (e.g. different pointer value) and must also be closed via obx_store_close(). The actual underlying store is only closed when the last store OBX_store instance is closed.

Parameters

store_id

Returns

nullptr if no open store was found (i.e. not opened before or already closed)

See also

obx_store_clone() for "attaching" to a available store instance.

obx_store_attach_or_open()

OBX_C_API OBX_store* obx_store_attach_or_open	(	OBX_store_options *	opt,
		bool	check_matching_options,
		bool *	out_attached
	)

Combines the functionality of obx_store_attach() and obx_store_open() in a thread-safe way.

Parameters

check_matching_options	if true, some effort will be taken to check if the given options match an existing store. Usually this should be set to true as options should not diverge when opening/attaching. Note that additional checks will be added in the future.
out_attached	(optional) if given a pointer to a flag that telling if the function attached to an existing store (true) or a new store was created (false).

obx_store_await_async_completion()

OBX_C_API bool obx_store_await_async_completion

(

OBX_store *

store

)

Await for all (including future) async submissions to be completed (the async queue becomes empty).

Returns

true if all submissions were completed or async processing was not started

false if shutting down or an error occurred

obx_store_await_async_submitted()

OBX_C_API bool obx_store_await_async_submitted

(

OBX_store *

store

)

Await async operations that have been submitted up to this point to be completed (the async queue may still contain elements).

Returns

true if all submissions were completed (or async processing was not started)

false if shutting down or an error occurred

obx_store_back_up_to_file()

OBX_C_API obx_err obx_store_back_up_to_file	(	OBX_store *	store,
		const char *	backup_file,
		uint32_t	backup_flags
	)

Backs up the store DB to the given backup-file, using the given flags. Note: backup is a server-only feature.

Parameters

backup_flags

0 for defaults or OBXBackupFlags bit flags

obx_store_clone()

OBX_C_API OBX_store* obx_store_clone

(

OBX_store *

store

)

Clone a previously opened store; while a store instance is usable from multiple threads, situations may exist in which cloning a store simplifies the overall lifecycle. E.g. when a store is used for multiple threads and it may only be fully released once the last thread completes. The returned store is a new instance (e.g. different pointer value) and must also be closed via obx_store_close(). The actual underlying store is only closed when the last store OBX_store instance is closed.

Returns

nullptr if the store could not be cloned

See also

obx_store_attach() for "cloning" using the store's path.

obx_store_close()

OBX_C_API obx_err obx_store_close

(

OBX_store *

store

)

Closes a previously opened store and thus freeing all resources associated with the store.

Note

This waits for write transactions to finish before returning from this call.

Parameters

store

may be NULL

obx_store_debug_flags()

OBX_C_API obx_err obx_store_debug_flags	(	OBX_store *	store,
		uint32_t	flags
	)

Configure debug logging.

Parameters

flags

See OBXDebugFlags for values (use bitwise OR to combine multiple flags)

obx_store_entity_id()

OBX_C_API obx_schema_id obx_store_entity_id	(	OBX_store *	store,
		const char *	entity_name
	)

Look for an entity with the given name in the model and return its Entity ID.

obx_store_entity_property_id()

OBX_C_API obx_schema_id obx_store_entity_property_id	(	OBX_store *	store,
		obx_schema_id	entity_id,
		const char *	property_name
	)

Return the property id from the property name or 0 if the name is not found.

obx_store_id()

OBX_C_API uint64_t obx_store_id

(

OBX_store *

store

)

Store IDs can be used to attach to a store later. The IDs are stable and unique during the lifetime of the process. E.g. these IDs can be shared across threads efficiently and can serve a similar purpose as weak pointers do.

obx_store_is_open()

OBX_C_API bool obx_store_is_open

(

const char *

path

)

Check if an open store was found for the given path (i.e. opened before and not yet closed).

obx_store_open()

OBX_C_API OBX_store* obx_store_open

(

OBX_store_options *

opt

)

Opens (creates) a "store", which represents an ObjectBox database instance in a given directory. The store is an entry point to data access APIs such as box (obx_box_*), query (obx_qb_* and obx_query_*), and transaction (obx_txn_*). It's possible to open multiple stores in different directories, e.g. at the same time. See also obx_store_close() to close a previously opened store. Note: the given options are always freed by this function, including when an error occurs.

Parameters

opt	required parameter holding the data model (obx_opt_model()) and optional options (see obx_opt_*())

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_store_opened_with_previous_commit()

OBX_C_API bool obx_store_opened_with_previous_commit

(

OBX_store *

store

)

Returns

true if the store was opened with a previous commit

See also

obx_opt_use_previous_commit()

obx_store_prepare_to_close()

OBX_C_API obx_err obx_store_prepare_to_close

(

OBX_store *

store

)

Prepares the store to close by setting its internal state to "closing". Functions relying on the store will result in OBX_ERROR_SHUTTING_DOWN status once closing is initiated. Unlike obx_store_close(), this method will return immediately and does not free resources just yet. This is typically used in a multi-threaded context to allow an orderly shutdown in stages which go through a "not accepting new requests" state.

obx_store_size()

OBX_C_API uint64_t obx_store_size

(

OBX_store *

store

)

Get the size of the store. For a disk-based store type, this corresponds to the size on disk, and for the in-memory store type, this is roughly the used memory bytes occupied by the data.

Returns

the size in bytes of the database, or 0 if the file does not exist or some error occurred.

obx_store_size_on_disk()

OBX_C_API uint64_t obx_store_size_on_disk

(

OBX_store *

store

)

The size in bytes occupied by the database on disk (if any).

Returns

0 if the underlying database is in-memory only, or the size could not be determined.

obx_store_type_id()

OBX_C_API uint32_t obx_store_type_id

(

OBX_store *

store

)

Gives the store type ID for the given store.

Returns

One of OBXStoreTypeId

obx_store_type_id_register_default()

OBX_C_API int obx_store_type_id_register_default

(

uint32_t

storeTypeId

)

Registers the default DB type, which is used if no other types matched a path prefix.

Parameters

storeTypeId

Must be one of OBXStoreTypeId (for now).

obx_store_wrap()

OBX_C_API OBX_store* obx_store_wrap

(

void *

core_store

)

For stores created outside of this C API, e.g. via C++ or Java, this is how you can use it via C too. Like this, it is OK to use the same store instance (same database) from multiple languages in parallel. Note: the store's life time will still be managed outside of the C API; thus ensure that store is not closed while calling any C function on it. Once you are done with the C specific OBX_store, call obx_store_close() to free any C related resources. This, however, will not close the "core store".

Parameters

core_store

A pointer to the core C++ ObjectStore, or the native JNI handle for a BoxStore.

obx_string_array_free()

OBX_C_API void obx_string_array_free

(

OBX_string_array *

array

)

Free the array struct.

obx_thread_number()

OBX_C_API int obx_thread_number

(

)

Gets the number, as used by ObjectBox, of the current thread. This e.g. allows to "associate" the thread with ObjectBox logs (each log entry contains the thread number).

obx_tree()

OBX_C_API OBX_tree* obx_tree	(	OBX_store *	store,
		OBX_tree_options *	options
	)

Creates a tree for the given store.

Parameters

options

can be null for default options (e.g. use '/' as a path delimiter). The options are always freed when calling this function.

obx_tree_async_consolidate_node_conflicts()

OBX_C_API obx_err obx_tree_async_consolidate_node_conflicts

(

OBX_tree *

tree

)

Explicitly consolidates tree node conflicts (non unique nodes sharing a common path) asynchronously. See also obx_tree_cursor_consolidate_node_conflicts() for a synchronous version.

obx_tree_async_get_raw()

OBX_C_API obx_err obx_tree_async_get_raw	(	OBX_tree *	tree,
		const char *	path,
		bool	with_metadata,
		obx_tree_async_get_callback *	callback,
		void *	callback_user_data
	)

Like obx_tree_cursor_get_raw(), but asynchronous.

Parameters

with_metadata	Flag if the callback also wants to receive the metadata (also as raw FlatBuffers).
callback	Optional (may be null) function that is called with results once the async operation completes.
callback_user_data	Any value you can supply, which is passed on to the callback (e.g. to identify user specific context).

obx_tree_async_put_raw()

OBX_C_API obx_err obx_tree_async_put_raw	(	OBX_tree *	tree,
		const char *	path,
		void *	leaf_data,
		size_t	leaf_data_size,
		OBXPropertyType	type,
		void *	leaf_metadata,
		size_t	leaf_metadata_size,
		OBXPutMode	leaf_put_mode,
		obx_tree_async_put_callback *	callback,
		void *	callback_user_data
	)

Like obx_tree_cursor_put_raw(), but asynchronous.

Parameters

callback	Optional (may be null) function that is called with results once the async operation completes.
callback_user_data	Any value you can supply, which is passed on to the callback (e.g. to identify user specific context).

obx_tree_close()

OBX_C_API void obx_tree_close

(

OBX_tree *

tree

)

obx_tree_cursor()

OBX_C_API OBX_tree_cursor* obx_tree_cursor	(	OBX_tree *	tree,
		OBX_txn *	txn
	)

To get/put data from tree, you need to create a tree cursor using this method.

Parameters

txn	may be null if the transaction will be set later via obx_tree_cursor_txn()

obx_tree_cursor_close()

OBX_C_API void obx_tree_cursor_close

(

OBX_tree_cursor *

cursor

)

Closes the tree cursor, e.g. before a transaction is ending. The cursor cannot be used afterwards (consider obx_tree_cursor_reset() if you want to keep using it).

obx_tree_cursor_consolidate_node_conflicts()

OBX_C_API obx_err obx_tree_cursor_consolidate_node_conflicts	(	OBX_tree_cursor *	cursor,
		size_t *	out_consolidated_count
	)

Explicitly consolidates tree node conflicts (non unique nodes sharing a common path). See also obx_tree_async_consolidate_node_conflicts() for an asynchronous version.

obx_tree_cursor_get_child_leaves_info()

OBX_C_API OBX_tree_leaves_info* obx_tree_cursor_get_child_leaves_info	(	OBX_tree_cursor *	cursor,
		const char *	path
	)

Given an existing path, return all existing leaves with their paths. As this traverses the data tree (i.e. not the meta tree), it will only return nodes that exist (obviously). Thus, the meta tree may contain additional paths, but these are unused by the data tree (currently at least).

Parameters

path	the branch or leaf path to use. Optional: if no path is given (null), the root node is taken.

Returns

leaf info ordered by path depth (i.e. starting from paths with the smallest number of branches); paths at same depth are ordered by id.

obx_tree_cursor_get_leaf_path()

OBX_C_API const char* obx_tree_cursor_get_leaf_path	(	OBX_tree_cursor *	cursor,
		obx_id	leaf_id
	)

Gets the full path (from the root) of the given leaf ID.

Returns

If successful, an allocated path is returned (malloc), which must be free()-ed by the caller.

If not successful, NULL is returned.

obx_tree_cursor_get_raw()

OBX_C_API obx_err obx_tree_cursor_get_raw	(	OBX_tree_cursor *	cursor,
		const char *	path,
		const void **	data,
		size_t *	size,
		const void **	metadata,
		size_t *	metadata_size
	)

A "low-level" get operation to access a tree leaf using the raw FlatBuffer bytes stored in the database. As usual, the data is only valid during the lifetime of the transaction and before the first write to the DB. An advantage of using "raw" operations is that custom properties can be passed in the FlatBuffer.

Parameters

data	receiver of the data pointer (non-null pointer to a pointer), which will be pointing to FlatBuffers bytes for the data leaf after this call.
metadata	optional FlatBuffers receiver (nullable pointer to a pointer) for the meta leaf.

Returns

general success/error codes and some tree-specific ones (OBX_ERROR_TREE_*)

obx_tree_cursor_put_raw()

OBX_C_API obx_err obx_tree_cursor_put_raw	(	OBX_tree_cursor *	cursor,
		const char *	path,
		void *	leaf_data,
		size_t	leaf_data_size,
		OBXPropertyType	type,
		obx_id *	out_id,
		void *	leaf_metadata,
		size_t	leaf_metadata_size,
		OBXPutMode	leaf_put_mode
	)

A "low-level" put operation for a tree leaf using given raw FlatBuffer bytes. Any non-existing branches and meta nodes are put on the fly if an optional meta-leaf FlatBuffers is given. A typical usage pattern is to first try without the meta-leaf, and if it does not work, create the meta-leaf and call again with the meta leaf. This approach takes into account that meta-leaves typically exist, and thus no resources are wasted for meta-leaf creation if it's not required. An advantage of using "raw" operations is that custom properties can be passed in the FlatBuffers.

Parameters

leaf_data	prepared FlatBuffers bytes for the data leaf (non-const as the data buffer will be mutated); note: slots for IDs must be already be prepared (zero values)
type	value type of the given leafObject: it has to be passed to verify against stored metadata
leaf_metadata	optional FlatBuffers for the meta leaf; at minimum, "name" and "type" must be set. Note: slots for IDs must be already be prepared (zero values). Passing null indicates that the branches and meta nodes must already exist; otherwise the operation will fail and OBX_NOT_FOUND will be returned.
leaf_put_mode	For the data leaf only (the actual value tree node)

Returns

OBX_NOT_FOUND if the path did not exist (and no metadata was given)

OBX_NO_SUCCESS if the put was not successful according to the put mode

also other standard result codes like OBX_SUCCESS or OBX_ERR_*

obx_tree_cursor_txn()

OBX_C_API obx_err obx_tree_cursor_txn	(	OBX_tree_cursor *	cursor,
		OBX_txn *	txn
	)

Sets or clears a transaction from the tree cursor.

A typical use case for this function is to cache the tree cursor for reusing it later. Note: before closing a transaction, ensure to clear it here first (set to null).

obx_tree_leaves_info_free()

OBX_C_API void obx_tree_leaves_info_free

(

OBX_tree_leaves_info *

leaves_info

)

Frees a leaves info reference.

obx_tree_leaves_info_id()

OBX_C_API obx_id obx_tree_leaves_info_id	(	OBX_tree_leaves_info *	leaves_info,
		size_t	index
	)

Gets the id of a given leaf (by index).

obx_tree_leaves_info_path()

OBX_C_API const char* obx_tree_leaves_info_path	(	OBX_tree_leaves_info *	leaves_info,
		size_t	index
	)

Gets the path of a given leaf (by index).

obx_tree_leaves_info_size()

OBX_C_API size_t obx_tree_leaves_info_size

(

OBX_tree_leaves_info *

leaves_info

)

Gets the number of leaves from the given leaves info.

obx_tree_leaves_info_type()

OBX_C_API OBXPropertyType obx_tree_leaves_info_type	(	OBX_tree_leaves_info *	leaves_info,
		size_t	index
	)

Gets the property type (as OBXPropertyType) of a given leaf (by index).

Returns

OBXPropertyType_Unknown if no property type was found.

obx_tree_node_conflict_count()

OBX_C_API size_t obx_tree_node_conflict_count

(

OBX_tree *

tree

)

Gets the number of currently tracked node conflicts (non-unique nodes at the same path). This count gets resent when conflicts get consolidated. Only tracked if OBXTreeOptionFlags_DetectNonUniqueNodes (or OBXTreeOptionFlags_AutoConsolidateNonUniqueNodes) is set.

obx_tree_opt_flags()

OBX_C_API obx_err obx_tree_opt_flags	(	OBX_tree_options *	options,
		uint32_t	flags
	)

Sets the given OBXTreeOptionFlags at the tree options. Combine multiple flags using bitwise OR.

obx_tree_opt_path_delimiter()

OBX_C_API obx_err obx_tree_opt_path_delimiter	(	OBX_tree_options *	options,
		char	path_delimiter
	)

Adjusts the path delimiter character, which is by default "/".

obx_tree_options()

OBX_C_API OBX_tree_options* obx_tree_options

(

)

Creates a options object that is passed to tree creation via obx_tree().

obx_tree_options_free()

OBX_C_API void obx_tree_options_free

(

OBX_tree_options *

options

)

Free the tree options if they were not used (and "consumed") by obx_tree(). Note: Only free unused options, obx_tree() frees the options internally.

obx_txn_abort()

OBX_C_API obx_err obx_txn_abort

(

OBX_txn *

txn

)

Note: At the moment, you typically want to use only obx_txn_close() instead. Abort the underlying transaction immediately and thus frees DB resources. Only obx_txn_close() is allowed to be called on the transaction after calling this.

obx_txn_close()

OBX_C_API obx_err obx_txn_close

(

OBX_txn *

txn

)

Close the transaction (read or write) and free all of its resources; the given OBX_txn pointer must not be used afterwards. If the given transaction is a write transaction, it is aborted (not committed) right away (without waiting for the top level transaction). If an error is returned (e.g., a commit failed because DB is full), you can assume that the transaction was closed.

Parameters

txn	may be NULL

obx_txn_data_size()

OBX_C_API obx_err obx_txn_data_size	(	OBX_txn *	txn,
		uint64_t *	out_committed_size,
		int64_t *	out_size_change
	)

obx_txn_read()

OBX_C_API OBX_txn* obx_txn_read

(

OBX_store *

store

)

Create a read transaction (read only). Transaction creation can be nested (recursive), however only the outermost transaction is relevant on the DB level. Once you are done tithe the transaction, you must call obx_txn_close().

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details

obx_txn_success()

OBX_C_API obx_err obx_txn_success

(

OBX_txn *

txn

)

"Finish" this write transaction successfully and close it, performing a commit if this is the top level transaction and all inner transactions (if any) were also successful (obx_txn_success() was called on them). Because this also closes the given transaction along with all resources, the given OBX_txn pointer becomes invalid. Thus, the OBX_txn pointer must not be used afterwards; do not even call obx_txn_close().

Returns

OBX_ERROR_ILLEGAL_STATE if the given transaction is not a write transaction.

obx_txn_write()

OBX_C_API OBX_txn* obx_txn_write

(

OBX_store *

store

)

Create a write transaction (read and write). Transaction creation can be nested (recursive), however only the outermost transaction is relevant on the DB level. Once you are done tithe the transaction, you must call obx_txn_success() or obx_txn_close().

Returns

NULL if the operation failed, see functions like obx_last_error_code() to get error details; e.g. code OBX_ERROR_ILLEGAL_STATE will be set if called when inside a read transaction.

obx_vector_distance_float32()

OBX_C_API float obx_vector_distance_float32	(	OBXVectorDistanceType	type,
		const float *	vector1,
		const float *	vector2,
		size_t	dimension
	)

Utility function to calculate the distance of two given vectors. Note: the memory of the two vectors may not overlap!

Parameters

type	The distance type that is to be used for the calculation.
dimension	The dimension of the vectors (number of elements).

Returns

A distance measure that is dependent on the distance type.

NaN on error; e.g. if the distance type is unknown, or the vector search feature is unavailable.

obx_vector_distance_to_relevance()

OBX_C_API float obx_vector_distance_to_relevance	(	OBXVectorDistanceType	type,
		float	distance
	)

Utility function to convert a vector distance (e.g. scores from query results) to a relevance score. The relevance score is a value between 0.0 and 1.0, with 1.0 indicating the most relevant. Note: the higher a distance (score), the lower the relevance score. Note: while the distance (score) is potentially unbound (e.g. Euclidean and dot product) and dependent on the type, relevance score always has fixed range (0.0 to 1.0).

Parameters

type	The distance type indicates how the given distance score was calculated.
distance	distance score to convert (0.0 is the nearest; upper bound depends on the distance type).

Returns

a relevance score between 0.0 and 1.0 (1.0 is the most relevant).

NaN on error; e.g. if the distance type is unknown, or the vector search feature is unavailable.

obx_version()

OBX_C_API void obx_version	(	int *	major,
		int *	minor,
		int *	patch
	)

Return the (runtime) version of the library as ints. Pointers may be null.

obx_version_core_string()

OBX_C_API const char* obx_version_core_string

(

void

)

Return the version of the ObjectBox core to be printed (currently also contains a version date and features). The format may change in any future release; only use for information purposes.

obx_version_is_at_least()

OBX_C_API bool obx_version_is_at_least	(	int	major,
		int	minor,
		int	patch
	)

Check if the (runtime) version of the library is equal to or higher than the given version ints.

obx_version_string()

OBX_C_API const char* obx_version_string

(

void

)

Return the (runtime) version of the library to be printed. The current format is "major.minor.patch" (e.g. "1.0.0") but may change in any future release. Thus, only use for information purposes.

See also

obx_version() and obx_version_is_at_least() for integer based versions

obx_weak_store()

OBX_C_API OBX_weak_store* obx_weak_store

(

OBX_store *

store

)

Creates a weak reference to the given store.

obx_weak_store_by_id()

OBX_C_API OBX_weak_store* obx_weak_store_by_id

(

uint64_t

store_id

)

Tries to get a weak reference to the store with the given ID.

Returns

null if no store was found for the given ID

obx_weak_store_free()

OBX_C_API void obx_weak_store_free

(

OBX_weak_store *

weak_store

)

Frees a weak store reference.

obx_weak_store_lock()

OBX_C_API OBX_store* obx_weak_store_lock

(

OBX_weak_store *

weak_store

)

Tries to create a regular store instance for the given weak reference.

Returns

null if the store was already closed (all "strong references" are gone)