Key-value data model

Explore the key-value data model

In the key-value data model, each key is associated with one and only one value. Key-value stores expose three basic APIs:

  • GET to fetch the value of a key (for example, GET('name'))
  • SET to store the value of a key (for example, SET('name', 'yugabyte'))
  • DEL to delete a key and its value (for example, DEL('name'))

With these three simple functionalities, key-value stores have carved themselves a niche in modern infrastructure because of their speed and simplicity.

YugabyteDB provides several advantages when used as a key-value store:

  • YugabyteDB internally stores data as a collection of key-value pairs and therefore automatically excels as a key-value store.
  • Being distributed by design, YugabyteDB also naturally acts as a distributed key-value store.
  • YugabyteDB inherently provides consistency of data because of RAFT replication, which is typically not guaranteed by other key-value stores.



To set up a local universe, refer to Set up a local YugabyteDB universe.


To set up a cluster, refer to Set up a YugabyteDB Managed cluster.


To set up a universe, refer to Set up a YugabyteDB Anywhere universe.

Store user data

For example, to store the details of a user, you could adopt a schema where each attribute is a separate key, such as the following: = "John Wick" = "USA" = "Harry Potter" = "UK"


You can also consider a schema where the value is a JSON structure consisting of multiple attributes associated with a user.

For this, you can create a table as follows:

CREATE TABLE kvstore (
    key VARCHAR,
    value VARCHAR,
    PRIMARY KEY(key)

To add some data, enter the following:

INSERT INTO kvstore VALUES ('', 'John Wick'), ('', 'USA'),
                           ('', 'Harry Potter'), ('', 'UK');


To get the name of user1, you can execute the following:

-- GET('')
SELECT value FROM kvstore WHERE key = '';
 John Wick


To store a value for a key, you can do an insert. Because the key could already exist, you should provide an ON CONFLICT UPDATE clause.

INSERT INTO kvstore(key, value) VALUES('', 'Jack Ryan') 
        ON CONFLICT (key) DO
        UPDATE SET value = EXCLUDED.value;


To delete a key and its value, you can execute a simple DELETE command as follows:

DELETE FROM kvstore WHERE key = '';

Use cases

Cache server

The key-value data model is best suited for designing cache servers where the cached data is represented by a key. The cached object could be represented in JSON string (to have multiple attributes) and parsed by the application.

Telephone directory

A telephone directory instantly falls into the key-value model, where the key is the phone number and the value is the name and address of the person that the phone number belongs to.

Session store

A session-oriented application, such as a web application, starts a session when a user logs in, and is active until the user logs out or the session times out. During this period, the application stores all session-related data like profile information, themes, zipcode, geography, and so on, in a fast key-value store.

Shopping cart

A user's shopping cart can be represented as a JSON string and stored under a key (for example, user1.cart). Given the strong consistency and resilience offered by YugabyteDB, the cart information will not be lost even in case of disasters.