description: >-

{% hint style="info" %}

Jobs: We're looking for a [C++ Developer](https://objectbox.io/jobs/objectbox-senior-c-plusplus-developer/) with a ❤️ for performant code

{% endhint %}

Are you ready use ObjectBox? These two pages will get you up to speed:

{% content-ref url="installation.md" %}

[installation.md](installation.md)

{% endcontent-ref %}

{% content-ref url="getting-started.md" %}

[getting-started.md](getting-started.md)

{% endcontent-ref %}

Alternatively, you can also dive into [some examples on GitHub](https://github.com/objectbox/objectbox-c/tree/main/examples) right away.

Your opinion matters to us! To make ObjectBox better for our users, we have set up an [Anonymous Feedback Form](https://forms.gle/bdktGBUmL4m48ruj7). Please do fill this in (it only takes 2 minutes). Every response is highly appreciated. To rate this documentation, you can use the "Was this page helpful?" smiley at the end of each page.

Otherwise, feel free to open an issue on [GitHub ](https://github.com/objectbox/objectbox-c/issues)or send us your comments to contact\[at]objectbox.io - Thank you! - and if you like what you see, we also appreciate a shoutout :) 

<div align="left">

<img src="https://img.shields.io/github/v/release/objectbox/objectbox-c?style=for-the-badge" alt="">

</div>

Note: 4.0.3 the first 4.0.x version working with ObjectBox Generator 4.0 and thus is the first full 4.0 release. For individual changes in the runtime library check the GitHub release notes: [4.0.0](https://github.com/objectbox/objectbox-c/releases/tag/v4.0.0), [4.0.1](https://github.com/objectbox/objectbox-c/releases/tag/v4.0.1) and [4.0.2](https://github.com/objectbox/objectbox-c/releases/tag/v4.0.2).

* CMake stubs to easily integrate with [ObjectBox Generator 4.0](https://github.com/objectbox/objectbox-generator/releases/tag/v4.0.0)

* ObjectBox now supports vector search ("vector database") to enable efficient similarity searches.\

This is particularly useful for AI/ML/RAG applications, e.g. image, audio, or text similarity.\

Other use cases include semantic search or recommendation engines.\

See [https://docs.objectbox.io/ann-vector-search](https://docs.objectbox.io/ann-vector-search) for details.

* Adjusting the version number to match the core version (4.0); we will be aligning on major versions from now on.

* Made closing the store more robust; e.g. it waits for ongoing queries and transactions to finish\

(please still ensure to clean up properly on your side, this is an additional safety net)

* Made Box API more robust when racing against store closing

* Add "vectorsearch-cities" example

* In-memory databases (simply provide a "memory:" prefixed "directory")

* New client/server statistics API

* New server API to enable authenticators

* Sync server: support for sync permissions, blocks client updates with no write permission

* Added sync-level login/write permissions for Admin Users DB and Web-UI

* New authenticator "ObjectBox Admin" with support for authorization

* New client API for username/password credentials

* New client-side error listener API; initially reports "receive-only" downgrade due to no write permissions.

* Added OBXFeature\_Backup to query for the feature's availability

* Internal: added a DB store abstraction layer (another announcement about this will follow)

* Tree API: fix for meta IDs vs. IDs

* Various internal improvements

* Sync clients may now supply multiple URLs; for each connection attempt a random one is chosen. This allows for client-side load balancing and failover with an ObjectBox Sync cluster.

* New K/V validation option on opening the store

* Additions cursor API: get current ID, ID-based seeks (seek to first ID, seek to next ID)

* Support scalar vector types with basic queries (APIs only, no generator support)

* Various tree API improvements, e.g. introspection

* Minor API clean up: e.g. using int types for bit flags not enums

* Fixes query link condition in combination with some "or" conditions

* Fixes query "less" condition for case-sensitive strings with value indexes (default is hashed index)

* Updated Linux toolchain; now requires glibc 2.28 or higher (and GLIBCXX\_3.4.25); e.g. the following minium versions are fine: Debian Buster 10 (2019), Ubuntu 20.04, RHEL 8 (2019)

* Various internal improvements

* Sync: various additions and improvements (client and server)

Recommended bugfix release; please update.

* Fixes "Could not put (-30786)", which may occur in some corner cases on some platforms.

* Date properties can now be tagged as expiration time; which can be then be easily evicted

* Tree API: various additions and improvements, e.g. OBXTreeOptionFlags to configure the tree behavior

* New query condition to match objects that have a given number of relations

* New "max data size" store setting

* Enabled stricter compiler settings

* Added stacktraces on errors (Linux only; very lightweight as it uses external addr2line or llvm-symbolizer)

* Added log callback for most important logs

* Consolidated "user data" passing as the last parameter

* Various internal improvements

* Added BoxTypeless, QueryBuilderBase and QueryBase: these can be used without generated code and template types.

* New APIs to get the schema IDs for entity types and properties

* Added two methods to Store to await asynchronous processing

* Added "internal" namespace so that internal members do not spill into the obx namespace

* Move more implementations to OBX\_CPP\_FILE

* Custom protocols for Sync: plugin your own messaging protocol, which ObjectBox Sync will run on

* Improvements to run Sync Server with limited disk space (e.g. on small devices)

* Tree Sync improvements; e.g. consolidate conflicts

* WebSockets (sync protocol) is now a feature, which can be turned off (special build version)

* Performance optimizations

* Added a "weak store" API providing weak reference for stores (typically used by background threads)

* Added Store ID API, e.g. getting a store by its ID

* Various internal improvements including minor optimizations for binary size and performance

* New "OBX\_CPP\_FILE" define to place declarations in a single .cpp/.cc file: improves compilation time and results

* New "Exception" base class for all thrown exceptions

* Various internal improvements, e.g. a "internal" namespace to better distinguish from userland API

* Allow UTF-8 for database directories on Windows (available for other platforms before)

* Various internal improvements

* Promoted `Options` to a top level class, as nested classes cannot be declared forward

* New `#define` to disable FlatBuffers includes to simplify new project setup

* Rename `Exception` to `DbException`

* Minor improvements

* Add store cloning

* Fix attaching to a reopened store

* Fix non-unique indexes triggering unique constraint violations in corner cases (requires at least two unique constraints in an entity and a specific order; introduced in 0.15.0)

* Admin UI now supports multiple sessions to the same host using different ports (session ID via HTTP request)

* Minor performance improvements with hashed indexes

* Performance improvements for compression and decompression

* New "Flex" data type that can contain data of various types like integers, floating points, strings, lists and maps

* New query conditions for Flex lists to find a specific element

* New query conditions for Flex maps to find elements with a specific key or key/value pair

* New unique on-conflict strategy: replace conflicting objects (OBXPropertyFlags\_UNIQUE\_ON\_CONFLICT\_REPLACE)

* New functions to attach to existing stores using only the file path (in the same process)

* New APIs for ObjectBox Admin, the web based UI (formerly known as Object Browser): obx\_admin\_\*

* Minor performance improvements for indexed access

* Major performance improvements for tree/GraphQL queries

* ARM binaries are now built for minimal size reducing the library size significantly

* New "no\_reader\_thread\_locals" store option

* Enable debug logging (requires a special build)

* API: Type for query offsets and limits was changed from uint64\_t to size\_t

* API: rarely used obx\_txn\_mark\_success() was removed; use obx\_txn\_success()

* API: feature checks consolidated to only use obx\_has\_feature()

* Many internal improvements

* Core version 3.0.1-2021-12-09

* New API for embedded server mode: obx\_sync\_server\_\* (implementation available on request)

The changelogs of earlier versions are available as part of the [GitHub releases](https://github.com/objectbox/objectbox-c/releases).

Provides native dynamic/shared library (.so/.dylib/.dll)

* Provides C & C++ headers (objectbox.h & objectbox.hpp)

<div align="left">

<img src="https://img.shields.io/github/v/release/objectbox/objectbox-generator?style=for-the-badge" alt="">

</div>

Check the [ObjectBox Generator](https://github.com/objectbox/objectbox-generator/releases) releases for details.

* [ObjectBox C / C++ Database](README.md)

* [Installation](installation.md)

* [How to get started](getting-started.md)

* [Entity Annotations](entity-annotations.md)

* [Generator](generator.md)

* [Store](store.md)

* [Queries](queries.md)

* [Relations](relations.md)

* [Transactions](transactions.md)

* [Schema Changes](schema-changes.md)

* [Time Series Data](time-series-data.md)

* [Dev Tools and Debugging](dev-tools-and-debugging.md)

* [FAQ](faq.md)

* [GitHub](https://github.com/objectbox/objectbox-c)

* [ObjectBox Generator](https://github.com/objectbox/objectbox-generator)

* [C API docs](https://objectbox.io/docfiles/c/current/)

* [Golang Database](https://golang.objectbox.io/)

* [Swift Database](https://swift.objectbox.io/)

* [Java Database](https://docs.objectbox.io/)

description: >-

[ObjectBox Admin](https://docs.objectbox.io/data-browser) is a web-app that can be used to view inside the ObjectBox database. Since it is available as a Docker container with a developer-friendly front-end script you can use it right from a developer console to get insights into your database.\

Example: Using just "docker" to run ObjectBox Admin on a database on path `./myapp` : &#x20;

Opening the URL `http://localhost:8081` with your browser will open the ObjectBox Admin UI:

<figure><img src="https://2056134408-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LETufmyus5LFkviJjr4%2Fuploads%2F4l4B1wXLIHFxdoxtBEAn%2Fadmin-data.png?alt=media&#x26;token=b2faf98f-75a0-448b-8154-4cefcdcaa05f" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

See [ObjectBox Admin](https://docs.objectbox.io/data-browser) Documentation for further details and to download developer-friendly front-end launcher shell script.

{% endhint %}

ObjectBox includes a logging facility for tracing, amongst others, transaction operations. \

The following C++ code below gives an example how to enable logging for transactions at the info level.

obx::Options options(create_obx_model());

options.addDebugFlags(

OBXDebugFlags_LOG_TRANSACTIONS_READ

| OBXDebugFlags_LOG_TRANSACTIONS_WRITE

);

obx::Store store(options);

{% hint style="info" %}

See [C API Documentation of OBXDebugFlag](https://objectbox.io/docfiles/c/current/group\_\_c.html#gade842fb1271541e05f848925f32efa9d) for a list of available debug flags.&#x20;

{% endhint %}

{% hint style="info" %}

ObjectBox also offers a **DebugLog** which gives insights at a very detail level. This is typically not used by an application end-user but might be helpful when things go wrong or when developing improvements, enhancements and features. \

This feature is not available in the public release but on request.

{% endhint %}

description: >-

The source FlatBuffer schema can contain some ObjectBox-specific annotations, declared as specially formatted comments to `table` and `field` FlatBuffer schema elements.&#x20;

Have a look at the following FlatBuffers schema example showing some ObjectBox annotations:

{% code title="schema.fbs" %}

{% endcode %}

To ensure that the annotations are recognized, follow these guidelines:

* Must be a comment immediately preceding an Entity or a Property (no empty lines between them).

* The comment must start with three slashes so it's picked up by FlatBuffer schema parser as a "documentation".

* Spaces between words inside the comment are skipped so you can use them for better readability if you like. See e.g. `Annotated`, `time`.

* The comment must start with the text `objectbox:` and is followed by one or more annotations, separated by commas.

* Each annotation has a name and some annotations also support specifying a value (some even require a value, e.g. the `name` annotation). See e.g. `Annotated`, `relId`.

* Value, if present, is added to the annotation by adding an equal sign and the actual value.

* A value may additionally be surrounded by double quotes but it's not necessary. See e.g. `fullName` showing both variants.

The following annotations are currently supported:

* **name** - specifies the name to use in the database if it's desired to be different than what the FlatBuffer schema "table" is called.

* **transient** - this entity is skipped, no code is generated for it. Useful if you have custom FlatBuffer handling but still want to generate ObjectBox binding code for some parts of the same file.

* **uid** - used to explicitly specify UID used with this entity; used when renaming entities. See [Schema changes](schema-changes.md) for more details.

* **relation** - adds a standalone (many-to-many) relation, usually to another entity. Example: creating a relation to the authors of a book: `objectbox:relation(name=authors,to=Author)`

* **sync** - enables synchronization for the entity - only relevant with [ObjectBox Sync](https://objectbox.io/sync/) library builds. Entities not marked with this annotation will not be synchronized to the server, i.e. they're local-only.

* `sync(sharedGlobalIds)` can be used to switch from the default behaviour (ID-mapping) to using a global ID space. This flag tells ObjectBox to treat object IDs globally and thus no ID mapping (local <-> global) is performed. Often this is used with `id(assignable)` annotation and some special ID scheme.

* **date** - tells ObjectBox the property is a timestamp in milliseconds, ObjectBox expects the value to be the number of milliseconds since UNIX epoch.

* **date-nano** - tells ObjectBox the property is a timestamp in nanoseconds, ObjectBox expects the value to be the number of nanoseconds since UNIX epoch.

* **id** - specifies this property is a unique identifier of the object - used for all CRUD operations.

* assignable IDs (set as `id(assignable)`) to switch from the default (ObjectBox assigns object IDs during insert, following auto-increment order). This will allow putting an object with any valid ID. You can still set the ID to zero to let ObjectBox auto-assign a new ID.

* **id-companion** - identifies a companion property, currently only supported on `date/date-nano` properties in time-series databases.

* **index** - creates a database index. This can improve performance when querying for that property. You can specify an index type as the annotation value:

* not specified - automatically choose the index type based on the property type (`hash` for string, `value` for others).

* `value` - uses property values to build the index. For string, this may require more storage than a hash-based index.

* `hash` - uses a 32-bit hash of property value to build the index. Occasional collisions may occur which should not have any performance impact in practice (with normal value distribution). Usually, a better choice than `hash64`, as it requires less storage.

* `hash64` - uses a long hash of property values to build the index. Requires more storage than `hash` and thus should not be the first choice in most cases.

* **relation** - declares the field as a relation ID, linking to another Entity which must be specified as a value of this annotation.

* **name** - specifies the name to use in the database if it's desired to be different than what the FlatBuffer schema "field" is called.

* **transient** - this property is skipped, no code is generated for it. Useful if you have custom FlatBuffer handling but still want to generate ObjectBox binding code for the entity.

* **uid** - used to explicitly specify UID used with this property; used when renaming properties. See [Schema changes](schema-changes.md) for more details.

* **unique** - set to enforce that values are unique before an entity is inserted/updated. A `put` operation will abort and return an error if the unique constraint is violated.