Class: Riak::Bucket

Inherits:
Object show all
Includes:
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

Constructor Details

#initialize(client, name) ⇒ Bucket

Create a Riak bucket manually.

Parameters:

Raises:

  • (ArgumentError) 


25
26
27
28
29
30
 
# 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

Instance Attribute Details

#client ⇒ Riak::Client (readonly)

Returns the associated client.

Returns:



17
18
19
 
# File 'lib/riak/bucket.rb', line 17

def client
  @client
end

#name ⇒ String (readonly)

Returns the bucket name.

Returns:

  • (String) —

    the bucket name



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

def name
  @name
end

Instance Method Details

#==(other) ⇒ true, false

Returns whether the other is equivalent.

Returns:

  • (true, false) —

    whether the other is equivalent



290
291
292
293
294
295
 
# 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

#allow_mult ⇒ true, false

Returns whether the bucket allows divergent siblings.

Returns:

  • (true, false) —

    whether the bucket allows divergent siblings



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

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



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

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



87
88
89
90
 
# File 'lib/riak/bucket.rb', line 87

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:



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

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



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

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.



250
251
252
253
254
255
256
257
 
# File 'lib/riak/bucket.rb', line 250

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.



239
240
241
242
243
244
245
246
 
# File 'lib/riak/bucket.rb', line 239

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



156
157
158
159
160
161
162
163
164
 
# 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

#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



101
102
103
 
# File 'lib/riak/bucket.rb', line 101

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



185
186
187
 
# File 'lib/riak/bucket.rb', line 185

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:



109
110
111
112
113
114
115
116
 
# 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

#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



131
132
133
134
135
136
137
138
139
140
141
 
# 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

#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:



194
195
196
197
 
# 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

#inspect ⇒ String

Returns a representation suitable for IRB and debugging output.

Returns:

  • (String) —

    a representation suitable for IRB and debugging output



270
271
272
 
# File 'lib/riak/bucket.rb', line 270

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



262
263
264
265
266
267
 
# 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

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

Yields:

  • (Array<String>) —

    a list of keys from the current chunk

Returns:



40
41
42
43
44
45
46
47
 
# 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

#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



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

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



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

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



285
286
287
 
# File 'lib/riak/bucket.rb', line 285

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



121
122
123
124
125
 
# 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_print(pp) ⇒ Object

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



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

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:



79
80
81
 
# File 'lib/riak/bucket.rb', line 79

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


69
70
71
72
73
74
 
# 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