Corrections and clarifications in K2V spec
All checks were successful
continuous-integration/drone/pr Build is passing
continuous-integration/drone/push Build is passing

This commit is contained in:
Alex 2022-05-03 21:55:59 +02:00
parent fe37f45007
commit 3ce6ffa270
Signed by: lx
GPG key ID: 0E496D15096376BE

View file

@ -10,10 +10,10 @@
- Bucket names and access keys are the same as for accessing the S3 API - Bucket names and access keys are the same as for accessing the S3 API
- K2V triplets exist separately from S3 objects. K2V triples don't exist for - K2V triplets exist separately from S3 objects. K2V triplets don't exist for
the S3 API, and S3 objects don't exist for the K2V API. the S3 API, and S3 objects don't exist for the K2V API.
- Values stored for triples have associated causality information, that enables - Values stored for triplets have associated causality information, that enables
Garage to detect concurrent writes. In case of concurrent writes, Garage Garage to detect concurrent writes. In case of concurrent writes, Garage
keeps the concurrent values until a further write supersedes the concurrent keeps the concurrent values until a further write supersedes the concurrent
values. This is the same method as Riak KV implements. The method used is values. This is the same method as Riak KV implements. The method used is
@ -28,17 +28,19 @@
Triples in K2V are constituted of three fields: Triples in K2V are constituted of three fields:
- a partition key (`pk`), an utf8 string that defines in what partition the triple is - a partition key (`pk`), an utf8 string that defines in what partition the
stored; triples in different partitions cannot be listed together, they must triplet is stored; triplets in different partitions cannot be listed together
be the object of different ReadItem or ReadBatch queries in a ReadBatch command, or deleted together in a DeleteBatch command: a
separate command must be included in the ReadBatch/DeleteBatch call for each
partition key in which the client wants to read/delete lists of items
- a sort key (`sk`), an utf8 string that defines the index of the triple inside its - a sort key (`sk`), an utf8 string that defines the index of the triplet inside its
partition; triples are uniquely idendified by their partition key + sort key partition; triplets are uniquely idendified by their partition key + sort key
- a value (`v`), an opaque binary blob associated to the partition key + sort key; - a value (`v`), an opaque binary blob associated to the partition key + sort key;
they are transmitted as binary when possible but in most case in the JSON API they are transmitted as binary when possible but in most case in the JSON API
they will be represented as strings using base64 encoding; a value can also they will be represented as strings using base64 encoding; a value can also
be `null` to indicate a deleted triple (a `null` value is called a tombstone) be `null` to indicate a deleted triplet (a `null` value is called a tombstone)
### Causality information ### Causality information
@ -137,8 +139,8 @@ Once encoded in binary, contexts are written and transmitted in base64.
### Indexing ### Indexing
K2V keeps an index, a secondary data structure that is updated asynchronously, K2V keeps an index, a secondary data structure that is updated asynchronously,
that keeps tracks of the number of triples stored for each partition key. that keeps tracks of the number of triplets stored for each partition key.
This allows easy listing of all of the partition keys for which triples exist This allows easy listing of all of the partition keys for which triplets exist
in a bucket, as the partition key becomes the sort key in the index. in a bucket, as the partition key becomes the sort key in the index.
How indexing works: How indexing works:
@ -172,7 +174,7 @@ TO UNDERSTAND IN ORDER TO USE IT CORRECTLY.**
- **Internal server errors on updates do not mean that the update isn't stored.** - **Internal server errors on updates do not mean that the update isn't stored.**
K2V will return an internal server error when it cannot reach a quorum of nodes on K2V will return an internal server error when it cannot reach a quorum of nodes on
which to save an updated value. However the value may still be stored on just one which to save an updated value. However the value may still be stored on just one
node, which whill then propagate it to other nodes asynchronously via anti-entropy. node, which will then propagate it to other nodes asynchronously via anti-entropy.
- **Batch operations are not transactions.** When calling InsertBatch or DeleteBatch, - **Batch operations are not transactions.** When calling InsertBatch or DeleteBatch,
items may appear partially inserted/deleted while the operation is being processed. items may appear partially inserted/deleted while the operation is being processed.
@ -447,11 +449,11 @@ insert in the following format:
The causality token should be the one returned in a previous read request (e.g. The causality token should be the one returned in a previous read request (e.g.
by ReadItem or ReadBatch), to indicate that this write takes into account the by ReadItem or ReadBatch), to indicate that this write takes into account the
values that were returned from these reads, and supersedes them causally. If values that were returned from these reads, and supersedes them causally. If
the triple is inserted for the first time, the causality token should be set to the triplet is inserted for the first time, the causality token should be set to
`null`. `null`.
The value is expected to be a base64-encoded binary blob. The value `null` can The value is expected to be a base64-encoded binary blob. The value `null` can
also be used to delete the triple while preserving causality information: this also be used to delete the triplet while preserving causality information: this
allows to know if a delete has happenned concurrently with an insert, in which allows to know if a delete has happenned concurrently with an insert, in which
case both are preserved and returned on reads (see below). case both are preserved and returned on reads (see below).
@ -507,7 +509,7 @@ control additional filters on the items that are returned.
The result is a list of length the number of searches, that consists in for The result is a list of length the number of searches, that consists in for
each search a JSON object specified similarly to the result of ReadIndex, but each search a JSON object specified similarly to the result of ReadIndex, but
that lists triples within a partition key. that lists triplets within a partition key.
The format of returned tuples is as follows: `{ sk: "<sort key>", ct: "<causality The format of returned tuples is as follows: `{ sk: "<sort key>", ct: "<causality
token>", v: ["<value1>", ...] }`, with the following fields: token>", v: ["<value1>", ...] }`, with the following fields: