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
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
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
58              increased 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
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
82       --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
88       --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
97       --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
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.    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
114       ·   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
118       ·   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
123       ·   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
128       ·   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
136       ·   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
141       ·   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
145       ·   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
150       ·   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
158       ·   enable_tracing=true/false: Activate/deactivate end-to-end tracing.
159
160       ·   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
165       ·   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
170       ·   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
175       ·   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
180       ·   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
184       ·   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
188       ·   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
192       ·   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
196       ·   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
200
201

COMMANDS

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

EXAMPLES

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

TODO

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

INTERFACE STABILITY

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

SEE ALSO

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

HISTORY

496       The cbc-subdoc tool was first introduced in libcouchbase 2.7.7.
497
498
499
500                                 October 2018                    CBC-SUBDOC(1)
Impressum