1CBC-SUBDOC(1)                                                    CBC-SUBDOC(1)
2
3
4

NAME

6       cbc-subdoc - Interactively Inspect Document Using Subdocument API
7

SYNOPSIS

9       cbc-subdoc [OPTIONS]
10

DESCRIPTION

12       cbc-subdoc  runs  an  interactive  shell with commands from subdocument
13       API.
14

OPTIONS

16       Options may be read either from the command line, or from a  configura‐
17       tion file (see cbcrc(4)):
18
19       The following options control workload generation:
20
21       -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
27              The default for this option is couchbase://localhost/default
28
29       -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
36       -P, --password=PASSWORD:
37
38
39       -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
46              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
51       -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
55       -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
60       -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
68       -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
82       --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
88       --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
97       --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
103       --dump Dump verbose internal state after operations are done.
104

ADDITIONAL OPTIONS

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
113operation_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
117config_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
122truststorepath=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
127certpath=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
135keypath=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
140ipv6=allow: Enable IPv6.
141
142ssl=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
146sasl_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
151bootstrap_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
159enable_tracing=true/false: Activate/deactivate end-to-end tracing.
160
161tracing_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
166tracing_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
171tracing_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
176tracing_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
181tracing_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
185tracing_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
189tracing_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
193tracing_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
197tracing_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
201
202

COMMANDS

204   help
205       Show list of accessible commands with short help.
206
207   LOOKUP COMMANDS
208       The following options are supported for lookup commands:
209
210-?, --help: Display built-in help
211
212-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
217-x, --xattr PATH: JSON path in the extended attributes.
218
219-d, --deleted Access XATTR attributes of deleted documents.
220
221
222
223   get
224       get [OPTIONS...] KEY...
225
226       Retrieve path from the item on the server.
227
228       This command requires that at least one key passed to it. If  no  paths
229       are specified, it will fetch full document.
230
231   exists
232       exists [OPTIONS...] KEY...
233
234       Check if path exists in the item on the server.
235
236       This  command requires that at least one key and one path are passed to
237       it. Command has alias exist.
238
239   size
240       size [OPTIONS...] KEY...
241
242       Count the number of elements in an array or dictionary. The command has
243       alias get-count.
244
245       This command requires that at least one key and one path passed to it.
246
247   MUTATION COMMANDS
248       The mutation commands below support the following options:
249
250       -x, --xattr PATH=VALUE
251              Store XATTR path (exentnded attributes).
252
253       -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
258       -e, --expiry TIME
259              Expiration time in seconds. Relative (up to 30 days) or absolute
260              (as Unix timestamp).
261
262       -i, --intermediates
263              Create intermediate paths [Default=FALSE].
264
265       -u, --upsert
266              Create document if it does not exist [Default=FALSE].
267
268   replace
269       replace [OPTIONS...] KEY...
270
271       Replace the value at the specified path.
272
273   dict-add
274       dict-add [OPTIONS...] KEY...
275
276       Add the value at the given path, if the given path does not exist.
277
278   dict-upsert
279       dict-upsert [OPTIONS...] KEY...
280
281       Unconditionally set the value at the path.
282
283   array-add-first
284       array-add-first [OPTIONS...] KEY...
285
286       Prepend the value(s) to the array. All array operations may accept mul‐
287       tiple objects. See examples below.
288
289   array-add-last
290       array-add-last [OPTIONS...] KEY...
291
292       Append the value(s) to the array.
293
294   array-add-unique
295       array-add-unique [OPTIONS...] KEY...
296
297       Add  the  value to the array indicated by the path, if the value is not
298       already in the array.
299
300   array-insert
301       array-insert [OPTIONS...] KEY...
302
303       Add the value at the given array index. Path must include  index,  e.g.
304       my.list[4]
305
306   counter
307       Increment  or  decrement  an  existing  numeric path. The value must be
308       64-bit integer.
309
310   set
311       set [OPTIONS...] KEY VALUE
312
313       Store document on the server.
314
315       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
319       -x, --xattr PATH=VALUE
320              Store XATTR path (exentnded attributes)
321
322       -e, --expiry TIME
323              Expiration time in seconds. Relative (up to 30 days) or absolute
324              (as Unix timestamp)
325
326   remove
327       remove [OPTIONS...] KEY...
328
329       Remove path in the item on the server.
330
331       This  command requires at least one key. If no paths specified, it will
332       remove whole document.
333
334       -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
339       -x, --xattr PATH
340              JSON path in the extended attributes.
341

EXAMPLES

343       Connect to the server and wait for commands:
344
345
346
347           cbc subdoc -u Administrator -P password -U couchbase://192.168.33.101/a_bucket
348           subdoc>
349
350
351
352       Create new document foo with empty JSON document:
353
354
355
356           subdoc> upsert foo {}
357           foo                  CAS=0x14d766f19a720000
358
359
360
361       Fetch document with virtual XATTR, containing its metadata:
362
363
364
365           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
374
375
376       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
380
381
382           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
395           ... wait for 5 seconds ...
396
397           subdoc> get foo
398           foo                  The key does not exist on the server (0xd)
399
400
401
402       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
405
406
407           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
415
416
417       Add several objects at once into ratings array:
418
419
420
421           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
429
430
431       Remove rating with index 2 in array (third number):
432
433
434
435           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
443
444
445       Insert new rating instead of removed one:
446
447
448
449           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
457
458
459       Fetch number of the items in the ratings array:
460
461
462
463           subdoc> size -p ratings foo
464           foo                  CAS=0x14d768a6daee0000
465           0. Size=1, RC=0x00 Success (Not an error)
466           4
467
468
469
470       Create document with spaces (surround the value with single quotes, and
471       escape inner single quotes with backslash \):
472
473
474
475           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
482
483

TODO

485       Port tool  to  Windows  platform.  Currently  linenoise  only  supports
486       UNIX-like systems, but there are unofficial patches for Windows.
487

INTERFACE STABILITY

489       This command´s options should be considered uncommitted and are subject
490       to change.
491

SEE ALSO

493       cbc(1),      cbcrc(4),       https://developer.couchbase.com/documenta
494       tion/server/current/developer-guide/sub-doc-api.html
495

HISTORY

497       The cbc-subdoc tool was first introduced in libcouchbase 2.7.7.
498
499
500
501                                  April 2019                     CBC-SUBDOC(1)
Impressum