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

#clientRiak::Client (readonly)

Returns the associated client

Returns:


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

def client
  @client
end

#nameString (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


294
295
296
297
298
299
300
301
302
303
# File 'lib/riak/bucket.rb', line 294

def ==(other)
  return false unless self.class == other.class
  return false unless self.client == other.client
  return true if self.name.nil? && other.name.nil?
  unless self.name.respond_to?(:bytes) && other.name.respond_to?(:bytes)
    return false
  end
  return false unless self.name.bytes == other.name.bytes
  true
end

#allow_multtrue, false

Returns whether the bucket allows divergent siblings

Returns:

  • (true, false)

    whether the bucket allows divergent siblings


204
205
206
# File 'lib/riak/bucket.rb', line 204

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


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

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

#clear_propstrue, 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


91
92
93
94
# File 'lib/riak/bucket.rb', line 91

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:


151
152
153
# File 'lib/riak/bucket.rb', line 151

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


178
179
180
# File 'lib/riak/bucket.rb', line 178

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.


254
255
256
257
258
259
260
261
# File 'lib/riak/bucket.rb', line 254

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.


243
244
245
246
247
248
249
250
# File 'lib/riak/bucket.rb', line 243

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 (R)

Returns:

  • (true, false)

    whether the key exists in this bucket


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

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


105
106
107
# File 'lib/riak/bucket.rb', line 105

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


189
190
191
# File 'lib/riak/bucket.rb', line 189

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:


113
114
115
116
117
118
119
120
# File 'lib/riak/bucket.rb', line 113

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


135
136
137
138
139
140
141
142
143
144
145
# File 'lib/riak/bucket.rb', line 135

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:


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

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

#inspectString

Returns a representation suitable for IRB and debugging output

Returns:

  • (String)

    a representation suitable for IRB and debugging output


274
275
276
# File 'lib/riak/bucket.rb', line 274

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


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

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:


44
45
46
47
48
49
50
51
# File 'lib/riak/bucket.rb', line 44

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_valueFixnum 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


217
218
219
# File 'lib/riak/bucket.rb', line 217

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


227
228
229
230
# File 'lib/riak/bucket.rb', line 227

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


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

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


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

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


279
280
281
282
283
284
# File 'lib/riak/bucket.rb', line 279

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

#propsHash Also known as: properties

Returns Internal Riak bucket properties.

Returns:

  • (Hash)

    Internal Riak bucket properties.

See Also:


83
84
85
# File 'lib/riak/bucket.rb', line 83

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

73
74
75
76
77
78
# File 'lib/riak/bucket.rb', line 73

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