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.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, mapkey, value, create=False, **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()
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: Raise: couchbase.exceptions.NotFoundError
if the document does not exist. and create was not specified
-
map_get
(key, mapkey)[source]¶ Retrieve a value from a map.
Parameters: - key (str) – The document ID
- mapkey (str) – Key within the map to retrieve
Returns: Raise: IndexError
if the mapkey does not existRaise: couchbase.exceptions.NotFoundError
if the document does not exist.See also
map_add()
for an example
-
map_size
(key)[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_remove
(key, mapkey, **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 existRaise: couchbase.exceptions.NotFoundError
if the document does not exist.See also
-
list_append
(key, value, create=False, **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: 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
-
list_prepend
(key, value, create=False, **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 itemSee also
-
list_set
(key, index, value, **kwargs)[source]¶ 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.NotFoundError
if the list does not existRaise: IndexError
if the index is out of boundsexample:
cb.upsert('a_list', ['hello', 'world']) cb.list_set('a_list', 1, 'good') cb.get('a_list').value # => ['hello', 'good']
See also
-
list_get
(key, index)[source]¶ Get a specific element within a list.
Parameters: - key – The document ID
- index – The index to retrieve
Returns: ValueResult
for the elementRaise: IndexError
if the index does not existRaise: couchbase.exceptions.NotFoundError
if the list does not exist
-
list_remove
(key, index, **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 existRaise: couchbase.exceptions.NotFoundError
if the list does not exist
-
list_size
(key)[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_size
(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, value, create=False, **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
-
set_remove
(key, value, **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 otherwiseRaise: couchbase.exceptions.NotFoundError
if the set does not exist.
-
set_contains
(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, value, create=False, **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, **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.
-
queue_size
(key)[source]¶ Get the length of the queue.
Parameters: key – The document ID of the queue Returns: The length of the queue Raise: couchbase.exceptions.NotFoundError
if the queue does not exist.
-