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: - client (
RiakClient
) – ARiakClient
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.
- client (
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 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:
-
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 theencoded_data
andcontent_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:
-
RiakBucket.
get
(key, r=None, pr=None, timeout=None, include_context=None, basic_quorum=None, notfound_ok=None)¶ Retrieve a
RiakObject
orDatatype
, based on the presence and value of thedatatype
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
Return type:
-
RiakBucket.
multiget
(keys, r=None, pr=None, timeout=None, basic_quorum=None, notfound_ok=None)¶ 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
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()
. SeeRiakClient.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: - client (
RiakClient
) – ARiakClient
instance - name (string) – The bucket-type’s name
-
name
¶ The name of the Bucket Type, a string.
- client (
-
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.
-
RiakBucket.
enable_search
()¶ Enable search indexing for this bucket.
Deprecated since version 2.1.0: (Riak 2.0) Use Riak Search 2.0 instead.
-
RiakBucket.
disable_search
()¶ 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