Datastructures API

New in version 2.1.1.

The datastructure API 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.

Couchbase datatypes are still JSON underneath, and use the couchbase.collection.Collection.mutate_in() and couchbase.collection.Collection.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.collection.Collection
map_add(key, mapkey, value, create=False, **kwargs)

Set a value for a key in a map.

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()

Raise

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

map_get(key, mapkey, **kwargs)

Retrieve a value from a map.

Parameters
  • key – The document ID

  • mapkey – Key within the map to retrieve

Returns

ValueResult

Raise

IndexError if the mapkey does not exist

Raise

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

See also

map_add() for an example

map_size(key, **kwargs)

Get the number of items in the map.

Parameters

key – The document ID of the map

Return int

The number of items in the map

Raise

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

See also

map_add()

map_remove(key, mapkey, **kwargs)

Remove an item from a map.

Parameters
  • key – The document ID

  • mapkey – The key in the map

:param See:meth:mutate_in for options :raise: IndexError if the mapkey does not exist :raise: couchbase.exceptions.DocumentNotFoundException if the document does not exist.

See also

map_add()

list_append(key, value, create=False, **kwargs)

Add an item to the end of a list.

Parameters
  • key – 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.DocumentNotFoundException 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, value, create=False, **kwargs)

Add an item to the beginning of a list.

Parameters
  • key – Document ID

  • value – Value to prepend

  • create – Whether the list should be created if it does not exist

  • kwargs – Additional arguments to mutate_in().

Returns

OperationResult.

Raise

couchbase.exceptions.DocumentNotFoundException 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_set(key, index, value, **kwargs)

Sets an item within a list at a given position.

Parameters
  • key – The key of the document

  • index – The position to replace

  • value – The value to be inserted

  • kwargs – Additional arguments to mutate_in()

Returns

OperationResult

Raise

couchbase.exceptions.DocumentNotFoundException if the list does not exist

Raise

IndexError if the index is out of bounds

example:

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

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.DocumentNotFoundException if the list does not exist

list_remove(key, index, **kwargs)

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.DocumentNotFoundException if the list does not exist

list_size(key, **kwargs)

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.DocumentNotFoundException if the list does not exist

set_size(key, **kwargs)

Get the length of a set.

Parameters

key – The document ID of the set

Returns

The length of the set

Raise

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

set_add(key, value, create=False, **kwargs)

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.DocumentNotFoundException if the document does not exist and create was not specified.

See also

map_add()

set_remove(key, value, **kwargs)

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.DocumentNotFoundException if the set does not exist.

See also

set_add(), map_add()

set_contains(key, value, **kwargs)

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.DocumentNotFoundException if the document does not exist

queue_push(key, value, create=False, **kwargs)

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.DocumentNotFoundException 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, **kwargs)

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.DocumentNotFoundException if the queue does not exist.

queue_size(key)

Get the length of the queue.

Parameters

key – The document ID of the queue

Returns

The length of the queue

Raise

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