Managing Entries

About Entries

The structure of an entry and a brief description of its elements is outlined in the following table:

Define Structure

KVDB's architecture does not require you to use a specific data structure inside the entry. So before working with KVDBs, define what what kind of entries you want to send.

We recommend future-proofing your entries right from the start, i.e. choosing an easily modifiable format.

It is also a good idea to include its type and version in the structure of the entries.

Here is an example entries structure that you can use in your project.

{
   “data”:{
     “content”: "string", // string / binary data containing for example: markdown, html or json
   },
   “info”: "ServerKvdbEntryInfo", // assigned by server,
   “publicMeta”:{
     “version”:number,
     “type”: “text”, // some kind of enum describing type of entry like “event”, “html”, “markdown” etc.
   },
   “privateMeta”:{
     // meta fields
   }
}

Remember that it is only an example and you should consider your app's requirements and limitations.

Sending

With the structure ready, its time to start creating entries.

// creating entry
std::string entryKey {"entry key"};
kvdbApi.setEntry(
    kvdbId, 
    entryKey,
    core::Buffer::from("some public meta-data"), 
    core::Buffer::from("some private meta-data"),
    core::Buffer::from("entry_data"),
    0
);

After creating the entry, you can get it by the key set while creation.

Entry Keys are unique within a KVDB.

Listing Entries

Your application may include multiple entries, each associated with different KVDBs. You can retrieve a list of all entries within a given KVDB.

Here's an example of how to download the last 30 entries created within a KVDB:

// list KVDBs
core::PagingQuery query = {.skip = 0, .limit = 30, .sortOrder = "desc"};

auto result {kvdbApi.listEntries(KVDB_ID, query)};
for (const auto& entry : result.readItems) {
    std::cout << "KVDB entry key: " << entry.info.key << std::endl;
}

To limit collecting too much data when downloading entries, specify the page index (starting from 0) and the number of items to be included on each page.

Modifying Entries

Depending on your project's specification, it may be necessary to modify an entry. It could be e.g. changing entry data, publicMeta, privateMeta. Each user with management rights is able to modify and delete entries.

Updating an entry means overwriting it with the provided data. To successfully update an entry, you must be entry creator or KVDB moderator.

Below there is an example of modifying an entry:

auto entry {kvdbApi.getEntry(
    kvdbId, 
    entryKey
)}; 
kvdbApi.setEntry(
    entry.info.kvdbId,
    entry.info.key,
    core::Buffer::from("some new entry public meta-data"), 
    core::Buffer::from("some new entry private meta-data"), 
    core::Buffer::from("entry new data"),
    entry.version
);

Deleting an Entry

To successfully delete an entry, you must be the entry creator or a KVDB moderator.

Below there is an example of deleting an entry:

kvdbApi.deleteEntry(kvdbId, entryKey);