KVDB 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.

Creating KVDB Entry

When you create a new entry, the version parameter must be set to 0 - which is the default value.

val kvdbId = "KVDB_ID"
val kvdbEntryKey = "KVDB_ENTRY_KEY"
val kvdbEntryData = "Plain Data"
val publicMeta = ByteArray(0)
val privateMeta = ByteArray(0)

val entryId = kvdbApi.setEntry(
    kvdbId,
    kvdbEntryKey,
    publicMeta,
    privateMeta,
    kvdbEntryData.encodeToByteArray()
)

Updating KVDB Entry

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.

If you want to update an existing KVDB entry - you have to provide current version of given entry. Even if certain fields haven’t changed, their current values must still be provided e.g. public and private meta.

val kvdbId = "KVDB_ID"
val kvdbEntryKey = "KVDB_ENTRY_KEY"
val kvdbEntry: KvdbEntry = kvdbApi.getEntry(kvdbId, kvdbEntryKey)
val newKvdbEntryData = "New data"

kvdbApi.setEntry(
    kvdbId,
    kvdbEntryKey,
    kvdbEntry.publicMeta,
    kvdbEntry.privateMeta,
    newKvdbEntryData.encodeToByteArray(),
    kvdbEntry.version + 1
)

Listing KVDB Entries

Define entry item class with decoded data and publicMeta:

data class KvdbEntryItem(
    val kvdbEntry: KvdbEntry,
    val decodedData: String,
    val decodedPublicMeta: KvdbEntryPublicMeta
)

val kvdbId = "KVDB_ID"
val startIndex = 0L
val pageSize = 100L

val kvdbEntriesPagingList = kvdbApi.listEntries(
    kvdbId,
    startIndex,
    pageSize,
    SortOrder.DESC
)

val kvdbEntries = kvdbEntriesPagingList.readItems.map {
    KvdbEntryItem(
        it,
        it.data.decodeToString(),
        Json.decodeFromString(it.publicMeta.decodeToString())
    )
}

Checking if an Entry Exists

You can check if a KVDB entry with the given key exists within the specified KVDB instance.

val kvdbId = "KVDB_ID"
val kvdbEntryKey = "KVDB_ENTRY_KEY"

val hasEntry: Boolean = kvdbApi.hasEntry(kvdbId, kvdbEntryKey)

Deleting KVDB Entries

The snippet below deletes KVDB entry and all its data. This action is irreversible.

val kvdbId = "KVDB_ID"
val kvdbEntryKey = "KVDB_ENTRY_KEY"

kvdbApi.deleteEntry(kvdbId, kvdbEntryKey)