NAME

cbc upsert - store document on the server

SYNOPSIS

cbc upsert [options] <id>...
cbc upsert [options] --inlined-value-separator=/ <id>/<value>...
cbc upsert (-h|--help)

DESCRIPTION

Store one or more documents on the server.

By default the document content read from the local filesystem, where <id> is the file path to the document, but the value could be embedded with the <id> and --inlined-value-separator switch.

OPTIONS

-h,--help: Print this help message and exit
--verbose: Include more context and information where it is applicable.
--bucket-name TEXT: Name of the bucket. [default: default]
--scope-name TEXT: Name of the scope. [default _default]
--collection-name TEXT: Name of the collection. [default: _default]
--inlined-value-separator TEXT: Specify value with the key instead of filesystem.
--inlined-keyspace: Extract bucket, scope, collection and key from the IDs (captures will be done with /^(.*?):(.*?)\.(.*?):(.*)$/).
--json-lines: Use JSON Lines format (https://jsonlines.org) to print results.
--preserve-expiry: Whether an existing document's expiry should be preserved. [default: 0]
--override-document-flags UINT: Override document flags instead of derived from the content.

EXPIRATION

Set expiration time for the document(s). Either --expire-relative or --expire-absolute switch is allowed.

--expire-relative INT: Expiration time in seconds from now
--expire-absolute TEXT: Absolute expiration time (format: YYYY-MM-DDTHH:MM:SS, e.g. the output of: date –utc –iso-8601=seconds –date 'next month')

DURABILITY

Extra persistency requirements. Either --durability-level or combination of --persist-to and --replicate-to switches is allowed.

--durability-level TEXT: Durability level for the server. (allowed values: none, majority, majority_and_persist_to_active, persist_to_majority)

The following switches implement client-side poll-based durability requirements.

--persist-to TEXT: Number of the nodes that have to have the document persisted. (allowed values: none, active, one, two, three, four)
--replicate-to TEXT: Number of the nodes that have to have the document replicated. (allowed values: none, one, two, three)

LOGGER OPTIONS

--log-level=LEVEL: Log level (allowed values are: trace, debug, info, warning, error, critical, off). [default: off]
--log-output=PATH: File to send logs (when is not set, logs will be written to STDERR).
--log-protocol=PATH: File to send protocol logs.

CONNECTION OPTIONS

--connection-string=STRING: Connection string for the cluster. [default: couchbase://localhost]
--username=STRING: Username for the cluster. [default: Administrator]
--password=STRING: Password for the cluster. [default: password]
--certificate-path=STRING: Path to the certificate.
--key-path=STRING: Path to the key.
--ldap-compatible: Whether to select authentication mechanism that is compatible with LDAP.
--configuration-profile=STRING: Apply configuration profile (might override other switches). (available profiles: wan_development)

SECURITY OPTIONS

--disable-tls: Whether to disable TLS.
--trust-certificate-path=STRING: Path to the trust certificate bundle.
--tls-verify-mode=MODE: Path to the certificate (allowed values: peer, none). [default: peer]

TIMEOUT OPTIONS

--bootstrap-timeout=DURATION: Timeout for overall bootstrap of the SDK. [default: 10000ms]
--connect-timeout=DURATION: Timeout for socket connection. [default: 10000ms]
--resolve-timeout=DURATION: Timeout to resolve DNS address for the sockets. [default: 2000ms]
--key-value-timeout=DURATION: Timeout for Key/Value operations. [default: 2500ms]
--key-value-durable-timeout=DURATION: Timeout for Key/Value durable operations. [default: 10000ms]
--query-timeout=DURATION: Timeout for Query service. [default: 75000ms]
--search-timeout=DURATION: Timeout for Search service. [default: 75000ms]
--eventing-timeout=DURATION: Timeout for Eventing service. [default: 75000ms]
--analytics-timeout=DURATION: Timeout for Analytics service. [default: 75000ms]
--view-timeout=DURATION: Timeout for View service. [default: 75000ms]
--management-timeout=DURATION: Timeout for management operations. [default: 75000ms]

COMPRESSION OPTIONS

--disable-compression: Whether to disable compression.
--compression-minimum-size=INTEGER: The minimum size of the document (in bytes), that will be compressed. [default: 32]
--compression-minimum-ratio=FLOAT: The minimum compression ratio to allow compressed form to be used. [default: 0.83]

DNS-SRV OPTIONS

--dns-srv-timeout=DURATION: Timeout for DNS SRV requests. [default: 500ms]
--dns-srv-nameserver=STRING: Hostname of the DNS server where the DNS SRV requests will be sent.
--dns-srv-port=INTEGER: Port of the DNS server where the DNS SRV requests will be sent.

NETWORK OPTIONS

--tcp-keep-alive-interval=DURATION: Interval for TCP keep alive. [default: 60000ms]
--config-poll-interval=DURATION: How often the library should poll for new configuration. [default: 2500ms]
--idle-http-connection-timeout=DURATION: Period to wait before calling HTTP connection idle. [default: 4500ms]

TRANSACTIONS OPTIONS

--transactions-durability-level=LEVEL: Durability level of the transaction (allowed values: none, majority, majority_and_persist_to_active, persist_to_majority). [default: majority]
--transactions-timeout=DURATION: Timeout of the transaction. [default: 15000ms]
--transactions-metadata-bucket=STRING: Bucket name where transaction metadata is stored.
--transactions-metadata-scope=STRING: Scope name where transaction metadata is stored. [default: _default]
--transactions-metadata-collection=STRING: Collection name where transaction metadata is stored. [default: _default]
--transactions-query-scan-consistency=MODE: Scan consistency for queries in transactions (allowed values: not_bounded, request_plus). [default: request_plus]
--transactions-cleanup-ignore-lost-attempts: Do not cleanup lost attempts.
--transactions-cleanup-ignore-client-attempts: Do not cleanup client attempts.
--transactions-cleanup-window=DURATION: Cleanup window. [default: 60000ms]

METRICS OPTIONS

--disable-metrics: Disable collecting and reporting metrics.
--metrics-emit-interval=DURATION: Interval to emit metrics report on INFO log level. [default: 600000ms]

TRACING OPTIONS

--disable-tracing: Disable collecting and reporting trace information.
--tracing-orphaned-emit-interval=DURATION: Interval to emit report about orphan operations. [default: 10000ms]
--tracing-orphaned-sample-size=INTEGER: Size of the sample of the orphan report. [default: 64]
--tracing-threshold-emit-interval=DURATION: Interval to emit report about operations exceeding threshold. [default: 10000ms]
--tracing-threshold-sample-size=INTEGER: Size of the sample of the threshold report. [default: 64]
--tracing-threshold-key-value=DURATION: Threshold for Key/Value service. [default: 500ms]
--tracing-threshold-query=DURATION: Threshold for Query service. [default: 1000ms]
--tracing-threshold-search=DURATION: Threshold for Search service. [default: 1000ms]
--tracing-threshold-analytics=DURATION: Threshold for Analytics service. [default: 1000ms]
--tracing-threshold-management=DURATION: Threshold for Management operations. [default: 1000ms]
--tracing-threshold-eventing=DURATION: Threshold for Eventing service. [default: 1000ms]
--tracing-threshold-view=DURATION: Threshold for View service. [default: 1000ms]

BEHAVIOR OPTIONS

--user-agent-extra=STRING: Append extra string SDK identifiers. [default: cbc].
--network=STRING: Network (a.k.a. Alternate Addresses) to use. [default: auto]
--show-queries: Log queries on INFO level.
--enable-clustermap-notifications: Allow server to send notifications when cluster configuration changes.
--disable-mutation-tokens: Do not request Key/Value service to send mutation tokens.
--disable-unordered-execution: Disable unordered execution for Key/Value service.

ENVIRONMENT

CBC_LOG_LEVEL: Overrides default value for --log-level.
CBC_CONNECTION_STRING: Overrides default value for --connection-string.
CBC_USERNAME: Overrides default value for --username.
CBC_PASSWORD: Overrides default value for --password.

EXAMPLES

Create document the default collection of the default bucket with the key myfile.json, and contents of this file on the local system:
```
cbc upsert myfile.json
```
Create document the default collection of the default bucket with the key foo, and content {"bar":42}:
```
cbc upsert --inlined-value-separator=/ foo/{"bar":42}
```

Create document in the scope myapp, collection users of the bucket accounts:

cbc upsert --bucket-name=accounts --scope-name=myapp --collection=users --inlined-value-separator=/ user_1/{"name":"john"}

All above, but inline bucket, scope, collection and value into the <id> to store two documents:

cbc upsert --inlined-keyspace --inlined-value-separator=/ \
     accounts:myapp:users:user_1/{"name":"john"} \
     accounts:myapp:users:user_2/{"name":"jane"}

Create document with expiration time of 5 seconds:
```
cbc upsert --expire-relative=5 my_file
```

Create document with abosolute expiration time in a year from now:

TIMESTAMP=$(date --utc --iso-8601=seconds --date 'next year')
# 2026-06-24T21:14:51+00:00

cbc upsert --expire-absolute=$TIMESTAMP my_file

Persist document to majority of the replica set:

cbc upsert --durability-level=majority --inlined-value-separator=/ foo/{"bar":42}

Wait until document will be persisted on at least one node from the replica set, but replicated to two nodes (and give it maximum time of 10 seconds to wait):
```
cbc upsert --key-value-timeout=10s --persist-to=one --replicate-to=two --inlined-value-separator=/ foo/{"bar":42}
```