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. Currently Aerospike supports the following language-specific Blob types:
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
resize
resize(policy, bin_name, n_bytes, resize_flags)
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.
Flags: create_only, update_only, no_fail
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)
insert
insert(policy, bin_name, byte_offset, value)
Inserts bytes at the specified byte_offset with the contents of buffer.
Flags: create_only, update_only, no_fail
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)
remove
remove(policy, bin_name, byte_offset, n_bytes)
Remove n_bytes bytes beginning at the specified byte_offset.
Flags: update_only, no_fail, partial
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)
set
set(policy, bin_name, bit_offset, n_bits, value)
Overwrites n_bits bits at the specified offset (in bits) with the first n_bits of value.
Flags: update_only, no_fail, partial
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)
or
or(policy, bin_name, bit_offset, n_bits, value)
Bitwise OR n_bits of the buffer with the leading n_bits of the Blob bin starting from the specified offset (in bits).
Flags: update_only, no_fail, partial
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)
xor
xor(policy, bin_name, bit_offset, n_bits, value)
Bitwise XOR n_bits of the buffer with the leading n_bits of the Blob bin starting from the specified offset (in bits).
Flags: update_only, no_fail, partial
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)
and
and(policy, bin_name, bit_offset, n_bits, value)
Bitwise AND n_bits of the buffer with the leading n_bits of the Blob bin starting from the specified offset (in bits).
Flags: update_only, no_fail, partial
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)
not
not(policy, bin_name, bit_offset, n_bits)
Bitwise NOT n_bits of the Blob bin starting from the specified offset (in bits).
Flags: update_only, no_fail, partial
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)
lshift
lshift(policy, bin_name, bit_offset, n_bits, shift)
Bitwise shift n_bits bits of the Blob bin n_bits to the left starting at the specified offset (in bits).
Flags: update_only, no_fail, partial
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)
rshift
rshift(policy, bin_name, bit_offset, n_bits, shift)
Bitwise shift n_bits bits of the Blob bin n_bits to the right starting at the specified offset (in bits).
Flags: update_only, no_fail, partial
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)
add
add(policy, bin_name, bit_offset, n_bits, value, signed, action)
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.
Flags: update_only, no_fail
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)
subtract
subtract(policy, bin_name, bit_offset, n_bits, value, signed, action)
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.
Flags: update_only, no_fail
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)
set_int
set_int(policy, bin_name, bit_offset, n_bits, value)
Overwrite n_bits bits at offset offset with uint64 converted to an n_bits bit big_endian integer.
Flags: update_only, no_fail
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)
Read Operations
get
get(bin_name, bit_offset, n_bits)
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.
Flags: update_only, no_fail
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)
count
count(bin_name, bit_offset, n_bits)
Count the number of bits set to 1 in the n_bits beginning at offset.
Flags: update_only, no_fail
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)
lscan
lscan(bin_name, bit_offset, n_bits, value)
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.
Flags: update_only, no_fail
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
rscan(bin_name, bit_offset, n_bits, value)
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.
Flags: update_only, no_fail
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)
get_integer
get_integer(bin_name, bit_offset, n_bits, signed)
Retrieve the n_bits bit big-endian integer beginning at offset offset as a 64 bit integer.
Flags: update_only, no_fail
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)