Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
xiaoyulei opened this issue Sep 26, 2016 · 10 comments

Comments

@xiaoyulei
Copy link
Contributor

commented Sep 26, 2016

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

This comment has been minimized.

Copy link
Contributor

commented Sep 26, 2016

@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 added the area/doc label Sep 26, 2016
@xiang90

This comment has been minimized.

Copy link
Contributor

commented Sep 26, 2016

Probably we should add the explanation into our docs.

@xiang90

This comment has been minimized.

Copy link
Contributor

commented Sep 26, 2016

@gyuho

This comment has been minimized.

Copy link
Member

commented Sep 26, 2016

@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

This comment has been minimized.

Copy link
Contributor Author

commented Sep 27, 2016

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

@xiang90

This comment has been minimized.

Copy link
Contributor

commented Sep 27, 2016

@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

This comment has been minimized.

Copy link
Contributor Author

commented Sep 27, 2016

@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

This comment has been minimized.

Copy link
Contributor

commented Sep 27, 2016

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

This comment has been minimized.

Copy link
Contributor Author

commented Sep 27, 2016

@xiang90 ok, thanks very much. Understand it.

@xiaoyulei xiaoyulei closed this Sep 27, 2016
@xiang90

This comment has been minimized.

Copy link
Contributor

commented Sep 27, 2016

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

iaguis added a commit to flatcar-linux/etcd that referenced this issue Apr 18, 2018
This confused me just looking at the protos; reading up on etcd-io/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.
iaguis added a commit to flatcar-linux/etcd that referenced this issue Apr 19, 2018
This confused me just looking at the protos; reading up on etcd-io/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.
iaguis added a commit to flatcar-linux/etcd that referenced this issue Apr 19, 2018
This confused me just looking at the protos; reading up on etcd-io/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.
iaguis added a commit to flatcar-linux/etcd that referenced this issue Apr 19, 2018
This confused me just looking at the protos; reading up on etcd-io/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.
iaguis added a commit to flatcar-linux/etcd that referenced this issue Apr 19, 2018
This confused me just looking at the protos; reading up on etcd-io/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.
iaguis added a commit to flatcar-linux/etcd that referenced this issue Apr 19, 2018
This confused me just looking at the protos; reading up on etcd-io/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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
4 participants
You can’t perform that action at this time.