Skip to main content

Metadata Key-Value Store Hello World

In this tutorial, we will take you through your first steps with the Metadata Key-Value Store (MDKVS). We will cover all the basic operations such as read, write, delete and restrict. You can read more about all of these concepts in the documentation and API reference.


To follow along you need access to a Seaplane account. You can create one here.


Before we start, make sure you are properly authenticated. All examples below assume you completed the authentication steps using the examples below.

Open a terminal and run seaplane account login. Follow the steps inside your terminal to complete the setup. For more detailed instructions, see the CLI API-key configuration documentation

Setting a key

Create your first key-value pair using one of the code snippets below. In these examples hello represents the key and world represents the value.

The MDKVS requires keys and values to be base64 encoded. The CLI and SDK handle the encoding automatically, for the cURL request we are providing a function to encode/decode your strings. You can read more about base64 encoding here

seaplane metadata set hello world

Getting a key

Retrieve the key you just created using one of the code snippets below.

Use the --decode or -D flag to automatically decode your key-value pair.

seaplane metadata get hello --decode

Deleting a key

Delete the key we just created using one of the code snippets below.

seaplane metadata delete hello

Using Directories

MDKVS supports the use of directories. You can use directories to restrict groups of key-value pairs. To learn more about restrictions have a look at the documentation here.

In this example, you are restricting your keys to North America. First, you are going to create a directory with a key-value pair and then restrict that directory. Seaplane uses the ISO Alpha2 codes to indicate countries and regions. You can learn more about them here. In this example, we are restricting to North America indicated by the ISO code XN.

  • The directory name is my-us-keys
  • The key is hello
  • The value is world

Creating the directory with a key-value pair

seaplane metadata set my-us-keys/hello world

Restricting the directory to stay inside North-America

seaplane restrict set config my-us-keys --region XN

Restriction enforcement

It might take a few seconds for all data to move to the new location, especially if you store a lot of keys in your directory. You can check the status of a restriction using the following command.

If the state is pending it means Seaplane is still moving your keys. enforced means all your keys inside your directory are restricted.

seaplane restrict list -D