Package org.bson

Class BinaryVector

java.lang.Object

org.bson.BinaryVector

Direct Known Subclasses:

Float32BinaryVector, Int8BinaryVector, PackedBitBinaryVector

public abstract class BinaryVector
extends Object

Binary Vectors are densely packed arrays of numbers, all the same type, which are stored and retrieved efficiently using the BSON Binary Subtype 9 format. This class supports multiple vector BinaryVector.DataType's and provides static methods to create vectors.

NOTE: This class should be treated as sealed: it must not be extended or implemented by consumers of the library.

Since:

5.3

See Also:

• BsonBinary

Since server release

6.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	BinaryVector.DataType	Represents the data type (dtype) of a vector.

Method Summary

Modifier and Type	Method	Description
Float32BinaryVector	asFloat32Vector()	Returns the Float32BinaryVector.
Int8BinaryVector	asInt8Vector()	Returns the Int8BinaryVector.
PackedBitBinaryVector	asPackedBitVector()	Returns the PackedBitBinaryVector.
static Float32BinaryVector	floatVector(float[] data)	Creates a vector with the BinaryVector.DataType.FLOAT32 data type.
BinaryVector.DataType	getDataType()	Returns BinaryVector.DataType of the vector.
static Int8BinaryVector	int8Vector(byte[] data)	Creates a vector with the BinaryVector.DataType.INT8 data type.
static PackedBitBinaryVector	packedBitVector(byte[] data, byte padding)	Creates a vector with the BinaryVector.DataType.PACKED_BIT data type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

packedBitVector

@Beta(SERVER)
public static PackedBitBinaryVector packedBitVector(byte[] data,
 byte padding)

Creates a vector with the BinaryVector.DataType.PACKED_BIT data type.

A BinaryVector.DataType.PACKED_BIT vector is a binary quantized vector where each element of a vector is represented by a single bit (0 or 1). Each byte can hold up to 8 bits (vector elements). The padding parameter is used to specify how many least-significant bits in the final byte should be ignored.

For example, a vector with two bytes and a padding of 4 would have the following structure:

 Byte 1: 238 (binary: 11101110)
 Byte 2: 224 (binary: 11100000)
 Padding: 4 (ignore the last 4 bits in Byte 2)
 Resulting vector: 12 bits: 111011101110
 

NOTE: The byte array `data` is not copied; changes to the provided array will be reflected in the created PackedBitBinaryVector instance.

Parameters:

data - The byte array representing the packed bit vector data. Each byte can store 8 bits.

padding - The number of least-significant bits (0 to 7) to ignore in the final byte of the vector data.

Returns:

A PackedBitBinaryVector instance with the BinaryVector.DataType.PACKED_BIT data type.

Throws:

IllegalArgumentException - If the padding value is greater than 7.

int8Vector

public static Int8BinaryVector int8Vector(byte[] data)

Creates a vector with the BinaryVector.DataType.INT8 data type.

A BinaryVector.DataType.INT8 vector is a vector of 8-bit signed integers where each byte in the vector represents an element of a vector, with values in the range [-128, 127].

NOTE: The byte array `data` is not copied; changes to the provided array will be reflected in the created Int8BinaryVector instance.

Parameters:

data - The byte array representing the BinaryVector.DataType.INT8 vector data.

Returns:

A Int8BinaryVector instance with the BinaryVector.DataType.INT8 data type.

floatVector

public static Float32BinaryVector floatVector(float[] data)

Creates a vector with the BinaryVector.DataType.FLOAT32 data type.

A BinaryVector.DataType.FLOAT32 vector is a vector of floating-point numbers, where each element in the vector is a float.

NOTE: The float array `data` is not copied; changes to the provided array will be reflected in the created Float32BinaryVector instance.

Parameters:

data - The float array representing the BinaryVector.DataType.FLOAT32 vector data.

Returns:

A Float32BinaryVector instance with the BinaryVector.DataType.FLOAT32 data type.

asPackedBitVector

public PackedBitBinaryVector asPackedBitVector()

Returns the PackedBitBinaryVector.

Returns:

PackedBitBinaryVector.

Throws:

IllegalStateException - if this vector is not of type BinaryVector.DataType.PACKED_BIT. Use getDataType() to check the vector type before calling this method.

asInt8Vector

public Int8BinaryVector asInt8Vector()

Returns the Int8BinaryVector.

Returns:

Int8BinaryVector.

Throws:

IllegalStateException - if this vector is not of type BinaryVector.DataType.INT8. Use getDataType() to check the vector type before calling this method.

asFloat32Vector

public Float32BinaryVector asFloat32Vector()

Returns the Float32BinaryVector.

Returns:

Float32BinaryVector.

Throws:

IllegalStateException - if this vector is not of type BinaryVector.DataType.FLOAT32. Use getDataType() to check the vector type before calling this method.

getDataType

public BinaryVector.DataType getDataType()

Returns BinaryVector.DataType of the vector.

Returns:

the data type of the vector.