From 2c919f6022f6ec1ded6447ef6fbe966811eb5808 Mon Sep 17 00:00:00 2001 From: Charles Eckman Date: Sat, 24 Mar 2018 12:56:03 -0700 Subject: [PATCH] Documentation: Clarify revisions vs. versions This confused me just looking at the protos; reading up on coreos/etcd#6518 helped clarify things. I highlighted the terms that show up as fields in protos and tried to clean up some of the language. --- Documentation/learning/data_model.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/learning/data_model.md b/Documentation/learning/data_model.md index e497238f2..546caac3d 100644 --- a/Documentation/learning/data_model.md +++ b/Documentation/learning/data_model.md @@ -8,9 +8,9 @@ etcd stores data in a multiversion [persistent][persistent-ds] key-value store. The store’s logical view is a flat binary key space. The key space has a lexically sorted index on byte string keys so range queries are inexpensive. -The key space maintains multiple revisions. Each atomic mutative operation (e.g., a transaction operation may contain multiple operations) creates a new revision on the key space. All data held by previous revisions remains unchanged. Old versions of key can still be accessed through previous revisions. Likewise, revisions are indexed as well; ranging over revisions with watchers is efficient. If the store is compacted to save space, revisions before the compact revision will be removed. +The key space maintains multiple **revisions**. Each atomic mutative operation (e.g., a transaction operation may contain multiple operations) creates a new revision on the key space. All data held by previous revisions remains unchanged. Old versions of key can still be accessed through previous revisions. Likewise, revisions are indexed as well; ranging over revisions with watchers is efficient. If the store is compacted to save space, revisions before the compact revision will be removed. Revisions are monotonically increasing over the lifetime of a cluster. -A key’s lifetime spans a generation, denoted by its version. Each key may have one or multiple generations. Creating a key increments the version of that key, starting at 1 if the key never existed. Deleting a key generates a key tombstone, concluding the key’s current generation by resetting its version. Each modification of a key increments its version. Once a compaction happens, any version ended before the given revision will be removed and values set before the compaction revision except the latest one will be removed. +A key's life spans a generation, from creation to deletion. Each key may have one or multiple generations. Creating a key increments the **version** of that key, starting at 1 if the key does not exist at the current revision. Deleting a key generates a key tombstone, concluding the key’s current generation by resetting its version to 0. Each modification of a key increments its version; so, versions are monotonically increasing within a key's generation. Once a compaction happens, any generation ended before the compaction revision will be removed, and values set before the compaction revision except the latest one will be removed. ### Physical view