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) 


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)

Returns the associated client.

Returns:



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

def client
  @client
end

#name ⇒ String (readonly)

Returns the bucket name.

Returns:

  • (String) —

    the bucket name



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

def name
  @name
end

Instance Method Details

#==(other) ⇒ true, false

Returns whether the other is equivalent.

Returns:

  • (true, false) —

    whether the other is equivalent



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

Returns whether the bucket allows divergent siblings.

Returns:

  • (true, false) —

    whether the bucket allows divergent siblings



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.

Parameters:

  • value (true, false) —

    whether the bucket should allow siblings



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.

Returns:

  • (true, false) —

    whether the properties were cleared

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.

Parameters:

  • key (String) —

    the key of the counter to fetch

Returns:



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

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



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.

Parameters:

Returns:



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.

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



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.

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



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.

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



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.

Parameters:

Returns:



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

Parameters:

  • key (String) —

    the key to fetch or create

Returns:

  • (RObject) —

    the new or existing object



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.

Parameters:

Returns:



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

Returns a representation suitable for IRB and debugging output.

Returns:

  • (String) —

    a representation suitable for IRB and debugging output



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.

Returns:

  • (true, false) —

    whether the bucket includes the search indexing hook



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

Returns:



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

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

Returns:

  • (Fixnum) —

    the N value, or number of replicas for this bucket



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.

Parameters:

  • value (Fixnum) —

    the number of replicas the bucket should keep of each object



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

Returns:

  • (Boolean) —

    false



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

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



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.

Returns:

  • (Hash) —

    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)

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


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