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 riak

client = riak.RiakClient()
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 riak.bucket.RiakBucket(client, name, bucket_type)

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

Returns a new RiakBucket instance.

Parameters:
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.

RiakBucket.get_properties()

Retrieve a dict of all bucket properties.

Return type:dict
RiakBucket.set_properties(props)

Set multiple bucket properties in one call.

Parameters:props (dict) – A dictionary of properties
RiakBucket.clear_properties()

Reset all bucket properties to their defaults.

RiakBucket.get_property(key)

Retrieve a bucket property.

Parameters:key (string) – The property to retrieve.
Return type:mixed
RiakBucket.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 RiakBucket.get_property() and RiakBucket.set_property() respectively.

RiakBucket.n_val

N-value for this bucket, which is the number of replicas that will be written of each object in the bucket.

Warning

Set this once before you write any data to the bucket, and never change it again, otherwise unpredictable things could happen. This should only be used if you know what you are doing.

RiakBucket.allow_mult

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

RiakBucket.r

The default ‘read’ quorum for this bucket (how many replicas must reply for a successful read). This should be an integer less than the ‘n_val’ property, or a string of ‘one’, ‘quorum’, ‘all’, or ‘default’

RiakBucket.pr

The default ‘primary read’ quorum for this bucket (how many primary replicas are required for a successful read). This should be an integer less than the ‘n_val’ property, or a string of ‘one’, ‘quorum’, ‘all’, or ‘default’

RiakBucket.w

The default ‘write’ quorum for this bucket (how many replicas must acknowledge receipt of a write). This should be an integer less than the ‘n_val’ property, or a string of ‘one’, ‘quorum’, ‘all’, or ‘default’

RiakBucket.dw

The default ‘durable write’ quorum for this bucket (how many replicas must commit the write). This should be an integer less than the ‘n_val’ property, or a string of ‘one’, ‘quorum’, ‘all’, or ‘default’

RiakBucket.pw

The default ‘primary write’ quorum for this bucket (how many primary replicas are required for a successful write). This should be an integer less than the ‘n_val’ property, or a string of ‘one’, ‘quorum’, ‘all’, or ‘default’

RiakBucket.rw

The default ‘read’ and ‘write’ quorum for this bucket (equivalent to ‘r’ and ‘w’ but for deletes). This should be an integer less than the ‘n_val’ property, or a string of ‘one’, ‘quorum’, ‘all’, or ‘default’

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.

RiakBucket.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:
Return type:

RiakObject or Datatype
RiakBucket.new_from_file(key, filename)

Create a new Riak object in the bucket, using the contents of the specified file. This is a shortcut for new(), where the encoded_data and content_type are set for you.

Warning

This is not supported for buckets that contain Datatypes.

Parameters:
  • key (string) – the key of the new object
  • filename (string) – the file to read the contents from
Return type:

RiakObject
RiakBucket.get(key, r=None, pr=None, timeout=None, include_context=None, basic_quorum=None, notfound_ok=None, head_only=False)

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

Parameters:
  • key (string) – Name of the key.
  • r (integer) – R-Value of the request (defaults to bucket’s R)
  • pr (integer) – PR-Value of the request (defaults to bucket’s PR)
  • timeout (int) – a timeout value in milliseconds
  • include_context (bool) – if the bucket contains datatypes, include the opaque context in the result
  • basic_quorum (bool) – whether to use the “basic quorum” policy for not-founds
  • notfound_ok (bool) – whether to treat not-found responses as successful
  • head_only (bool) – whether to fetch without value, so only metadata (only available on PB transport)
Return type:

RiakObject or Datatype
RiakBucket.multiget(keys, r=None, pr=None, timeout=None, basic_quorum=None, notfound_ok=None, head_only=False)

Retrieves a list of keys belonging to this bucket in parallel.

Parameters:
  • keys (list) – the keys to fetch
  • r (integer) – R-Value for the requests (defaults to bucket’s R)
  • pr (integer) – PR-Value for the requests (defaults to bucket’s PR)
  • 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
  • head_only (bool) – whether to fetch without value, so only metadata (only available on PB transport)
Return type:

list of RiakObjects, Datatypes, or tuples of bucket_type, bucket, key, and the exception raised on fetch
RiakBucket.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

Query operations

RiakBucket.search(query, index=None, **params)

Queries a search index over objects in this bucket/index. See RiakClient.fulltext_search() for more details.

Parameters:
  • query (string) – the search query
  • index (string or None) – the index to search over. Defaults to the bucket’s name.
  • params (dict) – additional query flags
RiakBucket.get_index(index, startkey, endkey=None, return_terms=None, max_results=None, continuation=None, timeout=None, term_regex=None)

Queries a secondary index over objects in this bucket, returning keys or index/key pairs. See RiakClient.get_index() for more details.

RiakBucket.stream_index(index, startkey, endkey=None, return_terms=None, max_results=None, continuation=None, timeout=None, term_regex=None)

Queries a secondary index over objects in this bucket, streaming keys or index/key pairs via an iterator. The caller must close the stream when finished. See RiakClient.stream_index() for more details.

RiakBucket.paginate_index(index, startkey, endkey=None, return_terms=None, max_results=1000, continuation=None, timeout=None, term_regex=None)

Paginates through a secondary index over objects in this bucket, returning keys or index/key pairs. See RiakClient.paginate_index() for more details.

RiakBucket.paginate_stream_index(index, startkey, endkey=None, return_terms=None, max_results=1000, continuation=None, timeout=None, term_regex=None)

Paginates through a secondary index over objects in this bucket, streaming keys or index/key pairs. The caller must close the stream when finished. See RiakClient.paginate_stream_index() for more details.

Serialization

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

RiakBucket.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
RiakBucket.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.
RiakBucket.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
RiakBucket.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() and RiakClient.stream_keys() are exposed on the bucket object. The same admonitions for these operations apply.

RiakBucket.get_keys()

Return all keys within the bucket.

Return type:list of keys
RiakBucket.stream_keys()

Streams all keys within the bucket through an iterator.

The caller must close the stream when finished. See RiakClient.stream_keys() for more details.

Return type:iterator

Bucket Type objects

class riak.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.

Returns a new BucketType instance.

Parameters:
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:RiakBucket

Bucket Type properties

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

BucketType.get_properties()

Retrieve a dict of all bucket-type properties.

Return type:dict
BucketType.set_properties(props)

Set multiple bucket-type properties in one call.

Parameters:props (dict) – A dictionary of properties
BucketType.get_property(key)

Retrieve a bucket-type property.

Parameters:key (string) – The property to retrieve.
Return type:mixed
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.

Return type:None or str

Listing buckets

Shortcuts for RiakClient.get_buckets() and RiakClient.stream_buckets() are exposed on the bucket type object. This is similar to Listing keys on buckets.

BucketType.get_buckets(timeout=None)

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

Warning

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

Note

This request is automatically retried retries times if it fails due to network error.

Parameters:timeout (int) – a timeout value in milliseconds
Return type:list of RiakBucket instances
BucketType.stream_buckets(timeout=None)

Streams the list of buckets under this bucket-type. This is a generator method that should be iterated over.

The caller must close the stream when finished. See RiakClient.stream_buckets() for more details.

Warning

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

Parameters:timeout (int) – a timeout value in milliseconds
Return type:iterator that yields lists of RiakBucket instances

Deprecated Features

Shortcuts for Riak Search 1.0

When Riak Search 1.0 is enabled on the server, you can toggle which buckets have automatic indexing turned on using the search bucket property (and on older versions, the precommit property). These methods simplify interacting with that configuration.

RiakBucket.search_enabled()

Returns True if search indexing is enabled for this bucket.

Deprecated since version 2.1.0: (Riak 2.0) Use Riak Search 2.0 instead.

Enable search indexing for this bucket.

Deprecated since version 2.1.0: (Riak 2.0) Use Riak Search 2.0 instead.

Disable search indexing for this bucket.

Deprecated since version 2.1.0: (Riak 2.0) Use Riak Search 2.0 instead.

Legacy Counters

The get_counter() and update_counter(). See Legacy Counters for more details.

Warning

Legacy counters are incompatible with Bucket Types.

RiakBucket.get_counter(key, **kwargs)

Gets the value of a counter stored in this bucket. See RiakClient.get_counter() for options.

Deprecated since version 2.1.0: (Riak 2.0) Riak 1.4-style counters are deprecated in favor of the Counter datatype.

Parameters:key (string) – the key of the counter
Return type:int
RiakBucket.update_counter(key, value, **kwargs)

Updates the value of a counter stored in this bucket. Positive values increment the counter, negative values decrement. See RiakClient.update_counter() for options.

Deprecated since version 2.1.0: (Riak 2.0) Riak 1.4-style counters are deprecated in favor of the Counter datatype.

Parameters:
  • key (string) – the key of the counter
  • value (integer) – the amount to increment or decrement