Class: Couchbase::Collection

Inherits:
Object
  • Object
show all
Defined in:
lib/couchbase/collection.rb,
lib/couchbase/collection_options.rb,
/Users/sergey.auseyau/code/couchbase-ruby-client/lib/couchbase/collection.rb,
/Users/sergey.auseyau/code/couchbase-ruby-client/lib/couchbase/collection_options.rb more...

Overview

Provides access to all collection APIs

Defined Under Namespace

Classes: ExistsResult, GetReplicaResult, GetResult, LookupInResult, MutateInResult, MutationResult

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(backend, bucket_name, scope_name, collection_name) ⇒ Collection

Returns a new instance of Collection.

Parameters:

  • backend (Couchbase::Backend)
  • bucket_name (String) —

    name of the bucket

  • scope_name (String) —

    name of the scope

  • collection_name (String) —

    name of the collection

[View source]

32
33
34
35
36
37
 
# File 'lib/couchbase/collection.rb', line 32

def initialize(backend, bucket_name, scope_name, collection_name)
  @backend = backend
  @bucket_name = bucket_name
  @scope_name = scope_name
  @name = collection_name
end

Instance Attribute Details

#bucket_name ⇒ Object (readonly)

Returns the value of attribute bucket_name.


22
23
24
 
# File 'lib/couchbase/collection.rb', line 22

def bucket_name
  @bucket_name
end

#name ⇒ Object (readonly)

Returns the value of attribute name.


24
25
26
 
# File 'lib/couchbase/collection.rb', line 24

def name
  @name
end

#scope_name ⇒ Object (readonly)

Returns the value of attribute scope_name.


23
24
25
 
# File 'lib/couchbase/collection.rb', line 23

def scope_name
  @scope_name
end

Instance Method Details

#binary ⇒ BinaryCollection

Provides access to the binary APIs, not used for JSON documents

Returns:

[View source]

42
43
44
 
# File 'lib/couchbase/collection.rb', line 42

def binary
  BinaryCollection.new(self)
end

#exists(id, options = Options::Exists::DEFAULT) ⇒ ExistsResult

Checks if the given document ID exists on the active partition.

Examples:

Check if the document exists without fetching its contents

res = collection.exists("customer123")
res.exists? #=> true

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • options (Options::Exists) (defaults to: Options::Exists::DEFAULT) —

    request customization

Returns:

[View source]

222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/couchbase/collection.rb', line 222

def exists(id, options = Options::Exists::DEFAULT)
  resp = @backend.document_exists(bucket_name, @scope_name, @name, id, options.to_backend)
  ExistsResult.new do |res|
    res.deleted = resp[:deleted]
    res.exists = resp[:exists]
    res.expiry = resp[:expiry]
    res.flags = resp[:flags]
    res.sequence_number = resp[:sequence_number]
    res.datatype = resp[:datatype]
    res.cas = resp[:cas]
  end
end

#get(id, options = Options::Get::DEFAULT) ⇒ GetResult

Fetches the full document from the collection

Examples:

Get document contents

res = collection.get("customer123")
res.content["addresses"]

# {"billing"=>
#   {"line1"=>"123 Any Street", "line2"=>"Anytown", "country"=>"United Kingdom"},
#  "delivery"=>
#   {"line1"=>"123 Any Street", "line2"=>"Anytown", "country"=>"United Kingdom"}}

Get partial document using projections

res = collection.get("customer123", Options::Get(projections: ["name", "addresses.billing"]))
res.content

# {"addresses"=>
#    {"billing"=>
#      {"country"=>"United Kingdom",
#       "line1"=>"123 Any Street",
#       "line2"=>"Anytown"}},
#   "name"=>"Douglas Reynholm"}

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it

  • options (Options::Get) (defaults to: Options::Get::DEFAULT) —

    request customization

Returns:

[View source]

72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/couchbase/collection.rb', line 72

def get(id, options = Options::Get::DEFAULT)
  resp = if options.need_projected_get?
           @backend.document_get_projected(bucket_name, @scope_name, @name, id, options.to_backend)
         else
           @backend.document_get(bucket_name, @scope_name, @name, id, options.to_backend)
         end
  GetResult.new do |res|
    res.transcoder = options.transcoder
    res.cas = resp[:cas]
    res.flags = resp[:flags]
    res.encoded = resp[:content]
    res.expiry = resp[:expiry] if resp.key?(:expiry)
  end
end

#get_all_replicas(id, options = Options::GetAllReplicas::DEFAULT) ⇒ Array<GetReplicaResult>

Reads from all available replicas and the active node and returns the results

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • options (Options::GetAllReplicas) (defaults to: Options::GetAllReplicas::DEFAULT) —

    request customization

Returns:

[View source]

171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/couchbase/collection.rb', line 171

def get_all_replicas(id, options = Options::GetAllReplicas::DEFAULT)
  resp = @backend.document_get_all_replicas(@bucket_name, @scope_name, @name, id, options.to_backend)
  resp.map do |entry|
    GetReplicaResult.new do |res|
      res.transcoder = options.transcoder
      res.cas = entry[:cas]
      res.flags = entry[:flags]
      res.encoded = entry[:content]
      res.is_replica = entry[:is_replica]
    end
  end
end

#get_and_lock(id, lock_time, options = Options::GetAndLock::DEFAULT) ⇒ GetResult

Fetches the full document and write-locks it for the given duration

Examples:

Retrieve document and lock for 10 seconds

collection.get_and_lock("customer123", 10, Options::GetAndLock(timeout: 3_000))

Update document pessimistically

res = collection.get_and_lock("customer123", 10)
user_data = res.content
user_data["admin"] = true
collection.replace("user", user_data, Options::Upsert(cas: res.cas))

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • lock_time (Integer, #in_seconds) —

    how long to lock the document (values over 30 seconds will be capped)

  • options (Options::GetAndLock) (defaults to: Options::GetAndLock::DEFAULT) —

    request customization

Returns:

[View source]

131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/couchbase/collection.rb', line 131

def get_and_lock(id, lock_time, options = Options::GetAndLock::DEFAULT)
  resp = @backend.document_get_and_lock(bucket_name, @scope_name, @name, id,
                                        lock_time.respond_to?(:in_seconds) ? lock_time.public_send(:in_seconds) : lock_time,
                                        options.to_backend)
  GetResult.new do |res|
    res.transcoder = options.transcoder
    res.cas = resp[:cas]
    res.flags = resp[:flags]
    res.encoded = resp[:content]
  end
end

#get_and_touch(id, expiry, options = Options::GetAndTouch::DEFAULT) ⇒ GetResult

Fetches a full document and resets its expiration time to the duration provided

Examples:

Retrieve document and prolong its expiration for another 10 seconds

collection.get_and_touch("customer123", 10)

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • expiry (Integer, #in_seconds, Time) —

    the new expiration time for the document

  • options (Options::GetAndTouch) (defaults to: Options::GetAndTouch::DEFAULT) —

    request customization

Returns:

[View source]

153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/couchbase/collection.rb', line 153

def get_and_touch(id, expiry, options = Options::GetAndTouch::DEFAULT)
  resp = @backend.document_get_and_touch(bucket_name, @scope_name, @name, id,
                                         Utils::Time.extract_expiry_time(expiry),
                                         options.to_backend)
  GetResult.new do |res|
    res.transcoder = options.transcoder
    res.cas = resp[:cas]
    res.flags = resp[:flags]
    res.encoded = resp[:content]
  end
end

#get_any_replica(id, options = Options::GetAnyReplica::DEFAULT) ⇒ GetReplicaResult

Reads all available replicas and active, and returns the first found.

Examples:

Get document contents

res = collection.get_any_replica("customer123")
res.is_active #=> false
res.content["addresses"]

# {"billing"=>
#   {"line1"=>"123 Any Street", "line2"=>"Anytown", "country"=>"United Kingdom"},
#  "delivery"=>
#   {"line1"=>"123 Any Street", "line2"=>"Anytown", "country"=>"United Kingdom"}}

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • options (Options::GetAnyReplica) (defaults to: Options::GetAnyReplica::DEFAULT) —

    request customization

Returns:

[View source]

201
202
203
204
205
206
207
208
209
210
 
# File 'lib/couchbase/collection.rb', line 201

def get_any_replica(id, options = Options::GetAnyReplica::DEFAULT)
  resp = @backend.document_get_any_replica(@bucket_name, @scope_name, @name, id, options.to_backend)
  GetReplicaResult.new do |res|
    res.transcoder = options.transcoder
    res.cas = resp[:cas]
    res.flags = resp[:flags]
    res.encoded = resp[:content]
    res.is_replica = resp[:is_replica]
  end
end

#get_multi(ids, options = Options::GetMulti::DEFAULT) ⇒ Array<GetResult>

Note:

that it will not generate Error::DocumentNotFound exceptions in this case. The caller should check Couchbase::Collection::GetResult#error property of the result

Fetches multiple documents from the collection.

Examples:

Fetch “foo” and “bar” in a batch

res = collection.get(["foo", "bar"], Options::GetMulti(timeout: 3_000))
res[0].content #=> content of "foo"
res[1].content #=> content of "bar"

Parameters:

  • ids (Array<String>) —

    the array of document identifiers

  • options (Options::GetMulti) (defaults to: Options::GetMulti::DEFAULT) —

    request customization

Returns:

[View source]

101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/couchbase/collection.rb', line 101

def get_multi(ids, options = Options::GetMulti::DEFAULT)
  resp = @backend.document_get_multi(ids.map { |id| [bucket_name, @scope_name, @name, id] }, options.to_backend)
  resp.map do |entry|
    GetResult.new do |res|
      res.transcoder = options.transcoder
      res.id = entry[:id]
      res.cas = entry[:cas]
      res.flags = entry[:flags]
      res.encoded = entry[:content]
      res.error = entry[:error]
    end
  end
end

#insert(id, content, options = Options::Insert::DEFAULT) ⇒ MutationResult

Inserts a full document which does not exist yet

Examples:

Insert new document in collection

res = collection.insert("mydoc", {"foo" => 42}, Options::Insert(expiry: 20))
res.cas #=> 242287264414742

Handle error when the document already exists

collection.exists("mydoc").exists? #=> true
begin
  res = collection.insert("mydoc", {"foo" => 42})
rescue Error::DocumentExists
  puts "Failed to insert the document, it already exists in the collection"
end

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • content (Object) —

    the document content to insert

  • options (Options::Insert) (defaults to: Options::Insert::DEFAULT) —

    request customization

Returns:

[View source]

321
322
323
324
325
326
327
328
 
# File 'lib/couchbase/collection.rb', line 321

def insert(id, content, options = Options::Insert::DEFAULT)
  blob, flags = options.transcoder ? options.transcoder.encode(content) : [content, 0]
  resp = @backend.document_insert(bucket_name, @scope_name, @name, id, blob, flags, options.to_backend)
  MutationResult.new do |res|
    res.cas = resp[:cas]
    res.mutation_token = extract_mutation_token(resp)
  end
end

#lookup_in(id, specs, options = Options::LookupIn::DEFAULT) ⇒ LookupInResult

Performs lookups to document fragments

Examples:

Get list of IDs of completed purchases

lookup_specs = [
  LookupInSpec::get("purchases.complete")
]
collection.lookup_in("customer123", lookup_specs)

Retrieve country name and check if pending purchases array is empty

collection.lookup_in "customer123", [
  LookupInSpec.get("addresses.delivery.country"),
  LookupInSpec.exists("purchases.pending[-1]"),
]

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • specs (Array<LookupInSpec>) —

    the list of specifications which describe the types of the lookups to perform

  • options (Options::LookupIn) (defaults to: Options::LookupIn::DEFAULT) —

    request customization

Returns:

[View source]

458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
 
# File 'lib/couchbase/collection.rb', line 458

def lookup_in(id, specs, options = Options::LookupIn::DEFAULT)
  resp = @backend.document_lookup_in(
    bucket_name, @scope_name, @name, id,
    specs.map do |s|
      {
        opcode: s.type,
        xattr: s.xattr?,
        path: s.path,
      }
    end, options.to_backend
  )
  LookupInResult.new do |res|
    res.transcoder = options.transcoder
    res.cas = resp[:cas]
    res.deleted = resp[:deleted]
    res.encoded = resp[:fields].map do |field|
      SubDocumentField.new do |f|
        f.exists = field[:exists]
        f.index = field[:index]
        f.path = field[:path]
        f.value = field[:value]
      end
    end
  end
end

#mutate_in(id, specs, options = Options::MutateIn::DEFAULT) ⇒ MutateInResult

Performs mutations to document fragments

Examples:

Append number into subarray of the document

mutation_specs = [
  MutateInSpec::array_append("purchases.complete", [42])
]
collection.mutate_in("customer123", mutation_specs, Options::MutateIn(expiry: 10))

Write meta attribute, remove array entry and replace email field

collection.mutate_in("customer123", [
  MutateInSpec.upsert("_framework.model_type", "Customer").xattr,
  MutateInSpec.remove("addresses.billing[2]"),
  MutateInSpec.replace("email", "dougr96@hotmail.com"),
])

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • specs (Array<MutateInSpec>) —

    the list of specifications which describe the types of the lookups to perform

  • options (Options::MutateIn) (defaults to: Options::MutateIn::DEFAULT) —

    request customization

Returns:

[View source]

504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
 
# File 'lib/couchbase/collection.rb', line 504

def mutate_in(id, specs, options = Options::MutateIn::DEFAULT)
  resp = @backend.document_mutate_in(
    bucket_name, @scope_name, @name, id,
    specs.map do |s|
      {
        opcode: s.type,
        path: s.path,
        param: s.param,
        xattr: s.xattr?,
        expand_macros: s.expand_macros?,
        create_path: s.create_path?,
      }
    end, options.to_backend
  )
  MutateInResult.new do |res|
    res.transcoder = options.transcoder
    res.cas = resp[:cas]
    res.deleted = resp[:deleted]
    res.mutation_token = extract_mutation_token(resp)
    res.encoded = resp[:fields].map do |field|
      SubDocumentField.new do |f|
        f.index = field[:index]
        f.path = field[:path]
        f.value = field[:value]
      end
    end
  end
end

#remove(id, options = Options::Remove::DEFAULT) ⇒ MutationResult

Removes a document from the collection

Examples:

Remove the document in collection

res = collection.remove("customer123")
res.cas #=> 241994216651798

Remove the document in collection, but apply optimistic lock

res = collection.upsert("mydoc", {"foo" => 42})
res.cas #=> 7751414725654

begin
  res = collection.remove("mydoc", Options::Remove(cas: 3735928559))
rescue Error::CasMismatch
  puts "Failed to remove the document, it might be changed by other application"
end

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • options (Options::Remove) (defaults to: Options::Remove::DEFAULT) —

    request customization

Returns:

[View source]

255
256
257
258
259
260
261
 
# File 'lib/couchbase/collection.rb', line 255

def remove(id, options = Options::Remove::DEFAULT)
  resp = @backend.document_remove(bucket_name, @scope_name, @name, id, options.to_backend)
  MutationResult.new do |res|
    res.cas = resp[:cas]
    res.mutation_token = extract_mutation_token(resp)
  end
end

#remove_multi(ids, options = Options::RemoveMulti::DEFAULT) ⇒ Array<MutationResult>

Note:

that it will not generate Error::DocumentNotFound or Error::CasMismatch exceptions in this case. The caller should check Couchbase::Collection::MutationResult#error property of the result

Removes a list of the documents from the collection

Examples:

Remove two documents in collection. For “mydoc” apply optimistic lock

res = collection.upsert("mydoc", {"foo" => 42})
res.cas #=> 7751414725654

res = collection.remove_multi(["foo", ["mydoc", res.cas]])
if res[1].error.is_a?(Error::CasMismatch)
  puts "Failed to remove the document, it might be changed by other application"
end

Parameters:

  • ids (Array<String, Array>) —

    the array of document ids, or ID/CAS pairs [String,Integer]

  • options (Options::RemoveMulti) (defaults to: Options::RemoveMulti::DEFAULT) —

    request customization

Returns:

[View source]

281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/couchbase/collection.rb', line 281

def remove_multi(ids, options = Options::RemoveMulti::DEFAULT)
  resp = @backend.document_remove_multi(bucket_name, @scope_name, @name, ids.map do |id|
    case id
    when String
      [id, nil]
    when Array
      id
    else
      raise ArgumentError, "id argument of remove_multi must be a String or Array<String, Integer>, given: #{id.inspect}"
    end
  end, options.to_backend)
  resp.map do |entry|
    MutationResult.new do |res|
      res.cas = entry[:cas]
      res.mutation_token = extract_mutation_token(entry)
      res.error = entry[:error]
      res.id = entry[:id]
    end
  end
end

#replace(id, content, options = Options::Replace::DEFAULT) ⇒ MutationResult

Replaces a full document which already exists

Examples:

Replace new document in collection with optimistic locking

res = collection.get("mydoc")
res = collection.replace("mydoc", {"foo" => 42}, Options::Replace(cas: res.cas))
res.cas #=> 242287264414742

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • content (Object) —

    the document content to upsert

  • options (Options::Replace) (defaults to: Options::Replace::DEFAULT) —

    request customization

Returns:

[View source]

395
396
397
398
399
400
401
402
 
# File 'lib/couchbase/collection.rb', line 395

def replace(id, content, options = Options::Replace::DEFAULT)
  blob, flags = options.transcoder ? options.transcoder.encode(content) : [content, 0]
  resp = @backend.document_replace(bucket_name, @scope_name, @name, id, blob, flags, options.to_backend)
  MutationResult.new do |res|
    res.cas = resp[:cas]
    res.mutation_token = extract_mutation_token(resp)
  end
end

#touch(id, expiry, options = Options::Touch::DEFAULT) ⇒ MutationResult

Update the expiration of the document with the given id

Examples:

Reset expiration timer for document to 30 seconds

res = collection.touch("customer123", 30)

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • expiry (Integer, #in_seconds, Time) —

    new expiration time for the document

  • options (Options::Touch) (defaults to: Options::Touch::DEFAULT) —

    request customization

Returns:

[View source]

414
415
416
417
418
419
420
421
 
# File 'lib/couchbase/collection.rb', line 414

def touch(id, expiry, options = Options::Touch::DEFAULT)
  resp = @backend.document_touch(bucket_name, @scope_name, @name, id,
                                 Utils::Time.extract_expiry_time(expiry),
                                 options.to_backend)
  MutationResult.new do |res|
    res.cas = resp[:cas]
  end
end

#unlock(id, cas, options = Options::Unlock::DEFAULT) ⇒ void

This method returns an undefined value.

Unlocks a document if it has been locked previously

Examples:

Lock (pessimistically) and unlock document

res = collection.get_and_lock("customer123", 10)
collection.unlock("customer123", res.cas)

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • cas (Integer) —

    CAS value which is needed to unlock the document

  • options (Options::Unlock) (defaults to: Options::Unlock::DEFAULT) —

    request customization

Raises:

[View source]

436
437
438
 
# File 'lib/couchbase/collection.rb', line 436

def unlock(id, cas, options = Options::Unlock::DEFAULT)
  @backend.document_unlock(bucket_name, @scope_name, @name, id, cas, options.to_backend)
end

#upsert(id, content, options = Options::Upsert::DEFAULT) ⇒ MutationResult

Upserts (inserts or updates) a full document which might or might not exist yet

Examples:

Upsert new document in collection

res = collection.upsert("mydoc", {"foo" => 42}, Options::Upsert(expiry: 20))
res.cas #=> 242287264414742

Parameters:

  • id (String) —

    the document id which is used to uniquely identify it.

  • content (Object) —

    the document content to upsert

  • options (Options::Upsert) (defaults to: Options::Upsert::DEFAULT) —

    request customization

Returns:

[View source]

341
342
343
344
345
346
347
348
 
# File 'lib/couchbase/collection.rb', line 341

def upsert(id, content, options = Options::Upsert::DEFAULT)
  blob, flags = options.transcoder ? options.transcoder.encode(content) : [content, 0]
  resp = @backend.document_upsert(bucket_name, @scope_name, @name, id, blob, flags, options.to_backend)
  MutationResult.new do |res|
    res.cas = resp[:cas]
    res.mutation_token = extract_mutation_token(resp)
  end
end

#upsert_multi(id_content, options = Options::UpsertMulti::DEFAULT) ⇒ Array<MutationResult>

Note:

that it will not generate exceptions in this case. The caller should check Couchbase::Collection::MutationResult#error property of the result

Upserts (inserts or updates) a list of documents which might or might not exist yet

Examples:

Upsert two documents with IDs “foo” and “bar” into a collection

res = collection.upsert_multi([
  "foo", {"foo" => 42},
  "bar", {"bar" => "some value"}
])
res[0].cas #=> 7751414725654
res[1].cas #=> 7751418925851

Parameters:

  • id_content (Array<Array>) —

    array of tuples String,Object, where first entry treated as document key, and the second as value to upsert.

  • options (Options::UpsertMulti) (defaults to: Options::UpsertMulti::DEFAULT) —

    request customization

Returns:

[View source]

368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'lib/couchbase/collection.rb', line 368

def upsert_multi(id_content, options = Options::UpsertMulti::DEFAULT)
  resp = @backend.document_upsert_multi(bucket_name, @scope_name, @name, id_content.map do |(id, content)|
    blob, flags = options.transcoder ? options.transcoder.encode(content) : [content, 0]
    [id, blob, flags]
  end, options.to_backend)
  resp.map do |entry|
    MutationResult.new do |res|
      res.cas = entry[:cas]
      res.mutation_token = extract_mutation_token(entry)
      res.error = entry[:error]
      res.id = entry[:id]
    end
  end
end