Skip to content

Blob/bytes

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Blob/bytes 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.

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, saving bandwidth.

These operations have expression counterparts, which evaluate to a value instead of writing it. See Bit expressions for the set, and Operations and expressions for which to reach for.

The examples throughout this page use a 5-byte Blob bin called flags with the value [0x01, 0x42, 0xB0, 0x04, 0x05], representing an IoT device configuration record. Bits 0-15 store a 16-bit device ID, byte 2 holds capability flags, and the remaining bytes hold status and version data.

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.

create_only is valid only on resize and insert, the two operations that can create the bin. The other bitwise modify operations reject it.

Most bitwise operations read or modify bits and return bits or an integer. b64_encode is the exception: it returns the base64 text of the blob, or of a byte span within it, as a String, and its offset and size arguments are expressed in bytes rather than bits. It requires Aerospike Database 8.2.0 or later. The decode direction, b64_decode, is a string operation.

Modify operations

add

update_only no_fail 
add(policy, bin_name, bit_offset, bit_size, value, signed, action)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to apply operation.

bit_sizeinteger

Size of the integer in bits (maximum of 64 bits).

valueinteger

The unsigned integer value to be added.

signedboolean

Read the integer from the Blob bin as signed (true) or unsigned (false).

actionOverflow action

How to handle integer overflow.

  • (Default) Fail transaction on overflow.
  • Set maximum value on overflow.
  • Wrap the value from the min value.

Returns
none
Expression form

bit_add

Examples
Increment the device ID

An IoT device stores its configuration in a 5-byte Blob bin called flags. Bits 0-15 hold a 16-bit device ID stored as a big-endian unsigned integer. The add operation increments this integer in place on the server, avoiding a read-modify-write round trip.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], the first 16 bits represent 0x0142 (decimal 322). Calling add("flags", 0, 16, 10) adds 10 to get 332 (0x014C). The result is flags = [0x01, 0x4C, 0xB0, 0x04, 0x05].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]
// bits 0-15: 0x0142 (322) + 10 = 0x014C (332)
import com.aerospike.client.sdk.operation.BitOverflowAction;


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitAdd(0, 16, 10, false, BitOverflowAction.FAIL)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x01, 0x4C, 0xB0, 0x04, 0x05]

and

update_only no_fail partial 
and(policy, bin_name, bit_offset, bit_size, value)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to apply operation.

bit_sizeinteger

Number of bits to apply operation to.

valueblob

Buffer containing at least bit_size bits.

Returns
none
Expression form

bit_and

Examples
Mask the lower nibble of a capability byte

An IoT device stores its configuration in a 5-byte Blob bin called flags. Byte 0 (bits 0-7) holds a device type identifier. ANDing with a mask clears specific bits while preserving others.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], calling and("flags", 0, 8, [0xF0]) masks the first byte with 0xF0 (1111 0000). This clears the lower four bits: 0x01 AND 0xF0 = 0x00. The result is flags = [0x00, 0x42, 0xB0, 0x04, 0x05].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitAnd(0, 8, new byte[] {(byte) 0xF0})
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x00, 0x42, 0xB0, 0x04, 0x05]

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
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

byte_offsetinteger

Offset to location of insertion.

valueblob

Bytes to be inserted.

Returns
none
Expression form

bit_insert

Examples
Insert extra status bytes

An IoT device stores its configuration in a 5-byte Blob bin called flags. To add two new bytes of status data in the middle of the blob, use insert at a byte offset. Existing bytes after the offset shift to the right, growing the blob.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05] (5 bytes), calling insert("flags", 2, [0xAA, 0xBB]) inserts 0xAA 0xBB at byte offset 2. The result is flags = [0x01, 0x42, 0xAA, 0xBB, 0xB0, 0x04, 0x05] (7 bytes).

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05] (5 bytes)


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitInsert(2, new byte[] {(byte) 0xAA, (byte) 0xBB})
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x01, 0x42, 0xAA, 0xBB, 0xB0, 0x04, 0x05] (7 bytes)

lshift

update_only no_fail partial 
lshift(policy, bin_name, bit_offset, bit_size, shift)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to apply operation.

bit_sizeinteger

Number of bits to apply operation to.

shiftinteger

Number of bits to shift.

Returns
none
Expression form

bit_lshift

Examples
Shift the device ID left

An IoT device stores its configuration in a 5-byte Blob bin called flags. Bits 0-15 hold a 16-bit device ID. Left-shifting multiplies the value by a power of 2. Bits shifted out on the left are lost, and zeros fill in on the right.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], the first two bytes are 0x0142 (decimal 322). Calling lshift("flags", 0, 16, 3) shifts the 16-bit field left by 3: 0x0142 << 3 = 0x0A10 (decimal 2576). The result is flags = [0x0A, 0x10, 0xB0, 0x04, 0x05].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]
// bits 0-15: 0x0142 (322) << 3 = 0x0A10 (2576)


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitLshift(0, 16, 3)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x0A, 0x10, 0xB0, 0x04, 0x05]

not

update_only no_fail partial 
not(policy, bin_name, bit_offset, bit_size)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to apply operation.

bit_sizeinteger

Number of bits to apply operation to.

Returns
none
Expression form

bit_not

Examples
Invert a device type byte

An IoT device stores its configuration in a 5-byte Blob bin called flags. NOT inverts every bit in the specified range, flipping 0s to 1s and 1s to 0s.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], calling not("flags", 0, 8) inverts the first byte: NOT 0x01 (0000 0001) = 0xFE (1111 1110). The result is flags = [0xFE, 0x42, 0xB0, 0x04, 0x05].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitNot(0, 8)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0xFE, 0x42, 0xB0, 0x04, 0x05]

or

update_only no_fail partial 
or(policy, bin_name, bit_offset, bit_size, value)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to apply operation.

bit_sizeinteger

Number of bits to apply operation to.

valueblob

Buffer containing at least bit_size bits.

Returns
none
Expression form

bit_or

Examples
Enable a feature flag

An IoT device stores its configuration in a 5-byte Blob bin called flags. Byte 0 (bits 0-7) holds a device type identifier. ORing with a value sets specific bits without affecting others.

Given flags = [0x00, 0x42, 0xB0, 0x04, 0x05], calling or("flags", 0, 8, [0x01]) sets the lowest bit in the first byte: 0x00 OR 0x01 = 0x01. The result is flags = [0x01, 0x42, 0xB0, 0x04, 0x05].

Code sample 
// flags = [0x00, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitOr(0, 8, new byte[] {0x01})
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]

remove

update_only no_fail partial 
remove(policy, bin_name, byte_offset, byte_size)
Description

Remove byte_size bytes beginning at the specified byte_offset.

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

byte_offsetinteger

Offset to location of removal.

byte_sizeinteger

Number of bytes to remove.

Returns
none
Expression form

bit_remove

Examples
Remove bytes from the middle

An IoT device stores its configuration in a 5-byte Blob bin called flags. To remove bytes from the middle of the blob, use remove at a byte offset with a count. Bytes after the removed range shift left, shrinking the blob.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05] (5 bytes), calling remove("flags", 2, 2) removes 2 bytes starting at byte offset 2 (bytes 0xB0 and 0x04). The result is flags = [0x01, 0x42, 0x05] (3 bytes).

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05] (5 bytes)


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitRemove(2, 2)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x01, 0x42, 0x05] (3 bytes)

resize

create_only update_only no_fail 
resize(policy, bin_name, byte_size, resize_flags)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

byte_sizeinteger

Number of bytes to resize to.

resize_flagsResize flags
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
Expression form

bit_resize

Examples
Extend the blob to accommodate new fields

An IoT device stores its configuration in a 5-byte Blob bin called flags. When the device schema grows to include additional fields, resize extends the blob to the new size. New bytes are initialized to zero and appended at the end by default.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05] (5 bytes), calling resize("flags", 10, 0) extends the blob to 10 bytes. The result is flags = [0x01, 0x42, 0xB0, 0x04, 0x05, 0x00, 0x00, 0x00, 0x00, 0x00].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05] (5 bytes)
import com.aerospike.client.sdk.operation.BitResizeFlags;


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitResize(10, BitResizeFlags.DEFAULT)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05, 0x00, 0x00, 0x00, 0x00, 0x00] (10 bytes)

rshift

update_only no_fail partial 
rshift(policy, bin_name, bit_offset, bit_size, shift)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to apply operation.

bit_sizeinteger

Number of bits to apply operation to.

shiftinteger

Number of bits to shift.

Returns
none
Expression form

bit_rshift

Examples
Shift the device ID right

An IoT device stores its configuration in a 5-byte Blob bin called flags. Bits 0-15 hold a 16-bit device ID. Right-shifting divides the value by a power of 2. Bits shifted out on the right are lost, and zeros fill in on the left.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], the first two bytes are 0x0142 (decimal 322). Calling rshift("flags", 0, 16, 3) shifts the 16-bit field right by 3: 0x0142 >> 3 = 0x0028 (decimal 40). The result is flags = [0x00, 0x28, 0xB0, 0x04, 0x05].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]
// bits 0-15: 0x0142 (322) >> 3 = 0x0028 (40)


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitRshift(0, 16, 3)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x00, 0x28, 0xB0, 0x04, 0x05]

set

update_only no_fail partial 
set(policy, bin_name, bit_offset, bit_size, value)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to overwrite.

bit_sizeinteger

Number of bits to overwrite.

valueblob

Buffer containing at least bit_size bits to be written. Bits are taken in order from the beginning of the buffer.

Returns
none
Expression form

bit_set

Examples
Set all capability flags at once

An IoT device stores its configuration in a 5-byte Blob bin called flags. Byte 2 (bits 16-23) holds capability flags. To enable all capabilities at once, overwrite that byte with 0xFF.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], calling set("flags", 16, 8, [0xFF]) replaces byte 2 with 0xFF (1111 1111), turning on every capability bit. The result is flags = [0x01, 0x42, 0xFF, 0x04, 0x05].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitSet(16, 8, new byte[] {(byte) 0xFF})
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x01, 0x42, 0xFF, 0x04, 0x05]

set_int

update_only no_fail 
set_int(policy, bin_name, bit_offset, bit_size, value)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to apply operation.

bit_sizeinteger

Size of the integer in bits (maximum of 64 bits).

valueinteger

The unsigned integer value to be set.

Returns
none
Expression form

bit_set_int

Examples
Set the device ID to a known value

An IoT device stores its configuration in a 5-byte Blob bin called flags. Bits 0-15 hold a 16-bit device ID. Instead of computing the raw bytes for a new ID, set_int writes an integer directly.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], calling set_int("flags", 0, 16, 500) writes 500 (0x01F4) into the first 16 bits as a big-endian integer. The result is flags = [0x01, 0xF4, 0xB0, 0x04, 0x05].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]
// 500 = 0x01F4


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitSetInt(0, 16, 500)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x01, 0xF4, 0xB0, 0x04, 0x05]

subtract

update_only no_fail 
subtract(policy, bin_name, bit_offset, bit_size, value, signed, action)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to apply operation.

bit_sizeinteger

Size of the integer in bits (maximum of 64 bits).

valueinteger

The unsigned integer value to be subtracted.

signedboolean

Read the integer from the Blob bin as signed (true) or unsigned (false).

actionOverflow action

How to handle integer underflow.

  • (Default) Fail transaction on underflow.
  • Set minimum value on underflow.
  • Wrap the value from the max value.

Returns
none
Expression form

bit_subtract

Examples
Decrement the device ID

An IoT device stores its configuration in a 5-byte Blob bin called flags. Bits 0-15 hold a 16-bit device ID stored as a big-endian unsigned integer. The subtract operation decrements this integer in place on the server.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], the first 16 bits represent 0x0142 (decimal 322). Calling subtract("flags", 0, 16, 5) subtracts 5 to get 317 (0x013D). The result is flags = [0x01, 0x3D, 0xB0, 0x04, 0x05].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]
// bits 0-15: 0x0142 (322) - 5 = 0x013D (317)
import com.aerospike.client.sdk.operation.BitOverflowAction;


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitSubtract(0, 16, 5, false, BitOverflowAction.FAIL)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x01, 0x3D, 0xB0, 0x04, 0x05]

xor

update_only no_fail partial 
xor(policy, bin_name, bit_offset, bit_size, value)
Description

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

Arguments
NameTypeDescription
policyBit policy

Bitwise modify policy.

bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to apply operation.

bit_sizeinteger

Number of bits to apply operation to.

valueblob

Buffer containing at least bit_size bits.

Returns
none
Expression form

bit_xor

Examples
Toggle the lower nibble of a byte

An IoT device stores its configuration in a 5-byte Blob bin called flags. XOR flips the bits where the mask has 1s, leaving other bits unchanged. This is useful for toggling specific flags.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], calling xor("flags", 0, 8, [0x0F]) flips the lower four bits of the first byte: 0x01 XOR 0x0F = 0x0E (0000 0001 XOR 0000 1111 = 0000 1110). The result is flags = [0x0E, 0x42, 0xB0, 0x04, 0x05].

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.upsert(key)
    .bin("flags").bitXor(0, 8, new byte[] {0x0F})
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// flags = [0x0E, 0x42, 0xB0, 0x04, 0x05]

Read operations

b64_encode 

b64_encode(bin_name[, byte_offset][, byte_size][, subflags])
Description

Return the base64 text of the Blob bin, or of a byte span within it, as a String.

Arguments
NameTypeDescription
bin_namestring

Name of bin.

byte_offsetinteger

Offset (in bytes) to the first byte to encode, unlike the bit offsets the other bitwise operations take. A negative value counts back from the end of the blob. Optional; defaults to 0.

byte_sizeinteger

Number of bytes to encode, counting forward from byte_offset. When the invert_size subflag is set, byte_size is instead the number of bytes to leave off the end, so the span runs from byte_offset to byte_size bytes before the end of the blob and a byte_size of 0 encodes through to the end. Optional; defaults to the remainder of the blob.

subflagsinteger

invert_size (0x01) makes byte_size the number of bytes to omit from the end of the blob rather than the number to encode from byte_offset. Optional; defaults to 0.

Returns
string
Introduced
8.2.0
Expression form

bit_b64_encode

Examples
Encode a whole blob

Encoding the whole flags bin returns its base64 text as a String. Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], calling b64_encode("flags") returns "AUKwBAU=".

This is the encode direction. b64_decode is the decode direction and takes a String bin back to a blob.

Encode a byte span

Supplying byte_offset and byte_size encodes part of the blob without reading the whole bin. b64_encode("flags", 1, 2) encodes bytes 1 and 2 (0x42, 0xB0) and returns "QrA=".

Setting the invert_size subflag measures byte_size from the end of the blob instead, so a byte_size of 0 runs through to the end: b64_encode("flags", 1, 0, invert_size) encodes bytes 1 through 4 and returns "QrAEBQ==".

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.query(key)
    .bin("flags").bitB64Encode()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns "AUKwBAU="
}


// Bytes 1-2 only.
try (RecordStream rs = session.query(key)
    .bin("flags").bitB64Encode(1, 2)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns "QrA="
}


// Byte 1 through the end (invertSize with a byteSize of 0).
try (RecordStream rs = session.query(key)
    .bin("flags").bitB64Encode(1, 0, true)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns "QrAEBQ=="
}

count 

count(bin_name, bit_offset, bit_size)
Description

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

Arguments
NameTypeDescription
bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to be checked.

bit_sizeinteger

Number of bits to check.

Returns
integer
Expression form

bit_count

Examples
Count enabled capabilities

An IoT device stores its configuration in a 5-byte Blob bin called flags. Bits 0-15 hold a 16-bit device ID. To find out how many bits are set in the device ID field, use count at offset 0 for 16 bits.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], the first two bytes are 0x01 0x42 (0000 0001 0100 0010 in binary). Calling count("flags", 0, 16) returns 3 — three bits are set in the device ID field.

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]
// bits 0-15: 0000 0001 0100 0010


try (RecordStream rs = session.query(key)
    .bin("flags").bitCount(0, 16)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 3
}

get 

get(bin_name, bit_offset, bit_size)
Description

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

Arguments
NameTypeDescription
bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to be retrieved.

bit_sizeinteger

Number of bits to retrieve.

Returns
bytes
Expression form

bit_get

Examples
Read the capability flags byte

An IoT device record stores its configuration in a 5-byte Blob bin called flags. Byte 2 (bits 16-23) holds capability flags such as WiFi, Bluetooth, and GPS. To read just that byte without transferring the entire blob, use get at bit offset 16 for 8 bits.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], calling get("flags", 16, 8) returns [0xB0] — the single capability byte.

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.query(key)
    .bin("flags").bitGet(16, 8)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns [0xB0]
}

get_integer 

get_integer(bin_name, bit_offset, bit_size, signed)
Description

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

Arguments
NameTypeDescription
bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first bit to be retrieved

bit_sizeinteger

Number of bits to retrieve.

signedboolean

If true, treat the value at offset as a signed n_bit bit integer, otherwise treat value as unsigned.

Returns
integer
Expression form

bit_get_int

Examples
Read the device ID as an integer

An IoT device stores its configuration in a 5-byte Blob bin called flags. Bits 0-15 hold a 16-bit device ID stored as a big-endian integer. To read the device ID as a number, use get_integer at offset 0 for 16 bits.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], calling get_integer("flags", 0, 16, false) returns 322 (0x0142 as an unsigned 16-bit integer).

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.query(key)
    .bin("flags").bitGetInt(0, 16, false)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 322 (0x0142 unsigned)
}

lscan 

lscan(bin_name, bit_offset, bit_size, value)
Description

Return the position of the first bit equal to value, scanning the bit_size bits at bit_offset from left to right. The position is relative to bit_offset, so 0 is the bit at bit_offset itself. Returns -1 if no bit matches.

Arguments
NameTypeDescription
bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first (leftmost) bit to be scanned.

bit_sizeinteger

Number of bits from the offset to scan.

valueboolean

If true, search for the first set bit. If false, search for the first unset bit.

Returns
integer
Expression form

bit_lscan

Examples
Find the first set bit in the blob

An IoT device stores its configuration in a 5-byte (40-bit) Blob bin called flags. To find the position of the first set bit across the entire blob, use lscan from offset 0 for all 40 bits, searching left to right.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], the first byte 0x01 is 0000 0001. Calling lscan("flags", 0, 40, true) returns 7 — the first set bit is at position 7 (the least-significant bit of the first byte).

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.query(key)
    .bin("flags").bitLscan(0, 40, true)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 7 (first set bit is at position 7)
}

rscan 

rscan(bin_name, bit_offset, bit_size, value)
Description

Return the position of the last bit equal to value, scanning the bit_size bits at bit_offset from right to left. The position is relative to bit_offset, so 0 is the bit at bit_offset itself. Returns -1 if no bit matches.

Arguments
NameTypeDescription
bin_namestring

Name of bin.

bit_offsetinteger

Offset (in bits) to the first (leftmost) bit to be scanned.

bit_sizeinteger

Number of bits from the offset to scan.

valueboolean

If true, search for the last set bit. If false, search for the last unset bit.

Returns
integer
Expression form

bit_rscan

Examples
Find the last set bit in the blob

An IoT device stores its configuration in a 5-byte (40-bit) Blob bin called flags. To find the position of the last set bit across the entire blob, use rscan from offset 0 for all 40 bits, searching right to left.

Given flags = [0x01, 0x42, 0xB0, 0x04, 0x05], the last byte 0x05 is 0000 0101, so its set bits are at positions 37 and 39. Calling rscan("flags", 0, 40, true) returns 39 — the rightmost set bit, counting from position 0 at the left of the scanned range.

Code sample 
// flags = [0x01, 0x42, 0xB0, 0x04, 0x05]


try (RecordStream rs = session.query(key)
    .bin("flags").bitRscan(0, 40, true)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 39 (last set bit is at position 39)
}