Class: Couchbase::Collection

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

Overview

Provides access to all collection APIs

Defined Under Namespace

Classes: ExistsResult, GetReplicaResult, GetResult, LookupInReplicaResult, LookupInResult, MutateInResult, MutationResult, ScanResult, ScanResults

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



35
36
37
38
39
40
 
# File 'lib/couchbase/collection.rb', line 35

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.



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

def bucket_name
  @bucket_name
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



27
28
29
 
# File 'lib/couchbase/collection.rb', line 27

def name
  @name
end

#scope_name ⇒ Object (readonly)

Returns the value of attribute scope_name.



26
27
28
 
# File 'lib/couchbase/collection.rb', line 26

def scope_name
  @scope_name
end

Instance Method Details

#binary ⇒ BinaryCollection

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

Returns:



45
46
47
 
# File 'lib/couchbase/collection.rb', line 45

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:



230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/couchbase/collection.rb', line 230

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:



80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/couchbase/collection.rb', line 80

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:



179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/couchbase/collection.rb', line 179

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:



139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/couchbase/collection.rb', line 139

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



161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/couchbase/collection.rb', line 161

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:



209
210
211
212
213
214
215
216
217
218
 
# File 'lib/couchbase/collection.rb', line 209

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:



109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/couchbase/collection.rb', line 109

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:



329
330
331
332
333
334
335
336
 
# File 'lib/couchbase/collection.rb', line 329

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:



466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
 
# File 'lib/couchbase/collection.rb', line 466

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]
        f.error = field[:error]
      end
    end
  end
end

#lookup_in_all_replicas(id, specs, options = Options::LookupInAllReplicas::DEFAULT) ⇒ Array<LookupInReplicaResult>

Performs lookups to document fragments. Reads from the active node and all available replicas and returns all of the results

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::LookupInAllReplicas) (defaults to: Options::LookupInAllReplicas::DEFAULT) —

    request customization

Returns:

Raises:



533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
 
# File 'lib/couchbase/collection.rb', line 533

def lookup_in_all_replicas(id, specs, options = Options::LookupInAllReplicas::DEFAULT)
  resp = @backend.document_lookup_in_all_replicas(
    bucket_name, @scope_name, @name, id,
    specs.map do |s|
      {
        opcode: s.type,
        xattr: s.xattr?,
        path: s.path,
      }
    end, options.to_backend
  )
  resp.map do |entry|
    extract_lookup_in_replica_result(entry, options)
  end
end

#lookup_in_any_replica(id, specs, options = Options::LookupInAnyReplica::DEFAULT) ⇒ LookupInReplicaResult

Performs lookups to document fragments. Reads from the active node and all available replicas and returns the first result found

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::LookupInAnyReplica) (defaults to: Options::LookupInAnyReplica::DEFAULT) —

    request customization

Returns:

Raises:



506
507
508
509
510
511
512
513
514
515
516
517
518
 
# File 'lib/couchbase/collection.rb', line 506

def lookup_in_any_replica(id, specs, options = Options::LookupInAnyReplica::DEFAULT)
  resp = @backend.document_lookup_in_any_replica(
    bucket_name, @scope_name, @name, id,
    specs.map do |s|
      {
        opcode: s.type,
        xattr: s.xattr?,
        path: s.path,
      }
    end, options.to_backend
  )
  extract_lookup_in_replica_result(resp, options)
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:



569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
 
# File 'lib/couchbase/collection.rb', line 569

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

#query_indexes ⇒ Management::CollectionQueryIndexManager

Returns:



50
51
52
 
# File 'lib/couchbase/collection.rb', line 50

def query_indexes
  Management::CollectionQueryIndexManager.new(@backend, @bucket_name, @scope_name, @name)
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:



263
264
265
266
267
268
269
 
# File 'lib/couchbase/collection.rb', line 263

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:



289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/couchbase/collection.rb', line 289

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:



403
404
405
406
407
408
409
410
 
# File 'lib/couchbase/collection.rb', line 403

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

#scan(scan_type, options = Options::Scan::DEFAULT) ⇒ ScanResults

Note:

Use this API for low concurrency batch queries where latency is not a critical as the system may have to scan a lot of documents to find the matching documents. For low latency range queries, it is recommended that you use SQL++ with the necessary indexes.

Performs a key-value scan operation on the collection

Examples:

Get a sample of up to 5 documents from the collection and store their IDs in an array

result = collection.scan(SamplingScan.new(5), Options::Scan.new(ids_only: true))
ids = result.map { |item| item.id }

Get all documents whose ID starts with ‘customer_1’ and output their content

result = collection.scan(PrefixScan.new("customer_1"))
result.each { |item| puts item.content }

Get all documents with ID between ‘customer_1’ and ‘customer_2’, excluding ‘customer_2’ and output their content

result = collection.scan(RangeScan.new(
  from: ScanTerm.new("customer_1"),
  to: ScanTerm.new("customer_2", exclusive: true)
))
result.each { |item| puts item.content }

Parameters:

Returns:



624
625
626
627
628
629
630
631
 
# File 'lib/couchbase/collection.rb', line 624

def scan(scan_type, options = Options::Scan::DEFAULT)
  ScanResults.new(
    core_scan_result: @backend.document_scan_create(
      @bucket_name, @scope_name, @name, scan_type.to_backend, options.to_backend
    ),
    transcoder: options.transcoder
  )
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:



422
423
424
425
426
427
428
429
 
# File 'lib/couchbase/collection.rb', line 422

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:



444
445
446
 
# File 'lib/couchbase/collection.rb', line 444

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:



349
350
351
352
353
354
355
356
 
# File 'lib/couchbase/collection.rb', line 349

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:



376
377
378
379
380
381
382
383
384
385
386
387
388
389
 
# File 'lib/couchbase/collection.rb', line 376

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