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

Right now there is no API in StatelyDB for listing out your Groups. So, for example, if your Groups were based on customers, there would not be an API to list all customers. Because of the way StatelyDB distributes Groups amongst partitions within the database (and eventually, across different databases around the world), listing all of the top level Groups would be slow and expensive. 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. However, we can help if you are looking to figure out how to work around this limitation.