KV Store Module

The KV store module provides persistent key-value storage for your Functions. The store is globally distributed and uses eventual consistency.

Execution boundaries

1. You can chain up to 3 hops from one Function to another using publish or fire.
2. Within one Function execution, you can perform up to 3 combined operations across KV store, XHRs, publish, and fire.

All KV store methods return a Promise.

Use the following require statement:

1const db = require("kvstore");

Scope

KV store data is scoped at a subscribe key level. This means data stored in the KV store is globally replicated across all points of presence (PoPs) and is available to all Functions under the same keyset.

Key and value limits

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

Data time to live (TTL)

When data is stored in the KV store, you can set a time to live (TTL). By default, the TTL is one day.

kvstore.set()

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

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

kvstore.set() with TTL

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

Takes a string key as the first parameter, a JavaScript object as the second parameter, and a TTL value (integer, minutes) as the third parameter. Data is stored persistently and is available whenever a block is triggered. TTL expires the stored object. In this example, the TTL is 2 days. The minimum TTL is 1 minute and the maximum is 1 year. Values below 1 minute are set to 1 minute; values above 1 year are set to 1 year. If not specified, the TTL defaults to one day.

kvstore.get()

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

Takes a string key as the only parameter and retrieves the stored value from the KV store.

kvstore.setItem()

1const db = require("kvstore");
2db.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

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

Takes a string key as the first parameter, a string value as the second parameter, and a TTL value (integer, minutes) as the third parameter. TTL expires the stored object. In this example, the TTL is 2 days. The minimum TTL is 1 minute and the maximum is 1 year. Values below 1 minute are set to 1 minute; values above 1 year are set to 1 year. If not specified, the TTL defaults to one day.

kvstore.getItem()

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

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

kvstore.removeItem()

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

Takes a string key as the only parameter and removes the stored value from the KV store.

kvstore.getKeys()

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

7    });

Lists all keys from the KV store.

Returns up to 100 keys. To paginate, pass the last key from the previous response as pagination_key (or undefined for the first request). Avoid static indices like result[99] because limits can change.

Counters

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

kvstore.getCounter()

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

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

kvstore.incrCounter()

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

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

kvstore.getCounterKeys()

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

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 may not cover every situation. If you need help with a case not covered here, please contact PubNub Support.