You can use complex data structures such as dictionaries and lists in Couchbase. These data structures may be manipulated with basic operations without retrieving and storing the entire document.
- Map is like Java Map<String, Object> and is a key-value structure, where a value is accessed by using a key string.
- List is like a Java List<Object> and is a sequential data structure. Values can be placed in the beginning or end of a list, and can be accessed using numeric indexes.
- Queue is a wrapper over a list which offers FIFO (first-in-first-out) semantics, allowing it to be used as a lightweight job queue.
- Set is a wrapper over a list which provides the ability to handle unique values.
These data structures are stored as JSON documents in Couchbase, and can therefore be accessed using N1QL, Full Text Search, and normal key-value operations. Data structures can also be manipulated using the traditional sub-document and full-document KV APIs.
- Simplicity: Data structures provide high level operations by which you can deal with documents as if they were container data structures. Adding an item to a dictionary is expressed as mapAdd, rather than retrieving the entire document, modifying it locally, and then saving it back to the server.
- Efficiency: Data structure operations do not transfer the entire document across the network. Only the relevant data is exchanged between client and server, allowing for less network overhead and lower latency.
Creating a Data StructureData structures are created implicitly if they do not exist. For example, to add an item to a map, specify the document ID of the map itself (i.e. the ID which uniquely identifies the map in the server), the key within the map, and the value to store under the key:
Likewise, to create a list, specify the document ID and the value to add:
bucket.mapAdd("map_id", "name", "Mark Nunberg");
Note that if the document already exists it will not be overwritten, more elements will be pushed to the list. It is therefore always safe to use, unless your application creates data structures independently.
Data structures can be explicitly created and reset using full-document methods, and initialized with its JSON equivalent. To create a new empty list, set, or queue, use bucket.insert(JsonArrayDocument.create("list_id", JsonArray.empty()));. To create an empty map, use bucket.insert(JsonDocument.create("map_id", JsonObject.empty())); .
Accessing Data StructuresData structures can be accessed using the appropriate methods. Most data access methods will return a generic type V which is provided as a generic parameter such as Class<V>.
The same subdocument exceptions are forwarded on the datastructures API, like if the map key or list index is not found within the document. If the document itself does not exist, a com.couchbase.client.java.error.DocumentDoesNotExistException will be raised instead.
bucket.listGet("list_id", 0, String.class); // "hello" bucket.mapGet("map_id", "name", String.class); // "mark nunberg"
|mapAdd||Add a key to the map.
|mapRemove||Remove a key from a map.
|mapGet||Get an item from a map.
If the key is not found, an PathNotFoundException is raised.
|listAppend||Add an item to the end of a list.
|listPrepend||Add an item to the beginning of a list.
|listRemove||Remove a value from a list.
|listSet||Set an element at a specific index in the list.
|listGet||Get an item from a list by its index.
If the index is out of range, an PathNotFoundException will be thrown. Note that you can get the last array element by specifying -1 as the index.
|setAdd||Add an item to a set, if the item does not yet exist in the set.
Note that a set is just a list. You can retrieve the entire set by simply using a full-document get operation:
Note: Currently, you can only store primitive values in sets, such as strings, ints, and booleans.
|setContains||Check if a value exists in the set.
|setRemove||Remove an item from a set, if it exists. An exception is not thrown if the item does not exist. You can determine if an item existed or not by the return value. If the item did not exist beforehand, null is returned.
|queuePush||Add an item to the beginning of the queue.
Note that a queue is just a list. You can retrieve items from the middle of the queue by using listGet
|queuePop||Remove an item from the end queue and return it.
If the queue is empty, then null is returned.
|mapSize, listSize, setSize, queueSize||These methods get the length of the data structure. For maps, this is the number of key-value pairs inside the map. For lists, queues, and sets, this is the number of elements in the structure.
Note that there are only two basic types: map and list. Types such as queue and set are merely derivatives of list.