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 aioriak.riak_object.RiakObject(client, bucket, key=None)[source]

The RiakObject holds meta information about a Riak object, plus the object’s data.

key

The key of this object, a string. If not present, the server will generate a key the first time this object is stored.

bucket

The bucket to which this object belongs.

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.

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.

Persistence

Fetching, storing, and deleting keys are the bread-and-butter of Riak.

coroutine RiakObject.store(return_body=True)[source]

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:return_body (bool) – if the newly stored object should be retrieved
Return type:RiakObject
coroutine RiakObject.reload()[source]

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 the exists property to see if the key was found.

Return type:RiakObject
coroutine RiakObject.delete()[source]

Delete this object from Riak.

Return type:RiakObject

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.usermeta

Arbitrary user-defined metadata dict, mapping strings to strings.

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

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 Persistence methods and attributes as the parent object.

RiakObject.siblings = []
class aioriak.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)[source]

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 Persistence 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)[source]

The default conflict-resolution function, which does nothing. To implement a resolver, define a function that sets the siblings property on the passed RiakObject instance to a list containing a single RiakContent object.

Parameters:riak_object (RiakObject) – an object-in-conflict that will be resolved
riak.resolver.last_written_resolver(riak_object)[source]

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 Persistence will result in a ConflictError being raised.

exception aioriak.error.ConflictError(message='Object in conflict')[source]

Raised when an operation is attempted on a RiakObject that has more than one sibling.