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
32 exisiting 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
58 increased 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
72 automatically 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
80 before establishing connection.
81 --truststorepath=PATH
83 The path to the server´s SSL certificate. This is typically
84 required for SSL connectivity unless the certificate has already
85 been added to the OpenSSL installation on the system (only
86 applicable with couchbases:// scheme)
87 --certpath=PATH
89 The path to the server´s SSL certificate. This is typically
90 required for SSL connectivity unless the certificate has already
91 been added to the OpenSSL installation on the system (only
92 applicable 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
99 required 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. couch‐
108 base://host/bucket?option1=value1&option2=value2) or as individual
109 key=value pairs passed to the -D switch (e.g. -Doption1=value1 -Dop‐
110 tion2=value). The -D will internally build the connection string, and
111 is provided as a convenience for options to be easily passed on the
112 command-line
113 · operation_timeout=SECONDS: Specify the operation timeout in sec‐
115 onds. This is the time the client will wait for an operation to
116 complete before timing it out. The default is 2.5
117 · config_cache=PATH: Enables the client to make use of a file based
119 configuration cache rather than connecting for the bootstrap opera‐
120 tion. If the file does not exist, the client will first connect to
121 the cluster and then cache the bootstrap information in the file.
122 · truststorepath=PATH: The path to the server´s SSL certificate. This
124 is typically required for SSL connectivity unless the certificate
125 has already been added to the OpenSSL installation on the system
126 (only applicable with couchbases:// scheme)
127 · certpath=PATH: The path to the server´s SSL certificate. This is
129 typically required for SSL connectivity unless the certificate has
130 already been added to the OpenSSL installation on the system (only
131 applicable with couchbases:// scheme). This also should contain
132 client certificate when certificate authentication used, and in
133 this case other public certificates could be extracted into trust‐
134 storepath chain.
135 · keypath=PATH: The path to the client SSL private key. This is typi‐
137 cally required for SSL client certificate authentication. The cer‐
138 tificate itself have to go first in chain specified by certpath
139 (only applicable with couchbases:// scheme)
140 · ssl=no_verify: Temporarily disable certificate verification for SSL
142 (only applicable with couchbases:// scheme). This should only be
143 used for quickly debugging SSL functionality.
144 · sasl_mech_force=MECHANISM: Force a specific SASL mechanism to be
146 used when performing the initial connection. This should only need
147 to be modified for debugging purposes. The currently supported
148 mechanisms are PLAIN and CRAM-MD5
149 · bootstrap_on=<both,http,cccp>: Specify the bootstrap protocol the
151 client should use when attempting to connect to the cluster.
152 Options are: cccp: Bootstrap using the Memcached protocol (sup‐
153 ported on clusters 2.5 and greater); http: Bootstrap using the HTTP
154 REST protocol (supported on any cluster version); and both: First
155 attempt bootstrap over the Memcached protocol, and use the HTTP
156 protocol if Memcached bootstrap fails. The default is both
157 · enable_tracing=true/false: Activate/deactivate end-to-end tracing.
159 · tracing_orphaned_queue_flush_interval=SECONDS: Flush interval for
161 orphaned spans queue in default tracer. This is the time the tracer
162 will wait between repeated attempts to flush most recent orphaned
163 spans. Default value is 10 seconds.
164 · tracing_orphaned_queue_size=NUMBER: Size of orphaned spans queue in
166 default tracer. Queues in default tracer has fixed size, and it
167 will remove information about older spans, when the limit will be
168 reached before flushing time. Default value is 128.
169 · tracing_threshold_queue_flush_interval=SECONDS: Flush interval for
171 spans with total time over threshold in default tracer. This is the
172 time the tracer will wait between repeated attempts to flush
173 threshold queue. Default value is 10 seconds.
174 · tracing_threshold_queue_size=NUMBER: Size of threshold queue in
176 default tracer. Queues in default tracer has fixed size, and it
177 will remove information about older spans, when the limit will be
178 reached before flushing time. Default value is 128.
179 · tracing_threshold_kv=SECONDS: Minimum time for the tracing span of
181 KV service to be considered by threshold tracer. Default value is
182 0.5 seconds.
183 · tracing_threshold_n1ql=SECONDS: Minimum time for the tracing span
185 of N1QL service to be considered by threshold tracer. Default value
186 is 1 second.
187 · tracing_threshold_view=SECONDS: Minimum time for the tracing span
189 of VIEW service to be considered by threshold tracer. Default value
190 is 1 second.
191 · tracing_threshold_fts=SECONDS: Minimum time for the tracing span of
193 FTS service to be considered by threshold tracer. Default value is
194 1 second.
195 · tracing_threshold_analytics=SECONDS: Minimum time for the tracing
197 span of ANALYTICS service to be considered by threshold tracer.
198 Default value is 1 second.
199
203 help
204 Show list of accessible commands with short help.
205 LOOKUP COMMANDS
207 The following options are supported for lookup commands:
208 · -?, --help: Display built-in help
210 · -p, --path PATH: JSON path in the document. Read more about paths
212 in the documentation https://developer.couchbase.com/documenta‐
213 tion/server/current/n1ql/n1ql-intro/queriesan‐
214 dresults.html#story-h2-2.
215 · -x, --xattr PATH: JSON path in the extended attributes.
217 · -d, --deleted Access XATTR attributes of deleted documents.
219 get
223 get [OPTIONS...] KEY...
224 Retrieve path from the item on the server.
226 This command requires that at least one key passed to it. If no paths
228 are specified, it will fetch full document.
229 exists
231 exists [OPTIONS...] KEY...
232 Check if path exists in the item on the server.
234 This command requires that at least one key and one path are passed to
236 it. Command has alias exist.
237 size
239 size [OPTIONS...] KEY...
240 Count the number of elements in an array or dictionary. The command has
242 alias get-count.
243 This command requires that at least one key and one path passed to it.
245 MUTATION COMMANDS
247 The mutation commands below support the following options:
248 -x, --xattr PATH=VALUE
250 Store XATTR path (exentnded attributes).
251 -p, --path PATH=VALUE
253 JSON path in the document. Read more about paths in the documen‐
254 tation https://developer.couchbase.com/documentation/server/cur‐
255 rent/n1ql/n1ql-intro/queriesandresults.html#story-h2-2.
256 -e, --expiry TIME
258 Expiration time in seconds. Relative (up to 30 days) or absolute
259 (as Unix timestamp).
260 -i, --intermediates
262 Create intermediate paths [Default=FALSE].
263 -u, --upsert
265 Create document if it does not exist [Default=FALSE].
266 replace
268 replace [OPTIONS...] KEY...
269 Replace the value at the specified path.
271 dict-add
273 dict-add [OPTIONS...] KEY...
274 Add the value at the given path, if the given path does not exist.
276 dict-upsert
278 dict-upsert [OPTIONS...] KEY...
279 Unconditionally set the value at the path.
281 array-add-first
283 array-add-first [OPTIONS...] KEY...
284 Prepend the value(s) to the array. All array operations may accept mul‐
286 tiple objects. See examples below.
287 array-add-last
289 array-add-last [OPTIONS...] KEY...
290 Append the value(s) to the array.
292 array-add-unique
294 array-add-unique [OPTIONS...] KEY...
295 Add the value to the array indicated by the path, if the value is not
297 already in the array.
298 array-insert
300 array-insert [OPTIONS...] KEY...
301 Add the value at the given array index. Path must include index, e.g.
303 my.list[4]
304 counter
306 Increment or decrement an existing numeric path. The value must be
307 64-bit integer.
308 set
310 set [OPTIONS...] KEY VALUE
311 Store document on the server.
313 This command requires exactly two argument, key and value. Command has
315 alias upsert. If no XATTR specified, the command will add its version
316 to the path _cbc.version.
317 -x, --xattr PATH=VALUE
319 Store XATTR path (exentnded attributes)
320 -e, --expiry TIME
322 Expiration time in seconds. Relative (up to 30 days) or absolute
323 (as Unix timestamp)
324 remove
326 remove [OPTIONS...] KEY...
327 Remove path in the item on the server.
329 This command requires at least one key. If no paths specified, it will
331 remove whole document.
332 -p, --path PATH
334 JSON path in the document. Read more about paths in the documen‐
335 tation https://developer.couchbase.com/documentation/server/cur‐
336 rent/n1ql/n1ql-intro/queriesandresults.html#story-h2-2.
337 -x, --xattr PATH
339 JSON path in the extended attributes.
340
342 Connect to the server and wait for commands:
343 cbc subdoc -u Administrator -P password -U couchbase://192.168.33.101/a_bucket
347 subdoc>
348 Create new document foo with empty JSON document:
352 subdoc> upsert foo {}
356 foo CAS=0x14d766f19a720000
357 Fetch document with virtual XATTR, containing its metadata:
361 subdoc> get -x $document foo
365 foo CAS=0x14d766f19a720000
366 0. Size=194, RC=0x00 Success (Not an error)
367 {"CAS":"0x14d766f19a720000","vbucket_uuid":"0x0000ef56295d9206",
368 "seqno":"0x0000000000000021","exptime":0,"value_bytes":2,
369 "datatype":["json","xattr"],"deleted":false,"last_modified":"1501782188"}
370 1. Size=2, RC=0x00 Success (Not an error)
371 {}
372 Increment counter with path site.hits twice and set document expiration
376 to 5 seconds. Note that it sends -i option to create site JSON object
377 automatically:
378 subdoc> counter -e 5 -i -p site.hits=1 foo
382 foo CAS=0x14d76764f3b60000
383 0. Size=1, RC=0x00 Success (Not an error)
384 1
385 subdoc> counter -e 5 -p site.hits=1 foo
386 foo CAS=0x14d76765ea2b0000
387 0. Size=1, RC=0x00 Success (Not an error)
388 2
389 subdoc> get foo
390 foo CAS=0x14d76765ea2b0000
391 0. Size=19, RC=0x00 Success (Not an error)
392 {"site":{"hits":2}}
393 ... wait for 5 seconds ...
395 subdoc> get foo
397 foo The key does not exist on the server (0xd)
398 Add into array at path ratings value 5. Note, that switch -u will ask
402 server to create the document if it does not exist:
403 subdoc> array-add-first -u -p ratings=5 foo
407 foo CAS=0x14d76814fbb00000
408 0. Size=0, RC=0x00 Success (Not an error)
409 subdoc> get foo
410 foo CAS=0x14d76814fbb00000
411 0. Size=15, RC=0x00 Success (Not an error)
412 {"ratings":[5]}
413 Add several objects at once into ratings array:
417 subdoc> array-add-last -p ratings=4,6,7 foo
421 foo CAS=0x14d7687097c50000
422 0. Size=0, RC=0x00 Success (Not an error)
423 subdoc> get foo
424 foo CAS=0x14d7687097c50000
425 0. Size=21, RC=0x00 Success (Not an error)
426 {"ratings":[5,4,6,7]}
427 Remove rating with index 2 in array (third number):
431 subdoc> remove -p ratings[2] foo
435 foo CAS=0x14d76885efd90000
436 0. Size=0, RC=0x00 Success (Not an error)
437 subdoc> get foo
438 foo CAS=0x14d76885efd90000
439 0. Size=19, RC=0x00 Success (Not an error)
440 {"ratings":[5,4,7]}
441 Insert new rating instead of removed one:
445 subdoc> array-insert -p ratings[2]=10 foo
449 foo CAS=0x14d768a6daee0000
450 0. Size=0, RC=0x00 Success (Not an error)
451 subdoc> get foo
452 foo CAS=0x14d768a6daee0000
453 0. Size=22, RC=0x00 Success (Not an error)
454 {"ratings":[5,4,10,7]}
455 Fetch number of the items in the ratings array:
459 subdoc> size -p ratings foo
463 foo CAS=0x14d768a6daee0000
464 0. Size=1, RC=0x00 Success (Not an error)
465 4
466 Create document with spaces (surround the value with single quotes, and
470 escape inner single quotes with backslash \):
471 subdoc> upsert bar ´{"text": "hello world"}´
475 bar CAS=0x14d768bc25270000
476 subdoc> get bar
477 bar CAS=0x14d768bc25270000
478 0. Size=23, RC=0x00 Success (Not an error)
479 {"text": "hello world"}
480
484 Port tool to Windows platform. Currently linenoise only supports
485 UNIX-like systems, but there are unofficial patches for Windows.
486
488 This command´s options should be considered uncommitted and are subject
489 to change.
490
492 cbc(1), cbcrc(4), https://developer.couchbase.com/documenta‐
493 tion/server/current/developer-guide/sub-doc-api.html
494
496 The cbc-subdoc tool was first introduced in libcouchbase 2.7.7.
497 October 2018 CBC-SUBDOC(1)