Cluster object

class couchbase.cluster.Cluster

class couchbase.cluster.ClusterOptions

class couchbase.cluster.CertAuthenticator

class couchbase.cluster.PasswordAuthenticator

Bucket object

class couchbase.bucket.Bucket

To open a bucket, you want to use the Cluster.

class couchbase.cluster.Cluster

Scope object

class couchbase.collection.Scope

Collection object

class couchbase.collection.Collection

Used internally by the SDK. This constructor is not intended for external use.

Passing Arguments

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)

Option Blocks

class couchbase.options.OptionBlock

class couchbase.options.OptionBlockTimeOut

class couchbase.collection.AppendOptions

class couchbase.collection.DecrementOptions

class couchbase.collection.ExistsOptions

class couchbase.collection.GetAllReplicasOptions

class couchbase.collection.GetAndLockOptions

class couchbase.collection.GetAndTouchOptions

class couchbase.collection.GetAnyReplicaOptions

class couchbase.collection.GetOptions

class couchbase.collection.IncrementOptions

class couchbase.collection.InsertOptions

class couchbase.collection.LookupInOptions

class couchbase.collection.PrependOptions

class couchbase.collection.RemoveOptions

class couchbase.collection.ReplaceOptions

class couchbase.collection.TouchOptions

class couchbase.collection.UnlockOptions

class couchbase.collection.UpsertOptions

Integer Types

Key and Value Format

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.

Format Options

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.

couchbase.FMT_JSON

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

couchbase.FMT_PICKLE

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)

couchbase.FMT_BYTES

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.

couchbase.FMT_UTF8

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 ValueFormatException is thrown).

Values with FMT_UTF8 are retrieved as unicode objects (for Python 3 unicode objects are plain str objects).

couchbase.FMT_AUTO

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.

Key Format

The above format options are only valid for values being passed to one of the storage methods (see couchbase.collection.Collection.upsert()).

For keys, the acceptable inputs are those for FMT_UTF8

Single-Key Data Methods

These methods all return a Result object containing information about the operation (such as status and value).

Storing Data

class couchbase.collection.Collection

These methods set the contents of a key in Couchbase. If successful, they replace the existing contents (if any) of the key.

Retrieving Data

class couchbase.collection.Collection

Modifying Data

These methods modify existing values in Couchbase

class couchbase.collection.BinaryCollection

Entry Operations

These methods affect an entry in Couchbase. They do not directly modify the value, but may affect the entry’s accessibility or duration.

class couchbase.collection.Collection

Sub-Document Operations

These methods provide entry points to modify parts of a document in Couchbase.

Note

Sub-Document API methods are available in Couchbase Server 4.5 (currently in Developer Preview).

The server and SDK implementations and APIs are subject to change

class couchbase.collection.Collection

Counter Operations

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 couchbase.collection.Collection.get() method

class couchbase.options.SignedInt64

class couchbase.collection.DeltaValue

class couchbase.collection.BinaryCollection

Multi-Key Data Methods

These methods tend to be more efficient than their single-key equivalents. They return a couchbase.result.MultiResultBase object (which is a dict subclass) which contains class:couchbase.result.Result objects as the values for its keys

class couchbase.collection.Collection

class couchbase.collection.BinaryCollection

Batch Operation Pipeline

Warning

The APIs below are from SDK2 and currently only available from the couchbase_v2 legacy support package. We plan to update these to support SDK3 shortly.

In addition to the multi methods, you may also use the Pipeline context manager to schedule multiple operations of different types

class couchbase_v2.bucket.Bucket

class couchbase_v2.bucket.Pipeline

MapReduce/View Methods

class couchbase.bucket.Bucket

N1QL Query Methods

class couchbase.cluster.Cluster

Full-Text Search Methods

class couchbase.cluster.Cluster

Analytics Query Methods

class couchbase.cluster.Cluster

Design Document Management

To perform design document management operations, you must first get an instance of the ViewIndexManager. You can do this by invoking the views() method on the Bucket object.

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.

class couchbase.management.views.ViewIndexManager

N1QL Index Management

Before issuing any N1QL query using query(), the bucket being queried must have an index defined for the query. The simplest index is the primary index.

To create a primary index, use:

mgr.create_primary_index('bucket_name', CreatePrimaryQueryIndexOptions(ignore_if_exists=True))

You can create additional indexes using:

mgr.create_index('bucket_name', 'idx_foo', fields=['foo'])

class couchbase.management.queries.QueryIndexManager

class couchbase.bucket..Bucket

Flushing (clearing) the Bucket

For some stages of development and/or deployment, it might be useful to be able to clear the bucket of its contents.

class couchbase.management.buckets.BucketManager

Informational Methods

Warning

The APIs below are from SDK2 and currently only available from the couchbase_v2 legacy support package. We plan to update these to support SDK3 shortly.

These methods do not operate on keys directly, but offer various information about things

class couchbase_core.client.Client

Item API Methods

Warning

The APIs below are from SDK2 and currently only available from the couchbase_v2 legacy support package. We plan to update these to support SDK3 shortly.

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

class couchbase_v2.bucket.Bucket

Durability Constraints

Durability constraints ensure safer protection against data loss.

class couchbase.durability.DurabilityOptionBlock

class couchbase.durability.ClientDurability

class couchbase.durability.ClientDurableOptionBlock

class couchbase.durability.ServerDurableOptionBlock

class couchbase.durability.DurabilityType

class couchbase.durability.ServerDurability

Attributes

class couchbase.bucket.Bucket

default_format

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

format_info and data_passthrough

quiet

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.NotFoundException exceptions. When set to True the operations will not raise an exception, but still set an error inside the Result object.

class couchbase.cluster.Cluster

Private APIs

class couchbase_core.client.Client

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.

Additional Connection Options

This section is intended to document some of the less common connection options and formats of the connection string (see couchbase.cluster.Cluster.__init__()).

Using Custom Ports

If you require to connect to an alternate port for bootstrapping the client (either because your administrator has configured the cluster to listen on alternate ports, or because you are using the built-in cluster_run script provided with the server source code), you may do so in the host list itself.

Simply provide the host in the format of host:port.

Note that the port is dependent on the scheme used. In this case, the scheme dictates what specific service the port points to.

Scheme	Protocol
couchbase	memcached port (default is 11210)
couchbases	SSL-encrypted memcached port (default is 11207)
http	REST API/Administrative port (default is 8091)

Options in Connection String

Additional client options may be specified within the connection string itself. These options are derived from the underlying libcouchbase library and thus will accept any input accepted by the library itself. The following are some influential options:

• config_total_timeout. Number of seconds to wait for the client bootstrap to complete.

• config_node_timeout. Maximum number of time to wait (in seconds) to attempt to bootstrap from the current node. If the bootstrap times out (and the config_total_timeout setting is not reached), the bootstrap is then attempted from the next node (or an exception is raised if no more nodes remain).

• config_cache. If set, this will refer to a file on the filesystem where cached “bootstrap” information may be stored. This path may be shared among multiple instance of the Couchbase client. Using this option may reduce overhead when using many short-lived instances of the client.

  If the file does not exist, it will be created.