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
(self, key, mapkey, value, create=False, **kwargs)¶ 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()
orlookup_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_core.exceptions.NotFoundError
if the document does not exist. and create was not specified
-
map_get
(self, key, mapkey)¶ 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_core.exceptions.NotFoundError
if the document does not exist.
See also
map_add()
for an example
-
map_size
(self, key)¶ 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_core.exceptions.NotFoundError
if the document does not exist.
See also
-
map_remove
(self, key, mapkey, **kwargs)¶ 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_core.exceptions.NotFoundError
if the document does not exist.
See also
-
list_append
(self, key, value, create=False, **kwargs)¶ 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_core.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
-
list_prepend
(self, key, value, create=False, **kwargs)¶ 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_core.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 itemSee also
-
list_set
(self, 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_core.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_set('a_list', 1, 'good') cb.get('a_list').value # => ['hello', 'good']
See also
-
list_get
(self, key, index)¶ 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_core.exceptions.NotFoundError
if the list does not exist
-
list_remove
(self, 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_core.exceptions.NotFoundError
if the list does not exist
-
list_size
(self, key)¶ 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_core.exceptions.NotFoundError
if the list does not exist
-
set_size
(self, key)¶ Get the length of a set.
- Parameters
key – The document ID of the set
- Returns
The length of the set
- Raise
couchbase_core.exceptions.NotFoundError
if the set does not exist.
-
set_add
(self, 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_core.exceptions.NotFoundError
if the document does not exist and create was not specified.
See also
-
set_remove
(self, 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_core.exceptions.NotFoundError
if the set does not exist.
-
set_contains
(self, key, value)¶ 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_core.exceptions.NotFoundError
if the document does not exist
-
queue_push
(self, 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_core.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
(self, 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_core.exceptions.QueueEmpty
if there are no items in the queue.- Raise
couchbase_core.exceptions.NotFoundError
if the queue does not exist.
-
queue_size
(self, key)¶ Get the length of the queue.
- Parameters
key – The document ID of the queue
- Returns
The length of the queue
- Raise
couchbase_core.exceptions.NotFoundError
if the queue does not exist.
-