CBC-SUBDOC(1)

📦 version 3.3.18, in alpine 3.24, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

🎀 NAME 🎀

okay bestie, meet cbc-subdoc — the icon that lets you interactively inspect documents using the Subdocument API. periodt.

✨ SYNOPSIS ✨

cbc-subdoc [OPTIONS]

💅 DESCRIPTION 💅

cbc-subdoc boots up an interactive shell, and inside that shell you get all the commands from the subdocument API. it's giving little REPL, big power. 🔥

🌸 OPTIONS 🌸

so the tea is: options can be read either from the command line or from a config file (peep cbcrc(4) for that one 👀):

The following options control workload generation:

@@common-options.markdown@@

🦋 ADDITIONAL OPTIONS 🦋

These ones are lowkey flexible — you can drop them into the connection string (via the -U option) as URI-style query params, like this:

couchbase://host/bucket?option1=value1&option2=value2

…or you can pass them as individual key=value pairs to the -D switch, like this:

-Doption1=value1 -Doption2=value

The -D will internally build the connection string, and honestly it exists purely as a convenience so you can yeet options onto the command-line without drama. 🫶

@@common-additional-options.markdown@@

👑 COMMANDS 👑

💖 help

Show a list of accessible commands, each with a short help blurb. baby's first help. ✨

🔍 LOOKUP COMMANDS

The following options are supported for lookup commands:

🍓 get

get [OPTIONS......] KEY......

Retrieve a path from the item sitting on the server.

This command requires that at least one key is passed to it. And if you don't specify any paths, it'll just fetch the whole full document for you. generous queen. 💅

🌈 exists

exists [OPTIONS......] KEY......

Check whether a path exists in the item on the server.

This command requires at least one key AND one path passed to it. also it has an alias: exist.

🧚 size

size [OPTIONS......] KEY......

Count the number of elements in an array or a dictionary. This command has the alias get-count.

This command requires at least one key and one path passed to it.

🔥 MUTATION COMMANDS

The mutation commands below support the following options:

  • -x, --xattr PATH=VALUE — Store XATTR path (exentnded attributes). (yes bestie, that's the typo from the source, i'm not touching it 💀)
  • -p, --path PATH=VALUE — JSON path in the document. Read more about paths in the documentation at https://developer.couchbase.com/documentation/server/current/n1ql/n1ql-intro/queriesandresults.html#story-h2-2.
  • -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

replace [OPTIONS......] KEY......

Replace the value at the specified path.

🎀 dict-add

dict-add [OPTIONS......] KEY......

Add the value at the given path, if the given path does not exist.

⭐ dict-upsert

dict-upsert [OPTIONS......] KEY......

Unconditionally set the value at the path. no thoughts, just set. ✨

🌸 array-add-first

array-add-first [OPTIONS......] KEY......

Prepend the value(s) to the array. Heads up: all array operations may accept multiple objects — check the examples below.

🦋 array-add-last

array-add-last [OPTIONS......] KEY......

Append the value(s) to the array.

🍓 array-add-unique

array-add-unique [OPTIONS......] KEY......

Add the value to the array indicated by the path — but only if the value isn't already in the array.

🧚 array-insert

array-insert [OPTIONS......] KEY......

Add the value at the given array index. The path must include the index, like my.list[4].

👑 counter

Increment or decrement an existing numeric path. The value must be a 64-bit integer. 🔢

💖 set

set [OPTIONS......] KEY VALUE

Store the document on the server.

This command requires exactly two arguments: key and value. It has the alias upsert. And here's the detail: if no XATTR is 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

remove [OPTIONS......] KEY......

Remove a path in the item on the server.

This command requires at least one key. And if no paths are specified, it will remove the whole document. 💀

🌟 EXAMPLES 🌟

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 the -i option to create the 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 the switch -u will ask the 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 the 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"}

😭 TODO 😭

Port the tool to the Windows platform. Currently linenoise only supports UNIX-like systems, but there are unofficial patches for Windows. (windows girlies, we're waiting 💀)

🫶 INTERFACE STABILITY 🫶

This command's options should be considered uncommitted and are subject to change. so don't get too attached, bestie. 🙈

💜 SEE ALSO 💜

cbc(1), cbcrc(4), https://developer.couchbase.com/documentation/server/current/developer-guide/sub-doc-api.html

⭐ HISTORY ⭐

The cbc-subdoc tool was first introduced in libcouchbase 2.7.7. a legend from day one, no cap. 👑

and that's the whole page, bestie!! 🎀 this one's from the General Commands Manual, version dating back to July 2024 — go forth and inspect those documents interactively, you absolute main character 💖✨🦋

📦 where this page comes from