Binary collection

class acouchbase.binary_collection.BinaryCollection(impl: AsyncBinaryCollectionInterface)

The operations on a collection’s binary documents and counters.

Get one from binary().

async append(key: str, value: str | bytes | bytearray, opts: AppendOptions | None = None, **kwargs: Unpack[AppendOptionsKwargs]) → 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 (str | bytes | bytearray) – The value to append to the document.

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

  • **kwargs – keyword arguments that can be used in place or to override provided AppendOptions

Returns:

A future that contains an instance of MutationResult if successful.

Return type:

Awaitable[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 = await collection.binary().append('string-doc', 'XYZ')

Simple append binary operation:

# ... other code ...

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

Simple append operation with options:

from datetime import timedelta

from acouchbase.options import AppendOptions

# ... other code ...

collection = bucket.default_collection()
res = await collection.binary().append('string-doc',
                                        'XYZ',
                                        AppendOptions(timeout=timedelta(seconds=2)))
async decrement(key: str, opts: DecrementOptions | None = None, **kwargs: Unpack[DecrementOptionsKwargs]) → CounterResult

Decrements the counter held in a document by the delta option, which defaults to 1.

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

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

  • **kwargs – keyword arguments that can be used in place or to override provided DecrementOptions

Returns:

A future that contains an instance of CounterResult if successful.

Return type:

Awaitable[CounterResult]

Raises:

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

Examples

Simple decrement operation:

from acouchbase.options import DecrementOptions, SignedInt64

# ... other code ...

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

Simple decrement operation, change default delta:

from acouchbase.options import DecrementOptions, DeltaValue

# ... other code ...

collection = bucket.default_collection()
res = await collection.binary().decrement('counter-doc', DecrementOptions(delta=DeltaValue(5))
print(f'Counter value: {res.content}')
async increment(key: str, opts: IncrementOptions | None = None, **kwargs: Unpack[IncrementOptionsKwargs]) → CounterResult

Increments the counter held in a document by the delta option, which defaults to 1.

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

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

  • **kwargs – keyword arguments that can be used in place or to override provided IncrementOptions

Returns:

A future that contains an instance of CounterResult if successful.

Return type:

Awaitable[CounterResult]

Raises:

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

Examples

Simple increment operation:

from acouchbase.options import IncrementOptions, SignedInt64

# ... other code ...

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

Simple increment operation, change default delta:

from acouchbase.options import IncrementOptions, DeltaValue

# ... other code ...

collection = bucket.default_collection()
res = await collection.binary().increment('counter-doc', IncrementOptions(delta=DeltaValue(5))
print(f'Counter value: {res.content}')
async prepend(key: str, value: str | bytes | bytearray, opts: PrependOptions | None = None, **kwargs: Unpack[PrependOptionsKwargs]) → 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 (str | bytes | bytearray) – The value to prepend to the document.

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

  • **kwargs – keyword arguments that can be used in place or to override provided PrependOptions

Returns:

A future that contains an instance of MutationResult if successful.

Return type:

Awaitable[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 = await collection.binary().prepend('string-doc', 'ABC')

Simple prepend binary operation:

# ... other code ...

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

Simple prepend operation with options:

from datetime import timedelta

from acouchbase.options import PrependOptions

# ... other code ...

collection = bucket.default_collection()
res = await collection.binary().prepend('string-doc',
                                        'ABC',
                                        PrependOptions(timeout=timedelta(seconds=2)))