Blob/bytes

Aerospike supports two main types of Blob/bytes bins. There are general purpose Blob bins and language-specific Blob bins.

The general purpose Blob bins are byte arrays of a specific size. Any binary data of any type can be stored in a Blob bin. They also support Bitwise Operations.

Language-specific Blob bins are only accessible from the client library language that wrote them. These are useful for serializing objects in that language to the Aerospike database.

Bitwise Operations

Aerospike supports a rich set of bitwise operations which can be used on the Blob data type. These operations allow an application to manipulate a large Blob bin on the server without needing to pull the entire blob to the client which can save client to server bandwidth.

Name	Value	Description
`create_only`	`0x01`	Disallow updating an existing value of this bin.
`update_only`	`0x02`	Disallow creation of a new Blob bin.
`no_fail`	`0x04`	If the operation should fail, continue as if it had succeeded.
`partial`	`0X08`	If the number of bytes from the offset to the end of the existing Blob bin is less than the specified number of bytes, then only apply the operations from the offset to the end.

Modify operations

`add`

update_only no_fail

add(policy, bin_name, bit_offset, n_bits, value, signed, action)

Description

Treat the n_bits bits beginning at offset in the Blob bin as an n_bits bit integer and add the integer value to it - the integer value will be converted to an n_bits bit integer. By default, fail if the result overflows. Integers in the Blob bin are stored and interpreted as big-endian integers.

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to apply operation.
`n_bits`	`integer`	Size of the integer in bits (maximum of 64 bits).
`value`	`integer`	The unsigned integer value to be added.
`signed`	`boolean`	Read the integer from the Blob bin as signed (true) or unsigned (false).
`action`	`client_specific`	How to handle integer overflow. (Default) Fail transaction on overflow. Set maximum value on overflow. Wrap the value from the min value.

Returns

none

`and`

update_only no_fail partial

and(policy, bin_name, bit_offset, n_bits, value)

Description

Bitwise AND n_bits of the buffer with the leading n_bits of the Blob bin starting from the specified offset (in bits).

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to apply operation.
`n_bits`	`integer`	Number of bits to apply operation to.
`value`	`bytes`	Buffer containing at least `n_bits` bits.

Returns

none

`insert`

create_only update_only no_fail

insert(policy, bin_name, byte_offset, value)

Description

Inserts bytes at the specified byte_offset with the contents of buffer.

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`byte_offset`	`integer`	Offset to location of insertion.
`value`	`bytes`	Bytes to be inserted.

Returns

none

`lshift`

update_only no_fail partial

lshift(policy, bin_name, bit_offset, n_bits, shift)

Description

Bitwise shift n_bits bits of the Blob bin n_bits to the left starting at the specified offset (in bits).

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to apply operation.
`n_bits`	`integer`	Number of bits to apply operation to.
`shift`	`integer`	Number of bits to shift.

Returns

none

`not`

update_only no_fail partial

not(policy, bin_name, bit_offset, n_bits)

Description

Bitwise NOT n_bits of the Blob bin starting from the specified offset (in bits).

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to apply operation.
`n_bits`	`integer`	Number of bits to apply operation to.

Returns

none

`or`

update_only no_fail partial

or(policy, bin_name, bit_offset, n_bits, value)

Description

Bitwise OR n_bits of the buffer with the leading n_bits of the Blob bin starting from the specified offset (in bits).

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to apply operation.
`n_bits`	`integer`	Number of bits to apply operation to.
`value`	`bytes`	Buffer containing at least `n_bits` bits.

Returns

none

`remove`

update_only no_fail partial

remove(policy, bin_name, byte_offset, n_bytes)

Description

Remove n_bytes bytes beginning at the specified byte_offset.

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`byte_offset`	`integer`	Offset to location of removal.
`n_bytes`	`integer`	Number of bytes to remove.

Returns

none

`resize`

create_only update_only no_fail

resize(policy, bin_name, n_bytes, resize_flags)

Description

Specify the size of the Blob bin to be n_bytes. This operation may (by default) create a new Bytes bin or extend or trim an existing Byte bin to the specified size of n_bytes. By default the resize operation will extend or trim from the end of the Blob bin.

Arguments

Name Type Description

policy

library_specific

Bitwise modify policy.

bin_name

string

Name of bin.

n_bytes

integer

Number of bytes to resize to.

resize_flags

integer

Name	Value	Description
from_front	0x01	Extend or trim the Blob bin from the beginning instead of the end.
grow_only	0x02	Disallow trimming existing objects.
shrink_only	0x04	Disallow extending existing objects.

Returns

none

`rshift`

update_only no_fail partial

rshift(policy, bin_name, bit_offset, n_bits, shift)

Description

Bitwise shift n_bits bits of the Blob bin n_bits to the right starting at the specified offset (in bits).

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to apply operation.
`n_bits`	`integer`	Number of bits to apply operation to.
`shift`	`integer`	Number of bits to shift.

Returns

none

`set`

update_only no_fail partial

set(policy, bin_name, bit_offset, n_bits, value)

Description

Overwrites n_bits bits at the specified offset (in bits) with the first n_bits of value.

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to overwrite.
`n_bits`	`integer`	Number of bits to overwrite.
`value`	`bytes`	Buffer containing at least `n_bits` bits to be written. Bits are taken in order from the beginning of the buffer.

Returns

none

`set_int`

update_only no_fail

set_int(policy, bin_name, bit_offset, n_bits, value)

Description

Overwrite n_bits bits at offset offset with uint64 converted to an n_bits bit big_endian integer.

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to apply operation.
`n_bits`	`integer`	Size of the integer in bits (maximum of 64 bits).
`value`	`integer`	The unsigned integer value to be set.

Returns

none

`subtract`

update_only no_fail

subtract(policy, bin_name, bit_offset, n_bits, value, signed, action)

Description

Treat the n_bits bits beginning at offset in the Blob bin as an n_bits bit integer and subtract the integer uint64 from it - the integer uint64 will be converted to an n_bits bit integer. By default, fail if the result underflows. Integers in the Blob bin are stored and interpreted as big-endian integers.

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to apply operation.
`n_bits`	`integer`	Size of the integer in bits (maximum of 64 bits).
`value`	`integer`	The unsigned integer value to be subtracted.
`signed`	`boolean`	Read the integer from the Blob bin as signed (true) or unsigned (false).
`action`	`client_specific`	How to handle integer underflow. (Default) Fail transaction on underflow. Set minimum value on underflow. Wrap the value from the max value.

Returns

none

`xor`

update_only no_fail partial

xor(policy, bin_name, bit_offset, n_bits, value)

Description

Bitwise XOR n_bits of the buffer with the leading n_bits of the Blob bin starting from the specified offset (in bits).

Arguments

Name	Type	Description
`policy`	`library_specific`	Bitwise modify policy.
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to apply operation.
`n_bits`	`integer`	Number of bits to apply operation to.
`value`	`bytes`	Buffer containing at least `n_bits` bits.

Returns

none

Read operations

`count`

update_only no_fail

count(bin_name, bit_offset, n_bits)

Description

Count the number of bits set to 1 in the n_bits beginning at offset.

Arguments

Name	Type	Description
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to be checked.
`n_bits`	`integer`	Number of bits to check.

Returns

bytes

`get`

update_only no_fail

get(bin_name, bit_offset, n_bits)

Description

Retrieve n_bits bits beginning at offset offset. If n_bits is not a multiple of 8 then there will be n_bits modulo 8 zeroed bits padding the end.

Arguments

Name	Type	Description
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to be retrieved.
`n_bits`	`integer`	Number of bits to retrieve.

Returns

bytes

`get_integer`

update_only no_fail

get_integer(bin_name, bit_offset, n_bits, signed)

Description

Retrieve the n_bits bit big-endian integer beginning at offset offset as a 64 bit integer.

Arguments

Name	Type	Description
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first bit to be retrieved
`n_bits`	`integer`	Number of bits to retrieve.
`signed`	`boolean`	If true, treat the value at offset as a signed `n_bit` bit integer, otherwise treat value as unsigned.

Returns

integer

`lscan`

update_only no_fail

lscan(bin_name, bit_offset, n_bits, value)

Description

Return the position relative to the offset of the first bit set to value searching from offset plus n_bits to offset. If the value isn’t found, returns -1.

Arguments

Name	Type	Description
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first (leftmost) bit to be scanned.
`n_bits`	`integer`	Number of bits from the `offset` to scan.
`value`	`boolean`	If true, search for the first set bit. If false, search for the first unset bit.

Returns

integer

`rscan`

update_only no_fail

rscan(bin_name, bit_offset, n_bits, value)

Description

Return the position relative to the offset of the first bit set to value searching from offset to offset plus n_bits. If the value isn’t found, returns -1.

Arguments

Name	Type	Description
`bin_name`	`string`	Name of bin.
`bit_offset`	`integer`	Offset (in bits) to the first (leftmost) bit to be scanned.
`n_bits`	`integer`	Number of bits from the `offset` to scan.
`value`	`boolean`	If true, search for the first set bit. If false, search for the first unset bit.

Returns

integer