Item Objects

New in version 1.1.0.

The Item class is a subclass of ValueResult. It differs from its parent in that it is instantiable by the user, and can also contain fields not originally defined in the superclass (i.e. it has a __dict__ field).

These objects may be passed (via either the couchbase.items.ItemOptionDict or couchbase.items.ItemSequence containers) to any of the _multi functions of the Bucket objects.

Since the Item structure is backwards-compatible (and therefore, interchangeable) with any of the key-value subtypes of the Result object, a new Result object is not created for each operation in the returned MultiResult dictionary.

This approach allows you to maintain a persistent object representing your data locally; periodically updating it from the Couchbase server.

Using the Item collections also allows per-item options for any of the _multi methods.

Creating Items

Item objects may be created simply by calling the zero-arg constructor:

from couchbase.items import Item
it = Item()

Before an Item object can be passed to any of the Bucket methods, it must have its key set. You can simply assign the key to the object’s key property:

it.key = "some_key"

In order to store the actual item, you should assign it a value, and place it inside one of the collections mentioned before. Here we’ll use the ItemOptionDict which can also contain per-item options:

from couchbase.items import ItemOptionDict
itmdict = ItemOptionDict()

# Need to add the value:
it.value = "some string"

itmdict.add(it, format=couchbase.FMT_UTF8)

To actually store the item, you pass the collection to the upsert_multi() method, and it will function as normally:

mres = cb.set_multi(itmdict)

mres is a MultiResult object. The value for each key will now contain the Item passed originally within the collection. The normal fields including cas, flags.

Class Reference

New in version 1.1.0.