KV Store Module

KV Store API

In Functions v2, you can use both the KV store module or directly call PubNub API to store your Functions data. For details on how to do that through API calls, refer to the REST API docs.

The kvstore module is a persistent key value store that acts as a database for your Functions. This database is globally distributed and eventually consistent.

Maximum recursion limit

1. The maximum recursion limit you can do is 3 - hops from one Function to another, using publish or fire, you can execute a maximum of three Functions.
2. The combined maximum number within a single Function execution of KV store operations, XHRs, publish and fire is 3.

All KV store methods return a promise object.

The kvstore module is made available via the following require() statement:

const db = require("kvstore");

Scope

KV store data is scoped at a subscribe key level. This means that data stored within the KV store is globally replicated across all PoPs, and available for all Functions under the same keyset to access.

Maximum keys and value length

The maximum length of the key is 1000 characters and the maximum length of the value is 32000 characters.

Data time to live (ttl)

When data is stored in the KV store, you can set the Time to Live (TTL). By default the TTL is 1 day.

kvstore.set()

const db = require("kvstore");
db.set("key", {value: true});

Takes a string key as the first parameter, a Javascript object as the second parameter. Data is stored persistently and is available whenever a block is triggered.

kvstore.set() with TTL

const db = require("kvstore");
db.set("key", {value: true}, 2880);

Takes a string key as the first parameter, a Javascript object as the second parameter, and an integer TTL as the third parameter, which is set in minutes.

Data is stored persistently and is available whenever a block is triggered. TTL causes expiration of the stored object. In the example, the TTL is set to 2 days. The minimum value of TTL is 1 minute, and the maximum value is 1 year. Specifying a value less than 1 minute sets the TTL to 1 minute, and specifying a value more than 1 year sets the TTL to 1 year. If not specified, the value defaults to 1 day.

kvstore.get()

const db = require("kvstore");
db.get("key").then((value) => {
    console.log("value", value);
});

Takes a string as the only parameter and retrieves the stored value from the database.

kvstore.setitem()

const db = require("kvstore");
db.setItem("key", "value");

Takes a string key as the first parameter and a string value as the second parameter. Same as db.set() but optimized for string values.

kvstore.setitem() with TTL

const db = require("kvstore");
db.setItem("key", "value", 2880);

Takes a string key as the first parameter, a string value as the second parameter, and an integer TTL as the third parameter, which is set in minutes.

TTL causes expiration of the stored object. In the example, the TTL is set to 2 days. The minimum value of TTL is 1 minute, and the maximum value is 1 year. Specifying a value less than 1 minute sets the TTL to 1 minute, and specifying a value more than 1 year sets the TTL to 1 year. If not specified, the value defaults to 1 day.

kvstore.getitem()

const db = require("kvstore");
db.getItem("key").then((value) => {
    console.log("value", value);
});

Takes a string as the only parameter and retrieves the stored value from the database. Same as db.get() but optimized for string values.

kvstore.removeitem()

const db = require("kvstore");
db.removeItem("key");

Takes a string as the only parameter and removes the stored value from the database.

kvstore.getkeys()

const db = require("kvstore");
db.getKeys().then((keys) => {
        for(var i=0; i<keys.length;i++){
            console.log(keys[i])
        }

    });

Lists all keys from kvstore.

The method returns a maximum of 100 keys. The method accepts a string argument for paginating results. The pagination_key should be the last key returned from a previous response (or undefined for the first response). Using a static index like result[99] would break code when the limit is changed.

Counters

Counters are an efficient way to increment a stored number in an atomic fashion. Counters stored in the key/value storage are not subjected to TTL.

kvstore.getcounter()

const db = require("kvstore");
db.getCounter("key").then((counter) => {
    console.log("counter", counter);
});

Takes a string as the only parameter and retrieves the stored counter value from the database. Returns 0L if no counter under key has yet been incremented.

kvstore.incrcounter()

const db = require("kvstore");
db.incrCounter("key", number);

Takes a string as the first parameter and a number as the second parameter. Increments counter stored under key by number. Creates a new counter initialized to zero if none yet exist under key. If the number is not set, the value defaults to 1.

kvstore.getcounterkeys()

const db = require("kvstore");
db.getCounterKeys().then((counterKeys) => {
        for(var i=0; i<counterKeys.length;i++){
            console.log(counterKeys[i])
        }
    });

Lists all keys from the KV Store Counter.

The method returns a maximum of 100 keys. The method accepts a string argument for paginating results. The pagination_key should be the last key returned from a previous response (or undefined for the first response). Using a static index like result[99] would break code when the limit is changed.

Functions support

Functions provides a rich set of tools, and this documentation does not cover all of the potential situations you may encounter. If you need help with a situation not covered by the documentation, please contact PubNub Support