Buckets & Bucket Types

Buckets are both namespaces for the key-value pairs you store in Riak, and containers for properties that apply to that namespace. In older versions of Riak, this was the only logical organization available. Now a higher-level collection called a Bucket Type can group buckets together. They allow for efficiently setting properties on a group of buckets at the same time.

Unlike buckets, Bucket Types must be explicitly created and activated before being used:

riak-admin bucket-type create n_equals_1 '{"props":{"n_val":1}}'
riak-admin bucket-type activate n_equals_1

Bucket Type creation and activation is only supported via the riak-admin bucket-type command-line tool. Riak 2.0 does not include an API to perform these actions, but the Python client can retrieve and set bucket-type properties.

If Bucket Types are not specified, the default bucket type is used. These buckets should be created via the bucket() method on the client object, like so:

import aioriak

async def go():
    client = await aioriak.RiakClient.create()
    mybucket = client.bucket('mybucket')

Buckets with a user-specified Bucket Type can also be created via the same bucket() method with an additional parameter or explicitly via bucket_type():

othertype = client.bucket_type('othertype')
otherbucket = othertype.bucket('otherbucket')

# Alternate way to get a bucket within a bucket-type
mybucket = client.bucket('mybucket', bucket_type='mybuckettype')

For more detailed discussion, see Using Bucket Types.

Bucket objects

class aioriak.bucket.Bucket(client, name, bucket_type)

The Bucket object allows you to access and change information about a Riak bucket, and provides async methods to create or retrieve objects within the bucket.

__init__(client, name, bucket_type)

Returns a new Bucket instance.

Parameters:

• client (RiakClient) – A RiakClient instance
• name (string) – The bucket name
• bucket_type (BucketType) – The parent bucket type of this bucket

name

The name of the bucket, a string.

bucket_type

The parent BucketType for the bucket.

resolver

The sibling-resolution function for this bucket. If the resolver is not set, the client’s resolver will be used.

Bucket properties

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

coroutine Bucket.get_properties()

Retrieve a dict of all bucket properties.

Return type:dict

coroutine Bucket.set_properties(props)

Set multiple bucket properties in one call.

Parameters:props (dict) – A dictionary of properties

coroutine Bucket.get_property(key)

Retrieve a bucket property.

Parameters:key (string) – The property to retrieve. Return type:mixed

coroutine Bucket.set_property(key, value)

Set a bucket property.

Parameters:

• key (string) – Property to set.
• value (mixed) – Property value.

Shortcuts for common properties

Some of the most commonly-used bucket properties are exposed as object properties as well. The getters and setters simply call Bucket.get_property() and Bucket.set_property() respectively.

Bucket.allow_mult

If set to True, then writes with conflicting data will be stored and returned to the client. :type bool: boolean

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.

coroutine Bucket.new(key=None, data=None, content_type='application/json', encoded_data=None)

A shortcut for manually instantiating a new RiakObject or a new Datatype, based on the presence and value of the datatype bucket property. When the bucket contains a Datatype, all arguments are ignored except key, otherwise they are used to initialize the RiakObject.

Parameters:

• key (str) – Name of the key. Leaving this to be None (default) will make Riak generate the key on store.
• data (object) – The data to store in a RiakObject, see RiakObject.data.
• content_type (str) – The media type of the data stored in the RiakObject, see RiakObject.content_type.
• encoded_data (str) – The encoded data to store in a RiakObject, see RiakObject.encoded_data.

Return type:

RiakObject or Datatype

coroutine Bucket.get(key)

Retrieve an RiakObject or Datatype, based on the presence and value of the datatype bucket property.

Parameters:key (string) – Name of the key. Return type:RiakObject or Datatype

coroutine Bucket.delete(key, **kwargs)

Deletes a key from Riak. Short hand for bucket.new(key).delete(). See RiakClient.delete() for options.

Parameters:key (string) – The key for the object Return type:RiakObject

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.

Bucket.get_encoder(content_type)

Get the encoding function for the provided content type for this bucket.

Parameters:

• content_type (str) – the requested media type
• content_type – Content type requested

Bucket.set_encoder(content_type, encoder)

Set the encoding function for the provided content type for this bucket.

Parameters:

• content_type (str) – the requested media type
• encoder (function) – an encoding function, takes a single object argument and returns a string data as single argument.

Bucket.get_decoder(content_type)

Get the decoding function for the provided content type for this bucket.

Parameters:content_type (str) – the requested media type Return type:function

Bucket.set_decoder(content_type, decoder)

Set the decoding function for the provided content type for this bucket.

Parameters:

• content_type (str) – the requested media type
• decoder (function) – a decoding function, takes a string and returns a Python type

Listing keys

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

coroutine Bucket.get_keys()

Return all keys within the bucket.

Return type:list of keys

Bucket Type objects

class aioriak.bucket.BucketType(client, name)

The BucketType object allows you to access and change properties on a Riak bucket type and access buckets within its namespace.

Async implementation of riak.bucket.BucketType

__init__(client, name)

Returns a new BucketType instance.

Parameters:

• client (RiakClient) – A RiakClient instance
• name (string) – The bucket-type’s name

name

The name of the Bucket Type, a string.

BucketType.is_default()

Whether this bucket type is the default type, or a user-defined type.

Return type:bool

BucketType.bucket(name)

Gets a bucket that belongs to this bucket-type.

Parameters:name (str) – the bucket name Return type:Bucket

Bucket Type properties

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

coroutine BucketType.get_properties()

Retrieve a dict of all bucket-type properties.

Return type:dict

coroutine BucketType.set_properties(props)

Set multiple bucket-type properties in one call.

Parameters:props (dict) – A dictionary of properties

coroutine BucketType.get_property(key)

Retrieve a bucket-type property.

Parameters:key (string) – The property to retrieve. Return type:mixed

coroutine BucketType.set_property(key, value)

Set a bucket-type property.

Parameters:

• key (string) – Property to set.
• value (mixed) – Property value.

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.

coroutine BucketType.get_buckets()

Get the list of buckets under this bucket-type as Bucket instances.

Warning

Do not use this in production, as it requires traversing through all keys stored in a cluster.

Return type:list of Bucket instances