Etcd: what is different about Revision, ModRevision and Version?

[xiaoyulei]

Revision in ResponseHeader, and ModRevision and Version in KeyValue, what is different about them. I am confused from the comment.

If I Watch with WithRev, which one I should fill into WithRev?

type ResponseHeader struct {
    // cluster_id is the ID of the cluster which sent the response.
    ClusterId uint64 `protobuf:"varint,1,opt,name=cluster_id,json=clusterId,proto3" json:"cluster_id,omitempty"`
    // member_id is the ID of the member which sent the response.
    MemberId uint64 `protobuf:"varint,2,opt,name=member_id,json=memberId,proto3" json:"member_id,omitempty"`
    // revision is the key-value store revision when the request was applied.
    Revision int64 `protobuf:"varint,3,opt,name=revision,proto3" json:"revision,omitempty"`
    // raft_term is the raft term when the request was applied.
    RaftTerm uint64 `protobuf:"varint,4,opt,name=raft_term,json=raftTerm,proto3" json:"raft_term,omitempty"`
}

type KeyValue struct {
    // key is the key in bytes. An empty key is not allowed.
    Key []byte `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
    // create_revision is the revision of last creation on this key.
    CreateRevision int64 `protobuf:"varint,2,opt,name=create_revision,json=createRevision,proto3" json:"create_revision,omitempty"`
    // mod_revision is the revision of last modification on this key.
    ModRevision int64 `protobuf:"varint,3,opt,name=mod_revision,json=modRevision,proto3" json:"mod_revision,omitempty"`
    // version is the version of the key. A deletion resets
    // the version to zero and any modification of the key
    // increases its version.
    Version int64 `protobuf:"varint,4,opt,name=version,proto3" json:"version,omitempty"`
    // value is the value held by the key, in bytes.
    Value []byte `protobuf:"bytes,5,opt,name=value,proto3" json:"value,omitempty"`
    // lease is the ID of the lease that attached to key.
    // When the attached lease expires, the key will be deleted.
    // If lease is 0, then no lease is attached to the key.
    Lease int64 `protobuf:"varint,6,opt,name=lease,proto3" json:"lease,omitempty"`
}

[heyitsanthony]

@YuleiXiao the Revision is the current revision of etcd. It is incremented every time the v3 backed is modified (e.g., Put, Delete, Txn). ModRevision is the etcd revision of the last update to a key. Version is the number of times the key has been modified since it was created. Get(..., WithRev(rev)) will perform a Get as if the etcd store is still at revision rev.

[xiang90]

Probably we should add the explanation into our docs.

[xiang90]

Explicitly call them out here? https://github.com/coreos/etcd/blob/master/Documentation/learning/data_model.md

[gyuho]

@YuleiXiao Here's a simple example

Revision and ModRevision are different in that ModRevision is the last revision of a key.

$ ETCDCTL_API=3 ./bin/etcdctl put foo bar

$ ETCDCTL_API=3 ./bin/etcdctl get foo --write-out=json
revision: 2
mod_revision: 2
version: 1

$ ETCDCTL_API=3 ./bin/etcdctl put foo bar

$ ETCDCTL_API=3 ./bin/etcdctl get foo --write-out=json
revision: 3
mod_revision: 3
version: 2

$ ETCDCTL_API=3 ./bin/etcdctl put hello world

$ ETCDCTL_API=3 ./bin/etcdctl get foo --write-out=json
revision: 4
mod_revision: 3
version: 2

$ ETCDCTL_API=3 ./bin/etcdctl get hello --write-out=json
revision: 4
mod_revision: 4
version: 1

$ ETCDCTL_API=3 ./bin/etcdctl put hello world

$ ETCDCTL_API=3 ./bin/etcdctl get hello --write-out=json
revision: 5
mod_revision: 5
version: 2

[xiaoyulei]

@heyitsanthony like Get(..., WithRev(rev)), which one I should assign to rev when I had already get key-value? ModRevision, Version or Revision?

[xiang90]

@YuleiXiao I do not think you understand what @heyitsanthony and @gyuho said. First, you need to understand what are revision and version. Then it is straightforward to decide if you want to use modRev or Rev. Both of them can be used. Version is not Rev. So it is irrelevant.

[xiaoyulei]

@xiang90 I try to understand. But still confused, like the example gyuho show me. If I Get(foo, WithRev(rev)), revision and mod_revision is different. How to decide which one can be used?

$ ETCDCTL_API=3 ./bin/etcdctl get foo --write-out=json
revision: 4
mod_revision: 3
version: 2

[xiang90]

It depends on what you want to get. You can use both, but you cannot use them at the same time.

Let me try again to explain what @heyitsanthony mentioned previously. Revision is a global revision. ModRevision is the revision that the key is modified.

It is just like time. You created a file at time 20:00(3). When you read the file at 21:00(4), the modified time (modRevision) is still 20:00 (3), but current time (revision) is 21:00(4).

etcd is a mvcc system which keeps all history until a compaction. It allows you to go back in time. Get with revision will allow you to go back in time. So basically you asked us, shall I go back to 20:00 to get the state of the store or should I go back to 21:00? We cannot decide this for you. It depends on your use case.

[xiaoyulei]

@xiang90 ok, thanks very much. Understand it.

[xiang90]

@YuleiXiao No problem. Please help to improve the doc if you have time. Thanks.