Class: Couchbase::Collection

Inherits:
Object
  • Object
show all
Defined in:
lib/couchbase/collection.rb,
lib/couchbase/collection_options.rb,
/home/runner/work/couchbase-ruby-client/couchbase-ruby-client/lib/couchbase/collection.rb,
/home/runner/work/couchbase-ruby-client/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

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:



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

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:



246
247
248
249
250
251
252
253
254
255
256
257
258
259
 
# File 'lib/couchbase/collection.rb', line 246

def exists(id, options = Options::Exists::DEFAULT)
  @observability.record_operation(Observability::OP_EXISTS, options.parent_span, self, :kv) do |obs_handler|
    resp = @backend.document_exists(bucket_name, @scope_name, @name, id, options.to_backend, obs_handler)
    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
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:



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/couchbase/collection.rb', line 84

def get(id, options = Options::Get::DEFAULT)
  @observability.record_operation(Observability::OP_GET, options.parent_span, self, :kv) do |obs_handler|
    resp = if options.need_projected_get?
             @backend.document_get_projected(bucket_name, @scope_name, @name, id, options.to_backend, obs_handler)
           else
             @backend.document_get(bucket_name, @scope_name, @name, id, options.to_backend, obs_handler)
           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
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:



191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/couchbase/collection.rb', line 191

def get_all_replicas(id, options = Options::GetAllReplicas::DEFAULT)
  @observability.record_operation(Observability::OP_GET_ALL_REPLICAS, options.parent_span, self, :kv) do |obs_handler|
    resp = @backend.document_get_all_replicas(@bucket_name, @scope_name, @name, id, options.to_backend, obs_handler)
    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
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:



147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/couchbase/collection.rb', line 147

def get_and_lock(id, lock_time, options = Options::GetAndLock::DEFAULT)
  @observability.record_operation(Observability::OP_GET_AND_LOCK, options.parent_span, self, :kv) do |obs_handler|
    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, obs_handler)
    GetResult.new do |res|
      res.transcoder = options.transcoder
      res.cas = resp[:cas]
      res.flags = resp[:flags]
      res.encoded = resp[:content]
    end
  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:



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

def get_and_touch(id, expiry, options = Options::GetAndTouch::DEFAULT)
  @observability.record_operation(Observability::OP_GET_AND_TOUCH, options.parent_span, self, :kv) do |obs_handler|
    resp = @backend.document_get_and_touch(bucket_name, @scope_name, @name, id,
                                           Utils::Time.extract_expiry_time(expiry),
                                           options.to_backend, obs_handler)
    GetResult.new do |res|
      res.transcoder = options.transcoder
      res.cas = resp[:cas]
      res.flags = resp[:flags]
      res.encoded = resp[:content]
    end
  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:



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

def get_any_replica(id, options = Options::GetAnyReplica::DEFAULT)
  @observability.record_operation(Observability::OP_GET_ANY_REPLICA, options.parent_span, self, :kv) do |obs_handler|
    resp = @backend.document_get_any_replica(@bucket_name, @scope_name, @name, id, options.to_backend, obs_handler)
    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
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:



115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/couchbase/collection.rb', line 115

def get_multi(ids, options = Options::GetMulti::DEFAULT)
  @observability.record_operation(Observability::OP_GET_MULTI, options.parent_span, self, :kv) do |_obs_handler|
    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
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:



353
354
355
356
357
358
359
360
361
362
363
 
# File 'lib/couchbase/collection.rb', line 353

def insert(id, content, options = Options::Insert::DEFAULT)
  @observability.record_operation(Observability::OP_INSERT, options.parent_span, self, :kv) do |obs_handler|
    obs_handler.add_durability_level(options.durability_level)
    blob, flags = encode_content(content, options, obs_handler)
    resp = @backend.document_insert(bucket_name, @scope_name, @name, id, blob, flags, options.to_backend, obs_handler)
    MutationResult.new do |res|
      res.cas = resp[:cas]
      res.mutation_token = extract_mutation_token(resp)
    end
  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:



503
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
 
# File 'lib/couchbase/collection.rb', line 503

def lookup_in(id, specs, options = Options::LookupIn::DEFAULT)
  @observability.record_operation(Observability::OP_LOOKUP_IN, options.parent_span, self, :kv) do |obs_handler|
    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, obs_handler
    )
    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
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:



574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
 
# File 'lib/couchbase/collection.rb', line 574

def lookup_in_all_replicas(id, specs, options = Options::LookupInAllReplicas::DEFAULT)
  @observability.record_operation(Observability::OP_LOOKUP_IN_ALL_REPLICAS, options.parent_span, self, :kv) do |obs_handler|
    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, obs_handler
    )
    resp.map do |entry|
      extract_lookup_in_replica_result(entry, options)
    end
  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:



545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
 
# File 'lib/couchbase/collection.rb', line 545

def lookup_in_any_replica(id, specs, options = Options::LookupInAnyReplica::DEFAULT)
  @observability.record_operation(Observability::OP_LOOKUP_IN_ANY_REPLICA, options.parent_span, self, :kv) do |obs_handler|
    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, obs_handler
    )
    extract_lookup_in_replica_result(resp, options)
  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:



612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
 
# File 'lib/couchbase/collection.rb', line 612

def mutate_in(id, specs, options = Options::MutateIn::DEFAULT)
  @observability.record_operation(Observability::OP_MUTATE_IN, options.parent_span, self, :kv) do |obs_handler|
    obs_handler.add_durability_level(options.durability_level)
    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, obs_handler
    )
    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
end

#query_indexes ⇒ Management::CollectionQueryIndexManager

Returns:



54
55
56
 
# File 'lib/couchbase/collection.rb', line 54

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



281
282
283
284
285
286
287
288
289
290
 
# File 'lib/couchbase/collection.rb', line 281

def remove(id, options = Options::Remove::DEFAULT)
  @observability.record_operation(Observability::OP_REMOVE, options.parent_span, self, :kv) do |obs_handler|
    obs_handler.add_durability_level(options.durability_level)
    resp = @backend.document_remove(bucket_name, @scope_name, @name, id, options.to_backend, obs_handler)
    MutationResult.new do |res|
      res.cas = resp[:cas]
      res.mutation_token = extract_mutation_token(resp)
    end
  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:



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/couchbase/collection.rb', line 310

def remove_multi(ids, options = Options::RemoveMulti::DEFAULT)
  @observability.record_operation(Observability::OP_REMOVE_MULTI, options.parent_span, self, :kv) do |obs_handler|
    obs_handler.add_durability_level(options.durability_level)
    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
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:



433
434
435
436
437
438
439
440
441
442
443
 
# File 'lib/couchbase/collection.rb', line 433

def replace(id, content, options = Options::Replace::DEFAULT)
  @observability.record_operation(Observability::OP_REPLACE, options.parent_span, self, :kv) do |obs_handler|
    obs_handler.add_durability_level(options.durability_level)
    blob, flags = encode_content(content, options, obs_handler)
    resp = @backend.document_replace(bucket_name, @scope_name, @name, id, blob, flags, options.to_backend, obs_handler)
    MutationResult.new do |res|
      res.cas = resp[:cas]
      res.mutation_token = extract_mutation_token(resp)
    end
  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:



670
671
672
673
674
675
676
677
678
679
 
# File 'lib/couchbase/collection.rb', line 670

def scan(scan_type, options = Options::Scan::DEFAULT)
  @observability.record_operation(Observability::OP_SCAN, options.parent_span, self, :kv) do |_obs_handler|
    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
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:



455
456
457
458
459
460
461
462
463
464
 
# File 'lib/couchbase/collection.rb', line 455

def touch(id, expiry, options = Options::Touch::DEFAULT)
  @observability.record_operation(Observability::OP_TOUCH, options.parent_span, self, :kv) do |obs_handler|
    resp = @backend.document_touch(bucket_name, @scope_name, @name, id,
                                   Utils::Time.extract_expiry_time(expiry),
                                   options.to_backend, obs_handler)
    MutationResult.new do |res|
      res.cas = resp[:cas]
    end
  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:



479
480
481
482
483
 
# File 'lib/couchbase/collection.rb', line 479

def unlock(id, cas, options = Options::Unlock::DEFAULT)
  @observability.record_operation(Observability::OP_UNLOCK, options.parent_span, self, :kv) do |obs_handler|
    @backend.document_unlock(bucket_name, @scope_name, @name, id, cas, options.to_backend, obs_handler)
  end
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:



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

def upsert(id, content, options = Options::Upsert::DEFAULT)
  @observability.record_operation(Observability::OP_UPSERT, options.parent_span, self, :kv) do |obs_handler|
    obs_handler.add_durability_level(options.durability_level)
    blob, flags = encode_content(content, options, obs_handler)
    resp = @backend.document_upsert(bucket_name, @scope_name, @name, id, blob, flags, options.to_backend, obs_handler)
    MutationResult.new do |res|
      res.cas = resp[:cas]
      res.mutation_token = extract_mutation_token(resp)
    end
  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:



406
407
408
409
410
411
412
413
414
415
416
417
418
419
 
# File 'lib/couchbase/collection.rb', line 406

def upsert_multi(id_content, options = Options::UpsertMulti::DEFAULT)
  @observability.record_operation(Observability::OP_UPSERT, options.parent_span, self, :kv) do |obs_handler|
    encoded_id_content = encode_content_multi(id_content, options, obs_handler)
    resp = @backend.document_upsert_multi(bucket_name, @scope_name, @name, encoded_id_content, 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
end