Skip to main content

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: C#, Java, Python, and Ruby.

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.

NameValueDescription
create_only0x01Disallow updating an existing value of this bin.
update_only0x02Disallow creation of a new Blob bin.
no_fail0x04If the operation should fail, continue as if it had succeeded.
partial0X08If 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

Arguments:
  • policy (library_specific): Bitwise modify policy.

  • bin_name (string): Name of bin.

  • n_bytes (integer): Number of bytes to resize to.

  • resize_flags (integer):

    NameValueDescription
    from_front0x01Extend or trim the Blob bin from the beginning instead of the end.
    grow_only0x02Disallow trimming existing objects.
    shrink_only0x04Disallow 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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

Arguments:
  • 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)