Client objects¶

Client-level Operations¶

Some operations are not scoped by buckets or bucket types and can be performed on the client directly:

Accessing Bucket Types and Buckets¶

Most client operations are on bucket type objects, the bucket objects they contain or keys within those buckets. Use the bucket_type or bucket methods for creating bucket types and buckets that will proxy operations to the called client.

Bucket Type Operations¶

Bucket Operations¶

Key-level Operations¶

Serialization¶

The client supports automatic transformation of Riak responses into Python types if encoders and decoders are registered for the media-types. Supported by default are application/json and text/plain.

Bucket objects¶

Bucket properties¶

Bucket properties are flags and defaults that apply to all keys in the bucket.

Working with keys¶

The primary purpose of buckets is to act as namespaces for keys. As such, you can use the bucket object to create, fetch and delete objects.

Serialization¶

Similar to RiakClient, buckets can register custom transformation functions for media-types. When undefined on the bucket, Bucket.get_encoder() and Bucket.get_decoder() will delegate to the client associated with the bucket.

Listing keys¶

Shortcuts for RiakClient.get_keys() are exposed on the bucket object. The same admonitions for these operation apply.

Bucket Type objects¶

Bucket Type properties¶

Bucket Type properties are flags and defaults that apply to all buckets in the Bucket Type.

BucketType.datatype¶

The assigned datatype for this bucket type, if present.

Listing buckets¶

Shortcut for RiakClient.get_buckets() is exposed on the bucket type object. This is similar to Listing keys on buckets.

RiakObject¶

Persistence¶

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

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:

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.

You do not typically have to create RiakContent objects yourself, but they will be created for you when fetching objects from Riak.

Sending Operations¶

Riak Data Types provide a further departure from Riak’s usual operation, in that the API is operation-based. Rather than fetching the data structure, reconciling conflicts, mutating the result, and writing it back, you instead tell Riak what operations to perform on the Data Type. Here are some example operations:

• increment a Counter by 10
• add 'joe' to a Set
• remove the Set field called 'friends' from a Map
• enable the prepay Flag in a Map

Datatypes can be fetched and created just like RiakObject instances, using Bucket.get and Bucket.new, except that the bucket must belong to a bucket-type that has a valid datatype property. If we have a bucket-type named “social-graph” that has the datatype “set”, we would fetch a Set like so:

graph = client.bucket_type('social-graph')
graph.datatype  # => 'set'
backet = graph.bucket('followers')
myfollowers = await bucket.get('seancribbs')
# => a Set datatype

Once we have a datatype, we can stage operations against it and then send those operations to Riak:

myfollowers.add('javajolt')
myfollowers.discard('roach')
await myfollowers.update()

While this looks in code very similar to manipulating RiakObject instances, only mutations are enqueued locally, not the new value.

Context and Observed-Remove¶

In order for Riak Data Types to behave well, you must have an opaque context received from a read when you:

• disable a Flag (set it to false)
• remove a field from a Map
• remove an element from a Set

The basic rule is “you cannot remove something you haven’t seen”, and the context tells Riak what you’ve actually seen, similar to the Vector clock on RiakObject. The Python client handles opaque contexts for you transparently as long as you fetch before performing one of these actions.

Datatype abstract class¶

Counter¶

Counter.value¶

The current value of the counter.

Set¶

Set.value¶

An immutable copy (frozenset) of the current value of the set.

Map¶

Map.counters¶

Filters keys in the map to only those of counter types. Example:

map.counters['views'].increment()
del map.counters['points']

Map.flags¶

Filters keys in the map to only those of flag types. Example:

map.flags['confirmed'].enable()
del map.flags['attending']

Map.maps¶

Filters keys in the map to only those of map types. Example:

map.maps['emails'].registers['home'].set("user@example.com")
del map.maps['spam']

Map.registers¶

Filters keys in the map to only those of register types. Example:

map.registers['username'].set_value("riak-user")
del map.registers['access_key']

Map.sets¶

Filters keys in the map to only those of set types. Example:

map.sets['friends'].add("brett")
del map.sets['favorites']

Map-only datatypes¶

Two of the new Data Types may only be embedded in Map objects (in addition to Map itself):

Register¶

Flag¶

Flag.value¶

The current value of the flag.