Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CBC-SUBDOC(1)							 CBC-SUBDOC(1)

NAME
       cbc-subdoc - Interactively Inspect Document Using Subdocument API

SYNOPSIS
       cbc-subdoc [OPTIONS]

DESCRIPTION
       cbc-subdoc  runs	 an  interactive  shell	with commands from subdocument
       API.

OPTIONS
       Options may be read either from the command line, or from a  configura-
       tion file (see cbcrc(4)):

       The following options control workload generation:

       -U, --spec=SPEC
	      A	 string	describing the cluster to connect to. The string is in
	      a	URI-like syntax, and may also contain other options.  See  the
	      EXAMPLES section for information.	Typically such a URI will look
	      like couchbase://host1,host2,host3/bucket.

	      The default for this option is couchbase://localhost/default

       -u, --username=USERNAME
	      Specify the username for the bucket. Since Couchbase 5.x this is
	      mandatory	 switch,  and it must specify the name of the user ex-
	      isiting on cluster (read more at	"Security/Authorization"  sec-
	      tion  of the server manual). For older servers this field	should
	      be either	left empty or set to the name of the bucket itself.

       -P, --password=PASSWORD:

       -P -, --password=-
	      Specify the password for the bucket. As for servers  before  5.x
	      this was only needed if the bucket is protected with a password.
	      For cluster version after	5.x, the password  is  mandatory,  and
	      should match the selected	account	(read more at "Security/Autho-
	      rization"	section	of the server manual).

	      Specifying the - as the  password	 indicates  that  the  program
	      should  prompt  for the password.	You may	also specify the pass-
	      word on the commandline, directly, but is	 insecure  as  command
	      line arguments are visible via commands such as ps.

       -T, --timings
	      Dump  command timings at the end of execution. This will display
	      a	histogram showing the latencies	for the	commands executed.

       -v, --verbose
	      Specify more information to standard error about what the	client
	      is  doing.  You  may  specify this option	multiple times for in-
	      creased output detail.

       -D, --cparam=OPTION=VALUE
	      Provide additional client	options. Acceptable options  can  also
	      be  placed in the	connection string, however this	option is pro-
	      vided as a convenience. This option may  be  specified  multiple
	      times, each time specifying a key=value pair (for	example, -Dop-
	      eration_timeout=10 -Dconfig_cache=/foo/bar/baz). See  ADDITIONAL
	      OPTIONS for more information

       -y, --compress
	      Enable  compressing  of  documents. When the library is compiled
	      with compression support,	this option will  enable  Snappy  com-
	      pression for outgoing data. Incoming compressed data handled au-
	      tomatically regardless of	this option. Note,  that  because  the
	      compression support have to be negotiated	with the server, first
	      packets might be sent uncompressed even  when  this  switch  was
	      specified. This is because the library might queue data commands
	      before socket connection has been	established, and  the  library
	      will  negotiate  compression  feature.  If  it is	known that all
	      server support compression repeating the switch (like -yy)  will
	      force compression	for all	outgoing mutations, even scheduled be-
	      fore establishing	connection.

       --truststorepath=PATH
	      The path to the server's SSL certificate.	This is	typically  re-
	      quired  for  SSL connectivity unless the certificate has already
	      been added to the	OpenSSL	installation on	the system  (only  ap-
	      plicable with couchbases:// scheme)

       --certpath=PATH
	      The  path	to the server's	SSL certificate. This is typically re-
	      quired for SSL connectivity unless the certificate  has  already
	      been  added  to the OpenSSL installation on the system (only ap-
	      plicable with couchbases:// scheme). This	 also  should  contain
	      client  certificate when certificate authentication used,	and in
	      this case	other public  certificates  could  be  extracted  into
	      truststorepath chain.

       --keypath=PATH
	      The  path	 to  the client	SSL private key. This is typically re-
	      quired for SSL client certificate	authentication.	 The  certifi-
	      cate  itself  have  to  go  first	in chain specified by certpath
	      (only applicable with couchbases:// scheme)

       --dump Dump verbose internal state after	operations are done.

ADDITIONAL OPTIONS
       The following options may be included in	the connection string (via the
       -U  option) as URI-style	query params (e.g. couchbase://host/bucket?op-
       tion1=value1&option2=value2) or as individual key=value pairs passed to
       the  -D switch (e.g. -Doption1=value1 -Doption2=value). The -D will in-
       ternally	build the connection string, and is provided as	a  convenience
       for options to be easily	passed on the command-line

       o   operation_timeout=SECONDS:  Specify	the  operation timeout in sec-
	   onds. This is the time the client will wait	for  an	 operation  to
	   complete before timing it out. The default is 2.5

       o   config_cache=PATH:  Enables	the client to make use of a file based
	   configuration cache rather than connecting for the bootstrap	opera-
	   tion.  If the file does not exist, the client will first connect to
	   the cluster and then	cache the bootstrap information	in the file.

       o   truststorepath=PATH:	The path to the	server's SSL certificate. This
	   is  typically  required for SSL connectivity	unless the certificate
	   has already been added to the OpenSSL installation  on  the	system
	   (only applicable with couchbases:// scheme)

       o   certpath=PATH:  The	path  to the server's SSL certificate. This is
	   typically required for SSL connectivity unless the certificate  has
	   already  been added to the OpenSSL installation on the system (only
	   applicable with couchbases:// scheme).  This	 also  should  contain
	   client  certificate	when  certificate  authentication used,	and in
	   this	case other public certificates could be	extracted into	trust-
	   storepath chain.

       o   keypath=PATH: The path to the client	SSL private key. This is typi-
	   cally required for SSL client certificate authentication. The  cer-
	   tificate  itself  have  to  go first	in chain specified by certpath
	   (only applicable with couchbases:// scheme)

       o   ssl=no_verify: Temporarily disable certificate verification for SSL
	   (only  applicable  with  couchbases:// scheme). This	should only be
	   used	for quickly debugging SSL functionality.

       o   sasl_mech_force=MECHANISM: Force a specific SASL  mechanism	to  be
	   used	 when performing the initial connection. This should only need
	   to be modified for  debugging  purposes.  The  currently  supported
	   mechanisms are PLAIN	and CRAM-MD5

       o   bootstrap_on=<both,http,cccp>:  Specify  the	bootstrap protocol the
	   client should use when attempting to	connect	to  the	 cluster.  Op-
	   tions  are: cccp: Bootstrap using the Memcached protocol (supported
	   on clusters 2.5 and greater); http: Bootstrap using the  HTTP  REST
	   protocol  (supported	 on  any cluster version); and both: First at-
	   tempt bootstrap over	the Memcached protocol,	and use	the HTTP  pro-
	   tocol if Memcached bootstrap	fails. The default is both

       o   enable_tracing=true/false: Activate/deactivate end-to-end tracing.

       o   tracing_orphaned_queue_flush_interval=SECONDS:  Flush  interval for
	   orphaned spans queue	in default tracer. This	is the time the	tracer
	   will	 wait  between repeated	attempts to flush most recent orphaned
	   spans. Default value	is 10 seconds.

       o   tracing_orphaned_queue_size=NUMBER: Size of orphaned	spans queue in
	   default  tracer.  Queues  in	 default tracer	has fixed size,	and it
	   will	remove information about older spans, when the limit  will  be
	   reached before flushing time. Default value is 128.

       o   tracing_threshold_queue_flush_interval=SECONDS:  Flush interval for
	   spans with total time over threshold	in default tracer. This	is the
	   time	 the  tracer  will  wait  between  repeated  attempts to flush
	   threshold queue. Default value is 10	seconds.

       o   tracing_threshold_queue_size=NUMBER:	Size of	threshold queue	in de-
	   fault  tracer. Queues in default tracer has fixed size, and it will
	   remove information about  older  spans,  when  the  limit  will  be
	   reached before flushing time. Default value is 128.

       o   tracing_threshold_kv=SECONDS:  Minimum time for the tracing span of
	   KV service to be considered by threshold tracer. Default  value  is
	   0.5 seconds.

       o   tracing_threshold_n1ql=SECONDS:  Minimum  time for the tracing span
	   of N1QL service to be considered by threshold tracer. Default value
	   is 1	second.

       o   tracing_threshold_view=SECONDS:  Minimum  time for the tracing span
	   of VIEW service to be considered by threshold tracer. Default value
	   is 1	second.

       o   tracing_threshold_fts=SECONDS: Minimum time for the tracing span of
	   FTS service to be considered	by threshold tracer. Default value  is
	   1 second.

       o   tracing_threshold_analytics=SECONDS:	 Minimum  time for the tracing
	   span	of ANALYTICS service to	be considered by threshold tracer. De-
	   fault value is 1 second.

COMMANDS
   help
       Show list of accessible commands	with short help.

   LOOKUP COMMANDS
       The following options are supported for lookup commands:

       o   -?, --help: Display built-in	help

       o   -p,	--path	PATH: JSON path	in the document. Read more about paths
	   in  the  documentation   https://developer.couchbase.com/documenta-
	   tion/server/current/n1ql/n1ql-intro/queriesan-
	   dresults.html#story-h2-2.

       o   -x, --xattr PATH: JSON path in the extended attributes.

       o   -d, --deleted Access	XATTR attributes of deleted documents.

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

       Retrieve	path from the item on the server.

       This command requires that at least one key passed to it. If  no	 paths
       are specified, it will fetch full document.

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

       Check if	path exists in the item	on the server.

       This  command requires that at least one	key and	one path are passed to
       it. Command has alias exist.

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

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

       This command requires that 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).

       -p, --path PATH=VALUE
	      JSON path	in the document. Read more about paths in the documen-
	      tation https://developer.couchbase.com/documentation/server/cur-
	      rent/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.

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

       Prepend the value(s) to the array. All array operations may accept mul-
       tiple objects. See 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, if the value	is not
       already in the array.

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

       Add the value at	the given array	index. Path must include  index,  e.g.
       my.list[4]

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

   set
       set [OPTIONS...]	KEY VALUE

       Store document on the server.

       This command requires exactly two argument, key and value. Command  has
       alias  upsert.  If no XATTR 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 path in the item on the server.

       This  command requires at least one key.	If no paths specified, it will
       remove whole document.

       -p, --path PATH
	      JSON path	in the document. Read more about paths in the documen-
	      tation https://developer.couchbase.com/documentation/server/cur-
	      rent/n1ql/n1ql-intro/queriesandresults.html#story-h2-2.

       -x, --xattr PATH
	      JSON path	in the extended	attributes.

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 -i option to create 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 switch -u  will  ask
       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 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 tool  to  Windows  platform.  Currently  linenoise	only  supports
       UNIX-like systems, but there are	unofficial patches for Windows.

INTERFACE STABILITY
       This command's options should be	considered uncommitted and are subject
       to change.

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

HISTORY
       The cbc-subdoc tool was first introduced	in libcouchbase	2.7.7.

				 October 2018			 CBC-SUBDOC(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ADDITIONAL OPTIONS | COMMANDS | EXAMPLES | TODO | INTERFACE STABILITY | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cbc-subdoc&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help