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 25 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 290 def ==(other) return false unless self.class == other.class return false unless self.client == other.client return false unless self.name == other.name true end
@return [true, false] whether the bucket allows divergent siblings
# File lib/riak/bucket.rb, line 200 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 207 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 87 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 147 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 174 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 ® @return [true, false] whether the key exists in this bucket
# File lib/riak/bucket.rb, line 156 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 101 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 185 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 109 def get_many(keys) pairs = keys.map{|k| [self, k]} results = Multiget.get_all @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 131 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 194 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 270 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 262 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. @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 40 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 213 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 223 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 285 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 121 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 275 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 79 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 69 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