Groups

The first segment in a key path is special—we refer to it as the “group key”. All the Items that share the same group key will be partitioned together in the database, and all items that share the same group key is called a Group. If you’re familiar with DynamoDB you may know this as the “partition key”. In the e-commerce example from Key Paths, the Group Key is /cust-p05olqcFSfC6zOqEojxT9g and all the Items for that customer - Customer, Orders, and LineItems - are in the same Group.

You generally want to spread your data out amongst many Groups, since different Groups can be distributed to different places in the database, allowing them to scale independently. Fortunately, most problems naturally have some grouping of data, such as by user. While StatelyDB supports cross-group operations in transactions or batch operations StatelyDB is optimized for work within a single group.

Group Versions: Tracking Changes

Each Group has a version associated with it. This is a number that automatically increases by one for every update performed in the group regardless of the number of Items that change. On the first write to a Group, the Group’s version is 1. On a subsequent batch put of two additional Items, the Group’s version is 2, though there are three total Items in the group. If the first Item is then deleted, the version becomes 3. And lastly, if the third Item is modified, the version becomes 4.

For groups that support Versions (by default this is all groups), StatelyDB maintains CreatedAtVersion and LastModifiedVersion metadata for the Items within a group. Following from the example above the first Item would have CreatedAtVersion = 1, LastModifiedVersion = 1 (before it is deleted) the second Item would have CreatedAtVersion = 2, LastModifiedVersion = 2, and the third item would have CreatedAtVersion = 2, LastModifiedVersion = 4. You can read this metadata by mapping it to fields.

Group Versions are a powerful feature that allows you to track changes within a group of Items. This allows you to understand the order in which items were modified or created within the same group. They are also what makes SyncList work!

Listing All Groups

You can use the Scan API to list out all item types of a type, including item types that represent top level groups. Because of the way StatelyDB distributes Groups amongst partitions within the database (and eventually, across different databases around the world), listing all items can be slow and/or expensive since it needs to read the whole database. Most applications will not need to perform an operation like this if the Group Key is chosen well - for example it is not frequently necessary to list out all users of an application in one place. The Scan API is there if you do need this capability.