Manage key-value data from a function

Store, read, and delete keys in a KV Store namespace from a function, with metadata, binary values, streams, and several namespaces.

Last updated

View as Markdown Agent setup

You store, read, and delete keys in a KV Store namespace from a function, with the Azion.KV client. Every specimen on this page opens the namespace with await Azion.KV.open(name): the constructor is private, and there is no default namespace.

Creating the namespace itself is an Azion API task, and a function cannot do it. For more information, refer to Namespaces.

Prerequisites

Create the function

The client is a global of Azion Runtime, so the code reaches it with no import line and no credential. To create the function that holds one of the specimens below:

Open the Functions page

Access Azion Console > Products Menu > Libraries > Functions.

Select + Function
Name the function

Enter a name for the function. For example: kv-store-handler.

Paste the code in the Code tab

In the Code tab, replace the placeholder code with one of the specimens on this page, and replace my-namespace with your namespace.

Select Save

The function is saved. It answers a request once a Rules Engine rule runs its instance on the application.

Store a value

put creates a key and replaces the value of a key that already exists, so one call covers both. A string is stored as it is, an object is serialized to JSON, and a third argument carries metadata and an expiry. To store three keys in one invocation:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('greeting', 'Hello, World!');
06
07 // An object is serialized to JSON, so it needs no stringify call.
08 await kv.put('user-preferences', {
09 theme: 'dark',
10 language: 'en',
11 notifications: true,
12 });
13
14 // metadata travels beside the value; expirationTtl expires the key after 3600 seconds.
15 await kv.put('session-token', 'abc123xyz', {
16 metadata: { userId: 'user-42' },
17 expirationTtl: 3600,
18 });
19
20 return new Response('Values stored', { status: 201 });
21 },
22};

The handler writes three keys and answers 201. For every option put accepts, refer to KV client.

Read a value

get reads one key and returns the value in the type its second argument names, which defaults to text. A key the namespace does not hold returns null, so the handler checks for it rather than catching an error. To read a string, an object, and a key that may be absent:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 const greeting = await kv.get('greeting', 'text');
06 const preferences = await kv.get('user-preferences', 'json');
07
08 if (greeting === null) {
09 return new Response('Key not found', { status: 404 });
10 }
11
12 return new Response(JSON.stringify({ greeting, preferences }), {
13 headers: { 'Content-Type': 'application/json' },
14 status: 200,
15 });
16 },
17};

The handler answers 404 when greeting is absent, and otherwise returns both values in one JSON body. A key the namespace does not hold reaches the null branch rather than throwing, which is why the check is an equality test and not a try.

Read several keys at once

An array as the first argument of get reads several keys in one call and returns a plain object keyed by key name. A key the namespace does not hold appears in that object with the value null. To write three keys and read four:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('user-1', 'Alice');
06 await kv.put('user-2', 'Bob');
07 await kv.put('user-3', 'Charlie');
08
09 const users = await kv.get(['user-1', 'user-2', 'user-3', 'user-4'], 'text');
10
11 // { "user-1": "Alice", "user-2": "Bob", "user-3": "Charlie", "user-4": null }
12
13 return new Response(JSON.stringify(users), {
14 headers: { 'Content-Type': 'application/json' },
15 status: 200,
16 });
17 },
18};

The three writes address three different keys, and user-4 comes back as null because the namespace holds no key by that name. The array form accepts only text and json: any other return type throws INVALID_MULTIPLE_GET_RETURN_TYPE.

Read a value with its metadata

getWithMetadata returns an object carrying value and metadata, so one call reads both. The metadata is whatever the write passed in the metadata option. To store a key with metadata and read the pair back:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('session', 'active-session-data', {
06 metadata: {
07 createdAt: new Date().toISOString(),
08 userId: 'user-42',
09 },
10 });
11
12 const result = await kv.getWithMetadata('session', 'text');
13
14 return new Response(JSON.stringify(result), {
15 headers: { 'Content-Type': 'application/json' },
16 status: 200,
17 });
18 },
19};

The handler returns result.value and result.metadata in the same response body.

Delete a key

delete removes one key and takes no array form, so several keys are removed with one call each. A read before the delete tells the handler which of the keys the namespace holds. To delete two keys and answer 404 when it holds neither:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04 const keys = ['session-token', 'session-token-2'];
05
06 try {
07 const found = await kv.get(keys, 'text');
08 const present = keys.filter((key) => found[key] !== null);
09
10 if (present.length === 0) {
11 return new Response('Key not found', { status: 404 });
12 }
13
14 await Promise.all(present.map((key) => kv.delete(key)));
15
16 return new Response(`Deleted ${present.length} keys`, { status: 200 });
17 } catch (error) {
18 return new Response(error.message, { status: 500 });
19 }
20 },
21};

The handler answers 200 with the number of keys it removed, 404 when the namespace holds neither key, and 500 carrying the message of a call that rejected.

Store and read binary data

put accepts an ArrayBuffer, and arrayBuffer as the return type of get reads the bytes back. TextEncoder and TextDecoder convert between a string and that buffer. To store a string as bytes and decode it on the way out:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 const binaryData = new TextEncoder().encode('Binary content here').buffer;
06 await kv.put('binary-key', binaryData);
07
08 const retrieved = await kv.get('binary-key', 'arrayBuffer');
09 const decoded = new TextDecoder('utf-8').decode(retrieved);
10
11 return new Response(decoded, {
12 headers: { 'Content-Type': 'text/plain' },
13 status: 200,
14 });
15 },
16};

The handler returns the decoded string, which is the text the write encoded.

Read a value as a stream

stream as the return type returns a ReadableStream instead of the assembled value, so a large value reaches the response without the handler holding it. An absent key still returns null, so the handler checks before it builds the response. To pass a value straight into the response body:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 const stream = await kv.get('large-content', 'stream');
06
07 if (stream === null) {
08 return new Response('Key not found', { status: 404 });
09 }
10
11 return new Response(stream, {
12 headers: { 'Content-Type': 'application/octet-stream' },
13 status: 200,
14 });
15 },
16};

The handler answers 404 when the key is absent, and otherwise streams the value as the response body.

Use a specific namespace

Azion.KV.open binds a client to the namespace it names, so a function that reaches two namespaces opens two clients. The same key name in two namespaces addresses two separate values. To write and read one key in each of two namespaces:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const productionKv = await Azion.KV.open('production-data');
04 const stagingKv = await Azion.KV.open('staging-data');
05
06 await productionKv.put('config', 'production-value');
07 await stagingKv.put('config', 'staging-value');
08
09 const production = await productionKv.get('config', 'text');
10 const staging = await stagingKv.get('config', 'text');
11
12 return new Response(JSON.stringify({ production, staging }), {
13 headers: { 'Content-Type': 'application/json' },
14 status: 200,
15 });
16 },
17};

Each config key belongs to its own namespace, so neither write overwrites the other. A name that belongs to no namespace on the account throws NotFound: KV namespace "staging-data" does not exist.

Next steps

KV clientEvery method, option, return type, and error of the Azion.KV client.NamespacesCreate, list, and retrieve a namespace through the Azion API.Best practicesThe recommendations to follow before the first key goes in.TroubleshootingWhat a KV Store call reports when it fails, and what to do about it.