Options

Cluster configuration

CONFIG_PROFILES

VOLATILE This API is subject to change at any time.

ClusterMetricsOptions(**kwargs)

Available metrics options to set when creating a cluster.

ClusterOptions(authenticator, **kwargs)

Available options to set when creating a cluster.

ClusterOrphanReportingOptions(**kwargs)

Available orphan reporting options to set when creating a cluster.

ClusterTimeoutOptions(**kwargs)

Available timeout options to set when creating a cluster.

ClusterTracingOptions(**kwargs)

Available tracing options to set when creating a cluster.

Compression(value[, names, module, ...])

How the SDK compresses the data it exchanges with the server.

ConfigProfile()

VOLATILE This API is subject to change at any time.

ConfigProfiles()

VOLATILE This API is subject to change at any time.

IpProtocol(value[, names, module, qualname, ...])

Which IP version the SDK connects over.

KnownConfigProfiles(value[, names, module, ...])

VOLATILE This API is subject to change at any time.

LockMode(value[, names, module, qualname, ...])

A locking mode from the 2.x and 3.x series of the SDK, which has no meaning in 4.x.

OptionValidationMode(value[, names, module, ...])

What the SDK does with an option key a class does not carry.

TLSVerifyMode(value[, names, module, ...])

Whether the SDK verifies the certificate a server presents over TLS.

WanDevelopmentProfile()

VOLATILE This API is subject to change at any time.

couchbase.options.CONFIG_PROFILES = <couchbase.common.config_profiles.ConfigProfiles object>

VOLATILE This API is subject to change at any time.

The ConfigProfiles class is responsible for keeping track of registered/known Configuration Profiles.

class couchbase.options.ClusterMetricsOptions(**kwargs: Unpack[ClusterMetricsOptionsKwargs])

Available metrics options to set when creating a cluster.

Parameters:
  • enable_metrics (bool, optional) – Set to False to disable default logging meter (enables no-op meter). Defaults to True (enabled).

  • emit_interval (timedelta, optional) – Interval to flush the metrics operations queue.

class couchbase.options.ClusterOptions(authenticator: Authenticator, **kwargs: Unpack[ClusterOptionsKwargs])

Available options to set when creating a cluster.

Warning

couchbase.cluster.ClusterOptions is deprecated, and will be removed in a future release. Import ClusterOptions from couchbase.options.

Cluster options enable the configuration of various global cluster settings. Some options can be set globally for the cluster, but overridden for specific operations (i.e. ClusterTimeoutOptions)

Parameters:
  • authenticator (Authenticator) – An authenticator instance

  • option_validation (OptionValidationMode | str, optional) – Specifies what the SDK does with an option key a class does not carry: ignore, warn or strict. Overrides PYCBC_OPTION_VALIDATION for this cluster. A value that is none of the three raises InvalidArgumentException. Defaults to warn, or PYCBC_OPTION_VALIDATION where that is set.

  • trust_store_path (str, optional) – Path to the trust store. May also be given on the authenticator, which wins.

  • timeout_options (ClusterTimeoutOptions, optional) – Timeout options for various SDK operations. See ClusterTimeoutOptions for details.

  • orphan_reporting_options (ClusterOrphanReportingOptions, optional) – Options for SDK orphaned response reporting. See ClusterOrphanReportingOptions for details.

  • metrics_options (ClusterMetricsOptions, optional) – Options for SDK metrics. See ClusterMetricsOptions for details.

  • tracing_options (ClusterTracingOptions, optional) – Tracing options for SDK tracing bevavior. See ClusterTracingOptions for details. These are ignored if an external tracer is specified.

  • enable_tls (bool, optional) – Set to True to enable tls. Defaults to False (disabled).

  • enable_mutation_tokens (bool, optional) – Set to False to disable mutation tokens in mutation results. Defaults to True (enabled).

  • enable_tcp_keep_alive (bool, optional) – Set to False to disable tcp keep alive. Defaults to True (enabled).

  • ip_protocol (IpProtocol | str, optional) – Set IP protocol. Defaults to IpProtocol.Any.

  • enable_dns_srv (bool, optional) – Set to False to disable DNS SRV. Defaults to True (enabled).

  • show_queries (bool, optional) – Set to True to enabled showing queries. Defaults to False (disabled).

  • enable_unordered_execution (bool, optional) – Set to False to disable unordered query execution. Defaults to True (enabled).

  • enable_clustermap_notification (bool, optional) – Set to False to disable cluster map notification. Defaults to True (enabled).

  • enable_compression (bool, optional) – Set to False to disable compression. Defaults to True (enabled).

  • enable_tracing (bool, optional) – Set to False to disable default threshold log tracing (enables no-op tracer). Defaults to True (enabled).

  • enable_metrics (bool, optional) – Set to False to disable default logging meter (enables no-op meter). Defaults to True (enabled).

  • enable_orphan_reporting (bool, optional) – Set to False to disable orphaned response reporting. Defaults to True (enabled).

  • network (str, optional) – Set network resolution method. Can be set to ‘default’ (if the client is running on the same network as the server) or ‘external’ (if the client is running on a different network). Defaults to ‘auto’.

  • tls_verify (TLSVerifyMode | str, optional) – Set tls verify mode. Defaults to TLSVerifyMode.PEER.

  • serializer (Serializer, optional) – Global serializer to translate JSON to Python objects. Used for any operation that does not set its own. Defaults to DefaultJsonSerializer.

  • transcoder (Transcoder, optional) – Global transcoder to use for key-value operations. Used for any operation that does not set its own. Defaults to JSONTranscoder.

  • tcp_keep_alive_interval (timedelta, optional) – TCP keep-alive interval. Defaults to 60 seconds.

  • config_poll_interval (timedelta, optional) – Config polling floor interval. Defaults to 2.5 seconds.

  • config_poll_floor (timedelta, optional) – Config polling floor interval. Defaults to 50 milliseconds.

  • max_http_connections (int, optional) – Maximum number of HTTP connections. Defaults to 0 (unlimited).

  • user_agent_extra (str, optional) – Appended to the user agent the SDK sends, after the Python version.

  • logging_meter_emit_interval (timedelta, optional) –

    Interval to flush the metrics operations queue.

    Deprecated since version 4.6.0: Use ClusterMetricsOptions instead.

  • transaction_config (TransactionConfig, optional) – Global configuration for transactions. Defaults to a default TransactionConfig.

  • log_redaction (bool, optional) – Set to True to tag user data, metadata and system data in log output so it can be redacted before logs are shared. Once any cluster enables it, it stays enabled for the life of the process. Defaults to False (disabled).

  • compression (Compression, optional) – Set compression mode.

  • compression_min_size (int, optional) – Set compression min size.

  • compression_min_ratio (float, optional) – Set compression min size.

  • lockmode (LockMode, optional) –

    Set LockMode mode.

    Deprecated since version 4.1.7: It has no effect.

  • tracer (RequestTracer, optional) – Set an external tracer. Defaults to None, enabling the threshold_logging_tracer. Note when this is set, all tracing_options (see ClusterTracingOptions) and then enable_tracing option are ignored.

  • meter (Meter, optional) – Set an external meter. Defaults to None, enabling the logging_meter. Note when this is set, the logging_meter_emit_interval option is ignored.

  • dns_nameserver (str, optional) – VOLATILE This API is subject to change at any time. Set to configure custom DNS nameserver. Defaults to the system resolver.

  • dns_port (int, optional) – VOLATILE This API is subject to change at any time. Set to configure custom DNS port. Defaults to 53.

  • disable_mozilla_ca_certificates (bool, optional) – Set to True to disable loading Mozilla’s list of CA certificates for TLS verification. Defaults to False (the bundled Mozilla roots are trusted).

  • dump_configuration (bool, optional) – Set to True to dump every new configuration when TRACE level logging. Defaults to False (disabled).

  • preferred_server_group (str, optional) – Specifies the preferred server group to be used for replica reads with ‘selected server group’ read preference.

  • enable_app_telemetry (bool, optional) – Specifies if application telemetry feature should be enabled. Defaults to True (enabled).

  • app_telemetry_endpoint (str, optional) – Specifies an endpoint to override the application metrics endpoint discovered during configuration. Defaults to the endpoint discovered during configuration.

  • app_telemetry_backoff (timedelta, optional) – Specifies the time to wait before attempting a websocket reconnection. Defaults to 1 hour.

  • app_telemetry_ping_interval (timedelta, optional) – Specifies the time to wait between sending consecutive websocket PING commands to the server. Defaults to 30 seconds.

  • app_telemetry_ping_timeout (timedelta, optional) – Specifies the time allowed for the server to respond to websocket PING command. Defaults to 2 seconds.

  • allow_enterprise_analytics (bool, optional) – Set to True to allow analytics queries against an Enterprise Analytics cluster, which this SDK otherwise refuses with FeatureUnavailableException. Defaults to False (disabled).

  • enable_lazy_connections (bool, optional) – Set to True to enable the C++ core to lazily establish bucket connections. Defaults to False (disabled).

apply_profile(profile_name: KnownConfigProfiles | str) → None

VOLATILE Apply a configuration profile’s options to these options.

Parameters:

profile_name (KnownConfigProfiles | str) – The name of the profile to apply.

Raises:

InvalidArgumentException – If no profile is registered under the name.

classmethod create_options_with_profile(authenticator: Authenticator, profile_name: KnownConfigProfiles | str) → ClusterOptions

VOLATILE Create cluster options with a configuration profile’s options applied.

Parameters:
Returns:

The new options.

Return type:

ClusterOptions

Raises:

InvalidArgumentException – If no profile is registered under the name.

static get_valid_options() → dict[str, Any]

DEPRECATED Each key these options carry, mapped to (key, None).

class couchbase.options.ClusterOrphanReportingOptions(**kwargs: Unpack[ClusterOrphanReportingOptionsKwargs])

Available orphan reporting options to set when creating a cluster.

Parameters:
  • enable_orphan_reporting (bool, optional) – Set to False to disable orphaned response reporting. Defaults to True (enabled).

  • sample_size (int, optional) – Size of orphan operations queue.

  • emit_interval (timedelta, optional) – Interval to flush the orphaned operations queue.

class couchbase.options.ClusterTimeoutOptions(**kwargs: Unpack[ClusterTimeoutOptionsKwargs])

Available timeout options to set when creating a cluster.

Warning

couchbase.cluster.ClusterTimeoutOptions is deprecated, and will be removed in a future release. Import ClusterTimeoutOptions from couchbase.options.

These will set the default timeouts for operations for the cluster. Some operations allow the timeout to be overridden on a per operation basis.

Parameters:
  • bootstrap_timeout (timedelta, optional) – Overall bootstrap timeout. Defaults to 10 seconds.

  • resolve_timeout (timedelta, optional) – Time to resolve hostnames. Defaults to 2 seconds.

  • connect_timeout (timedelta, optional) – connect timeout. Defaults to 2 seconds.

  • kv_timeout (timedelta, optional) – KV operations timeout. Defaults to 2.5 seconds.

  • kv_durable_timeout (timedelta, optional) – KV durability operations timeout. Defaults to 10 seconds.

  • views_timeout (timedelta, optional) – views operations timeout. Defaults to 75 seconds.

  • query_timeout (timedelta, optional) – query operations timeout. Defaults to 75 seconds.

  • analytics_timeout (timedelta, optional) – analytics operations timeout. Defaults to 75 seconds.

  • search_timeout (timedelta, optional) – search operations timeout. Defaults to 75 seconds.

  • management_timeout (timedelta, optional) – management operations timeout. Defaults to 75 seconds.

  • dns_srv_timeout (timedelta, optional) – Time to make DNS-SRV query. Defaults to 500 milliseconds.

  • idle_http_connection_timeout (timedelta, optional) – Idle HTTP connection timeout. Defaults to 1 second.

  • config_idle_redial_timeout (timedelta, optional) – Idle redial timeout. Defaults to 5 minutes.

  • config_total_timeout (timedelta, optional) –

    Complete bootstrap timeout.

    Deprecated since version 4.0.0: It has no effect.

class couchbase.options.ClusterTracingOptions(**kwargs: Unpack[ClusterTracingOptionsKwargs])

Available tracing options to set when creating a cluster.

Warning

couchbase.cluster.ClusterTracingOptions is deprecated, and will be removed in a future release. Import ClusterTracingOptions from couchbase.options.

Parameters:
  • enable_tracing (bool, optional) – Set to False to disable default threshold log tracing (enables no-op tracer). Defaults to True (enabled).

  • tracing_threshold_kv (timedelta, optional) – KV operations threshold. Defaults to 500 milliseconds.

  • tracing_threshold_view (timedelta, optional) – Views operations threshold. Defaults to 1 second.

  • tracing_threshold_query (timedelta, optional) – Query operations threshold. Defaults to 1 second.

  • tracing_threshold_search (timedelta, optional) – Search operations threshold.. Defaults to 1 second.

  • tracing_threshold_analytics (timedelta, optional) – Analytics operations threshold. Defaults to 1 second.

  • tracing_threshold_eventing (timedelta, optional) – Eventing operations threshold. Defaults to 1 second.

  • tracing_threshold_management (timedelta, optional) – Management operations threshold. Defaults to 1 second.

  • tracing_threshold_queue_size (int, optional) – Size of tracing operations queue. Defaults to 10.

  • tracing_threshold_queue_flush_interval (timedelta, optional) – Interval to flush tracing operations queue. Defaults to 10 seconds.

  • tracing_orphaned_queue_size (int, optional) –

    Size of the orphaned response queue.

    Deprecated since version 4.6.0: Use ClusterOrphanReportingOptions instead.

  • tracing_orphaned_queue_flush_interval (timedelta, optional) –

    Interval to flush the orphaned response queue.

    Deprecated since version 4.6.0: Use ClusterOrphanReportingOptions instead.

class couchbase.options.Compression(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

How the SDK compresses the data it exchanges with the server.

Warning

couchbase.cluster.Compression is deprecated, and will be removed in a future release. Import Compression from couchbase.options.

NONE neither compresses nor decompresses. IN decompresses what the server sends compressed, OUT compresses what the SDK sends, and INOUT does both.

FORCE is INOUT without waiting to learn whether the server supports compression. The SDK asks each server when it connects, and a command sent before the answer arrives goes uncompressed unless FORCE is set.

FORCE = 'force'
IN = 'inflate_only'
INOUT = 'on'
NONE = 'off'
OUT = 'deflate_only'
class couchbase.options.ConfigProfile

VOLATILE This API is subject to change at any time.

This is an abstract base class intended to use with creating Configuration Profiles. Any derived class will need to implement the apply() method.

abstract apply(options: ClusterOptions) → None

VOLATILE This API is subject to change at any time.

Apply the provided options to ClusterOptions. This method will need to be implemented in derived classes.

Parameters:

options (ClusterOptions) – The options the profile will apply toward.

class couchbase.options.ConfigProfiles

VOLATILE This API is subject to change at any time.

The ConfigProfiles class is responsible for keeping track of registered/known Configuration Profiles.

apply_profile(profile_name: str, options: ClusterOptions) → None

VOLATILE This API is subject to change at any time.

Apply the provided ConfigProfile options.

Parameters:
  • profile_name (str) – The name of the profile to apply.

  • options (ClusterOptions) – The options to apply the ConfigProfile options toward. The ConfigProfile options will override any matching option(s) previously set.

Raises:

InvalidArgumentException – If the specified profile is not registered.

register_profile(profile_name: str, profile: ConfigProfile) → None

VOLATILE This API is subject to change at any time.

Register a ConfigProfile.

Parameters:
Raises:

InvalidArgumentException – If the specified profile is not derived from ConfigProfile.

unregister_profile(profile_name: str) → ConfigProfile | None

VOLATILE This API is subject to change at any time.

Unregister a ConfigProfile.

Parameters:

profile_name (str) – The name of the ConfigProfile to unregister.

Returns:

The profile that was registered under the name, or None if none was.

Return type:

ConfigProfile | None

class couchbase.options.IpProtocol(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Which IP version the SDK connects over.

Any uses whichever a server’s address resolves to; ForceIPv4 and ForceIPv6 use only the one they name.

Any = 'any'
ForceIPv4 = 'force_ipv4'
ForceIPv6 = 'force_ipv6'
class couchbase.options.KnownConfigProfiles(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

VOLATILE This API is subject to change at any time.

Represents the name of a specific configuration profile that is associated with predetermined cluster options.

WanDevelopment = 'wan_development'
class couchbase.options.LockMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

A locking mode from the 2.x and 3.x series of the SDK, which has no meaning in 4.x.

Deprecated since version 4.1.7: This Enum will be removed in a future version of the SDK.

EXC = 1
NONE = 2
WAIT = 0
class couchbase.options.OptionValidationMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

What the SDK does with an option key a class does not carry.

A str enum because the same dial is set from the environment, where there is nothing but a string to set it with.

Ignore = 'ignore'
Strict = 'strict'
Warn = 'warn'
class couchbase.options.TLSVerifyMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Whether the SDK verifies the certificate a server presents over TLS.

PEER verifies it; NONE does not, and NO_VERIFY is another name for NONE.

NONE = 'none'
NO_VERIFY = 'no_verify'
PEER = 'peer'
class couchbase.options.WanDevelopmentProfile

VOLATILE This API is subject to change at any time.

Timeouts long enough for developing against a cluster across a WAN.

It sets 20 seconds for KV, durable KV, connect, DNS SRV and hostname resolution, and 120 seconds for analytics, query, search, management, views and bootstrap.

apply(options: ClusterOptions) → None

VOLATILE This API is subject to change at any time.

Apply the provided options to ClusterOptions. This method will need to be implemented in derived classes.

Parameters:

options (ClusterOptions) – The options the profile will apply toward.

Key-value

ExistsOptions(**kwargs)

Available options for a key-value exists operation.

GetAllReplicasOptions(**kwargs)

Available options for a key-value get-all-replicas operation.

GetAndLockOptions(**kwargs)

Available options for a key-value get and lock operation.

GetAndTouchOptions(**kwargs)

Available options for a key-value get and touch operation.

GetAnyReplicaOptions(**kwargs)

Available options for a key-value get-any-replica operation.

GetOptions(**kwargs)

Available options for a key-value get operation.

GetReplicaOptions(**kwargs)

Available options for a key-value get-replica operation.

InsertOptions(**kwargs)

Available options for a key-value insert operation.

MutationOptions

Represent a PEP 604 union type

RemoveOptions(**kwargs)

Available options for a key-value remove operation.

ReplaceOptions(**kwargs)

Available options for a key-value replace operation.

ScanOptions(**kwargs)

Available options for a key-value scan operation.

TouchOptions(**kwargs)

Available options for a key-value touch operation.

UnlockOptions(**kwargs)

Available options for a key-value unlock operation.

UpsertOptions(**kwargs)

Available options for a key-value upsert operation.

class couchbase.options.ExistsOptions(**kwargs: Unpack[ExistsOptionsKwargs])

Available options for a key-value exists operation.

Warning

couchbase.collection.ExistsOptions is deprecated, and will be removed in a future release. Import ExistsOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.GetAllReplicasOptions(**kwargs: Unpack[GetAllReplicasOptionsKwargs])

Available options for a key-value get-all-replicas operation.

Warning

couchbase.collection.GetAllReplicasOptions is deprecated, and will be removed in a future release. Import GetAllReplicasOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • read_preference (ReadPreference, optional) – Specifies how the replica nodes will be selected. Defaults to no preference.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.GetAndLockOptions(**kwargs: Unpack[GetAndLockOptionsKwargs])

Available options for a key-value get and lock operation.

Warning

couchbase.collection.GetAndLockOptions is deprecated, and will be removed in a future release. Import GetAndLockOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.GetAndTouchOptions(**kwargs: Unpack[GetAndTouchOptionsKwargs])

Available options for a key-value get and touch operation.

Warning

couchbase.collection.GetAndTouchOptions is deprecated, and will be removed in a future release. Import GetAndTouchOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.GetAnyReplicaOptions(**kwargs: Unpack[GetAnyReplicaOptionsKwargs])

Available options for a key-value get-any-replica operation.

Warning

couchbase.collection.GetAnyReplicaOptions is deprecated, and will be removed in a future release. Import GetAnyReplicaOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • read_preference (ReadPreference, optional) – Specifies how the replica nodes will be selected. Defaults to no preference.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.GetOptions(**kwargs: Unpack[GetOptionsKwargs])

Available options for a key-value get operation.

Warning

couchbase.collection.GetOptions is deprecated, and will be removed in a future release. Import GetOptions from couchbase.options.

Parameters:
  • project (Iterable[str], optional) – Specifies a list of fields within the document which should be fetched. This allows for easy retrieval of select fields without incurring the overhead of fetching the whole document.

  • with_expiry (bool, optional) – Indicates that the expiry of the document should be fetched alongside the data itself. Defaults to False.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

property project: Iterable[str]

The value of the project option, or [] if it was not set.

property with_expiry: bool

The value of the with_expiry option, or False if it was not set.

class couchbase.options.GetReplicaOptions(**kwargs: Unpack[GetReplicaOptionsKwargs])

Available options for a key-value get-replica operation.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.InsertOptions(**kwargs: Unpack[InsertOptionsKwargs])

Available options for a key-value insert operation.

Warning

couchbase.collection.InsertOptions is deprecated, and will be removed in a future release. Import InsertOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • expiry (timedelta, optional) – Specifies the expiry time for this document.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

property expiry: timedelta | None

The value of the expiry option, or None if it was not set.

couchbase.options.MutationOptions = couchbase.common.options.InsertOptions | couchbase.common.options.UpsertOptions | couchbase.common.options.ReplaceOptions | couchbase.common.options.RemoveOptions | couchbase.common.options.MutateInOptions | couchbase.common.options.AppendOptions | couchbase.common.options.PrependOptions | couchbase.common.options.IncrementOptions | couchbase.common.options.DecrementOptions

Represent a PEP 604 union type

E.g. for int | str

class couchbase.options.RemoveOptions(**kwargs: Unpack[RemoveOptionsKwargs])

Available options for a key-value remove operation.

Warning

couchbase.collection.RemoveOptions is deprecated, and will be removed in a future release. Import RemoveOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.ReplaceOptions(**kwargs: Unpack[ReplaceOptionsKwargs])

Available options for a key-value replace operation.

Warning

couchbase.collection.ReplaceOptions is deprecated, and will be removed in a future release. Import ReplaceOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • expiry (timedelta, optional) – Specifies the expiry time for this document.

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • preserve_expiry (bool, optional) – Specifies that any existing expiry on the document should be preserved. Defaults to False.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

property expiry: timedelta | None

The value of the expiry option, or None if it was not set.

class couchbase.options.ScanOptions(**kwargs: Unpack[ScanOptionsKwargs])

Available options for a key-value scan operation.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • ids_only (bool, optional) – Specifies that scan should only return document ids. Defaults to False.

  • consistent_with (MutationState, optional) – Specifies a MutationState which the operation should be consistent with.

  • batch_byte_limit (int, optional) – The limit applied to the number of bytes returned from the server for each partition batch. Defaults to 15000.

  • batch_item_limit (int, optional) – The limit applied to the number of items returned from the server for each partition batch. Defaults to 50.

  • batch_time_limit (timedelta, optional) – Not applied: the server takes no time limit for a scan batch.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • concurrency (int, optional) – The upper bound on the number of vbuckets that should be scanned in parallel. Defaults to 1.

  • parent_span (RequestSpan, optional) – Not applied: a scan is not traced.

class couchbase.options.TouchOptions(**kwargs: Unpack[TouchOptionsKwargs])

Available options for a key-value touch operation.

Warning

couchbase.collection.TouchOptions is deprecated, and will be removed in a future release. Import TouchOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.UnlockOptions(**kwargs: Unpack[UnlockOptionsKwargs])

Available options for a key-value unlock operation.

Warning

couchbase.collection.UnlockOptions is deprecated, and will be removed in a future release. Import UnlockOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.UpsertOptions(**kwargs: Unpack[UpsertOptionsKwargs])

Available options for a key-value upsert operation.

Warning

couchbase.collection.UpsertOptions is deprecated, and will be removed in a future release. Import UpsertOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • expiry (timedelta, optional) – Specifies the expiry time for this document.

  • preserve_expiry (bool, optional) – Specifies that any existing expiry on the document should be preserved. Defaults to False.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

property expiry: timedelta | None

The value of the expiry option, or None if it was not set.

Binary

AppendOptions(**kwargs)

Available options for a binary append operation.

DecrementOptions(**kwargs)

Available options for a key-value decrement operation.

DeltaValue(value)

An integer between 0 and 0x7FFFFFFFFFFFFFFF inclusive.

IncrementOptions(**kwargs)

Available options for a binary increment operation.

PrependOptions(**kwargs)

Available options for a binary prepend operation.

class couchbase.options.AppendOptions(**kwargs: Unpack[AppendOptionsKwargs])

Available options for a binary append operation.

Warning

couchbase.collection.AppendOptions is deprecated, and will be removed in a future release. Import AppendOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.DecrementOptions(**kwargs: Unpack[DecrementOptionsKwargs])

Available options for a key-value decrement operation.

Warning

couchbase.collection.DecrementOptions is deprecated, and will be removed in a future release. Import DecrementOptions from couchbase.options.

Parameters:
  • delta (DeltaValue, optional) – The amount to decrement the key. Defaults to 1.

  • initial (SignedInt64, optional) – The initial value to use for the document if it does not already exist. Setting it to a negative value means that the document will not be created if it does not exist. Defaults to 0.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • expiry (timedelta, optional) – Specifies the expiry time for this document.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

property expiry: timedelta | None

The value of the expiry option, or None if it was not set.

class couchbase.options.DeltaValue(value: c_long | c_ulong | int)

An integer between 0 and 0x7FFFFFFFFFFFFFFF inclusive.

Warning

couchbase.collection.DeltaValue is deprecated, and will be removed in a future release. Import DeltaValue from couchbase.options.

Used as an argument for increment() and decrement().

Parameters:

value (AcceptableInts) – The value to initialise this with.

classmethod max() → int

Get the largest value the class accepts.

Returns:

The largest value the class accepts.

Return type:

int

classmethod min() → int

Get the smallest value the class accepts.

Returns:

The smallest value the class accepts.

Return type:

int

class couchbase.options.IncrementOptions(**kwargs: Unpack[IncrementOptionsKwargs])

Available options for a binary increment operation.

Warning

couchbase.collection.IncrementOptions is deprecated, and will be removed in a future release. Import IncrementOptions from couchbase.options.

Parameters:
  • delta (DeltaValue, optional) – The amount to increment the key. Defaults to 1.

  • initial (SignedInt64, optional) – The initial value to use for the document if it does not already exist. Setting it to a negative value means that the document will not be created if it does not exist. Defaults to 0.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • expiry (timedelta, optional) – Specifies the expiry time for this document.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

property expiry: timedelta | None

The value of the expiry option, or None if it was not set.

class couchbase.options.PrependOptions(**kwargs: Unpack[PrependOptionsKwargs])

Available options for a binary prepend operation.

Warning

couchbase.collection.PrependOptions is deprecated, and will be removed in a future release. Import PrependOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

Multi-document key-value

AppendMultiOptions(**kwargs)

Available options for a binary multi-append operation.

DecrementMultiOptions(**kwargs)

Available options for a binary multi-decrement operation.

ExistsMultiOptions(**kwargs)

Available options for a key-value multi-exists operation.

GetAllReplicasMultiOptions(**kwargs)

Available options for a key-value multi-get-all-replicas operation.

GetAndLockMultiOptions(**kwargs)

Available options for a key-value multi-lock operation.

GetAnyReplicaMultiOptions(**kwargs)

Available options for a key-value multi-get-any-replica operation.

GetMultiOptions(**kwargs)

Available options for a key-value multi-get operation.

IncrementMultiOptions(**kwargs)

Available options for a binary multi-increment operation.

InsertMultiOptions(**kwargs)

Available options for a key-value multi-insert operation.

LockMultiOptions

alias of GetAndLockMultiOptions

MutationMultiOptions

Represent a PEP 604 union type

NoValueMultiOptions

Represent a PEP 604 union type

PrependMultiOptions(**kwargs)

Available options for a binary multi-prepend operation.

RemoveMultiOptions(**kwargs)

Available options for a key-value multi-remove operation.

ReplaceMultiOptions(**kwargs)

Available options for a key-value multi-replace operation.

TouchMultiOptions(**kwargs)

Available options for a key-value multi-touch operation.

UnlockMultiOptions(**kwargs)

Available options for a key-value multi-unlock operation.

UpsertMultiOptions(**kwargs)

Available options for a key-value multi-upsert operation.

class couchbase.options.AppendMultiOptions(**kwargs: Unpack[AppendMultiOptionsKwargs])

Available options for a binary multi-append operation.

Options can be set at a global level (i.e. for all append operations handled with this multi-append operation). Use per_key_options to set specific AppendOptions for specific keys.

Parameters:
  • per_key_options (dict[str, AppendOptions], optional) – Specify AppendOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.DecrementMultiOptions(**kwargs: Unpack[DecrementMultiOptionsKwargs])

Available options for a binary multi-decrement operation.

Options can be set at a global level (i.e. for all decrement operations handled with this multi-decrement operation). Use per_key_options to set specific DecrementOptions for specific keys.

Parameters:
  • delta (DeltaValue, optional) – The amount to decrement the key. Defaults to 1.

  • initial (SignedInt64, optional) – The initial value to use for the document if it does not already exist. Setting it to a negative value means that the document will not be created if it does not exist. Defaults to 0.

  • per_key_options (dict[str, DecrementOptions], optional) – Specify DecrementOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.ExistsMultiOptions(**kwargs: Unpack[ExistsMultiOptionsKwargs])

Available options for a key-value multi-exists operation.

Options can be set at a global level (i.e. for all exists operations handled with this multi-exists operation). Use per_key_options to set specific ExistsOptions for specific keys.

Parameters:
  • per_key_options (dict[str, ExistsOptions], optional) – Specify ExistsOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.GetAllReplicasMultiOptions(**kwargs: Unpack[GetAllReplicasMultiOptionsKwargs])

Available options for a key-value multi-get-all-replicas operation.

Options can be set at a global level (i.e. for all get operations handled with this multi-get-all-replicas operation). Use per_key_options to set specific GetAllReplicasOptions for specific keys.

Parameters:
  • per_key_options (dict[str, GetAllReplicasOptions], optional) – Specify GetAllReplicasOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • read_preference (ReadPreference, optional) – Specifies how the replica nodes will be selected. Defaults to no preference.

class couchbase.options.GetAndLockMultiOptions(**kwargs: Unpack[GetAndLockMultiOptionsKwargs])

Available options for a key-value multi-lock operation.

Options can be set at a global level (i.e. for all lock operations handled with this multi-lock operation). Use per_key_options to set specific GetAndLockOptions for specific keys.

Parameters:
  • per_key_options (dict[str, GetAndLockOptions], optional) – Specify GetAndLockOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

class couchbase.options.GetAnyReplicaMultiOptions(**kwargs: Unpack[GetAnyReplicaMultiOptionsKwargs])

Available options for a key-value multi-get-any-replica operation.

Options can be set at a global level (i.e. for all get operations handled with this multi-get-any-replica operation). Use per_key_options to set specific GetAnyReplicaOptions for specific keys.

Parameters:
  • per_key_options (dict[str, GetAnyReplicaOptions], optional) – Specify GetAnyReplicaOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

  • read_preference (ReadPreference, optional) – Specifies how the replica nodes will be selected. Defaults to no preference.

class couchbase.options.GetMultiOptions(**kwargs: Unpack[GetMultiOptionsKwargs])

Available options for a key-value multi-get operation.

Options can be set at a global level (i.e. for all get operations handled with this multi-get operation). Use per_key_options to set specific GetOptions for specific keys.

Parameters:
  • project (Iterable[str], optional) – Not supported by a multi get, here or in per_key_options. Setting it raises InvalidArgumentException.

  • with_expiry (bool, optional) –

    Not supported by a multi get, here or in per_key_options.

    Deprecated since version 4.7.0: A multi get does not fetch the expiry, so it has no effect.

  • per_key_options (dict[str, GetOptions], optional) – Specify GetOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

property project: Iterable[str]

The value of the project option, or [] if it was not set.

property with_expiry: bool

The value of the with_expiry option, or False if it was not set.

class couchbase.options.IncrementMultiOptions(**kwargs: Unpack[IncrementMultiOptionsKwargs])

Available options for a binary multi-increment operation.

Options can be set at a global level (i.e. for all increment operations handled with this multi-increment operation). Use per_key_options to set specific IncrementOptions for specific keys.

Parameters:
  • delta (DeltaValue, optional) – The amount to increment the key. Defaults to 1.

  • initial (SignedInt64, optional) – The initial value to use for the document if it does not already exist. Setting it to a negative value means that the document will not be created if it does not exist. Defaults to 0.

  • per_key_options (dict[str, IncrementOptions], optional) – Specify IncrementOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.InsertMultiOptions(**kwargs: Unpack[InsertMultiOptionsKwargs])

Available options for a key-value multi-insert operation.

Options can be set at a global level (i.e. for all insert operations handled with this multi-insert operation). Use per_key_options to set specific InsertOptions for specific keys.

Parameters:
  • per_key_options (dict[str, InsertOptions], optional) – Specify InsertOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • expiry (timedelta, optional) – Specifies the expiry time for this document.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

property expiry: timedelta | None

The value of the expiry option, or None if it was not set.

couchbase.options.LockMultiOptions

alias of GetAndLockMultiOptions

couchbase.options.MutationMultiOptions = couchbase.common.options.InsertMultiOptions | couchbase.common.options.UpsertMultiOptions | couchbase.common.options.ReplaceMultiOptions

Represent a PEP 604 union type

E.g. for int | str

couchbase.options.NoValueMultiOptions = couchbase.common.options.GetMultiOptions | couchbase.common.options.ExistsMultiOptions | couchbase.common.options.RemoveMultiOptions | couchbase.common.options.TouchMultiOptions | couchbase.common.options.GetAndLockMultiOptions | couchbase.common.options.UnlockMultiOptions

Represent a PEP 604 union type

E.g. for int | str

class couchbase.options.PrependMultiOptions(**kwargs: Unpack[PrependMultiOptionsKwargs])

Available options for a binary multi-prepend operation.

Options can be set at a global level (i.e. for all prepend operations handled with this multi-prepend operation). Use per_key_options to set specific PrependOptions for specific keys.

Parameters:
  • per_key_options (dict[str, PrependOptions], optional) – Specify PrependOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.RemoveMultiOptions(**kwargs: Unpack[RemoveMultiOptionsKwargs])

Available options for a key-value multi-remove operation.

Options can be set at a global level (i.e. for all remove operations handled with this multi-remove operation). Use per_key_options to set specific RemoveOptions for specific keys.

Parameters:
  • per_key_options (dict[str, RemoveOptions], optional) – Specify RemoveOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • transcoder (Transcoder, optional) –

    A remove carries no value to transcode.

    Deprecated since version 4.7.0: It has no effect.

class couchbase.options.ReplaceMultiOptions(**kwargs: Unpack[ReplaceMultiOptionsKwargs])

Available options for a key-value multi-replace operation.

Options can be set at a global level (i.e. for all replace operations handled with this multi-replace operation). Use per_key_options to set specific ReplaceOptions for specific keys.

Parameters:
  • per_key_options (dict[str, ReplaceOptions], optional) – Specify ReplaceOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • expiry (timedelta, optional) – Specifies the expiry time for this document.

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • preserve_expiry (bool, optional) – Specifies that any existing expiry on the document should be preserved. Defaults to False.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

property expiry: timedelta | None

The value of the expiry option, or None if it was not set.

class couchbase.options.TouchMultiOptions(**kwargs: Unpack[TouchMultiOptionsKwargs])

Available options for a key-value multi-touch operation.

Options can be set at a global level (i.e. for all touch operations handled with this multi-touch operation). Use per_key_options to set specific TouchOptions for specific keys.

Parameters:
  • per_key_options (dict[str, TouchOptions], optional) – Specify TouchOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.UnlockMultiOptions(**kwargs: Unpack[UnlockMultiOptionsKwargs])

Available options for a key-value multi-unlock operation.

Options can be set at a global level (i.e. for all unlock operations handled with this multi-unlock operation). Use per_key_options to set specific UnlockOptions for specific keys.

Parameters:
  • per_key_options (dict[str, UnlockOptions], optional) – Specify UnlockOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.UpsertMultiOptions(**kwargs: Unpack[UpsertMultiOptionsKwargs])

Available options for a key-value multi-upsert operation.

Options can be set at a global level (i.e. for all upsert operations handled with this multi-upsert operation). Use per_key_options to set specific UpsertOptions for specific keys.

Parameters:
  • per_key_options (dict[str, UpsertOptions], optional) – Specify UpsertOptions per key.

  • return_exceptions (bool, optional) – If False, raise an Exception when encountered. If True return the Exception without raising. Defaults to True.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • expiry (timedelta, optional) – Specifies the expiry time for this document.

  • preserve_expiry (bool, optional) – Specifies that any existing expiry on the document should be preserved. Defaults to False.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

property expiry: timedelta | None

The value of the expiry option, or None if it was not set.

Sub-document

LookupInAllReplicasOptions(**kwargs)

Available options for a subdocument lookup-in-all-replicas operation.

LookupInAnyReplicaOptions(**kwargs)

Available options for a subdocument lookup-in-any-replica operation.

LookupInOptions(**kwargs)

Available options for a subdocument lookup-in operation.

MutateInOptions(**kwargs)

Available options for a subdocument mutate-in operation.

class couchbase.options.LookupInAllReplicasOptions(**kwargs: Unpack[LookupInAllReplicasOptionsKwargs])

Available options for a subdocument lookup-in-all-replicas operation.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific operation. Defaults to DefaultJsonSerializer.

  • read_preference (ReadPreference, optional) – Specifies how the replica nodes will be selected. Defaults to no preference.

class couchbase.options.LookupInAnyReplicaOptions(**kwargs: Unpack[LookupInAnyReplicaOptionsKwargs])

Available options for a subdocument lookup-in-any-replica operation.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific operation. Defaults to DefaultJsonSerializer.

  • read_preference (ReadPreference, optional) – Specifies how the replica nodes will be selected. Defaults to no preference.

class couchbase.options.LookupInOptions(**kwargs: Unpack[LookupInOptionsKwargs])

Available options for a subdocument lookup-in operation.

Warning

couchbase.collection.LookupInOptions is deprecated, and will be removed in a future release. Import LookupInOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • access_deleted (bool, optional) – Whether the operation may access a deleted document’s extended attributes.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific operation. Defaults to DefaultJsonSerializer.

class couchbase.options.MutateInOptions(**kwargs: Unpack[MutateInOptionsKwargs])

Available options for a subdocument mutate-in operation.

Warning

couchbase.subdocument.MutateInOptions is deprecated, and will be removed in a future release. Import MutateInOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • expiry (timedelta, optional) – Specifies the expiry time for this document. Cannot be combined with preserve_expiry.

  • cas (int, optional) – If specified, indicates that operation should be failed if the CAS has changed from this value, indicating that the document has changed.

  • durability (DurabilityType, optional) – Specifies the level of durability for this operation.

  • store_semantics (StoreSemantics, optional) – Specifies the store semantics to use for this operation.

  • access_deleted (bool, optional) – Whether the operation may access a deleted document’s extended attributes.

  • preserve_expiry (bool, optional) – Specifies that any existing expiry on the document should be preserved. Defaults to False.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific operation. Defaults to DefaultJsonSerializer.

property expiry: timedelta | None

The value of the expiry option, or None if it was not set.

Query, analytics, search and views

AnalyticsOptions(**kwargs)

Available options for an analytics query.

QueryOptions(**kwargs)

Available options for a N1QL (SQL++) query.

SearchOptions(**kwargs)

Available options for a search (FTS) query.

VectorSearchOptions(**kwargs)

Available options for a FTS vector search.

ViewOptions(**kwargs)

Available options for a view query.

class couchbase.options.AnalyticsOptions(**kwargs: Unpack[AnalyticsOptionsKwargs])

Available options for an analytics query.

Warning

couchbase.analytics.AnalyticsOptions is deprecated, and will be removed in a future release. Import AnalyticsOptions from couchbase.options.

Parameters:
  • client_context_id (str, optional) – The returned client context id for this query. Defaults to a generated UUID.

  • raw (dict[str, JSONType], optional) – Specifies any additional parameters which should be passed to the query engine when executing the query.

  • metrics (bool, optional) – Specifies whether metrics should be captured as part of the execution of the query. Defaults to True.

  • named_parameters (dict[str, JSONType], optional) – Named values to be used for the placeholders within the query.

  • positional_parameters (Iterable[JSONType], optional) – Positional values to be used for the placeholders within the query.

  • read_only (bool, optional) – Specifies that this query should be executed in read-only mode, disabling the ability for the query to make any changes to the data. Defaults to False.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s query_timeout, from ClusterTimeoutOptions.

  • scan_consistency (AnalyticsScanConsistency, optional) – Specifies the consistency requirements when executing the query. Defaults to NotBounded.

  • priority (bool, optional) – Indicates whether this analytics query should be executed with a specific priority level. Defaults to False.

  • query_context (str, optional) – Specifies the context within which this query should be executed. This can be scoped to a scope or a collection within the dataset.

  • serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific operation. Defaults to DefaultJsonSerializer.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.QueryOptions(**kwargs: Unpack[QueryOptionsKwargs])

Available options for a N1QL (SQL++) query.

Warning

couchbase.cluster.QueryOptions is deprecated, and will be removed in a future release. Import QueryOptions from couchbase.options.

Parameters:
  • client_context_id (str, optional) – The returned client context id for this query. Defaults to a generated UUID.

  • raw (dict[str, JSONType], optional) – Specifies any additional parameters which should be passed to the query engine when executing the query.

  • adhoc (bool, optional) – Specifies whether this is an ad-hoc query, or if it should be prepared for faster execution in the future. Defaults to True.

  • max_parallelism (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • pipeline_batch (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • pipeline_cap (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • profile (QueryProfile, optional) – Specifies the level of profiling that should be used for the query. Defaults to Off.

  • scan_cap (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • scan_wait (timedelta, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • metrics (bool, optional) – Specifies whether metrics should be captured as part of the execution of the query. Defaults to False.

  • named_parameters (dict[str, JSONType], optional) – Named values to be used for the placeholders within the query.

  • positional_parameters (Iterable[JSONType], optional) – Positional values to be used for the placeholders within the query.

  • read_only (bool, optional) – Specifies that this query should be executed in read-only mode, disabling the ability for the query to make any changes to the data. Defaults to False.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s query_timeout, from ClusterTimeoutOptions.

  • scan_consistency (QueryScanConsistency, optional) – Specifies the consistency requirements when executing the query. Defaults to NotBounded.

  • query_context (str, optional) – Specifies the context within which this query should be executed. This can be scoped to a scope or a collection within the dataset.

  • flex_index (bool, optional) – Specifies whether flex-indexes should be enabled. Allowing the use of full-text search from the query service. Defaults to False.

  • preserve_expiry (bool, optional) – Specifies that any existing expiry on the document should be preserved. Defaults to False.

  • use_replica (bool, optional) – Specifies that the query engine should use replica nodes for KV fetches if the active node is down.

  • consistent_with (MutationState, optional) – Specifies a MutationState which the operation should be consistent with.

  • send_to_node (str, optional) – The node to send the query to, rather than one the SDK chooses.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific operation. Defaults to DefaultJsonSerializer.

class couchbase.options.SearchOptions(**kwargs: Unpack[SearchOptionsKwargs])

Available options for a search (FTS) query.

Warning

couchbase.search.SearchOptions is deprecated, and will be removed in a future release. Import SearchOptions from couchbase.options.

Parameters:
  • client_context_id (str, optional) – The returned client context id for this query. Defaults to a generated UUID.

  • raw (dict[str, JSONType], optional) – Specifies any additional parameters which should be passed to the query engine when executing the query.

  • limit (int, optional) – Specifies the limit to the number of results that should be returned.

  • skip (int, optional) – Specifies the number of results to skip from the index before returning results.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s search_timeout, from ClusterTimeoutOptions.

  • explain (bool, optional) – Configures whether the result should contain the execution plan for the search query. Defaults to False.

  • fields (list[str], optional) – Specifies the list of fields which should be searched.

  • highlight_style (HighlightStyle, optional) – Specifies the mode used for highlighting.

  • highlight_fields (list[str], optional) – Specifies the list of fields that should be highlighted.

  • scan_consistency (SearchScanConsistency, optional) – Specifies the consistency requirements when executing the query. Defaults to NotBounded.

  • consistent_with (MutationState, optional) – Specifies a MutationState which the operation should be consistent with.

  • facets (dict[str, Facet], optional) – Specifies any facets that should be included in the search query.

  • sort (Sequence[str] | Sequence[Sort], optional) – Specifies a list of fields or search Sort’s to use when sorting the result sets.

  • disable_scoring (bool, optional) –

    Specifies that scoring should be disabled. This improves performance but makes it impossible to sort based on how well a particular result scored. Defaults to False.

    Deprecated since version 4.7.0: Use scoring with ScoringNone instead.

  • scoring (SearchScoring, optional) – Controls result scoring and how a hybrid request combines FTS and vector results into one ranked list. Cannot be combined with disable_scoring=True.

  • scope_name (str, optional) –

    Specifies the scope which should be searched as part of the search query.

    Deprecated since version 4.7.0: Use Scope.search() instead.

  • collections (list[str], optional) – Specifies the collections which should be searched as part of the search query.

  • include_locations (bool, optional) – If set to True, will include the locations in the search result. Defaults to False.

  • serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific operation. Defaults to DefaultJsonSerializer.

  • show_request (bool, optional) – Specifies if the search response should contain the request for the search query.

  • log_request (bool, optional) – UNCOMMITTED Specifies if search request body should appear the log. Defaults to False.

  • log_response (bool, optional) – UNCOMMITTED Specifies if search response should appear in the log. Defaults to False.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.VectorSearchOptions(**kwargs: Unpack[VectorSearchOptionsKwargs])

Available options for a FTS vector search.

Parameters:

vector_query_combination (VectorQueryCombination, optional) – Specifies logical operation to use with multiple vector queries.

class couchbase.options.ViewOptions(**kwargs: Unpack[ViewOptionsKwargs])

Available options for a view query.

Warning

couchbase.bucket.ViewOptions is deprecated, and will be removed in a future release. Import ViewOptions from couchbase.options.

Parameters:
  • client_context_id (str, optional) – The returned client context id for this query. Defaults to a generated UUID.

  • raw (dict[str, str], optional) – Specifies any additional parameters which should be passed to the query engine when executing the query.

  • limit (int, optional) – Specifies the limit to the number of results that should be returned.

  • skip (int, optional) – Specifies the number of results to skip from the index before returning results.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s views_timeout, from ClusterTimeoutOptions.

  • scan_consistency (ViewScanConsistency, optional) – Specifies the consistency requirements when executing the query. Defaults to NotBounded.

  • startkey (JSONType, optional) – Specifies the first key that should be included in the results.

  • endkey (JSONType, optional) – Specifies the last key that should be included in the results.

  • startkey_docid (str, optional) – Specifies the first document ID that should be included in the results.

  • endkey_docid (str, optional) – Specifies the last document ID that should be included in the results.

  • inclusive_end (bool, optional) – Specifies whether the end key should be considered inclusive or exclusive. Defaults to True.

  • group (bool, optional) – Specifies whether the results should be grouped together.

  • group_level (int, optional) – Specifies the level to which results should be group.

  • key (JSONType, optional) – Specifies a specific key which should be fetched from the index.

  • keys (Sequence[JSONType], optional) – Specifies a list of keys which should be fetched from the index.

  • order (ViewOrdering, optional) – Specifies the ordering that should be used when returning results.

  • reduce (bool, optional) – Specifies whether reduction should be performed as part of the view query.

  • on_error (ViewErrorMode, optional) – Specifies the error-handling behaviour that should be used when an error occurs.

  • debug (bool, optional) – Whether the view service should include debug information in the response.

  • namespace (DesignDocumentNamespace, optional) – Specifies the namespace for the design document. Defaults to Development.

  • query_string (list[str], optional) – Raw query string parameters, each written key=value, added to the view request.

  • full_set (bool, optional) – Specifies whether the query should force the entire set of document in the index to be included in the result. Defaults to False.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

  • serializer (Serializer, optional) – Specifies an explicit serializer to use for this specific operation. Defaults to DefaultJsonSerializer.

Transactions

TransactionConfig(**kwargs)

The configuration of the transactions a cluster runs.

TransactionGetMultiOptions(**kwargs)

Available options for transaction get_multi operation.

TransactionGetMultiReplicasFromPreferredServerGroupOptions(...)

Available options for transaction get_multi_replicas_from_preferred_server_group operation.

TransactionGetOptions(**kwargs)

Available options for transaction get operation.

TransactionGetReplicaFromPreferredServerGroupOptions(...)

Available options for transaction get_replica_from_preferred_server_group operation.

TransactionInsertOptions(**kwargs)

Available options for transaction insert operation.

TransactionOptions(**kwargs)

Available options for a single transaction.

TransactionQueryOptions(**kwargs)

Available options for a query run inside a transaction.

TransactionReplaceOptions(**kwargs)

Available options for transaction replace operation.

class couchbase.options.TransactionConfig(**kwargs: Unpack[TransactionConfigKwargs])

The configuration of the transactions a cluster runs.

Set it through transaction_config on ClusterOptions. TransactionOptions overrides some of it for a single transaction.

Parameters:
  • expiration_time (timedelta, optional) –

    Maximum amount of time a transaction can take before rolling back.

    Deprecated since version 4.1.10: Use timeout instead.

  • metadata_collection (TransactionKeyspace, optional) – The collection to store transaction metadata in.

  • durability (ServerDurability, optional) – Specifies the level of durability for this operation.

  • cleanup_window (timedelta, optional) – The query metadata is cleaned up over a the cleanup_window. Longer windows mean less background activity, shorter intervals will clean things faster.

  • kv_timeout (timedelta, optional) –

    KV operations timeout.

    Deprecated since version 4.1.10: It has no effect. Transactions use the cluster’s kv_durable_timeout.

  • cleanup_lost_attempts (bool, optional) – Whether to look for, in the background, transactions that were lost and clean them up. See cleanup_window.

  • cleanup_client_attempts (bool, optional) – Whether to clean up, in the background, the transactions this client attempted.

  • scan_consistency (QueryScanConsistency, optional) – Specifies the consistency requirements when executing the query. Defaults to NotBounded.

  • timeout (timedelta, optional) – The maximum time a transaction may run, across all its attempts, before it expires. Defaults to 15 seconds.

class couchbase.options.TransactionGetMultiOptions(**kwargs: Unpack[TransactionGetMultiOptionsKwargs])

Available options for transaction get_multi operation.

Parameters:

mode (TransactionGetMultiMode, optional) – Specifies the mode to use for this specific operation. Defaults to PrioritiseLatency.

class couchbase.options.TransactionGetMultiReplicasFromPreferredServerGroupOptions(**kwargs: Unpack[TransactionGetMultiReplicasFromPreferredServerGroupOptionsKwargs])

Available options for transaction get_multi_replicas_from_preferred_server_group operation.

Parameters:

mode (TransactionGetMultiReplicasFromPreferredServerGroupMode, optional) – Specifies the mode to use for this specific operation. Defaults to PrioritiseLatency.

class couchbase.options.TransactionGetOptions(**kwargs: Unpack[TransactionGetOptionsKwargs])

Available options for transaction get operation.

Parameters:

transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

class couchbase.options.TransactionGetReplicaFromPreferredServerGroupOptions(**kwargs: Unpack[TransactionGetReplicaFromPreferredServerGroupOptionsKwargs])

Available options for transaction get_replica_from_preferred_server_group operation.

Parameters:

transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

class couchbase.options.TransactionInsertOptions(**kwargs: Unpack[TransactionInsertOptionsKwargs])

Available options for transaction insert operation.

Parameters:

transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

class couchbase.options.TransactionOptions(**kwargs: Unpack[TransactionOptionsKwargs])

Available options for a single transaction.

Each one set here overrides the cluster’s TransactionConfig for this transaction.

Parameters:
  • expiration_time (timedelta, optional) –

    Maximum amount of time a transaction can take before rolling back.

    Deprecated since version 4.1.10: Use timeout instead.

  • metadata_collection (TransactionKeyspace, optional) – The collection to store transaction metadata in.

  • durability (ServerDurability, optional) – Specifies the level of durability for this operation.

  • kv_timeout (timedelta, optional) –

    KV operations timeout.

    Deprecated since version 4.1.10: It has no effect. Transactions use the cluster’s kv_durable_timeout.

  • scan_consistency (QueryScanConsistency, optional) – Specifies the consistency requirements when executing the query. Defaults to NotBounded.

  • timeout (timedelta, optional) – The maximum time this transaction may run, across all its attempts, before it expires. Defaults to the timeout of the cluster’s TransactionConfig.

class couchbase.options.TransactionQueryOptions(**kwargs: Unpack[TransactionQueryOptionsKwargs])

Available options for a query run inside a transaction.

Parameters:
  • client_context_id (str, optional) – The returned client context id for this query. Defaults to a generated UUID.

  • raw (dict[str, JSONType], optional) – Specifies any additional parameters which should be passed to the query engine when executing the query.

  • adhoc (bool, optional) – Specifies whether this is an ad-hoc query, or if it should be prepared for faster execution in the future. Defaults to True.

  • max_parallelism (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • pipeline_batch (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • pipeline_cap (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • profile (QueryProfile, optional) – Specifies the level of profiling that should be used for the query. Defaults to Off.

  • scan_cap (int, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • scan_wait (timedelta, optional) – This is an advanced option, see the query service reference for more information on the proper use and tuning of this option.

  • metrics (bool, optional) – Specifies whether metrics should be captured as part of the execution of the query. Defaults to True.

  • named_parameters (dict[str, JSONType], optional) – Named values to be used for the placeholders within the query.

  • positional_parameters (Iterable[JSONType], optional) – Positional values to be used for the placeholders within the query.

  • read_only (bool, optional) – Specifies that this query should be executed in read-only mode, disabling the ability for the query to make any changes to the data. Defaults to False.

  • scan_consistency (QueryScanConsistency, optional) – Specifies the consistency requirements when executing the query. Defaults to NotBounded.

  • scope (ScopeKeyspace, optional) – Specify the scope of the query.

split_scope_qualifier(remove_backticks: bool | None = True) → tuple[str, str] | None

The bucket and scope a scope was given for, or nothing if none was.

Read from the scope’s own two names rather than from a qualifier string assembled out of them, which is one parse and one format fewer.

class couchbase.options.TransactionReplaceOptions(**kwargs: Unpack[TransactionReplaceOptionsKwargs])

Available options for transaction replace operation.

Parameters:

transcoder (Transcoder, optional) – Specifies an explicit transcoder to use for this specific operation. Defaults to JSONTranscoder.

Diagnostics

DiagnosticsOptions(**kwargs)

Available options for a diagnostics operation.

PingOptions(**kwargs)

Available options for a ping operation.

WaitUntilReadyOptions(**kwargs)

Available options for a wait until ready operation.

class couchbase.options.DiagnosticsOptions(**kwargs: Unpack[DiagnosticsOptionsKwargs])

Available options for a diagnostics operation.

Warning

couchbase.cluster.DiagnosticsOptions is deprecated, and will be removed in a future release. Import DiagnosticsOptions from couchbase.options.

Parameters:
  • report_id (str, optional) – A unique identifier for the report generated by this operation.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.PingOptions(**kwargs: Unpack[PingOptionsKwargs])

Available options for a ping operation.

Warning

couchbase.bucket.PingOptions is deprecated, and will be removed in a future release. Import PingOptions from couchbase.options.

Parameters:
  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • report_id (str, optional) – A unique identifier for the report generated by this operation.

  • service_types (Iterable[ServiceType] | Iterable[str], optional) – The services which should be pinged. Either every element is a ServiceType or every element is its .value string; the two forms are equivalent and are not intended to be mixed within one iterable.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

class couchbase.options.WaitUntilReadyOptions(**kwargs: Unpack[WaitUntilReadyOptionsKwargs])

Available options for a wait until ready operation.

Parameters:
  • desired_state (ClusterState, optional) – The desired state to wait for in order to determine the cluster or bucket is ready. Defaults to Online.

  • service_types (Iterable[ServiceType] | Iterable[str], optional) – The services which should be pinged. Either every element is a ServiceType or every element is its .value string; the two forms are equivalent and are not intended to be mixed within one iterable.

  • timeout (timedelta, optional) – The timeout for this operation. Defaults to the cluster’s kv_timeout, from ClusterTimeoutOptions.

  • parent_span (RequestSpan, optional) – The parent span for this operation.

Value types

AcceptableInts

Represent a PEP 604 union type

ConstrainedInt(value)

An integer a subclass checks against the range it states.

SignedInt64(value)

An integer between -0x8000000000000000 and 0x7FFFFFFFFFFFFFFF inclusive.

UnsignedInt32(*args, **kwargs)

An integer between 0x00000000 and 0x80000000 inclusive.

UnsignedInt64(value)

An integer between 0x0000000000000000 and 0x8000000000000000 inclusive.

couchbase.options.AcceptableInts = ctypes.c_long | ctypes.c_ulong | int

Represent a PEP 604 union type

E.g. for int | str

class couchbase.options.ConstrainedInt(value: c_long | c_ulong | int)

An integer a subclass checks against the range it states.

Warning

couchbase.collection.ConstrainedInt is deprecated, and will be removed in a future release. Import ConstrainedInt from couchbase.options.

Parameters:

value (AcceptableInts) – The value to initialise this with.

classmethod is_valid(value: c_long | c_ulong | int) → bool

Get whether a value is an instance of the class.

Parameters:

value (AcceptableInts) – The value to check.

Returns:

True if the value is an instance of the class.

Return type:

bool

classmethod max() → int

Get the largest value the class accepts.

Returns:

The largest value the class accepts.

Return type:

int

classmethod min() → int

Get the smallest value the class accepts.

Returns:

The smallest value the class accepts.

Return type:

int

classmethod verify_value(value: c_long | c_ulong | int) → int

Check that a value is an integer in the class’s range.

Parameters:

value (AcceptableInts) – The value to check.

Returns:

The value, as an int.

Return type:

int

Raises:

InvalidArgumentException – If the value is not an integer in range.

class couchbase.options.SignedInt64(value: c_long | c_ulong | int)

An integer between -0x8000000000000000 and 0x7FFFFFFFFFFFFFFF inclusive.

Warning

couchbase.collection.SignedInt64 is deprecated, and will be removed in a future release. Import SignedInt64 from couchbase.options.

Parameters:

value (AcceptableInts) – The value to initialise this with.

classmethod max() → int

Get the largest value the class accepts.

Returns:

The largest value the class accepts.

Return type:

int

classmethod min() → int

Get the smallest value the class accepts.

Returns:

The smallest value the class accepts.

Return type:

int

class couchbase.options.UnsignedInt32(*args: Any, **kwargs: Any)

An integer between 0x00000000 and 0x80000000 inclusive.

Deprecated since version 4.7.0: Use an int instead.

Parameters:

value (AcceptableInts) – The value to initialise this with.

classmethod max() → int

Get the largest value the class accepts.

Returns:

The largest value the class accepts.

Return type:

int

classmethod min() → int

Get the smallest value the class accepts.

Returns:

The smallest value the class accepts.

Return type:

int

class couchbase.options.UnsignedInt64(value: c_long | c_ulong | int)

An integer between 0x0000000000000000 and 0x8000000000000000 inclusive.

Parameters:

value (AcceptableInts) – The value to initialise this with.

classmethod max() → int

Get the largest value the class accepts.

Returns:

The largest value the class accepts.

Return type:

int

classmethod min() → int

Get the smallest value the class accepts.

Returns:

The smallest value the class accepts.

Return type:

int