Couchbase C Client
3.3.12
Asynchronous C Client for Couchbase
|
cbc-subdoc
[OPTIONS]
cbc-subdoc
runs an interactive shell with commands from subdocument API.
Options may be read either from the command line, or from a configuration file (see cbcrc(4)):
The following options control workload generation:
@common-options.markdown@
The following options may be included in the connection string (via the -U
option) as URI-style query params (e.g. couchbase://host/bucket?option1=value1&option2=value2
) or as individual key=value pairs passed to the -D
switch (e.g. -Doption1=value1 -Doption2=value
). The -D
will internally build the connection string, and is provided as a convenience for options to be easily passed on the command-line
@common-additional-options.markdown@
Show list of accessible commands with short help.
The following options are supported for lookup commands:
-?
, --help
: Display built-in help-p
, --path
PATH: JSON path in the document. Read more about paths in the documentation.-x
, --xattr
PATH: JSON path in the extended attributes.-d
, --deleted
Access XATTR attributes of deleted documents.get
[OPTIONS...] KEY...
Retrieve path from the item on the server.
This command requires that at least one key passed to it. If no paths are specified, it will fetch full document.
exists
[OPTIONS...] KEY...
Check if path exists in the item on the server.
This command requires that at least one key and one path are passed to it. Command has alias exist
.
size
[OPTIONS...] KEY...
Count the number of elements in an array or dictionary. The command has alias get-count
.
This command requires that at least one key and one path passed to it.
The mutation commands below support the following options:
-x
, --xattr
PATH=VALUE: Store XATTR path (exentnded attributes).-p
, --path
PATH=VALUE: JSON path in the document. Read more about paths in the documentation.-e
, --expiry
TIME: Expiration time in seconds. Relative (up to 30 days) or absolute (as Unix timestamp).-i
, --intermediates
: Create intermediate paths [Default=FALSE].-u
, --upsert
: Create document if it does not exist [Default=FALSE].replace
[OPTIONS...] KEY...
Replace the value at the specified path.
dict-add
[OPTIONS...] KEY...
Add the value at the given path, if the given path does not exist.
dict-upsert
[OPTIONS...] KEY...
Unconditionally set the value at the path.
array-add-first
[OPTIONS...] KEY...
Prepend the value(s) to the array. All array operations may accept multiple objects. See examples below.
array-add-last
[OPTIONS...] KEY...
Append the value(s) to the array.
array-add-unique
[OPTIONS...] KEY...
Add the value to the array indicated by the path, if the value is not already in the array.
array-insert
[OPTIONS...] KEY...
Add the value at the given array index. Path must include index, e.g. my.list[4]
Increment or decrement an existing numeric path. The value must be 64-bit integer.
set
[OPTIONS...] KEY VALUE
Store document on the server.
This command requires exactly two argument, key and value. Command has alias upsert
. If no XATTR specified, the command will add its version to the path _cbc.version
.
-x
, --xattr
PATH=VALUE: Store XATTR path (exentnded attributes)-e
, --expiry
TIME: Expiration time in seconds. Relative (up to 30 days) or absolute (as Unix timestamp)remove
[OPTIONS...] KEY...
Remove path in the item on the server.
This command requires at least one key. If no paths specified, it will remove whole document.
-p
, --path
PATH: JSON path in the document. Read more about paths in the documentation.-x
, --xattr
PATH: JSON path in the extended attributes.Connect to the server and wait for commands:
cbc subdoc -u Administrator -P password -U couchbase://192.168.33.101/a_bucket subdoc>
Create new document foo
with empty JSON document:
subdoc> upsert foo {} foo CAS=0x14d766f19a720000
Fetch document with virtual XATTR, containing its metadata:
subdoc> get -x $document foo foo CAS=0x14d766f19a720000 0. Size=194, RC=0x00 Success (Not an error) {"CAS":"0x14d766f19a720000","vbucket_uuid":"0x0000ef56295d9206", "seqno":"0x0000000000000021","exptime":0,"value_bytes":2, "datatype":["json","xattr"],"deleted":false,"last_modified":"1501782188"} 1. Size=2, RC=0x00 Success (Not an error) {}
Increment counter with path site.hits
twice and set document expiration to 5 seconds. Note that it sends -i
option to create site
JSON object automatically:
subdoc> counter -e 5 -i -p site.hits=1 foo foo CAS=0x14d76764f3b60000 0. Size=1, RC=0x00 Success (Not an error) 1 subdoc> counter -e 5 -p site.hits=1 foo foo CAS=0x14d76765ea2b0000 0. Size=1, RC=0x00 Success (Not an error) 2 subdoc> get foo foo CAS=0x14d76765ea2b0000 0. Size=19, RC=0x00 Success (Not an error) {"site":{"hits":2}} ... wait for 5 seconds ... subdoc> get foo foo The key does not exist on the server (0xd)
Add into array at path ratings
value 5
. Note, that switch -u
will ask server to create the document if it does not exist:
subdoc> array-add-first -u -p ratings=5 foo foo CAS=0x14d76814fbb00000 0. Size=0, RC=0x00 Success (Not an error) subdoc> get foo foo CAS=0x14d76814fbb00000 0. Size=15, RC=0x00 Success (Not an error) {"ratings":[5]}
Add several objects at once into ratings
array:
subdoc> array-add-last -p ratings=4,6,7 foo foo CAS=0x14d7687097c50000 0. Size=0, RC=0x00 Success (Not an error) subdoc> get foo foo CAS=0x14d7687097c50000 0. Size=21, RC=0x00 Success (Not an error) {"ratings":[5,4,6,7]}
Remove rating with index 2 in array (third number):
subdoc> remove -p ratings[2] foo foo CAS=0x14d76885efd90000 0. Size=0, RC=0x00 Success (Not an error) subdoc> get foo foo CAS=0x14d76885efd90000 0. Size=19, RC=0x00 Success (Not an error) {"ratings":[5,4,7]}
Insert new rating instead of removed one:
subdoc> array-insert -p ratings[2]=10 foo foo CAS=0x14d768a6daee0000 0. Size=0, RC=0x00 Success (Not an error) subdoc> get foo foo CAS=0x14d768a6daee0000 0. Size=22, RC=0x00 Success (Not an error) {"ratings":[5,4,10,7]}
Fetch number of the items in the ratings
array:
subdoc> size -p ratings foo foo CAS=0x14d768a6daee0000 0. Size=1, RC=0x00 Success (Not an error) 4
Create document with spaces (surround the value with single quotes, and escape inner single quotes with backslash \
):
subdoc> upsert bar '{"text": "hello world"}' bar CAS=0x14d768bc25270000 subdoc> get bar bar CAS=0x14d768bc25270000 0. Size=23, RC=0x00 Success (Not an error) {"text": "hello world"}
Port tool to Windows platform. Currently linenoise only supports UNIX-like systems, but there are unofficial patches for Windows.
This command's options should be considered uncommitted and are subject to change.
cbc(1), cbcrc(4), https://developer.couchbase.com/documentation/server/current/developer-guide/sub-doc-api.html
The cbc-subdoc
tool was first introduced in libcouchbase 2.7.7.