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

SEARCH_PRECOMMIT_HOOK

(Riak Search) The precommit specification for kv/search integration

Attributes

client[R]

@return [Riak::Client] the associated client

name[R]

@return [String] the bucket name

Public Class Methods

new(client, name) click to toggle source

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

==(other) click to toggle source

@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
[](key, options = {})
Alias for: get
allow_mult() click to toggle source

@return [true, false] whether the bucket allows divergent siblings

# File lib/riak/bucket.rb, line 206
def allow_mult
  props['allow_mult']
end
allow_mult=(value) click to toggle source

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
clear_properties()
Alias for: clear_props
clear_props() click to toggle source

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
Also aliased as: clear_properties
counter(key) click to toggle source

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
delete(key, options = {}) click to toggle source

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
disable_index!() click to toggle source

(Riak Search) Removes the precommit hook that automatically indexes objects into riak_search.

# File lib/riak/bucket.rb, line 256
def disable_index!
  if is_indexed?
    self.props = {
      "precommit" => (props['precommit'] - [SEARCH_PRECOMMIT_HOOK]),
      "search" => false
    }
  end
end
enable_index!() click to toggle source

(Riak Search) Installs a precommit hook that automatically indexes objects into riak_search.

# File lib/riak/bucket.rb, line 245
def enable_index!
  unless is_indexed?
    self.props = {
      "precommit" => (props['precommit'] + [SEARCH_PRECOMMIT_HOOK]),
      "search" => true
    }
  end
end
exist?(key, options = {})
Alias for: exists?
exists?(key, options = {}) click to toggle source

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
Also aliased as: exist?
get(key, options = {}) click to toggle source

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
Also aliased as: []
get_index(index, query, options = {}) click to toggle source

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
get_many(keys) click to toggle source

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
get_or_new(key, options = {}) click to toggle source

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
get_preflist(key, options = { }) click to toggle source

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
inspect() click to toggle source

@return [String] a representation suitable for IRB and debugging output

# File lib/riak/bucket.rb, line 276
def inspect
  "#<Riak::Bucket {#{name}}>"
end
is_indexed?() click to toggle source

(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
keys(options = {}, &block) click to toggle source

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
n_val()
Alias for: n_value
n_value() click to toggle source

@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
Also aliased as: n_val
n_value=(value) click to toggle source

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
needs_type?() click to toggle source

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
new(key = nil) click to toggle source

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_print(pp) click to toggle source

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
properties()
Alias for: props
props() click to toggle source

@return [Hash] Internal Riak bucket properties. @see props=

# File lib/riak/bucket.rb, line 85
def props
  @props ||= @client.get_bucket_props(self)
end
Also aliased as: properties
props=(properties) click to toggle source

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