Class: Riak::Bucket

Inherits:
Object show all
Includes:
Util::Escape, Util::Translation
Defined in:
riak-client/lib/riak/bucket.rb,
riak-client/lib/riak/search.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

SEARCH_PRECOMMIT_HOOK =

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

#escape, #unescape

Methods included from Util::Translation

#i18n_scope, #t

Constructor Details

- (Bucket) initialize(client, name)

Create a Riak bucket manually.

Parameters:

Raises:

  • (ArgumentError) 


37
38
39
40
41
 
# File 'riak-client/lib/riak/bucket.rb', line 37

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

- (Riak::Client) client (readonly)

The associated client

Returns:



29
30
31
 
# File 'riak-client/lib/riak/bucket.rb', line 29

def client
  @client
end

- (String) name (readonly)

The bucket name

Returns:

  • (String) —

    the bucket name 



32
33
34
 
# File 'riak-client/lib/riak/bucket.rb', line 32

def name
  @name
end

Instance Method Details

- (true, false) ==(other)

Whether the other is equivalent

Returns:

  • (true, false) —

    whether the other is equivalent 



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

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

- (true, false) allow_mult

Whether the bucket allows divergent siblings

Returns:

  • (true, false) —

    whether the bucket allows divergent siblings 



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

def allow_mult
  props['allow_mult']
end

- (Object) allow_mult=(value)

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 'riak-client/lib/riak/bucket.rb', line 160

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

- (Object) delete(key, options = {})

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 



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

def delete(key, options={})
  client.backend.delete_object(self, key, options[:rw])
end

- (Object) disable_index!

Removes the precommit hook that automatically indexes objects into riak_search. 



137
138
139
140
141
 
# File 'riak-client/lib/riak/search.rb', line 137

def disable_index!
  if is_indexed?
    self.props = {"precommit" => (props['precommit'] - [SEARCH_PRECOMMIT_HOOK])}
  end
end

- (Object) enable_index!

Installs a precommit hook that automatically indexes objects into riak_search. 



129
130
131
132
133
 
# File 'riak-client/lib/riak/search.rb', line 129

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

- (true, false) exists?(key, options = {}) 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 



135
136
137
138
139
140
141
142
 
# File 'riak-client/lib/riak/bucket.rb', line 135

def exists?(key, options={})
  begin
    get(key, options)
    true
  rescue Riak::FailedRequest
    false
  end
end

- (Riak::RObject) get(key, options = {}) 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 'riak-client/lib/riak/bucket.rb', line 101

def get(key, options={})
  @client.backend.fetch_object(self, key, options[:r])
end

- (RObject) get_or_new(key, options = {})

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 



118
119
120
121
122
123
124
125
126
127
128
 
# File 'riak-client/lib/riak/bucket.rb', line 118

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

- (String) inspect

A representation suitable for IRB and debugging output

Returns:

  • (String) —

    a representation suitable for IRB and debugging output 



194
195
196
 
# File 'riak-client/lib/riak/bucket.rb', line 194

def inspect
  "#<Riak::Bucket {#{name}}#{" keys=[#{keys.join(',')}]" if defined?(@keys)}>"
end

- (true, false) is_indexed?

Detects whether the bucket is automatically indexed into riak_search.

Returns:

  • (true, false) —

    whether the bucket includes the search indexing hook 



146
147
148
 
# File 'riak-client/lib/riak/search.rb', line 146

def is_indexed?
  props['precommit'].include?(SEARCH_PRECOMMIT_HOOK)
end

- (Array<String>) keys(options = {}) {|Array<String>| ... }

Accesses or 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 retained in the local Bucket object.

Parameters:

  • options (Hash) (defaults to: {}) —

    extra options

Options Hash (options):

  • :reload (Boolean) — default: false —

    If present, will force reloading of the bucket’s keys from Riak

Yields:

  • (Array<String>) —

    a list of keys from the current chunk

Returns:



51
52
53
54
55
56
57
58
59
 
# File 'riak-client/lib/riak/bucket.rb', line 51

def keys(options={}, &block)
  if block_given?
    @client.backend.list_keys(self, &block)
    @keys = nil
  elsif @keys.nil? || options[:reload]
    @keys = @client.backend.list_keys(self)
  end
  @keys
end

- (Fixnum) n_value Also known as: n_val

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 'riak-client/lib/riak/bucket.rb', line 166

def n_value
  props['n_val']
end

- (Object) n_value=(value) 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 'riak-client/lib/riak/bucket.rb', line 174

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

- (RObject) new(key = nil)

Create a new blank object

Parameters:

  • key (String) (defaults to: nil) —

    the key of the new object

Returns:

  • (RObject) —

    the new, unsaved object 



109
110
111
112
113
 
# File 'riak-client/lib/riak/bucket.rb', line 109

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

- (Hash) props Also known as: properties

Internal Riak bucket properties.

Returns:

  • (Hash) —

    Internal Riak bucket properties.

See Also:



90
91
92
 
# File 'riak-client/lib/riak/bucket.rb', line 90

def props
  @props ||= @client.backend.get_bucket_props(self)
end

- (Hash) props=(properties) 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


80
81
82
83
84
85
 
# File 'riak-client/lib/riak/bucket.rb', line 80

def props=(properties)
  raise ArgumentError, t("hash_type", :hash => properties.inspect) unless Hash === properties
  props.merge!(properties)
  @client.backend.set_bucket_props(self, properties)
  props
end