Datastructures API

New in version 2.1.1.

The datastructure API is a new experimental API added which allows your application to view Couchbase documents as common data structures such as lists, maps, and queues.

Datastructure operations are implemented largely using couchbase.subdocument operations, and also carry with some more efficiency.

Warning

The data structure API is currently experimental. The API may change or be removed entirely.

In order to use this API you must first enable experimental functionality:

import couchbase.experimental
couchbase.experimental.enable()

Couchbase datatypes are still JSON underneath, and use the couchbase.bucket.Bucket.mutate_in() and couchbase.bucket.Bucket.lookup_in() methods to access the structures themselves.

The datastructures are:

  • Map: This is similar to a Python dict. It is represented as a JSON object (i.e. {}). Maps can be manipulated using the map_* methods below.
  • List: This is similar to a Python list. It is represented as a JSON array ([]). Lists can be accessed using the list_* methods below.
  • Set: This is like a List, but also contains methods allowing to avoid inserting duplicates. All List methods may be used on Sets, and vice versa. Sets can be accessed using the set_* methods below, as well as various list_* methods.
  • Queues: This is like a list, but also features a queue_pop method which can make it suitable for a light weight FIFO queue. You can access queues using the queue_* methods below.

Note

Datastructures are just JSON documents and can be accessed using any of the full-document (e.g. upsert() and get()) or sub-document (e.g. lookup_in() and mutate_in()) methods.

class couchbase.bucket.Bucket[source]
map_add(key, *args, **kwargs)[source]

Set a value for a key in a map.

Warning

The functionality of the various map_*, list_*, queue_* and set_* functions are considered experimental and are included in the library to demonstrate new functionality. They may change in the future or be removed entirely!

These functions are all wrappers around the mutate_in() or lookup_in() methods.

Parameters:
  • key – The document ID of the map
  • mapkey – The key in the map to set
  • value – The value to use (anything serializable to JSON)
  • create – Whether the map should be created if it does not exist
  • kwargs – Additional arguments passed to mutate_in()
Returns:

A OperationResult

Raise:

couchbase.exceptions.NotFoundError if the document does not exist. and create was not specified

map_get(key, *args, **kwargs)[source]

Retrieve a value from a map.

Parameters:
  • key (str) – The document ID
  • mapkey (str) – Key within the map to retrieve
Returns:

ValueResult

Raise:

IndexError if the mapkey does not exist

Raise:

couchbase.exceptions.NotFoundError if the document does not exist.

See also

map_add() for an example

map_length(key, *args, **kwargs)[source]

Get the number of items in the map.

Parameters:key (str) – The document ID of the map
Return int:The number of items in the map
Raise:couchbase.exceptions.NotFoundError if the document does not exist.

See also

map_add()

map_remove(key, *args, **kwargs)[source]

Remove an item from a map.

Parameters:
  • key (str) – The document ID
  • mapkey (str) – The key in the map
  • kwargs – See mutate_in() for options
Raise:

IndexError if the mapkey does not exist

Raise:

couchbase.exceptions.NotFoundError if the document does not exist.

See also

map_add()

list_append(key, *args, **kwargs)[source]

Add an item to the end of a list.

Parameters:
  • key (str) – The document ID of the list
  • value – The value to append
  • create – Whether the list should be created if it does not exist. Note that this option only works on servers >= 4.6
  • kwargs – Additional arguments to mutate_in()
Returns:

OperationResult.

Raise:

couchbase.exceptions.NotFoundError if the document does not exist. and create was not specified.

example:

cb.list_append('a_list', 'hello')
cb.list_append('a_list', 'world')

See also

map_add()

list_prepend(key, *args, **kwargs)[source]

Add an item to the beginning of a list.

Parameters:
  • key (str) – Document ID
  • value – Value to prepend
  • create (bool) – Whether the list should be created if it does not exist
  • kwargs – Additional arguments to mutate_in().
Returns:

OperationResult.

Raise:

couchbase.exceptions.NotFoundError if the document does not exist. and create was not specified.

This function is identical to list_append(), except for prepending rather than appending the item

list_insert(key, *args, **kwargs)[source]

Insert an item within a list at a given position.

Parameters:
  • key – The key of the document
  • index – The position at which the item should be inserted
  • value – The value to be inserted
  • kwargs – Additional arguments to mutate_in()
Returns:

OperationResult

Raise:

couchbase.exceptions.NotFoundError if the list does not exist

Raise:

IndexError if the index is out of bounds

example:

cb.upsert('a_list', ['hello', 'world'])
cb.list_insert('a_list', 1, 'good')
cb.get('a_list').value # => ['hello', 'good', 'world']
list_get(key, *args, **kwargs)[source]

Get a specific element within a list.

Parameters:
  • key – The document ID
  • index – The index to retrieve
Returns:

ValueResult for the element

Raise:

IndexError if the index does not exist

Raise:

couchbase.exceptions.NotFoundError if the list does not exist

list_remove(key, *args, **kwargs)[source]

Remove the element at a specific index from a list.

Parameters:
  • key – The document ID of the list
  • index – The index to remove
  • kwargs – Arguments to mutate_in()
Returns:

OperationResult

Raise:

IndexError if the index does not exist

Raise:

couchbase.exceptions.NotFoundError if the list does not exist

list_length(key, *args, **kwargs)[source]

Retrieve the number of elements in the list.

Parameters:key – The document ID of the list
Returns:The number of elements within the list
Raise:couchbase.exceptions.NotFoundError if the list does not exist
set_length(key)[source]

Get the length of a set.

Parameters:key – The document ID of the set
Returns:The length of the set
Raise:couchbase.exceptions.NotFoundError if the set does not exist.
set_add(key, *args, **kwargs)[source]

Add an item to a set if the item does not yet exist.

Parameters:
  • key – The document ID
  • value – Value to add
  • create – Create the set if it does not exist
  • kwargs – Arguments to mutate_in()
Returns:

A OperationResult if the item was added,

Raise:

couchbase.exceptions.NotFoundError if the document does not exist and create was not specified.

See also

map_add()

set_remove(key, *args, **kwargs)[source]

Remove an item from a set.

Parameters:
  • key – The docuent ID
  • value – Value to remove
  • kwargs – Arguments to mutate_in()
Returns:

A OperationResult if the item was removed, false otherwise

Raise:

couchbase.exceptions.NotFoundError if the set does not exist.

See also

set_add(), map_add()

set_exists(key, value)[source]

Determine if an item exists in a set :param key: The document ID of the set :param value: The value to check for :return: True if value exists in the set :raise: couchbase.exceptions.NotFoundError if the document does not exist

queue_push(key, *args, **kwargs)[source]

Add an item to the end of a queue.

Parameters:
  • key – The document ID of the queue
  • value – The item to add to the queue
  • create – Whether the queue should be created if it does not exist
  • kwargs – Arguments to pass to mutate_in()
Returns:

OperationResult

Raise:

couchbase.exceptions.NotFoundError if the queue does not exist and create was not specified.

example:

# Ensure it's removed first

cb.remove('a_queue')
cb.queue_push('a_queue', 'job9999', create=True)
cb.queue_pop('a_queue').value  # => job9999
queue_pop(key, *args, **kwargs)[source]

Remove and return the first item queue.

Parameters:
  • key – The document ID
  • kwargs – Arguments passed to mutate_in()
Returns:

A ValueResult

Raise:

couchbase.exceptions.QueueEmpty if there are no items in the queue.

Raise:

couchbase.exceptions.NotFoundError if the queue does not exist.