Updated on 2025-04-14 GMT+08:00

Basic Concepts

  • Store

    A store is a collection of tables. You can create different stores based on the division of your business.

  • Table

    A table is a collection of KV items and belongs to a store. You can create tables in a store to store KV data and use the local and global secondary indexes to retrieve data from tables quickly and accurately.

  • Key-Value (KV) Item

    A KV item is a document that is uniquely identified by its primary key. KV data is stored in tables.

  • Shard Key & Sort Key

    Shard key: As a table field, it determines in which shard a KV item is stored. In a user table, for example, you can specify the username field as the shard key. KVS then stores KV items with the same username in the same shard.

    Sort key: As a table field, it is used to sort KV items before storing them in the table. When querying data, you can specify the sort key to specify the order in which the data is returned.

    When creating a table, you must specify a primary key. A primary key uniquely identifies a KV item in the table. The primary keys of any two KV items are different. KVS supports two types of primary keys:

    Simple primary key: It is a shard key.

    Composite primary key: It consists of a shard key and a sort key.

  • Index

    An index lets you query the data in the table using a different primary key from the base table, enabling faster and more accurate retrieval. KVS supports local and global secondary indexes.

    Local secondary index: An index with the same shard key as its base table, but a different sort key. It is supported for tables with a composite primary key (shard key and sort key) and helps accelerate queries through the specified sort key. When a KV item is written, a local secondary index item is automatically generated and stored with strong consistency.

    Global secondary index: An index with a different shard key from the base table. Each index item stores only the index data. Other data in the corresponding KV item is not included. When a KV item is written, an index item is automatically generated and then asynchronously written to the global secondary index with eventual consistency.

For details about the relationships between stores, tables, KV items, and indexes, see Figure 1.

Figure 1 Relationships between basic KVS concepts