A newer version of this documentation is available.

View Latest

Hello Couchbase

This example works with the "beer-sample" bucket that is available with Couchbase Server in the "Sample Buckets" section. This bucket may be installed during installation, or later on by loading the sample bucket from the Couchbase Web Console.

To follow the tradition of programming tutorials, we’ll start with "Hello Couchbase."

hello-couchbase.py
from couchbase.bucket import Bucket
from couchbase.exceptions import CouchbaseError

c = Bucket('couchbase://localhost/beer-sample')

try:
    beer = c.get("aass_brewery-juleol")

except CouchbaseError as e:
    print "Couldn't retrieve value for key", e
    # Rethrow the exception, making the application exit
    raise

doc = beer.value

# Because Python 2.x will complain if an ASCII format string is used
# with Unicode format values, we make the format string unicode as well.


print unicode("{name}, ABV: {abv}").format(name=doc['name'], abv=doc['abv'])

doc['comment'] = "Random beer from Norway"

try:
    result = c.replace("aass_brewery-juleol", doc)
    print result

except CouchbaseError as e:
    print "Couldn't replace key"
    raise

The following points explain each step in the example:

  • Connecting

    The Bucket instance represents a connection to a single bucket within the cluster. In this example we instantiate a bucket with a connection string; this is a URI-like string which allows you to provide the location of the Couchbase cluster you are connecting to. The scheme used is couchbase, the host is localhost, and the bucket, provided as the path of the connection string, is beer-sample.

  • Retrieving Data

    The get method retrieves the document stored under the given key. If the document exists a Result object that contains the value of the key as well as additional metadata is returned. To get the actual value of the object, you can access the Result object’s value property.

    If the key does not exist on the server, an exception of type CouchbaseError is thrown. This exception object can be caught and examined or printed to see more details about why the operation failed. See the API documentation for more details.

    We treat the value as a dict object. As a documented oriented database, values stored to the server are considered to be JSON by default, and when retrieved from the server are interpreted to be JSON (and unserialized into a Python dict ). It is possible to use other formats than the default JSON, however. The upsert methods accept a format keyword argument that indicates the conversion type to be used. The default is couchbase.FMT_JSON, but you can also use couchbase.FMT_BYTES, couchbase.FMT_UTF8, or couchbase.FMT_PICKLE instead. If none of these are sufficient, you can write your own custom Transcoder object to handle conversion on your own.

    Starting from version 1.1.0, you may also use the couchbase.FMT_AUTO flag which will guess the suitable format based on the Python data type being passed.

  • Storing Data

    To store documents in the server, you can use one of the upsert family of methods. Here we use replace, which enforces the constraint that a previous value of the document must already exist. This can be thought of as an update operation in terms of CRUD (create, read, update, delete).

    The storage methods also return a Result object that contains metadata about the value stored.