Skip to content

what is different about Revision, ModRevision and Version? #6518

Closed
@xiaoyulei

Description

@xiaoyulei
Contributor

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"`
}

Activity

heyitsanthony

heyitsanthony commented on Sep 26, 2016

@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

xiang90 commented on Sep 26, 2016

@xiang90
Contributor

Probably we should add the explanation into our docs.

xiang90

xiang90 commented on Sep 26, 2016

@xiang90
Contributor
gyuho

gyuho commented on Sep 26, 2016

@gyuho
Contributor

@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

xiaoyulei commented on Sep 27, 2016

@xiaoyulei
ContributorAuthor

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

xiang90

xiang90 commented on Sep 27, 2016

@xiang90
Contributor

@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

xiaoyulei commented on Sep 27, 2016

@xiaoyulei
ContributorAuthor

@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

xiang90 commented on Sep 27, 2016

@xiang90
Contributor

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

xiaoyulei commented on Sep 27, 2016

@xiaoyulei
ContributorAuthor

@xiang90 ok, thanks very much. Understand it.

xiang90

xiang90 commented on Sep 27, 2016

@xiang90
Contributor

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

pzheng1025

pzheng1025 commented on Mar 26, 2022

@pzheng1025

Hi all,

Read through the thread. I have a question.
If I run a put request to update a key and receive a PutResponse, can I assume that the revision in response header is always equal to the mod_revision of this key if there is no future update on that key?

In another way, is it possible that etcd receives a put request, current global revision is 1 so key's mod_revision will be 1 + 1 = 2, however due to other client operations, global revision goes to 5 for example, so when etcd send PutResponse, it will put 5 in the header? Or etcd will always use key's mod_revision as the header version for PutResponse.

Thanks.

pzheng1025

pzheng1025 commented on Mar 26, 2022

@pzheng1025

After check the source code, looks like the assumption is correct. Please correct me if I am wrong.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @xiang90@gyuho@pzheng1025@xiaoyulei@heyitsanthony

        Issue actions

          what is different about Revision, ModRevision and Version? · Issue #6518 · etcd-io/etcd