1CBC-SUBDOC(1) CBC-SUBDOC(1)
2
6 cbc-subdoc - Interactively Inspect Document Using Subdocument API
7
9 cbc-subdoc [OPTIONS]
10
12 cbc-subdoc runs an interactive shell with commands from subdocument
13 API.
14
16 Options may be read either from the command line, or from a configura‐
17 tion file (see cbcrc(4)):
18 The following options control workload generation:
20 -U, --spec=SPEC
22 A string describing the cluster to connect to. The string is in
23 a URI-like syntax, and may also contain other options. See the
24 EXAMPLES section for information. Typically such a URI will look
25 like couchbase://host1,host2,host3/bucket.
26 The default for this option is couchbase://localhost/default
28 -u, --username=USERNAME
30 Specify the username for the bucket. Since Couchbase 5.x this is
31 mandatory switch, and it must specify the name of the user ex‐
32 isiting on cluster (read more at "Security/Authorization" sec‐
33 tion of the server manual). For older servers this field should
34 be either left empty or set to the name of the bucket itself.
35 -P, --password=PASSWORD:
37 -P -, --password=-
40 Specify the password for the bucket. As for servers before 5.x
41 this was only needed if the bucket is protected with a password.
42 For cluster version after 5.x, the password is mandatory, and
43 should match the selected account (read more at "Security/Autho‐
44 rization" section of the server manual).
45 Specifying the - as the password indicates that the program
47 should prompt for the password. You may also specify the pass‐
48 word on the commandline, directly, but is insecure as command
49 line arguments are visible via commands such as ps.
50 -T, --timings
52 Dump command timings at the end of execution. This will display
53 a histogram showing the latencies for the commands executed.
54 -v, --verbose
56 Specify more information to standard error about what the client
57 is doing. You may specify this option multiple times for in‐
58 creased output detail.
59 -D, --cparam=OPTION=VALUE
61 Provide additional client options. Acceptable options can also
62 be placed in the connection string, however this option is pro‐
63 vided as a convenience. This option may be specified multiple
64 times, each time specifying a key=value pair (for example, -Dop‐
65 eration_timeout=10 -Dconfig_cache=/foo/bar/baz). See ADDITIONAL
66 OPTIONS for more information
67 -y, --compress
69 Enable compressing of documents. When the library is compiled
70 with compression support, this option will enable Snappy com‐
71 pression for outgoing data. Incoming compressed data handled au‐
72 tomatically regardless of this option. Note, that because the
73 compression support have to be negotiated with the server, first
74 packets might be sent uncompressed even when this switch was
75 specified. This is because the library might queue data commands
76 before socket connection has been established, and the library
77 will negotiate compression feature. If it is known that all
78 server support compression repeating the switch (like -yy) will
79 force compression for all outgoing mutations, even scheduled be‐
80 fore establishing connection.
81 --truststorepath=PATH
83 The path to the server´s SSL certificate. This is typically re‐
84 quired for SSL connectivity unless the certificate has already
85 been added to the OpenSSL installation on the system (only ap‐
86 plicable with couchbases:// scheme)
87 --certpath=PATH
89 The path to the server´s SSL certificate. This is typically re‐
90 quired for SSL connectivity unless the certificate has already
91 been added to the OpenSSL installation on the system (only ap‐
92 plicable with couchbases:// scheme). This also should contain
93 client certificate when certificate authentication used, and in
94 this case other public certificates could be extracted into
95 truststorepath chain.
96 --keypath=PATH
98 The path to the client SSL private key. This is typically re‐
99 quired for SSL client certificate authentication. The certifi‐
100 cate itself have to go first in chain specified by certpath
101 (only applicable with couchbases:// scheme)
102 --dump Dump verbose internal state after operations are done.
104
106 The following options may be included in the connection string (via the
107 -U option) as URI-style query params (e.g. couchbase://host/bucket?op‐
108 tion1=value1&option2=value2) or as individual key=value pairs passed to
109 the -D switch (e.g. -Doption1=value1 -Doption2=value). The -D will in‐
110 ternally build the connection string, and is provided as a convenience
111 for options to be easily passed on the command-line
112 • operation_timeout=SECONDS: Specify the operation timeout in sec‐
114 onds. This is the time the client will wait for an operation to
115 complete before timing it out. The default is 2.5
116 • config_cache=PATH: Enables the client to make use of a file based
118 configuration cache rather than connecting for the bootstrap opera‐
119 tion. If the file does not exist, the client will first connect to
120 the cluster and then cache the bootstrap information in the file.
121 • truststorepath=PATH: The path to the server´s SSL certificate. This
123 is typically required for SSL connectivity unless the certificate
124 has already been added to the OpenSSL installation on the system
125 (only applicable with couchbases:// scheme)
126 • certpath=PATH: The path to the server´s SSL certificate. This is
128 typically required for SSL connectivity unless the certificate has
129 already been added to the OpenSSL installation on the system (only
130 applicable with couchbases:// scheme). This also should contain
131 client certificate when certificate authentication used, and in
132 this case other public certificates could be extracted into trust‐
133 storepath chain.
134 • keypath=PATH: The path to the client SSL private key. This is typi‐
136 cally required for SSL client certificate authentication. The cer‐
137 tificate itself have to go first in chain specified by certpath
138 (only applicable with couchbases:// scheme)
139 • ipv6=allow: Enable IPv6.
141 • ssl=no_verify: Temporarily disable certificate verification for SSL
143 (only applicable with couchbases:// scheme). This should only be
144 used for quickly debugging SSL functionality.
145 • sasl_mech_force=MECHANISM: Force a specific SASL mechanism to be
147 used when performing the initial connection. This should only need
148 to be modified for debugging purposes. The currently supported
149 mechanisms are PLAIN and CRAM-MD5
150 • bootstrap_on=<both,http,cccp>: Specify the bootstrap protocol the
152 client should use when attempting to connect to the cluster. Op‐
153 tions are: cccp: Bootstrap using the Memcached protocol (supported
154 on clusters 2.5 and greater); http: Bootstrap using the HTTP REST
155 protocol (supported on any cluster version); and both: First at‐
156 tempt bootstrap over the Memcached protocol, and use the HTTP pro‐
157 tocol if Memcached bootstrap fails. The default is both
158 • enable_tracing=true/false: Activate/deactivate end-to-end tracing.
160 • tracing_orphaned_queue_flush_interval=SECONDS: Flush interval for
162 orphaned spans queue in default tracer. This is the time the tracer
163 will wait between repeated attempts to flush most recent orphaned
164 spans. Default value is 10 seconds.
165 • tracing_orphaned_queue_size=NUMBER: Size of orphaned spans queue in
167 default tracer. Queues in default tracer has fixed size, and it
168 will remove information about older spans, when the limit will be
169 reached before flushing time. Default value is 128.
170 • tracing_threshold_queue_flush_interval=SECONDS: Flush interval for
172 spans with total time over threshold in default tracer. This is the
173 time the tracer will wait between repeated attempts to flush
174 threshold queue. Default value is 10 seconds.
175 • tracing_threshold_queue_size=NUMBER: Size of threshold queue in de‐
177 fault tracer. Queues in default tracer has fixed size, and it will
178 remove information about older spans, when the limit will be
179 reached before flushing time. Default value is 128.
180 • tracing_threshold_kv=SECONDS: Minimum time for the tracing span of
182 KV service to be considered by threshold tracer. Default value is
183 0.5 seconds.
184 • tracing_threshold_query=SECONDS: Minimum time for the tracing span
186 of QUERY service to be considered by threshold tracer. Default
187 value is 1 second.
188 • tracing_threshold_view=SECONDS: Minimum time for the tracing span
190 of VIEW service to be considered by threshold tracer. Default value
191 is 1 second.
192 • tracing_threshold_search=SECONDS: Minimum time for the tracing span
194 of SEARCH service to be considered by threshold tracer. Default
195 value is 1 second.
196 • tracing_threshold_analytics=SECONDS: Minimum time for the tracing
198 span of ANALYTICS service to be considered by threshold tracer. De‐
199 fault value is 1 second.
200
204 help
205 Show list of accessible commands with short help.
206 LOOKUP COMMANDS
208 The following options are supported for lookup commands:
209 • -?, --help: Display built-in help
211 • -p, --path PATH: JSON path in the document. Read more about paths
213 in the documentation https://developer.couchbase.com/documenta‐
214 tion/server/current/n1ql/n1ql-intro/queriesan‐
215 dresults.html#story-h2-2.
216 • -x, --xattr PATH: JSON path in the extended attributes.
218 • -d, --deleted Access XATTR attributes of deleted documents.
220 get
224 get [OPTIONS...] KEY...
225 Retrieve path from the item on the server.
227 This command requires that at least one key passed to it. If no paths
229 are specified, it will fetch full document.
230 exists
232 exists [OPTIONS...] KEY...
233 Check if path exists in the item on the server.
235 This command requires that at least one key and one path are passed to
237 it. Command has alias exist.
238 size
240 size [OPTIONS...] KEY...
241 Count the number of elements in an array or dictionary. The command has
243 alias get-count.
244 This command requires that at least one key and one path passed to it.
246 MUTATION COMMANDS
248 The mutation commands below support the following options:
249 -x, --xattr PATH=VALUE
251 Store XATTR path (exentnded attributes).
252 -p, --path PATH=VALUE
254 JSON path in the document. Read more about paths in the documen‐
255 tation https://developer.couchbase.com/documentation/server/cur‐
256 rent/n1ql/n1ql-intro/queriesandresults.html#story-h2-2.
257 -e, --expiry TIME
259 Expiration time in seconds. Relative (up to 30 days) or absolute
260 (as Unix timestamp).
261 -i, --intermediates
263 Create intermediate paths [Default=FALSE].
264 -u, --upsert
266 Create document if it does not exist [Default=FALSE].
267 replace
269 replace [OPTIONS...] KEY...
270 Replace the value at the specified path.
272 dict-add
274 dict-add [OPTIONS...] KEY...
275 Add the value at the given path, if the given path does not exist.
277 dict-upsert
279 dict-upsert [OPTIONS...] KEY...
280 Unconditionally set the value at the path.
282 array-add-first
284 array-add-first [OPTIONS...] KEY...
285 Prepend the value(s) to the array. All array operations may accept mul‐
287 tiple objects. See examples below.
288 array-add-last
290 array-add-last [OPTIONS...] KEY...
291 Append the value(s) to the array.
293 array-add-unique
295 array-add-unique [OPTIONS...] KEY...
296 Add the value to the array indicated by the path, if the value is not
298 already in the array.
299 array-insert
301 array-insert [OPTIONS...] KEY...
302 Add the value at the given array index. Path must include index, e.g.
304 my.list[4]
305 counter
307 Increment or decrement an existing numeric path. The value must be
308 64-bit integer.
309 set
311 set [OPTIONS...] KEY VALUE
312 Store document on the server.
314 This command requires exactly two argument, key and value. Command has
316 alias upsert. If no XATTR specified, the command will add its version
317 to the path _cbc.version.
318 -x, --xattr PATH=VALUE
320 Store XATTR path (exentnded attributes)
321 -e, --expiry TIME
323 Expiration time in seconds. Relative (up to 30 days) or absolute
324 (as Unix timestamp)
325 remove
327 remove [OPTIONS...] KEY...
328 Remove path in the item on the server.
330 This command requires at least one key. If no paths specified, it will
332 remove whole document.
333 -p, --path PATH
335 JSON path in the document. Read more about paths in the documen‐
336 tation https://developer.couchbase.com/documentation/server/cur‐
337 rent/n1ql/n1ql-intro/queriesandresults.html#story-h2-2.
338 -x, --xattr PATH
340 JSON path in the extended attributes.
341
343 Connect to the server and wait for commands:
344 cbc subdoc -u Administrator -P password -U couchbase://192.168.33.101/a_bucket
348 subdoc>
349 Create new document foo with empty JSON document:
353 subdoc> upsert foo {}
357 foo CAS=0x14d766f19a720000
358 Fetch document with virtual XATTR, containing its metadata:
362 subdoc> get -x $document foo
366 foo CAS=0x14d766f19a720000
367 0. Size=194, RC=0x00 Success (Not an error)
368 {"CAS":"0x14d766f19a720000","vbucket_uuid":"0x0000ef56295d9206",
369 "seqno":"0x0000000000000021","exptime":0,"value_bytes":2,
370 "datatype":["json","xattr"],"deleted":false,"last_modified":"1501782188"}
371 1. Size=2, RC=0x00 Success (Not an error)
372 {}
373 Increment counter with path site.hits twice and set document expiration
377 to 5 seconds. Note that it sends -i option to create site JSON object
378 automatically:
379 subdoc> counter -e 5 -i -p site.hits=1 foo
383 foo CAS=0x14d76764f3b60000
384 0. Size=1, RC=0x00 Success (Not an error)
385 1
386 subdoc> counter -e 5 -p site.hits=1 foo
387 foo CAS=0x14d76765ea2b0000
388 0. Size=1, RC=0x00 Success (Not an error)
389 2
390 subdoc> get foo
391 foo CAS=0x14d76765ea2b0000
392 0. Size=19, RC=0x00 Success (Not an error)
393 {"site":{"hits":2}}
394 ... wait for 5 seconds ...
396 subdoc> get foo
398 foo The key does not exist on the server (0xd)
399 Add into array at path ratings value 5. Note, that switch -u will ask
403 server to create the document if it does not exist:
404 subdoc> array-add-first -u -p ratings=5 foo
408 foo CAS=0x14d76814fbb00000
409 0. Size=0, RC=0x00 Success (Not an error)
410 subdoc> get foo
411 foo CAS=0x14d76814fbb00000
412 0. Size=15, RC=0x00 Success (Not an error)
413 {"ratings":[5]}
414 Add several objects at once into ratings array:
418 subdoc> array-add-last -p ratings=4,6,7 foo
422 foo CAS=0x14d7687097c50000
423 0. Size=0, RC=0x00 Success (Not an error)
424 subdoc> get foo
425 foo CAS=0x14d7687097c50000
426 0. Size=21, RC=0x00 Success (Not an error)
427 {"ratings":[5,4,6,7]}
428 Remove rating with index 2 in array (third number):
432 subdoc> remove -p ratings[2] foo
436 foo CAS=0x14d76885efd90000
437 0. Size=0, RC=0x00 Success (Not an error)
438 subdoc> get foo
439 foo CAS=0x14d76885efd90000
440 0. Size=19, RC=0x00 Success (Not an error)
441 {"ratings":[5,4,7]}
442 Insert new rating instead of removed one:
446 subdoc> array-insert -p ratings[2]=10 foo
450 foo CAS=0x14d768a6daee0000
451 0. Size=0, RC=0x00 Success (Not an error)
452 subdoc> get foo
453 foo CAS=0x14d768a6daee0000
454 0. Size=22, RC=0x00 Success (Not an error)
455 {"ratings":[5,4,10,7]}
456 Fetch number of the items in the ratings array:
460 subdoc> size -p ratings foo
464 foo CAS=0x14d768a6daee0000
465 0. Size=1, RC=0x00 Success (Not an error)
466 4
467 Create document with spaces (surround the value with single quotes, and
471 escape inner single quotes with backslash \):
472 subdoc> upsert bar ´{"text": "hello world"}´
476 bar CAS=0x14d768bc25270000
477 subdoc> get bar
478 bar CAS=0x14d768bc25270000
479 0. Size=23, RC=0x00 Success (Not an error)
480 {"text": "hello world"}
481
485 Port tool to Windows platform. Currently linenoise only supports
486 UNIX-like systems, but there are unofficial patches for Windows.
487
489 This command´s options should be considered uncommitted and are subject
490 to change.
491
493 cbc(1), cbcrc(4), https://developer.couchbase.com/documenta‐
494 tion/server/current/developer-guide/sub-doc-api.html
495
497 The cbc-subdoc tool was first introduced in libcouchbase 2.7.7.
498 April 2019 CBC-SUBDOC(1)