componentized

A keyvalue interface that provides batch operations.

A batch operation is an operation that operates on multiple keys at once.

Batch operations are useful for reducing network round-trip time. For example, if you want to get the values associated with 100 keys, you can either do 100 get operations or you can do 1 batch get operation. The batch operation is faster because it only needs to make 1 network call instead of 100.

A batch operation does not guarantee atomicity, meaning that if the batch operation fails, some of the keys may have been modified and some may not.

This interface does has the same consistency guarantees as the store interface, meaning that you should be able to "read your writes."

Please note that this interface is bare functions that take a reference to a bucket. This is to get around the current lack of a way to "extend" a resource with additional methods inside of wit. Future version of the interface will instead extend these methods on the base bucket resource.

Types

use resource bucket

from wasi:keyvalue/store@0.2.0-draft

A bucket is a collection of key-value pairs. Each key-value pair is stored as a entry in the bucket, and the bucket itself acts as a collection of all these entries.

It is worth noting that the exact terminology for bucket in key-value stores can very depending on the specific implementation. For example:

  1. Amazon DynamoDB calls a collection of key-value pairs a table
  2. Redis has hashes, sets, and sorted sets as different types of collections
  3. Cassandra calls a collection of key-value pairs a column family
  4. MongoDB calls a collection of key-value pairs a collection
  5. Riak calls a collection of key-value pairs a bucket
  6. Memcached calls a collection of key-value pairs a slab
  7. Azure Cosmos DB calls a collection of key-value pairs a container

In this interface, we use the term bucket to refer to a collection of key-value pairs

  • functionget: func(key: string) -> result<option<list<u8>>, error>

    Get the value associated with the specified key

    The value is returned as an option. If the key-value pair exists in the store, it returns Ok(value). If the key does not exist in the store, it returns Ok(none).

    If any other error occurs, it returns an Err(error).

  • functionset: func(key: string, value: list<u8>) -> result<_, error>

    Set the value associated with the key in the store. If the key already exists in the store, it overwrites the value.

    If the key does not exist in the store, it creates a new key-value pair.

    If any other error occurs, it returns an Err(error).

  • functiondelete: func(key: string) -> result<_, error>

    Delete the key-value pair associated with the key in the store.

    If the key does not exist in the store, it does nothing.

    If any other error occurs, it returns an Err(error).

  • functionexists: func(key: string) -> result<bool, error>

    Check if the key exists in the store.

    If the key exists in the store, it returns Ok(true). If the key does not exist in the store, it returns Ok(false).

    If any other error occurs, it returns an Err(error).

  • functionlist-keys: func(cursor: option<u64>) -> result<key-response, error>

    Get all the keys in the store with an optional cursor (for use in pagination). It returns a list of keys. Please note that for most KeyValue implementations, this is a can be a very expensive operation and so it should be used judiciously. Implementations can return any number of keys in a single response, but they should never attempt to send more data than is reasonable (i.e. on a small edge device, this may only be a few KB, while on a large machine this could be several MB). Any response should also return a cursor that can be used to fetch the next page of keys. See the key-response record for more information.

    Note that the keys are not guaranteed to be returned in any particular order.

    If the store is empty, it returns an empty list.

    MAY show an out-of-date list of keys if there are concurrent writes to the store.

    If any error occurs, it returns an Err(error).

use variant error

from wasi:keyvalue/store@0.2.0-draft

The set of errors which may be raised by functions in this package

  • no-such-store

    The host does not recognize the store identifier requested.

  • access-denied

    The requesting component does not have access to the specified store (which may or may not exist).

  • other: string

    Some implementation-specific error has occurred (e.g. I/O)

Functions

functionget-many: func( bucket: borrow<bucket>, keys: list<string>, ) -> result<list<option<tuple<string, list<u8>>>>, error>

Get the key-value pairs associated with the keys in the store. It returns a list of key-value pairs.

If any of the keys do not exist in the store, it returns a none value for that pair in the list.

MAY show an out-of-date value if there are concurrent writes to the store.

If any other error occurs, it returns an Err(error).

functionset-many: func( bucket: borrow<bucket>, key-values: list<tuple<string, list<u8>>>, ) -> result<_, error>

Set the values associated with the keys in the store. If the key already exists in the store, it overwrites the value.

Note that the key-value pairs are not guaranteed to be set in the order they are provided.

If any of the keys do not exist in the store, it creates a new key-value pair.

If any other error occurs, it returns an Err(error). When an error occurs, it does not rollback the key-value pairs that were already set. Thus, this batch operation does not guarantee atomicity, implying that some key-value pairs could be set while others might fail.

Other concurrent operations may also be able to see the partial results.

functiondelete-many: func( bucket: borrow<bucket>, keys: list<string>, ) -> result<_, error>

Delete the key-value pairs associated with the keys in the store.

Note that the key-value pairs are not guaranteed to be deleted in the order they are provided.

If any of the keys do not exist in the store, it skips the key.

If any other error occurs, it returns an Err(error). When an error occurs, it does not rollback the key-value pairs that were already deleted. Thus, this batch operation does not guarantee atomicity, implying that some key-value pairs could be deleted while others might fail.

Other concurrent operations may also be able to see the partial results.

WIT

/// A keyvalue interface that provides batch operations.
///
/// A batch operation is an operation that operates on multiple keys at once.
///
/// Batch operations are useful for reducing network round-trip time. For example, if you want to
/// get the values associated with 100 keys, you can either do 100 get operations or you can do 1
/// batch get operation. The batch operation is faster because it only needs to make 1 network call
/// instead of 100.
///
/// A batch operation does not guarantee atomicity, meaning that if the batch operation fails, some
/// of the keys may have been modified and some may not.
///
/// This interface does has the same consistency guarantees as the `store` interface, meaning that
/// you should be able to "read your writes."
///
/// Please note that this interface is bare functions that take a reference to a bucket. This is to
/// get around the current lack of a way to "extend" a resource with additional methods inside of
/// wit. Future version of the interface will instead extend these methods on the base `bucket`
/// resource.
interface batch {
  use store.{bucket, error};

  /// Get the key-value pairs associated with the keys in the store. It returns a list of
  /// key-value pairs.
  ///
  /// If any of the keys do not exist in the store, it returns a `none` value for that pair in the
  /// list.
  ///
  /// MAY show an out-of-date value if there are concurrent writes to the store.
  ///
  /// If any other error occurs, it returns an `Err(error)`.
  get-many: func(bucket: borrow<bucket>, keys: list<string>) -> result<list<option<tuple<string, list<u8>>>>, error>;

  /// Set the values associated with the keys in the store. If the key already exists in the
  /// store, it overwrites the value.
  ///
  /// Note that the key-value pairs are not guaranteed to be set in the order they are provided.
  ///
  /// If any of the keys do not exist in the store, it creates a new key-value pair.
  ///
  /// If any other error occurs, it returns an `Err(error)`. When an error occurs, it does not
  /// rollback the key-value pairs that were already set. Thus, this batch operation does not
  /// guarantee atomicity, implying that some key-value pairs could be set while others might
  /// fail.
  ///
  /// Other concurrent operations may also be able to see the partial results.
  set-many: func(bucket: borrow<bucket>, key-values: list<tuple<string, list<u8>>>) -> result<_, error>;

  /// Delete the key-value pairs associated with the keys in the store.
  ///
  /// Note that the key-value pairs are not guaranteed to be deleted in the order they are
  /// provided.
  ///
  /// If any of the keys do not exist in the store, it skips the key.
  ///
  /// If any other error occurs, it returns an `Err(error)`. When an error occurs, it does not
  /// rollback the key-value pairs that were already deleted. Thus, this batch operation does not
  /// guarantee atomicity, implying that some key-value pairs could be deleted while others might
  /// fail.
  ///
  /// Other concurrent operations may also be able to see the partial results.
  delete-many: func(bucket: borrow<bucket>, keys: list<string>) -> result<_, error>;
}