Skip to content


A bot is be able to store and retrieve global information (e.g. over all conversations).

The KV module

The KV module exposes a key/value database to Bubblescript processes. It supports multiple databases in a single bot, for instance for skills that need to manage their own keyspace. Databases for debugging and live conversations are separate, so data from studio sessions does not mix with real data.


Declaring that a bot uses a database is done through the integrations YAML file. A key/value database is declared in the integrations yaml file like this:

- provider: keyvalue_db
  alias: mydb
  context: bot
  description: My database

By doing this, multiple things happen:

  • In Bubblescript, a new constant named @mydb (the alias of the integration) will be accessible for use with calls to the KV module
  • The KV module will be accessible to call KV-related functions. Note that before you enable the integration, any calls to KV will result in a compile-time "undefined function" error.
  • In the integrations UI, a page appears for this database, showing statistics about the data, allowing import and export, and maybe even a table view of the data (although this can be hard because the values are unstructured)

KV: the Key/value interface

When the keyvalue_db integration is present, Bubblescript adds a KV module that is used to access all KV-related calls.

Keys in the database are always strings. Values are unstructured, they can be of any type. They are stored in the database as jsonb values.

KV.put(@mydb, "key", "Hello")

say KV.get(@mydb, "key", default: "Hi")
# "Hello"

# Listing keys with SQL LIKE pattern
repeat key in KV.keys(@mydb, "%") do
  say key

# Listing values for pattern (not redis-like but handy for us / match engine), returns a map:
_all = KV.get_many(@mydb, "*")

# TTL (in seconds; default `nil` = 1 year)
KV.put(@mydb, "key", "Hello", ttl: 3600)

# Complicated values
KV.put(@mydb, "key", %{"country" => "NL"})
KV.put(@mydb, "last_intent", intent)

See the KV function reference for a full overview of the KV functions.