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)[source]¶ 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)[source]¶ Returns a new
Bucket
instance.Parameters: - client (
RiakClient
) – ARiakClient
instance - name (string) – The bucket name
- bucket_type (
BucketType
) – The parent bucket type of this bucket
- client (
-
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
()[source]¶ Retrieve a dict of all bucket properties.
Return type: dict
-
coroutine
Bucket.
set_properties
(props)[source]¶ Set multiple bucket properties in one call.
Parameters: props (dict) – A dictionary of properties
-
coroutine
Bucket.
get_property
(key)[source]¶ Retrieve a bucket property.
Parameters: key (string) – The property to retrieve. Return type: mixed
-
coroutine
Bucket.
set_property
(key, value)[source]¶ 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)[source]¶ A shortcut for manually instantiating a new
RiakObject
or a newDatatype
, based on the presence and value of thedatatype
bucket property. When the bucket contains aDatatype
, all arguments are ignored exceptkey
, otherwise they are used to initialize theRiakObject
.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
, seeRiakObject.data
. - content_type (str) – The media type of the data stored in the
RiakObject
, seeRiakObject.content_type
. - encoded_data (str) – The encoded data to store in a
RiakObject
, seeRiakObject.encoded_data
.
Return type:
-
coroutine
Bucket.
get
(key)[source]¶ Retrieve an
RiakObject
orDatatype
, based on the presence and value of thedatatype
bucket property.Parameters: key (string) – Name of the key. Return type: RiakObject
orDatatype
-
coroutine
Bucket.
delete
(key, **kwargs)[source]¶ Deletes a key from Riak. Short hand for
bucket.new(key).delete()
. SeeRiakClient.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)[source]¶ 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)[source]¶ 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.
Listing keys¶
Shortcuts for RiakClient.get_keys()
are exposed on the bucket
object. The same admonitions for these operation apply.
Bucket Type objects¶
-
class
aioriak.bucket.
BucketType
(client, name)[source]¶ 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)[source]¶ Returns a new
BucketType
instance.Parameters: - client (
RiakClient
) – ARiakClient
instance - name (string) – The bucket-type’s name
- client (
-
name
¶ The name of the Bucket Type, a string.
-
Bucket Type properties¶
Bucket Type properties are flags and defaults that apply to all buckets in the Bucket Type.
-
coroutine
BucketType.
get_properties
()[source]¶ Retrieve a dict of all bucket-type properties.
Return type: dict
-
coroutine
BucketType.
set_properties
(props)[source]¶ Set multiple bucket-type properties in one call.
Parameters: props (dict) – A dictionary of properties
-
coroutine
BucketType.
get_property
(key)[source]¶ Retrieve a bucket-type property.
Parameters: key (string) – The property to retrieve. Return type: mixed
-
coroutine
BucketType.
set_property
(key, value)[source]¶ 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.