class Riak::Bucket
Represents and encapsulates operations on a Riak
bucket. You may retrieve a bucket using {Client#bucket}, or create it manually and retrieve its meta-information later.
Constants
Attributes
@return [Riak::Client] the associated client
@return [String] the bucket name
Public Class Methods
Create a Riak
bucket manually. @param [Client] client the {Riak::Client} for this bucket @param [String] name the name of the bucket
# File lib/riak/bucket.rb, line 27 def initialize(client, name) raise ArgumentError, t('client_type', :client => client.inspect) unless Client === client raise ArgumentError, t('string_type', :string => name.inspect) unless String === name raise ArgumentError, t('zero_length_bucket') if name == '' @client, @name = client, name end
Public Instance Methods
@return [true,false] whether the other is equivalent
# File lib/riak/bucket.rb, line 296 def ==(other) return false unless self.class == other.class return false unless self.client == other.client return equal_bytes?(self.name, other.name) end
@return [true, false] whether the bucket allows divergent siblings
# File lib/riak/bucket.rb, line 206 def allow_mult props['allow_mult'] end
Set
the allow_mult
property. NOTE This will result in a PUT request to Riak
. @param [true, false] value whether the bucket should allow siblings
# File lib/riak/bucket.rb, line 213 def allow_mult=(value) self.props = {'allow_mult' => value} value end
Clears bucket properties, reverting them to the defaults. @return [true, false] whether the properties were cleared @since Riak
1.3
# File lib/riak/bucket.rb, line 93 def clear_props @props = nil @client.clear_bucket_props(self) end
Gets a counter object. Counters initially hvae a value of zero, and can be incremented and decremented by integer values. @param [String] key the key of the counter to fetch @return [Counter]
# File lib/riak/bucket.rb, line 153 def counter(key) Riak::Counter.new self, key end
Deletes a key from the bucket @param [String] key the key to delete @param [Hash] options quorum options @option options [Fixnum] :rw - the read/write quorum for the
delete
@option options [String] :vclock - the causal context/vector clock of the
object being deleted
# File lib/riak/bucket.rb, line 180 def delete(key, options = {}) client.delete_object(self, key, options) end
Checks whether an object exists in Riak
. @param [String] key the key to check @param [Hash] options quorum options @option options [Fixnum] :r - the read quorum value for the request (R) @return [true, false] whether the key exists in this bucket
# File lib/riak/bucket.rb, line 162 def exists?(key, options = {}) begin get(key, options.merge({ :head => true })) true rescue Riak::FailedRequest => e raise e unless e.not_found? false end end
Retrieve an object from within the bucket. @param [String] key the key of the object to retrieve @param [Hash] options query parameters for the request @option options [Fixnum] :r - the read quorum for the request - how many
nodes should concur on the read
@return [Riak::RObject] the object @raise [FailedRequest] if the object is not found or some other error
occurs
# File lib/riak/bucket.rb, line 107 def get(key, options = {}) @client.get_object(self, key, options) end
Queries a secondary index on the bucket. @note This will only work if your Riak
installation supports 2I. @param [String] index the name of the index @param [String,Integer,Range] query the value of the index, or a
Range of values to query
@return [Array<String>] a list of keys that match the index
query
# File lib/riak/bucket.rb, line 191 def get_index(index, query, options = {}) client.get_index(self, index, query, options) end
Retrieve multiple keys from this bucket. @param [Array<String>] keys array of keys to fetch @return [Hash<String, Riak::RObject>] hash of keys to objects
# File lib/riak/bucket.rb, line 115 def get_many(keys) pairs = keys.map{|k| [self, k]} results = Multiget.perform @client, pairs results.keys.inject(Hash.new) do |mem, var| mem[var[1]] = results[var] mem end end
Fetches an object if it exists, otherwise creates a new one with the given key @param [String] key the key to fetch or create @return [RObject] the new or existing object
# File lib/riak/bucket.rb, line 137 def get_or_new(key, options = {}) begin get(key, options) rescue Riak::FailedRequest => fr if fr.not_found? new(key) else raise fr end end end
Retrieves a preflist for the given key; useful for figuring out where in the cluster an object is stored. @param [String] key the key @return [Array<PreflistItem>] an array of preflist entries
# File lib/riak/bucket.rb, line 200 def get_preflist(key, options = { }) type = self.type.name if needs_type? client.get_preflist self, key, type, options end
@return [String] a representation suitable for IRB and debugging output
# File lib/riak/bucket.rb, line 276 def inspect "#<Riak::Bucket {#{name}}>" end
(Riak
Search
) Detects whether the bucket is automatically indexed into riak_search. @return [true,false] whether the bucket includes the search indexing hook
# File lib/riak/bucket.rb, line 268 def is_indexed? return true if props['search'] == true return true if props.has_key?('precommit') && props['precommit'].include?(SEARCH_PRECOMMIT_HOOK) false end
Retrieves a list of keys in this bucket. If a block is given, keys will be streamed through the block (useful for large buckets). When streaming, results of the operation will not be returned to the caller.
Returned keys will be in binary encoding regardless of the key's original encoding.
@yield [Array<String>] a list of keys from the current chunk @return [Array<String>] Keys in this bucket @note This operation has serious performance implications and
should not be used in production applications.
# File lib/riak/bucket.rb, line 46 def keys(options = {}, &block) warn(t('list_keys', :backtrace => caller.join("\n "))) unless Riak.disable_list_keys_warnings if block_given? @client.list_keys(self, options, &block) else @client.list_keys(self, options) end end
@return [Fixnum] the N value, or number of replicas for this bucket
# File lib/riak/bucket.rb, line 219 def n_value props['n_val'] end
Set
the N value (number of replicas). NOTE This will result in a PUT request to Riak
. Setting this value after the bucket has objects stored in it may have unpredictable results. @param [Fixnum] value the number of replicas the bucket should keep of
each object
# File lib/riak/bucket.rb, line 229 def n_value=(value) self.props = {'n_val' => value} value end
Does this {Bucket} have a non-default bucket type? {BucketTyped::Bucket} instances with non-default types return `true`. @return [Boolean] false
# File lib/riak/bucket.rb, line 291 def needs_type? false end
Create a new blank object @param [String] key the key of the new object @return [RObject] the new, unsaved object
# File lib/riak/bucket.rb, line 127 def new(key = nil) RObject.new(self, key).tap do |obj| obj.content_type = "application/json" end end
Pretty prints the bucket for `pp` or `pry`.
# File lib/riak/bucket.rb, line 281 def pretty_print(pp) pp.object_group self do pp.breakable pp.text "name=#{name}" end end
@return [Hash] Internal Riak
bucket properties. @see props=
# File lib/riak/bucket.rb, line 85 def props @props ||= @client.get_bucket_props(self) end
Sets internal properties on the bucket Note: this results in a request to the Riak
server! @param [Hash] properties new properties for the bucket @option properties [Fixnum] :n_val (3) The N value (replication factor) @option properties [true,false] :allow_mult (false) Whether to permit object siblings @option properties [true,false] :last_write_wins (false) Whether to ignore
causal context in regular key-value buckets
@option properties [Array<Hash>] :precommit ([]) precommit hooks @option properties [Array<Hash>] :postcommit ([])postcommit hooks @option properties [Fixnum,String] :r (“quorum”) read quorum (numeric or symbolic) @option properties [Fixnum,String] :w (“quorum”) write quorum (numeric or symbolic) @option properties [Fixnum,String] :dw (“quorum”) durable write quorum (numeric or symbolic) @option properties [Fixnum,String] :rw (“quorum”) delete quorum (numeric or symbolic) @return [Hash] the merged bucket properties @raise [FailedRequest] if the new properties were not accepted by the Riakserver @see n_value
, allow_mult
, r, w, dw, rw
# File lib/riak/bucket.rb, line 75 def props=(properties) raise ArgumentError, t("hash_type", :hash => properties.inspect) unless Hash === properties props.merge!(properties) @client.set_bucket_props(self, properties) props end