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.

Raises:

  • (ArgumentError) 


42
43
44
45
46
47
 
# File 'lib/riak/bucket.rb', line 42

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) 



34
35
36
 
# File 'lib/riak/bucket.rb', line 34

def client
  @client
end

#name ⇒ String (readonly) 



37
38
39
 
# File 'lib/riak/bucket.rb', line 37

def name
  @name
end

Instance Method Details

#==(other) ⇒ true, false 



315
316
317
318
319
 
# File 'lib/riak/bucket.rb', line 315

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 



225
226
227
 
# File 'lib/riak/bucket.rb', line 225

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.



232
233
234
235
 
# File 'lib/riak/bucket.rb', line 232

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.

Since:

  • Riak 1.3



111
112
113
114
 
# File 'lib/riak/bucket.rb', line 111

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.



173
174
175
 
# File 'lib/riak/bucket.rb', line 173

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

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

Deletes a key from the bucket

Options Hash (options):

  • :rw (Fixnum) —

    • the read/write quorum for the

    delete

  • :vclock (String) —

    • the causal context/vector clock of the

    object being deleted



200
201
202
 
# File 'lib/riak/bucket.rb', line 200

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.



275
276
277
278
279
280
281
282
 
# File 'lib/riak/bucket.rb', line 275

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.



264
265
266
267
268
269
270
271
 
# File 'lib/riak/bucket.rb', line 264

def enable_index!
  unless is_indexed?
    self.props = {
      "precommit" => (props['precommit'] + [SEARCH_PRECOMMIT_HOOK]),
      "search" => true
    }
  end
end

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

Check multiple keys from this bucket.



140
141
142
 
# File 'lib/riak/bucket.rb', line 140

def exist_many(keys)
  perform_multi(Multiexist, keys)
end

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

Checks whether an object exists in Riak.

Options Hash (options):

  • :r (Fixnum) —

    • the read quorum value for the request ®



182
183
184
185
186
187
188
189
190
 
# File 'lib/riak/bucket.rb', line 182

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.

Options Hash (options):

  • :r (Fixnum) —

    • the read quorum for the request - how many

    nodes should concur on the read

Raises:

  • (FailedRequest) —

    if the object is not found or some other error occurs



125
126
127
 
# File 'lib/riak/bucket.rb', line 125

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.



211
212
213
 
# File 'lib/riak/bucket.rb', line 211

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.



133
134
135
 
# File 'lib/riak/bucket.rb', line 133

def get_many(keys)
  perform_multi(Multiget, keys)
end

#get_or_new(key, options = {}) ⇒ RObject

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



157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/riak/bucket.rb', line 157

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.



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

def get_preflist(key, options = {})
  type = self.type.name if needs_type?
  client.get_preflist self, key, type, options
end

#inspect ⇒ String 



295
296
297
 
# File 'lib/riak/bucket.rb', line 295

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

#is_indexed? ⇒ true, false

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



287
288
289
290
291
292
 
# File 'lib/riak/bucket.rb', line 287

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



61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/riak/bucket.rb', line 61

def keys(options = {}, &block)
  unless Riak.disable_list_exceptions
    msg = t('list_keys', :backtrace => caller.join("\n    "))
    raise Riak::ListError.new(msg)
  end
  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 



238
239
240
 
# File 'lib/riak/bucket.rb', line 238

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.



248
249
250
251
 
# File 'lib/riak/bucket.rb', line 248

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`.



310
311
312
 
# File 'lib/riak/bucket.rb', line 310

def needs_type?
  false
end

#new(key = nil) ⇒ RObject

Create a new blank object



147
148
149
150
151
 
# File 'lib/riak/bucket.rb', line 147

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`.



300
301
302
303
304
305
 
# File 'lib/riak/bucket.rb', line 300

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.

See Also:



103
104
105
 
# File 'lib/riak/bucket.rb', line 103

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)

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

Raises:

  • (FailedRequest) —

    if the new properties were not accepted by the Riakserver

See Also:

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


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

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