Module: Couchbase::Options

Defined in:
lib/couchbase/options.rb

Overview

Definition of the Option classes for data APIs

Defined Under Namespace

Classes: Analytics, Append, Base, Cluster, CouchbaseList, CouchbaseMap, CouchbaseQueue, CouchbaseSet, Decrement, Diagnostics, Exists, Get, GetAllReplicas, GetAndLock, GetAndTouch, GetAnyReplica, GetMulti, Increment, Insert, LookupIn, MutateIn, Ping, Prepend, Query, Remove, RemoveMulti, Replace, Search, Touch, Unlock, Upsert, UpsertMulti, View

Class Method Summary collapse

Class Method Details

.Analytics(**args) ⇒ Analytics

Construct Analytics options for Cluster#analytics_query

Examples:

Select name of the given user

cluster.analytics_query("SELECT u.name AS uname FROM GleambookUsers u WHERE u.id = $user_id ",
                        Options::Analytics(named_parameters: {user_id: 2}))

Returns:



2174
2175
2176
# File 'lib/couchbase/options.rb', line 2174

def Analytics(**args)
  Analytics.new(**args)
end

.Append(**args) ⇒ Append

Construct Append options for BinaryCollection#append

Examples:

Append “bar” to the content of the existing document

collection.upsert("mydoc", "foo")
collection.binary.append("mydoc", "bar", Options::Append(timeout: 3_000))
collection.get("mydoc", Options::Get(transcoder: nil)).content #=> "foobar"

Returns:



2091
2092
2093
# File 'lib/couchbase/options.rb', line 2091

def Append(**args)
  Append.new(**args)
end

.Cluster(**args) ⇒ Cluster

Construct Cluster options for Cluster.connect

Examples:

Pass authenticator object to Options

Cluster.connect("couchbase://localhost",
  Options::Cluster(authenticator: PasswordAuthenticator.new("Administrator", "password")))

Shorter version, more useful for interactive sessions

Cluster.connect("couchbase://localhost", "Administrator", "password")

Authentication with TLS client certificate (note couchbases:// schema)

Cluster.connect("couchbases://localhost?trust_certificate=/tmp/ca.pem",
  Options::Cluster(authenticator: CertificateAuthenticator.new("/tmp/certificate.pem", "/tmp/private.key")))

Returns:

See Also:



2137
2138
2139
# File 'lib/couchbase/options.rb', line 2137

def Cluster(**args)
  Cluster.new(**args)
end

.Decrement(**args) ⇒ Decrement

Construct Decrement options for BinaryCollection#decrement

Examples:

Decrement value by 2, and initialize to 100 if it does not exist

res = collection.binary.decrement("raw_counter", Options::Decrement(delta: 2, initial: 100))
res.value #=> 100
res = collection.binary.decrement("raw_counter", Options::Decrement(delta: 2, initial: 100))
res.value #=> 98

Returns:



2163
2164
2165
# File 'lib/couchbase/options.rb', line 2163

def Decrement(**args)
  Decrement.new(**args)
end

.Diagnostics(**args) ⇒ Diagnostics

Construct Diagnostics options for Cluster#diagnostics

Returns:



2110
2111
2112
# File 'lib/couchbase/options.rb', line 2110

def Diagnostics(**args)
  Diagnostics.new(**args)
end

.Exists(**args) ⇒ Exists

Construct Exists options for Collection#exists

Examples:

Check if the document exists without fetching its contents

res = collection.exists("customer123", Options::Exists(timeout: 3_000))
res.exists? #=> true

Returns:



1950
1951
1952
# File 'lib/couchbase/options.rb', line 1950

def Exists(**args)
  Exists.new(**args)
end

.Get(**args) ⇒ Get

Construct Get options for Collection#get

Examples:

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"}

Returns:



1893
1894
1895
# File 'lib/couchbase/options.rb', line 1893

def Get(**args)
  Get.new(**args)
end

.GetAllReplicas(**args) ⇒ GetAllReplicas

Returns:



1932
1933
1934
# File 'lib/couchbase/options.rb', line 1932

def GetAllReplicas(**args)
  GetAllReplicas.new(**args)
end

.GetAndLock(**args) ⇒ GetAndLock

Construct GetAndLock options for Collection#get_and_lock

Examples:

Retrieve document and lock for 10 seconds

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

Returns:



1915
1916
1917
# File 'lib/couchbase/options.rb', line 1915

def GetAndLock(**args)
  GetAndLock.new(**args)
end

.GetAndTouch(**args) ⇒ GetAndTouch

Construct GetAndTouch options for Collection#get_and_touch

Examples:

Retrieve document and prolong its expiration for 10 seconds

collection.get_and_touch("customer123", 10, Options::GetAndTouch(timeout: 3_000))

Returns:



1925
1926
1927
# File 'lib/couchbase/options.rb', line 1925

def GetAndTouch(**args)
  GetAndTouch.new(**args)
end

.GetAnyReplica(**args) ⇒ GetAnyReplica

Returns:



1939
1940
1941
# File 'lib/couchbase/options.rb', line 1939

def GetAnyReplica(**args)
  GetAnyReplica.new(**args)
end

.GetMulti(**args) ⇒ GetMulti

Construct GetMulti options for Collection#get_multi

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"

Returns:



1905
1906
1907
# File 'lib/couchbase/options.rb', line 1905

def GetMulti(**args)
  GetMulti.new(**args)
end

.Increment(**args) ⇒ Increment

Construct Increment options for BinaryCollection#increment

Examples:

Increment value by 10, and initialize to 0 if it does not exist

res = collection.binary.increment("raw_counter", Options::Increment(delta: 10, initial: 0))
res.content #=> 0
res = collection.binary.increment("raw_counter", Options::Increment(delta: 10, initial: 0))
res.content #=> 10

Returns:



2150
2151
2152
# File 'lib/couchbase/options.rb', line 2150

def Increment(**args)
  Increment.new(**args)
end

.Insert(**args) ⇒ Insert

Construct Insert options for Collection#insert

Examples:

Insert new document in collection

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

Returns:



2015
2016
2017
# File 'lib/couchbase/options.rb', line 2015

def Insert(**args)
  Insert.new(**args)
end

.LookupIn(**args) ⇒ LookupIn

Construct LookupIn options for Collection#lookup_in

Examples:

Get list of IDs of completed purchases

lookup_specs = [
  LookupInSpec::get("purchases.complete")
]
collection.lookup_in("customer123", lookup_specs, Options::LookupIn(timeout: 3_000))

Returns:



2079
2080
2081
# File 'lib/couchbase/options.rb', line 2079

def LookupIn(**args)
  LookupIn.new(**args)
end

.MutateIn(**args) ⇒ MutateIn

Construct MutateIn options for Collection#mutate_in

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))

Returns:



2066
2067
2068
# File 'lib/couchbase/options.rb', line 2066

def MutateIn(**args)
  MutateIn.new(**args)
end

.Ping(**args) ⇒ Ping

Construct Ping options for Bucket#ping

Returns:



2117
2118
2119
# File 'lib/couchbase/options.rb', line 2117

def Ping(**args)
  Ping.new(**args)
end

.Prepend(**args) ⇒ Prepend

Construct Prepend options for BinaryCollection#prepend

Examples:

Prepend “bar” to the content of the existing document

collection.upsert("mydoc", "foo")
collection.binary.prepend("mydoc", "bar", Options::Prepend(timeout: 3_000))
collection.get("mydoc", Options::Get(transcoder: nil)).content #=> "barfoo"

Returns:



2103
2104
2105
# File 'lib/couchbase/options.rb', line 2103

def Prepend(**args)
  Prepend.new(**args)
end

.Query(**args) ⇒ Query

Construct Query options for Cluster#query

Examples:

Select first ten hotels from travel sample dataset

cluster.query("SELECT * FROM `travel-sample` WHERE type = $type LIMIT 10",
              Options::Query(named_parameters: {type: "hotel"}, metrics: true))

Returns:



2185
2186
2187
# File 'lib/couchbase/options.rb', line 2185

def Query(**args)
  Query.new(**args)
end

.Remove(**args) ⇒ Remove

Construct Remove options for Collection#remove

Examples:

Remove the document in collection, but apply optimistic lock

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

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

Returns:



1988
1989
1990
# File 'lib/couchbase/options.rb', line 1988

def Remove(**args)
  Remove.new(**args)
end

.RemoveMulti(**args) ⇒ RemoveMulti

Construct RemoveMulti options for Collection#remove_multi

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]], Options::RemoveMulti(timeout: 3_000))
if res[1].error.is_a?(Error::CasMismatch)
  puts "Failed to remove the document, it might be changed by other application"
end

Returns:



2004
2005
2006
# File 'lib/couchbase/options.rb', line 2004

def RemoveMulti(**args)
  RemoveMulti.new(**args)
end

.Replace(**args) ⇒ Replace

Construct Replace options for Collection#replace

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

Returns:



2053
2054
2055
# File 'lib/couchbase/options.rb', line 2053

def Replace(**args)
  Replace.new(**args)
end

.Search(**args) ⇒ Search

Construct Search options for Cluster#search_query

Examples:

Return first 10 results of “hop beer” query and request highlighting

cluster.search_query("beer_index", Cluster::SearchQuery.match_phrase("hop beer"),
                     Options::Search(
                       limit: 10,
                       fields: %w[name],
                       highlight_style: :html,
                       highlight_fields: %w[name description]
                     ))

Returns:



2201
2202
2203
# File 'lib/couchbase/options.rb', line 2201

def Search(**args)
  Search.new(**args)
end

.Touch(**args) ⇒ Touch

Construct Touch options for Collection#touch

Examples:

Reset expiration timer for document to 30 seconds (and use custom operation timeout)

res = collection.touch("customer123", 30, Options::Touch(timeout: 3_000))

Returns:



1960
1961
1962
# File 'lib/couchbase/options.rb', line 1960

def Touch(**args)
  Touch.new(**args)
end

.Unlock(**args) ⇒ Unlock

Construct Unlock options for Collection#touch

Examples:

Lock (pessimistically) and unlock document

res = collection.get_and_lock("customer123", 10, Options::Unlock(timeout: 3_000))
collection.unlock("customer123", res.cas)

Returns:



1971
1972
1973
# File 'lib/couchbase/options.rb', line 1971

def Unlock(**args)
  Unlock.new(**args)
end

.Upsert(**args) ⇒ Upsert

Construct Upsert options for Collection#upsert

Examples:

Upsert new document in collection

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

Returns:



2026
2027
2028
# File 'lib/couchbase/options.rb', line 2026

def Upsert(**args)
  Upsert.new(**args)
end

.UpsertMulti(**args) ⇒ UpsertMulti

Construct UpsertMulti options for Collection#upsert_multi

Examples:

Upsert two documents with IDs “foo” and “bar” into a collection with expiration 20 seconds.

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

Returns:



2041
2042
2043
# File 'lib/couchbase/options.rb', line 2041

def UpsertMulti(**args)
  UpsertMulti.new(**args)
end

.View(**args) ⇒ View

Construct View options for Bucket#view_query

Examples:

Make sure the view engine catch up with all mutations and return keys starting from [“random_brewery:”]

bucket.view_query("beer", "brewery_beers",
                  Options::View(
                    start_key: ["random_brewery:"],
                    scan_consistency: :request_plus
                  ))

Returns:



2215
2216
2217
# File 'lib/couchbase/options.rb', line 2215

def View(**args)
  View.new(**args)
end