BinaryCollection

class couchbase.binary_collection.BinaryCollection(collection)
append(key, value, *opts, **kwargs) → MutationResult

Appends the specified value to the beginning of document of the specified key.

Parameters:

  • key (str) – The key of the document to append to.

  • value (Union[str, bytes, bytearray]) – The value to append to the document.

  • opts (AppendOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided AppendOptions

Returns:

An instance of MutationResult.

Return type:

MutationResult

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

Examples

Simple append string operation:

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().append('string-doc', 'XYZ')

Simple append binary operation:

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().append('binary-doc', b'XYZ')

Simple append operation with options:

from datetime import timedelta

from couchbase.options import AppendOptions

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().append('string-doc',
                                'XYZ',
                                AppendOptions(timeout=timedelta(seconds=2)))
prepend(key, value, *opts, **kwargs) → MutationResult

Prepends the specified value to the beginning of document of the specified key.

Parameters:

  • key (str) – The key of the document to prepend to.

  • value (Union[str, bytes, bytearray]) – The value to prepend to the document.

  • opts (PrependOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided PrependOptions

Returns:

An instance of MutationResult.

Return type:

MutationResult

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

Examples

Simple prepend string operation:

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().prepend('string-doc', 'ABC')

Simple prepend binary operation:

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().prepend('binary-doc', b'ABC')

Simple prepend operation with options:

from datetime import timedelta

from couchbase.options import PrependOptions

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().prepend('string-doc',
                                'ABC',
                                PrependOptions(timeout=timedelta(seconds=2)))
increment(key, *opts, **kwargs) → CounterResult

Increments the ASCII value of the document, specified by the key, by the amount indicated in the delta option (defaults to 1).

Parameters:

  • key (str) – The key of the document to increment.

  • opts (IncrementOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided IncrementOptions

Returns:

An instance of CounterResult.

Return type:

CounterResult

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

Examples

Simple increment operation:

from couchbase.options import IncrementOptions, SignedInt64

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().increment('counter-doc', IncrementOptions(initial=SignedInt64(100))
print(f'Counter value: {res.content}')

Simple increment operation, change default delta:

from couchbase.options import IncrementOptions, DeltaValue

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().increment('counter-doc', IncrementOptions(delta=DeltaValue(5))
print(f'Counter value: {res.content}')
decrement(key, *opts, **kwargs) → CounterResult

Decrements the ASCII value of the document, specified by the key, by the amount indicated in the delta option (defaults to 1).

Parameters:

  • key (str) – The key of the document to decrement.

  • opts (DecrementOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided DecrementOptions

Returns:

An instance of CounterResult.

Return type:

CounterResult

Raises:

DocumentNotFoundException – If the key provided does not exist on the server.

Examples

Simple decrement operation:

from couchbase.options import DecrementOptions, SignedInt64

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().decrement('counter-doc', DecrementOptions(initial=SignedInt64(100))
print(f'Counter value: {res.content}')

Simple decrement operation, change default delta:

from couchbase.options import DecrementOptions, DeltaValue

# ... other code ...

collection = bucket.default_collection()
res = collection.binary().decrement('counter-doc', DecrementOptions(delta=DeltaValue(5))
print(f'Counter value: {res.content}')
append_multi(keys_and_values, *opts, **kwargs) → MultiMutationResult

For each key-value pair, appends the specified value to the end of the document specified by the key.

Parameters:

  • keys_and_values (Dict[str, Union[str,bytes,bytearray]]) – The key-value pairs to use for the multiple append operations. Each key should correspond to the document to append to and each value should correspond to the value to append to the document.

  • opts (AppendMultiOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided AppendMultiOptions

Returns:

An instance of MultiMutationResult.

Return type:

MultiMutationResult

Raises:

DocumentNotFoundException – If the key provided does not exist on the server and the return_exceptions options is False. Otherwise the exception is returned as a match to the key, but is not raised.

Examples

Simple append-multi string operation:

# ... other code ...

collection = bucket.default_collection()
keys = ['str-doc1', 'str-doc2', 'str-doc3']
values = ['foo', 'bar', 'baz']
keys_and_docs = dict(zip(keys, values))
res = collection.binary().append_multi(keys_and_docs)

Simple append-multi binary operation:

# ... other code ...

collection = bucket.default_collection()
keys = ['bin-doc1', 'bin-doc2', 'bin-doc3']
values = [b'foo', b'bar', b'baz']
keys_and_docs = dict(zip(keys, values))
res = collection.binary().append_multi(keys_and_docs)

Simple append-multi operation with options:

from datetime import timedelta

from couchbase.options import AppendMultiOptions

# ... other code ...

collection = bucket.default_collection()
keys = ['bin-doc1', 'bin-doc2', 'bin-doc3']
values = [b'foo', b'bar', b'baz']
keys_and_docs = dict(zip(keys, values))
res = collection.binary().append_multi(keys_and_docs,
                                    AppendMultiOptions(timeout=timedelta(seconds=2)))

Simple append-multi operation, raise an Exception if an Exception occurs:

from couchbase.options import AppendMultiOptions

# ... other code ...

collection = bucket.default_collection()
keys = ['bin-doc1', 'bin-doc2', 'bin-doc3']
values = [b'foo', b'bar', b'baz']
keys_and_docs = dict(zip(keys, values))
res = collection.binary().append_multi(keys_and_docs,
                                    AppendMultiOptions(return_exceptions=False))

Simple append-multi operation, individual key options:

from datetime import timedelta

from couchbase.options import AppendMultiOptions, AppendOptions

# ... other code ...

collection = bucket.default_collection()
keys = ['bin-doc1', 'bin-doc2', 'bin-doc3']
values = [b'foo', b'bar', b'baz']
keys_and_docs = dict(zip(keys, values))
per_key_opts = {'bin-doc1': AppendOptions(timeout=timedelta(seconds=10))}
res = collection.binary().append_multi(keys_and_docs,
                                    AppendMultiOptions(return_exceptions=False,
                                    per_key_options=per_key_opts))
prepend_multi(keys_and_values, *opts, **kwargs) → MultiMutationResult

For each key-value pair, prepends the specified value to the beginning of the document specified by the key.

Parameters:

  • keys_and_values (Dict[str, Union[str,bytes,bytearray]]) – The key-value pairs to use for the multiple prepend operations. Each key should correspond to the document to prepend to and each value should correspond to the value to prepend to the document.

  • opts (PrependMultiOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided PrependMultiOptions

Returns:

An instance of MultiMutationResult.

Return type:

MultiMutationResult

Raises:

DocumentNotFoundException – If the key provided does not exist on the server and the return_exceptions options is False. Otherwise the exception is returned as a match to the key, but is not raised.

Examples

Simple prepend-multi string operation:

# ... other code ...

collection = bucket.default_collection()
keys = ['str-doc1', 'str-doc2', 'str-doc3']
values = ['foo', 'bar', 'baz']
keys_and_docs = dict(zip(keys, values))
res = collection.binary().prepend_multi(keys_and_docs)

Simple prepend-multi binary operation:

# ... other code ...

collection = bucket.default_collection()
keys = ['bin-doc1', 'bin-doc2', 'bin-doc3']
values = [b'foo', b'bar', b'baz']
keys_and_docs = dict(zip(keys, values))
res = collection.binary().prepend_multi(keys_and_docs)

Simple prepend-multi operation with options:

from datetime import timedelta

from couchbase.options import PrependMultiOptions

# ... other code ...

collection = bucket.default_collection()
keys = ['bin-doc1', 'bin-doc2', 'bin-doc3']
values = [b'foo', b'bar', b'baz']
keys_and_docs = dict(zip(keys, values))
res = collection.binary().prepend_multi(keys_and_docs,
                                    PrependMultiOptions(timeout=timedelta(seconds=2)))

Simple prepend-multi operation, raise an Exception if an Exception occurs:

from couchbase.options import PrependMultiOptions

# ... other code ...

collection = bucket.default_collection()
keys = ['bin-doc1', 'bin-doc2', 'bin-doc3']
values = [b'foo', b'bar', b'baz']
keys_and_docs = dict(zip(keys, values))
res = collection.binary().prepend_multi(keys_and_docs,
                                    PrependMultiOptions(return_exceptions=False))

Simple prepend-multi operation, individual key options:

from datetime import timedelta

from couchbase.options import PrependMultiOptions, PrependOptions

# ... other code ...

collection = bucket.default_collection()
keys = ['bin-doc1', 'bin-doc2', 'bin-doc3']
values = [b'foo', b'bar', b'baz']
keys_and_docs = dict(zip(keys, values))
per_key_opts = {'bin-doc1': PrependOptions(timeout=timedelta(seconds=10))}
res = collection.binary().prepend_multi(keys_and_docs,
                                    PrependMultiOptions(return_exceptions=False,
                                    per_key_options=per_key_opts))
increment_multi(keys, *opts, **kwargs) → MultiCounterResult

For each key in the provided list, increments the ASCII value of the document, specified by the key, by the amount indicated in the delta option (defaults to 1).

Parameters:

  • keys (List[str]) – The keys to use for the multiple increment operations. Each key should correspond to the document to increment.

  • opts (IncrementMultiOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided IncrementMultiOptions

Returns:

An instance of MultiMutationResult.

Return type:

MultiMutationResult

Raises:

DocumentNotFoundException – If the key provided does not exist on the server and the return_exceptions options is False. Otherwise the exception is returned as a match to the key, but is not raised.

Examples

Simple increment-multi operation, set initial value:

from couchbase.options import IncrementMultiOptions, SignedInt64

# ... other code ...

collection = bucket.default_collection()
keys = ['counter_doc1', 'counter_doc1', 'counter_doc1']
res = collection.binary().increment_multi(keys, IncrementMultiOptions(initial=SignedInt64(100))
for k, v in res.results.items():
    print(f'Counter doc {k} has value: {v.content}')

Simple increment-multi operation, change default delta:

from couchbase.options import IncrementMultiOptions, DeltaValue

# ... other code ...

collection = bucket.default_collection()
keys = ['counter_doc1', 'counter_doc1', 'counter_doc1']
res = collection.binary().increment_multi(keys, IncrementMultiOptions(delta=DeltaValue(5))
for k, v in res.results.items():
    print(f'Counter doc {k} has value: {v.content}')

Simple increment-multi operation, raise an Exception if an Exception occurs:

from couchbase.options import IncrementMultiOptions

# ... other code ...

collection = bucket.default_collection()
keys = ['counter_doc1', 'counter_doc1', 'counter_doc1']
res = collection.binary().increment_multi(keys,
                                    IncrementMultiOptions(return_exceptions=False))
for k, v in res.results.items():
    print(f'Counter doc {k} has value: {v.content}')

Simple increment-multi operation, individual key options:

from datetime import timedelta

from couchbase.options import IncrementMultiOptions, IncrementOptions, DeltaValue, SignedInt64

# ... other code ...

collection = bucket.default_collection()
keys = ['counter_doc1', 'counter_doc1', 'counter_doc1']
per_key_opts = {'counter_doc1': IncrementOptions(delta=DeltaValue(100),initial=SignedInt64(100))}
res = collection.binary().increment_multi(keys,
                                    IncrementMultiOptions(per_key_options=per_key_opts))
for k, v in res.results.items():
    print(f'Counter doc {k} has value: {v.content}')
decrement_multi(keys, *opts, **kwargs) → MultiCounterResult

For each key in the provided list, decrements the ASCII value of the document, specified by the key, by the amount indicated in the delta option (defaults to 1).

Parameters:

  • keys (List[str]) – The keys to use for the multiple decrement operations. Each key should correspond to the document to decrement.

  • opts (DecrementMultiOptions) – Optional parameters for this operation.

  • **kwargs (Dict[str, Any]) – keyword arguments that can be used in place or to override provided DecrementMultiOptions

Returns:

An instance of MultiMutationResult.

Return type:

MultiMutationResult

Raises:

DocumentNotFoundException – If the key provided does not exist on the server and the return_exceptions options is False. Otherwise the exception is returned as a match to the key, but is not raised.

Examples

Simple decrement-multi operation, set initial value:

from couchbase.options import DecrementMultiOptions, SignedInt64

# ... other code ...

collection = bucket.default_collection()
keys = ['counter_doc1', 'counter_doc1', 'counter_doc1']
res = collection.binary().decrement_multi(keys, DecrementMultiOptions(initial=SignedInt64(100))
for k, v in res.results.items():
    print(f'Counter doc {k} has value: {v.content}')

Simple decrement-multi operation, change default delta:

from couchbase.options import DecrementMultiOptions, DeltaValue

# ... other code ...

collection = bucket.default_collection()
keys = ['counter_doc1', 'counter_doc1', 'counter_doc1']
res = collection.binary().decrement_multi(keys, DecrementMultiOptions(delta=DeltaValue(5))
for k, v in res.results.items():
    print(f'Counter doc {k} has value: {v.content}')

Simple decrement-multi operation, raise an Exception if an Exception occurs:

from couchbase.options import DecrementMultiOptions

# ... other code ...

collection = bucket.default_collection()
keys = ['counter_doc1', 'counter_doc1', 'counter_doc1']
res = collection.binary().decrement_multi(keys,
                                    DecrementMultiOptions(return_exceptions=False))
for k, v in res.results.items():
    print(f'Counter doc {k} has value: {v.content}')

Simple decrement-multi operation, individual key options:

from datetime import timedelta

from couchbase.options import DecrementMultiOptions, DecrementOptions, DeltaValue, SignedInt64

# ... other code ...

collection = bucket.default_collection()
keys = ['counter_doc1', 'counter_doc1', 'counter_doc1']
per_key_opts = {'counter_doc1': DecrementOptions(delta=DeltaValue(100),initial=SignedInt64(100))}
res = collection.binary().decrement_multi(keys,
                                    DecrementMultiOptions(per_key_options=per_key_opts))
for k, v in res.results.items():
    print(f'Counter doc {k} has value: {v.content}')