Connect to a bucket.
| Parameters: |
|
|---|---|
| Raise: | couchbase.exceptions.BucketNotFoundError if there is no such bucket to connect to couchbase.exceptions.ConnectError if the socket wasn’t accessible (doesn’t accept connections or doesn’t respond in time) couchbase.exceptions.ArgumentError if the bucket wasn’t specified |
| Returns: | instance of couchbase.connection.Connection |
Initialize connection using default options:
from couchbase import Couchbase
cb = Couchbase.connect(bucket='mybucket')
Connect to protected bucket:
cb = Couchbase.connect(password='secret', bucket='protected')
Connect to a different server on the default port 8091:
cb = Couchbase.connect(host='example.com',
password='secret', bucket='mybucket')
All keyword arguments passed to methods should be specified as keyword arguments, and the user should not rely on their position within the keyword specification - as this is subject to change.
Thus, if a function is prototyped as:
def foo(self, key, foo=None, bar=1, baz=False)
then arguments passed to foo() should always be in the form of
obj.foo(key, foo=fooval, bar=barval, baz=bazval)
and never like
obj.foo(key, fooval, barval, bazval)
Arguments passed to *_multi methods involves passing an iterable of keys. The iterable must have __len__ and __iter__ implemented.
For operations which require values (i.e. the set_multi() family), a dict must be passed with the values set as the values which should be stored for the keys.
Some of the multi methods accept keyword arguments; these arguments apply to all the keys within the iterable passed.
Starting in version 1.1.0, you can pass an ItemCollection as the keys or kv parameter. The Item interfaces allows in-place modifications to an object across multiple operations avoiding the need for copying the result into your own data structure.
See the documentation for Item for more information.
By default, keys are encoded as UTF-8, while values are encoded as JSON; which was selected to be the default for compatibility and ease-of-use with views.
The following constants may be used as values to the format option in methods where this is supported. This is also the value returned in the flags attribute of the ValueResult object from a get() operation.
Each format specifier has specific rules about what data types it accepts.
Indicates the value is to be converted to JSON. This accepts any plain Python object and internally calls json.dumps(value)(). See the Python json documentation for more information. It is recommended you use this format if you intend to examine the value in a MapReduce view function
Convert the value to Pickle. This is the most flexible format as it accepts just about any Python object. This should not be used if operating in environments where other Couchbase clients in other languages might be operating (as Pickle is a Python-specific format)
Pass the value as a byte string. No conversion is performed, but the value must already be of a bytes type. In Python 2.x bytes is a synonym for str. In Python 3.x, bytes and str are distinct types. Use this option to store “binary” data. An exception will be thrown if a unicode object is passed, as unicode objects do not have any specific encoding. You must first encode the object to your preferred encoding and pass it along as the value.
Note that values with FMT_BYTES are retrieved as byte objects.
FMT_BYTES is the quickest conversion method.
Pass the value as a UTF-8 encoded string. This accepts unicode objects. It may also accept str objects if their content is encodable as UTF-8 (otherwise a ValueFormatError is thrown).
Values with FMT_UTF8 are retrieved as unicode objects (for Python 3 unicode objects are plain str objects).
New in version 1.1.0.
Automatically determine the format of the input type. The value of this constant is an opaque object.
The rules are as follows:
If the value is a str, FMT_UTF8 is used. If it is a bytes object then FMT_BYTES is used. If it is a list, tuple or dict, bool, or None then FMT_JSON is used. For anything else FMT_PICKLE is used.
The above format options are only valid for values being passed to one of the storage methods (see couchbase.connection.Connection.set()).
For keys, the acceptable inputs are those for FMT_UTF8
These methods all return a Result object containing information about the operation (such as status and value).
These methods set the contents of a key in Couchbase. If successful, they replace the existing contents (if any) of the key.
Unconditionally store the object in Couchbase.
| Parameters: |
|
|---|---|
| Raise: | couchbase.exceptions.ArgumentError if an argument is supplied that is not applicable in this context. For example setting the CAS as a string. |
| Raise: | couchbase.exceptions.ConnectError if the connection closed |
| Raise: | couchbase.exceptions.KeyExistsError if the key already exists on the server with a different CAS value. |
| Raise: | couchbase.exceptions.ValueFormatError if the value cannot be serialized with chosen encoder, e.g. if you try to store a dictionaty in plain mode. |
| Returns: |
Simple set:
cb.set('key', 'value')
Force JSON document format for value:
cb.set('foo', {'bar': 'baz'}, format=couchbase.FMT_JSON)
Perform optimistic locking by specifying last known CAS version:
cb.set('foo', 'bar', cas=8835713818674332672)
Several sets at the same time (mutli-set):
cb.set_multi({'foo': 'bar', 'baz': 'value'})
See also
Store an object in Couchbase unless it already exists.
Follows the same conventions as set() but the value is stored only if it does not exist already. Conversely, the value is not stored if the key already exists.
Notably missing from this method is the cas parameter, this is because add will only succeed if a key does not already exist on the server (and thus can have no CAS)
| Raise: | couchbase.exceptions.KeyExistsError if the key already exists |
|---|
See also
Store an object in Couchbase only if it already exists.
Follows the same conventions as set(), but the value is stored only if a previous value already exists.
| Raise: | couchbase.exceptions.NotFoundError if the key does not exist |
|---|
See also
Obtain an object stored in Couchbase by given key.
| Parameters: |
|
|---|---|
| Raise: | couchbase.exceptions.NotFoundError if the key is missing in the bucket |
| Raise: | couchbase.exceptions.ConnectError if the connection closed |
| Raise: | couchbase.exceptions.ValueFormatError if the value cannot be deserialized with chosen decoder, e.g. if you try to retreive an object stored with an unrecognized format |
| Returns: | A Result object |
Simple get:
value = cb.get('key').value
Get multiple values:
cb.get_multi(['foo', 'bar'])
# { 'foo' : <Result(...)>, 'bar' : <Result(...)> }
Inspect the flags:
rv = cb.get("key")
value, flags, cas = rv.value, rv.flags, rv.cas
Update the expiration time:
rv = cb.get("key", ttl=10)
# Expires in ten seconds
See also
These methods modify existing values in Couchbase
Append a string to an existing value in Couchbase.
This follows the same conventions as set().
The format argument must be one of FMT_UTF8 or FMT_BYTES. If not specified, it will be FMT_UTF8 (overriding the default_format attribute). This is because JSON or Pickle formats will be nonsensical when random data is appended to them. If you wish to modify a JSON or Pickle encoded object, you will need to retrieve it (via get()), modify it, and then store it again (using set()).
Additionally, you must ensure the value (and flags) for the current value is compatible with the data to be appended. For an example, you may append a FMT_BYTES value to an existing FMT_JSON value, but an error will be thrown when retrieving the value using get() (you may still use the data_passthrough to overcome this).
| Raise: | couchbase.exceptions.NotStoredError if the key does not exist |
|---|
See also
These methods affect an entry in Couchbase. They do not directly modify the value, but may affect the entry’s accessibility or duration.
Remove the key-value entry for a given key in Couchbase.
| Parameters: |
|
|---|---|
| Raise: | couchbase.exceptions.NotFoundError if the key does not exist on the bucket |
| Raise: | couchbase.exceptions.KeyExistsError if a CAS was specified, but the CAS on the server had changed |
| Raise: | couchbase.exceptions.ConnectError if the connection was closed |
| Returns: | A Result object. |
Simple delete:
ok = cb.delete("key").success
Don’t complain if key does not exist:
ok = cb.delete("key", quiet=True)
Only delete if CAS matches our version:
rv = cb.get("key")
cb.delete("key", cas=rv.cas)
Remove multiple keys:
oks = cb.delete_multi(["key1", "key2", "key3"])
Remove multiple keys with CAS:
oks = cb.delete({
"key1" : cas1,
"key2" : cas2,
"key3" : cas3
})
See also
delete_multi(), endure() for more information on the persist_to and replicate_to options.
Lock and retrieve a key-value entry in Couchbase.
| Parameters: |
|
|---|
This function otherwise functions similarly to get(); specifically, it will return the value upon success. Note the cas value from the couchbase.result.Result object. This will be needed to unlock() the key.
Note the lock will also be implicitly released if modified by one of the set() family of functions when the valid CAS is supplied
| Raise: | couchbase.exceptions.TemporaryFailError if the key was already locked. |
|---|---|
| Raise: | See get() for possible exceptions |
Lock a key
rv = cb.lock("locked_key", ttl=5)
# This key is now locked for the next 5 seconds.
# attempts to access this key will fail until the lock
# is released.
# do important stuff...
cb.unlock("locked_key", rv.cas)
Lock a key, implicitly unlocking with set() with CAS
rv = self.cb.lock("locked_key", ttl=5)
new_value = rv.value.upper()
cb.set("locked_key", new_value, rv.cas)
Poll and Lock
rv = None
begin_time = time.time()
while time.time() - begin_time < 15:
try:
rv = cb.lock("key", ttl=10)
except TemporaryFailError:
print("Key is currently locked.. waiting")
time.sleep(1)
if not rv:
raise Exception("Waited too long..")
# Do stuff..
cb.unlock("key", rv.cas)
See also
Unlock a Locked Key in Couchbase.
| Parameters: |
|
|---|
Unlock a previously-locked key in Couchbase. A key is locked by a call to lock().
See lock() for an example.
| Raise: | couchbase.exceptions.KeyExistsError if the CAS supplied does not match the CAS on the server (possibly because it was unlocked by previous call). |
|---|
Update a key’s expiration time
| Parameters: |
|
|---|---|
| Returns: |
Update the expiration time of a key
cb.set("key", ttl=100)
# expires in 100 seconds
cb.touch("key", ttl=0)
# key should never expire now
| Raise: | The same things that get() does |
|---|
See also
get() - which can be used to get and update the expiration, touch_multi()
These are atomic counter operations for Couchbase. They increment or decrement a counter. A counter is a key whose value can be parsed as an integer. Counter values may be retrieved (without modification) using the Connection.get() method
Increment the numeric value of a key.
| Parameters: |
|
|---|---|
| Raise: | couchbase.exceptions.NotFoundError if the key does not exist on the bucket (and initial was None) |
| Raise: | couchbase.exceptions.DeltaBadvalError if the key exists, but the existing value is not numeric |
| Returns: | A couchbase.result.Result object. The current value of the counter may be obtained by inspecting the return value’s value attribute. |
Simple increment:
rv = cb.incr("key")
rv.value
# 42
Increment by 10:
ok = cb.incr("key", amount=10)
Increment by 20, set initial value to 5 if it does not exist:
ok = cb.incr("key", amount=20, initial=5)
Increment three keys:
kv = cb.incr_multi(["foo", "bar", "baz"])
for key, result in kv.items():
print "Key %s has value %d now" % (key, result.value)
See also
These methods tend to be more efficient than their single-key equivalents. They return a couchbase.result.MultiResult object (which is a dict subclass) which contains class:couchbase.result.Result objects as the values for its keys
Set multiple keys
This follows the same semantics as set()
| Parameters: |
|
|---|---|
| Returns: | A MultiResult object, which is a dict subclass. |
The multi methods are more than just a convenience, they also save on network performance by batch-scheduling operations, reducing latencies. This is especially noticeable on smaller value sizes.
See also
Get multiple keys Multi variant of get()
| Parameters: | |
|---|---|
| Returns: | A MultiResult object. This object is a subclass of dict and contains the keys (passed as) keys as the dictionary keys, and Result objects as values |
Add multiple keys. Multi variant of add()
See also
Replace multiple keys. Multi variant of replace()
See also
Append to multiple keys. Multi variant of append().
Warning
If using the Item interface, use the append_items() and prepend_items() instead, as those will automatically update the couchbase.items.Item.value property upon successful completion.
See also
Prepend to multiple keys. Multi variant of prepend()
See also
Multi-key variant of delete
Lock multiple keys
Multi variant of lock()
| Parameters: |
|
|---|---|
| Returns: | a MultiResult object |
See also
Unlock multiple keys
Multi variant of unlock()
| Parameters: | keys (dict) – the keys to unlock |
|---|---|
| Returns: | a MultiResult object |
The value of the keys argument should be either the CAS, or a previously returned Result object from a lock() call. Effectively, this means you may pass a MultiResult as the keys argument.
Thus, you can do something like
keys = (....)
rvs = cb.lock_multi(keys, ttl=5)
# do something with rvs
cb.unlock_multi(rvs)
See also
Touch multiple keys
Multi variant of touch()
| Parameters: | keys (iterable) – the keys to touch |
|---|
keys can also be a dictionary with values being integers, in whic case the value for each key will be used as the TTL instead of the global one (i.e. the one passed to this function)
| Parameters: | ttl (int) – The new expiration time |
|---|---|
| Returns: | A MultiResult object |
Update three keys to expire in 10 seconds
cb.touch_multi(("key1", "key2", "key3"), ttl=10)
Update three keys with different expiration times
cb.touch_multi({"foo" : 1, "bar" : 5, "baz" : 10})
See also
In addition to the multi methods, you may also use the Pipeline context manager to schedule multiple operations of different types
Returns a new Pipeline context manager. When the context manager is active, operations performed will return None, and will be sent on the network when the context leaves (in its __exit__ method). To get the results of the pipelined operations, inspect the Pipeline.results property.
Operational errors (i.e. negative replies from the server, or network errors) are delivered when the pipeline exits, but argument errors are thrown immediately.
| Returns: | a Pipeline object |
|---|---|
| Raise: | couchbase.exceptions.PipelineError if a pipeline is already in progress |
| Raise: | Other operation-specific errors. |
Scheduling multiple operations, without checking results:
with cb.pipeline():
cb.set("key1", "value1")
cb.incr("counter")
cb.add_multi({
"new_key1" : "new_value_1",
"new_key2" : "new_value_2"
})
Retrieve the results for several operations:
pipeline = cb.pipeline()
with pipeline:
cb.set("foo", "bar")
cb.replace("something", "value")
for result in pipeline.results:
print("Pipeline result: CAS {0}".format(result.cas))
Note
When in pipeline mode, you cannot execute view queries. Additionally, pipeline mode is not supported on async handles
Warning
Pipeline mode should not be used if you are using the same object concurrently from multiple threads. This only refers to the internal lock within the object itself. It is safe to use if you employ your own locking mechanism (for example a connection pool)
New in version 1.2.0.
Contains a list of results for each pipelined operation executed within the context. The list remains until this context is reused.
The elements in the list are either Result objects (for single operations) or MultiResult objects (for multi operations)
Query a pre-defined MapReduce view, passing parameters.
This method executes a view on the cluster. It accepts various parameters for the view and returns an iterable object (specifically, a View).
| Parameters: |
|
|---|
Note
Design document management functions are async. This means that any successful return value simply means that the operation was scheduled successfuly on the server. It is possible that the view or design will still not yet exist after creating, deleting, or publishing a design document. Therefore it may be recommended to verify that the view exists by “polling” until the view does not fail. This may be accomplished by specifying the syncwait parameter to the various design methods which accept them.
Note
The normal process for dealing with views and design docs is to first create a development design document. Such design documents are prefixed with the string dev_. They operate on a small subset of cluster data and as such are ideal for testing as they do not impact load very much.
Once you are satisfied with the behavior of the development design doc, you can publish it into a production mode design doc. Such design documents always operate on the full cluster dataset.
The view and design functions accept a use_devmode parameter which prefixes the design name with dev_ if not already prefixed.
Store a design document
| Parameters: |
|
|---|---|
| Raise: | couchbase.exceptions.TimeoutError if syncwait was specified and the operation could not be verified within the interval specified. |
| Returns: | An HttpResult object. |
See also
Retrieve a design document
| Parameters: |
|
|---|---|
| Returns: | A HttpResult containing a dict representing the format of the design document |
| Raise: | couchbase.exceptions.HTTPError if the design does not exist. |
See also
Convert a development mode view into a production mode views. Production mode views, as opposed to development views, operate on the entire cluster data (rather than a restricted subset thereof).
| Parameters: | name (string) – The name of the view to convert. |
|---|
Once the view has been converted, ensure that all functions (such as design_get()) have the use_devmode parameter disabled, otherwise an error will be raised when those functions are used.
Note that the use_devmode option is missing. This is intentional as the design document must currently be a development view.
| Returns: | An HttpResult object. |
|---|---|
| Raise: | couchbase.exceptions.HTTPError if the design does not exist |
See also
Delete a design document
| Parameters: |
|
|---|---|
| Returns: | An HttpResult object. |
| Raise: | couchbase.exceptions.HTTPError if the design does not exist |
| Raise: | couchbase.exceptions.TimeoutError if syncwait was specified and the operation could not be verified within the specified interval. |
See also
These methods do not operate on keys directly, but offer various information about things
Request server statistics Fetches stats from each node in the cluster. Without a key specified the server will respond with a default set of statistical information. It returns the a dict with stats keys and node-value pairs as a value.
| Parameters: | stats (string or list of string) – One or several stats to query |
|---|---|
| Raise: | couchbase.exceptions.ConnectError if the connection closed |
| Returns: | dict where keys are stat keys and values are host-value pairs |
Find out how many items are in the bucket:
total = 0
for key, value in cb.stats()['total_items'].items():
total += value
Get memory stats (works on couchbase buckets):
cb.stats('memory')
# {'mem_used': {...}, ...}
Get miscellaneous error information.
This function returns error information relating to the client instance. This will contain error information not related to any specific operation and may also provide insight as to what caused a specific operation to fail.
| Parameters: | clear_existing (boolean) – If set to true, the errors will be cleared once they are returned. The client will keep a history of the last 1000 errors which were received. |
|---|---|
| Returns: | a tuple of ((errnum, errdesc), ...) (which may be empty) |
Get libcouchbase version information
| Returns: | a tuple of (version_string, version_number) corresponding to the underlying libcouchbase version |
|---|
Show the versions
verstr, vernum = Connection.lcb_version()
print('0x{0:x}'.format(vernum))
# 0x020005
print(verstr)
# 2.0.5
Return storage information for a key. The observe function maps to the low-level OBSERVE command.
It returns a couchbase.result.ValueResult object with the value field set to a list of ObserveInfo objects. Each element in the list responds to the storage status for the key on the given node. The length of the list (and thus the number of ObserveInfo objects) are equal to the number of online replicas plus the master for the given key.
| Parameters: |
|
|---|
See also
These methods are specifically for the Item API. Most of the multi methods will accept Item objects as well, however there are some special methods for this interface
Method to append data to multiple Item objects.
This method differs from the normal append_multi() in that each Item‘s value field is updated with the appended data upon successful completion of the operation.
| Parameters: | items (ItemOptionDict.) – The item dictionary. The value for each key should contain a fragment field containing the object to append to the value on the server. |
|---|
The rest of the options are passed verbatim to append_multi()
See also
Method to prepend data to multiple Item objects.
See append_items() for more information
See also
Durability constraints ensure safer protection against data loss.
Wait until a key has been distributed to one or more nodes
New in version 1.1.0.
By default, when items are stored to Couchbase, the operation is considered successful if the vBucket master (i.e. the “primary” node) for the key has successfuly stored the item in its memory.
In most situations, this is sufficient to assume that the item has successfuly been stored. However the possibility remains that the “master” server will go offline as soon as it sends back the successful response and the data is lost.
The endure function allows you to provide stricter criteria for success. The criteria may be expressed in terms of number of nodes for which the item must exist in that node’s RAM and/or on that node’s disk. Ensuring that an item exists in more than one place is a safer way to guarantee against possible data loss.
We call these requirements Durability Constraints, and thus the method is called endure.
| Parameters: |
|
|---|---|
| Returns: | |
| Raise: | CouchbaseError. see set() and get() for possible errors |
See also
New in version 1.1.0.
Check durability requirements for multiple keys
| Parameters: | keys – The keys to check |
|---|
The type of keys may be one of the following:
- Sequence of keys
- A MultiResult object
- A dict with CAS values as the dictionary value
- A sequence of Result objects
| Returns: | A MultiResult object of OperationResult items. |
|---|
See also
Returns a context manager which will apply the given persistence/replication settings to all mutation operations when active
| Parameters: |
|
|---|
See endure() for the meaning of these two values
Thus, something like:
with cb.durability(persist_to=3):
cb.set("foo", "foo_value")
cb.set("bar", "bar_value")
cb.set("baz", "baz_value")
is equivalent to:
cb.set("foo", "foo_value", persist_to=3)
cb.set("bar", "bar_value", persist_to=3)
cb.set("baz", "baz_value", persist_to=3)
New in version 1.2.0.
See also
Whether to suppress errors when keys are not found (in get() and delete() operations).
An error is still returned within the Result object
The Transcoder object being used.
This is normally None unless a custom couchbase.transcoder.Transcoder is being used
When this flag is set, values are always returned as raw bytes
Whether GIL manipulation is enabeld for this connection object.
This attribute can only be set from the constructor.
The timeout value for operations, in seconds
Set the timeout for views requests, in seconds
Name of the bucket this object is connected to
Get a list of the current nodes in the cluster
Specify the default format (default: FMT_JSON) to encode your data before storing in Couchbase. It uses the flags field to store the format.
See Key and Value Format for the possible values
On a get() the original value will be returned. This means the JSON will be decoded, respectively the object will be unpickled.
See also
It controlls whether to raise an exception when the client executes operations on non-existent keys (default: False). If it is False it will raise couchbase.exceptions.NotFoundError exceptions. When set to True the operations will not raise an exception, but still set an error inside the Result object.
How access from multiple threads is handled. See Using a Connection from multiple threads for more information
The following APIs are not supported because using them is inherently dangerous. They are provided as workarounds for specific problems which may be encountered by users, and for potential testing of certain states and/or modifications which are not attainable with the public API.
Close the instance’s underlying socket resources
Note that operations pending on the connection may fail.
Interface to ‘lcb_cntl’.
This method accepts an opcode and an optional value. Constants are intentionally not defined for the various opcodes to allow saner error handling when an unknown opcode is not used.
Warning
If you pass the wrong parameters to this API call, your application may crash. For this reason, this is not a public API call. Nevertheless it may be used sparingly as a workaround for settings which may have not yet been exposed directly via a supported API
| Parameters: |
|
|---|---|
| Returns: | If no value argument is provided, retrieves the current setting (per the value_type specification). Otherwise this function returns None. |
Returns a tuple of (vbucket, server index) for a key