Class: Riak::Bucket

Inherits:
Object show all
Includes:
Util::String, Util::Translation
Defined in:
lib/riak/bucket.rb

Overview

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.

Direct Known Subclasses

Riak::BucketTyped::Bucket

Constant Summary collapse

SEARCH_PRECOMMIT_HOOK =

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

{"mod" => "riak_search_kv_hook", "fun" => "precommit"}

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Util::Translation

#i18n_scope, #t

Methods included from Util::String

equal_bytes?

Constructor Details

#initialize(client, name) ⇒ Bucket

Create a Riak bucket manually.

Parameters:

Raises:

  • (ArgumentError) 


27
28
29
30
31
32
 
# 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

Instance Attribute Details

#client ⇒ Riak::Client (readonly)

Returns the associated client.

Returns:



19
20
21
 
# File 'lib/riak/bucket.rb', line 19

def client
  @client
end

#name ⇒ String (readonly)

Returns the bucket name.

Returns:

  • (String) —

    the bucket name



22
23
24
 
# File 'lib/riak/bucket.rb', line 22

def name
  @name
end

Instance Method Details

#==(other) ⇒ true, false

Returns whether the other is equivalent.

Returns:

  • (true, false) —

    whether the other is equivalent



296
297
298
299
300
 
# 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

#allow_mult ⇒ true, false

Returns whether the bucket allows divergent siblings.

Returns:

  • (true, false) —

    whether the bucket allows divergent siblings



206
207
208
 
# File 'lib/riak/bucket.rb', line 206

def allow_mult
  props['allow_mult']
end

#allow_mult=(value) ⇒ Object

Set the allow_mult property. NOTE This will result in a PUT request to Riak.

Parameters:

  • value (true, false) —

    whether the bucket should allow siblings



213
214
215
216
 
# File 'lib/riak/bucket.rb', line 213

def allow_mult=(value)
  self.props = {'allow_mult' => value}
  value
end

#clear_props ⇒ true, false Also known as: clear_properties

Clears bucket properties, reverting them to the defaults.

Returns:

  • (true, false) —

    whether the properties were cleared

Since:

  • Riak 1.3



93
94
95
96
 
# File 'lib/riak/bucket.rb', line 93

def clear_props
  @props = nil
  @client.clear_bucket_props(self)
end

#counter(key) ⇒ Counter

Gets a counter object. Counters initially hvae a value of zero, and can be incremented and decremented by integer values.

Parameters:

  • key (String) —

    the key of the counter to fetch

Returns:



153
154
155
 
# File 'lib/riak/bucket.rb', line 153

def counter(key)
  Riak::Counter.new self, key
end

#delete(key, options = {}) ⇒ Object

Deletes a key from the bucket

Parameters:

  • key (String) —

    the key to delete

  • options (Hash) (defaults to: {}) —

    quorum options

Options Hash (options):

  • :rw (Fixnum) —

    • the read/write quorum for the

    delete

  • :vclock (String) —

    • the causal context/vector clock of the

    object being deleted



180
181
182
 
# File 'lib/riak/bucket.rb', line 180

def delete(key, options = {})
  client.delete_object(self, key, options)
end

#disable_index! ⇒ Object

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



256
257
258
259
260
261
262
263
 
# 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! ⇒ Object

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



245
246
247
248
249
250
251
252
 
# 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

#exists?(key, options = {}) ⇒ true, false Also known as: exist?

Checks whether an object exists in Riak.

Parameters:

  • key (String) —

    the key to check

  • options (Hash) (defaults to: {}) —

    quorum options

Options Hash (options):

  • :r (Fixnum) —

    • the read quorum value for the request ®

Returns:

  • (true, false) —

    whether the key exists in this bucket



162
163
164
165
166
167
168
169
170
 
# 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

#get(key, options = {}) ⇒ Riak::RObject Also known as: []

Retrieve an object from within the bucket.

Parameters:

  • key (String) —

    the key of the object to retrieve

  • options (Hash) (defaults to: {}) —

    query parameters for the request

Options Hash (options):

  • :r (Fixnum) —

    • the read quorum for the request - how many

    nodes should concur on the read

Returns:

Raises:

  • (FailedRequest) —

    if the object is not found or some other error occurs



107
108
109
 
# File 'lib/riak/bucket.rb', line 107

def get(key, options = {})
  @client.get_object(self, key, options)
end

#get_index(index, query, options = {}) ⇒ Array<String>

Note:

This will only work if your Riak installation supports 2I.

Queries a secondary index on the bucket.

Parameters:

  • index (String) —

    the name of the index

  • query (String, Integer, Range) —

    the value of the index, or a Range of values to query

Returns:

  • (Array<String>) —

    a list of keys that match the index query



191
192
193
 
# File 'lib/riak/bucket.rb', line 191

def get_index(index, query, options = {})
  client.get_index(self, index, query, options)
end

#get_many(keys) ⇒ Hash<String, Riak::RObject>

Retrieve multiple keys from this bucket.

Parameters:

Returns:



115
116
117
118
119
120
121
122
 
# 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 = {}) ⇒ RObject

Fetches an object if it exists, otherwise creates a new one with the given key

Parameters:

  • key (String) —

    the key to fetch or create

Returns:

  • (RObject) —

    the new or existing object



137
138
139
140
141
142
143
144
145
146
147
 
# 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 = { }) ⇒ Array<PreflistItem>

Retrieves a preflist for the given key; useful for figuring out where in the cluster an object is stored.

Parameters:

Returns:



200
201
202
203
 
# 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 ⇒ String

Returns a representation suitable for IRB and debugging output.

Returns:

  • (String) —

    a representation suitable for IRB and debugging output



276
277
278
 
# File 'lib/riak/bucket.rb', line 276

def inspect
  "#<Riak::Bucket {#{name}}>"
end

#is_indexed? ⇒ true, false

(Riak Search) Detects whether the bucket is automatically indexed into riak_search.

Returns:

  • (true, false) —

    whether the bucket includes the search indexing hook



268
269
270
271
272
273
 
# 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 = {}) {|Array<String>| ... } ⇒ Array<String>

Note:

This operation has serious performance implications and should not be used in production applications.

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.

Yields:

  • (Array<String>) —

    a list of keys from the current chunk

Returns:



46
47
48
49
50
51
52
53
 
# 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_value ⇒ Fixnum Also known as: n_val

Returns the N value, or number of replicas for this bucket.

Returns:

  • (Fixnum) —

    the N value, or number of replicas for this bucket



219
220
221
 
# File 'lib/riak/bucket.rb', line 219

def n_value
  props['n_val']
end

#n_value=(value) ⇒ Object Also known as: n_val=

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.

Parameters:

  • value (Fixnum) —

    the number of replicas the bucket should keep of each object



229
230
231
232
 
# File 'lib/riak/bucket.rb', line 229

def n_value=(value)
  self.props = {'n_val' => value}
  value
end

#needs_type? ⇒ Boolean

Does this Riak::Bucket have a non-default bucket type? Riak::BucketTyped::Bucket instances with non-default types return ‘true`.

Returns:

  • (Boolean) —

    false



291
292
293
 
# File 'lib/riak/bucket.rb', line 291

def needs_type?
  false
end

#new(key = nil) ⇒ RObject

Create a new blank object

Parameters:

  • key (String) (defaults to: nil) —

    the key of the new object

Returns:

  • (RObject) —

    the new, unsaved object



127
128
129
130
131
 
# 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) ⇒ Object

Pretty prints the bucket for ‘pp` or `pry`.



281
282
283
284
285
286
 
# File 'lib/riak/bucket.rb', line 281

def pretty_print(pp)
  pp.object_group self do
    pp.breakable
    pp.text "name=#{name}"
  end
end

#props ⇒ Hash Also known as: properties

Returns Internal Riak bucket properties.

Returns:

  • (Hash) —

    Internal Riak bucket properties.

See Also:



85
86
87
 
# File 'lib/riak/bucket.rb', line 85

def props
  @props ||= @client.get_bucket_props(self)
end

#props=(properties) ⇒ Hash Also known as: properties=

Sets internal properties on the bucket Note: this results in a request to the Riak server! symbolic) symbolic) (numeric or symbolic) symbolic)

Parameters:

  • properties (Hash) —

    new properties for the bucket

Options Hash (properties):

  • :n_val (Fixnum) — default: 3 —

    The N value (replication factor)

  • :allow_mult (true, false) — default: false —

    Whether to permit object siblings

  • :last_write_wins (true, false) — default: false —

    Whether to ignore causal context in regular key-value buckets

  • :precommit (Array<Hash>) — default: [] —

    precommit hooks

  • :postcommit (Array<Hash>) — default: [] —

    postcommit hooks

  • :r (Fixnum, String) — default: "quorum" —

    read quorum (numeric or

  • :w (Fixnum, String) — default: "quorum" —

    write quorum (numeric or

  • :dw (Fixnum, String) — default: "quorum" —

    durable write quorum

  • :rw (Fixnum, String) — default: "quorum" —

    delete quorum (numeric or

Returns:

  • (Hash) —

    the merged bucket properties

Raises:

  • (FailedRequest) —

    if the new properties were not accepted by the Riakserver

See Also:

  • #allow_mult, #r, #w, #dw, #rw


75
76
77
78
79
80
 
# 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