Key Value Store

Want to go straight to the reference documentation? Find it here.

Key value functions are available in the spin_sdk::key_value module. The function names match the operations above. For example:

use anyhow::Result;
use spin_sdk::{
    http::{IntoResponse, Request, Response},
    http_component,
    key_value::{Store},
};
#[http_component]
fn handle_request(_req: Request) -> Result<impl IntoResponse> {
    let store = Store::open_default()?;
    store.set("mykey", b"myvalue")?;
    let value = store.get("mykey")?;
    let response = value.unwrap_or_else(|| "not found".into());
    Ok(Response::builder()
        .status(200)
        .header("content-type", "text/plain")
        .body(response)
        .build())
}

General Notes

set Operation

• For set, the value argument can be of any type that implements AsRef<[u8]>

get Operation

• For get, the return value is of type Option<Vec<u8>>. If the key does not exist it returns None.

open and close Operations

• The close operation is not surfaced; it is called automatically when the store is dropped.

set_json and get_json Operation

• Rust applications can store and retrieve serializable Rust types.

Want to go straight to the reference documentation? Find it here.

The key value functions can be accessed after opening a store using either the Kv.open or the Kv.openDefault methods which returns a handle to the store. For example:

import { ResponseBuilder , Kv} from "@fermyon/spin-sdk";

export async function handler(req: Request, res: ResponseBuilder) {
    let store = Kv.openDefault()
    store.set("mykey", "myvalue")
    res.status(200)
    res.set({"content-type":"text/plain"})
    res.send(store.get("mykey") ?? "Key not found")
}

General Notes

• The SDK doesn’t surface the close operation. It automatically closes all stores at the end of the request; there’s no way to close them early.

get Operation

• The result is of the type Uint8Array | null
• If the key does not exist, get returns null

set Operation

• The value argument is of the type Uint8Array | string | object.

setJson and getJson Operation

• Applications can store JavaScript objects using setJson; these are serialized within the store as JSON. These serialized objects can be retrieved and deserialized using getJson. If you call getJson on a key that doesn’t exist then it returns an empty object.

Want to go straight to the reference documentation? Find it here.

The key value functions are provided through the spin_key_value module in the Python SDK. For example:

from spin_sdk import http, key_value
from spin_sdk.http import Request, Response

class IncomingHandler(http.IncomingHandler):
    def handle_request(self, request: Request) -> Response:
        with key_value.open_default() as store:
            store.set("test", bytes("hello world!", "utf-8"))
            val = store.get("test")
            
        return Response(
            200,
            {"content-type": "text/plain"},
            val
        )

General Notes

• The Python SDK doesn’t surface the close operation. It automatically closes all stores at the end of the request; there’s no way to close them early.

get Operation

• If a key does not exist, it returns None

Want to go straight to the Spin SDK reference documentation? Find it here.

Key value functions are provided by the github.com/fermyon/spin/sdk/go/v2/kv module. See Go Packages for reference documentation. For example:

import "github.com/fermyon/spin/sdk/go/v2/kv"

func example() error {
    store, err := kv.OpenStore("default")
    if err != nil {
        return err
    }
    defer store.Close()
    previous, err := store.Get("mykey")
    return store.Set("mykey", []byte("myvalue"))
}