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.

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) 


24
25
26
27
28
 
# File 'lib/riak/bucket.rb', line 24

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
  @client, @name = client, name
end

Instance Attribute Details

#client ⇒ Riak::Client (readonly)

Returns the associated client.

Returns:



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

def client
  @client
end

#name ⇒ String (readonly)

Returns the bucket name.

Returns:

  • (String) —

    the bucket name



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

def name
  @name
end

Instance Method Details

#==(other) ⇒ true, false

Returns whether the other is equivalent.

Returns:

  • (true, false) —

    whether the other is equivalent



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

def ==(other)
  Bucket === other && other.client == client && other.name == name
end

#allow_mult ⇒ true, false

Returns whether the bucket allows divergent siblings.

Returns:

  • (true, false) —

    whether the bucket allows divergent siblings



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

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



160
161
162
163
 
# File 'lib/riak/bucket.rb', line 160

def allow_mult=(value)
  self.props = {'allow_mult' => value}
  value
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 vector clock of the

    object being deleted



138
139
140
 
# File 'lib/riak/bucket.rb', line 138

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.



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

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.



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

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



121
122
123
124
125
126
127
128
 
# File 'lib/riak/bucket.rb', line 121

def exists?(key, options={})
  begin
    get(key, options)
    true
  rescue Riak::FailedRequest
    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



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

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

#get_index(index, query) ⇒ 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



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

def get_index(index, query)
  client.get_index(self, index, query)
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



104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/riak/bucket.rb', line 104

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

#inspect ⇒ String

Returns a representation suitable for IRB and debugging output.

Returns:

  • (String) —

    a representation suitable for IRB and debugging output



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

def inspect
  "#<Riak::Bucket {#{name}}#{" keys=[#{keys.join(',')}]" if defined?(@keys)}>"
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



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

def is_indexed?
  props['search'] == true || props['precommit'].include?(SEARCH_PRECOMMIT_HOOK)
end

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



38
39
40
41
42
43
44
45
 
# File 'lib/riak/bucket.rb', line 38

def keys(&block)
  warn(t('list_keys', :backtrace => caller.join("\n    "))) unless Riak.disable_list_keys_warnings
  if block_given?
    @client.list_keys(self, &block)
  else
    @client.list_keys(self)
  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



166
167
168
 
# File 'lib/riak/bucket.rb', line 166

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



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

def n_value=(value)
  self.props = {'n_val' => value}
  value
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



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

def new(key=nil)
  RObject.new(self, key).tap do |obj|
    obj.content_type = "application/json"
  end
end

#props ⇒ Hash Also known as: properties

Returns Internal Riak bucket properties.

Returns:

  • (Hash) —

    Internal Riak bucket properties.

See Also:



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

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 vclocks

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


66
67
68
69
70
71
 
# File 'lib/riak/bucket.rb', line 66

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