Values & Objects¶
Keys in Riak are namespaced into buckets
, and their associated values are represented
by objects
, not to be confused with Python
“objects”. A RiakObject
is a container for the key, the
Vector clock, the value(s) and any metadata associated with the
value(s).
Values may also be datatypes
, but
are not discussed here.
RiakObject¶
-
class
riak.riak_object.
RiakObject
(client, bucket, key=None)¶ The RiakObject holds meta information about a Riak object, plus the object’s data.
Construct a new RiakObject.
Parameters: - client (
RiakClient
) – A RiakClient object. - bucket (
RiakBucket
) – A RiakBucket object. - key (string) – An optional key. If not specified, then the key
is generated by the server when
store()
is called.
-
key
¶ The key of this object, a string. If not present, the server will generate a key the first time this object is stored.
-
resolver
¶ The sibling-resolution function for this object. If the resolver is not set, the bucket’s resolver will be used.
-
vclock
¶ The Vector clock for this object.
-
exists
¶ Whether the object exists. This is only
False
when there are no siblings (the object was not found), or the solitary sibling is a tombstone.
- client (
Vector clock¶
Vector clocks are Riak’s means of tracking the relationships between writes to a key. It is best practice to fetch the latest version of a key before attempting to modify or overwrite the value; if you do not, you may create Siblings or lose data! The content of a vector clock is essentially opaque to the user.
-
class
riak.riak_object.
VClock
(value, encoding)¶ A representation of a vector clock received from Riak.
Persistence¶
Fetching, storing, and deleting keys are the bread-and-butter of Riak.
-
RiakObject.
store
(w=None, dw=None, pw=None, return_body=True, if_none_match=False, timeout=None)¶ Store the object in Riak. When this operation completes, the object could contain new metadata and possibly new data if Riak contains a newer version of the object according to the object’s vector clock.
Parameters: - w (integer) – W-value, wait for this many partitions to respond before returning to client.
- dw (integer) – DW-value, wait for this many partitions to confirm the write before returning to client.
- pw (integer) – PW-value, require this many primary partitions to be available before performing the put
- return_body (bool) – if the newly stored object should be retrieved
- if_none_match (bool) – Should the object be stored only if there is no key previously defined
- timeout (int) – a timeout value in milliseconds
Return type:
-
RiakObject.
reload
(r=None, pr=None, timeout=None, basic_quorum=None, notfound_ok=None)¶ Reload the object from Riak. When this operation completes, the object could contain new metadata and a new value, if the object was updated in Riak since it was last retrieved.
Note
Even if the key is not found in Riak, this will return a
RiakObject
. Check theexists
property to see if the key was found.Parameters: - r (integer) – R-Value, wait for this many partitions to respond before returning to client.
- pr (integer) – PR-value, require this many primary partitions to be available before performing the read that precedes the put
- timeout (int) – a timeout value in milliseconds
- basic_quorum (bool) – whether to use the “basic quorum” policy for not-founds
- notfound_ok (bool) – whether to treat not-found responses as successful
Return type:
-
RiakObject.
delete
(r=None, w=None, dw=None, pr=None, pw=None, timeout=None)¶ Delete this object from Riak.
Parameters: - r (integer) – R-value, wait for this many partitions to read object before performing the put
- w (integer) – W-value, wait for this many partitions to respond before returning to client.
- dw (integer) – DW-value, wait for this many partitions to confirm the write before returning to client.
- pr (integer) – PR-value, require this many primary partitions to be available before performing the read that precedes the put
- pw (integer) – PW-value, require this many primary partitions to be available before performing the put
- timeout (int) – a timeout value in milliseconds
Return type:
Value and Metadata¶
Unless you have enabled Siblings via the allow_mult
bucket property, you can
inspect and manipulate the value and metadata of an object directly using these
properties and methods:
-
RiakObject.
data
¶ The data stored in this object, as Python objects. For the raw data, use the encoded_data property. If unset, accessing this property will result in decoding the encoded_data property into Python values. The decoding is dependent on the content_type property and the bucket’s registered decoders.
-
RiakObject.
encoded_data
¶ The raw data stored in this object, essentially the encoded form of the data property. If unset, accessing this property will result in encoding the data property into a string. The encoding is dependent on the content_type property and the bucket’s registered encoders.
-
RiakObject.
content_type
¶ The MIME media type of the encoded data as a string
-
RiakObject.
charset
¶ The character set of the encoded data as a string
-
RiakObject.
content_encoding
¶ The encoding (compression) of the encoded data. Valid values are identity, deflate, gzip
-
RiakObject.
last_modified
¶ The UNIX timestamp of the modification time of this value.
-
RiakObject.
etag
¶ A unique entity-tag for the value.
-
RiakObject.
usermeta
¶ Arbitrary user-defined metadata dict, mapping strings to strings.
-
RiakObject.
links
¶ A set of bucket/key/tag 3-tuples representing links to other keys.
-
RiakObject.
indexes
¶ The set of secondary index entries, consisting of index-name/value tuples
-
RiakObject.
add_index
(field, value)¶ Tag this object with the specified field/value pair for indexing.
Parameters: - field (string) – The index field.
- value (string or integer) – The index value.
Return type:
-
RiakObject.
remove_index
(field=None, value=None)¶ Remove the specified field/value pair as an index on this object.
Parameters: - field (string) – The index field.
- value (string or integer) – The index value.
Return type:
-
RiakObject.
set_index
(field, value)¶ Works like
add_index()
, but ensures that there is only one index on given field. If other found, then removes it first.Parameters: - field (string) – The index field.
- value (string or integer) – The index value.
Return type:
Siblings¶
Because Riak’s consistency model is “eventual” (and not linearizable), there is no way for it to disambiguate writes that happen concurrently. The Vector clock helps establish a “happens after” relationships so that concurrent writes can be detected, but with the exception of Data Types, Riak has no way to determine which write has the correct value.
Instead, when allow_mult
is True
, Riak keeps all writes that appear to be concurrent. Thus,
the contents of a key’s value may, in fact, be multiple values, which
are called “siblings”. Siblings are modeled in RiakContent
objects, which contain all of the same
Value and Metadata methods and attributes as the parent object.
-
RiakObject.
siblings
= []¶ The list of sibling values contained in this object
-
class
riak.content.
RiakContent
(robject, data=None, encoded_data=None, charset=None, content_type='application/json', content_encoding=None, last_modified=None, etag=None, usermeta=None, links=None, indexes=None, exists=False)¶ The RiakContent holds the metadata and value of a single sibling within a RiakObject. RiakObjects that have more than one sibling are considered to be in conflict.
You do not typically have to create RiakContent
objects yourself, but they will be created
for you when fetching
objects from Riak.
Note
The Value and Metadata accessors on RiakObject
are actually proxied to the first sibling when the object has only
one.
Conflicts and Resolvers¶
When an object is not in conflict, it has only one sibling. When it
is in conflict, you will have to resolve the conflict before it can be
written again. How you choose to resolve the conflict is up to you,
but you can automate the process using a resolver
function.
-
riak.resolver.
default_resolver
(riak_object)¶ The default conflict-resolution function, which does nothing. To implement a resolver, define a function that sets the
siblings
property on the passedRiakObject
instance to a list containing a singleRiakContent
object.Parameters: riak_object ( RiakObject
) – an object-in-conflict that will be resolved
-
riak.resolver.
last_written_resolver
(riak_object)¶ A conflict-resolution function that resolves by selecting the most recently-modified sibling by timestamp.
Parameters: riak_object ( RiakObject
) – an object-in-conflict that will be resolved
If you do not supply a resolver function, or your resolver leaves
multiple siblings present, accessing the Value and Metadata will
result in a ConflictError
being raised.
-
exception
riak.
ConflictError
(message='Object in conflict')¶ Raised when an operation is attempted on a
RiakObject
that has more than one sibling.