Vector Data Types

class neo4j.vector.Vector(data: Iterable[float], dtype: Literal[VectorDType.F32, VectorDType.F64, 'f32', 'f64'], /)
class neo4j.vector.Vector(data: Iterable[int], dtype: Literal[VectorDType.I8, VectorDType.I16, VectorDType.I32, VectorDType.I64, 'i8', 'i16', 'i32', 'i64'], /)
class neo4j.vector.Vector(data: bytes | bytearray, dtype: VectorDType | Literal['f32', 'f64', 'i8', 'i16', 'i32', 'i64'], /, *, byteorder: VectorEndian | Literal['big', 'little'] = 'big')
class neo4j.vector.Vector(data: ndarray, /)
class neo4j.vector.Vector(data: Array, /)

A class representing a Neo4j vector.

The constructor accepts various types of data to create a vector. Depending on data’s type, further arguments may be required/allowed. Examples of valid invocations are:

Vector([1, 2, 3], "i8")
Vector(b"\x00\x01\x00\x02", VectorDType.I16)
Vector(b"\x01\x00\x02\x00", "i16", byteorder="little")
Vector(numpy.array([1, 2, 3]))
Vector(pyarrow.array([1, 2, 3]))

Internally, a vector is stored as a contiguous block of memory (bytes), containing homogeneous values encoded in big-endian order. Support for this feature requires a DBMS supporting Bolt version 6.0 or later.

Parameters:

  • data –

    The data from which the vector will be constructed. The constructor accepts the following types:

    • Iterable[float], Iterable[int] (but not bytes or bytearray): Use an iterable of floats or an iterable of ints to construct the vector from native Python values. The dtype parameter is required. See also: from_native().

    • bytes, bytearray: Use raw bytes to construct the vector. The dtype parameter is required and byteorder is optional.

    • numpy.ndarray: Use a numpy array to construct the vector. No further parameters are accepted. See also: from_numpy().

    • pyarrow.Array: Use a pyarrow array to construct the vector. No further parameters are accepted. See also: from_pyarrow().

  • dtype –

    The type of the vector. See VectorDType for currently supported inner data types. See also dtype.

    This parameter is required if data is of type bytes, bytearray, Iterable[float], or Iterable[int]. Otherwise, it must be omitted.

  • byteorder –

    The endianness of the input data (default: "big"). If "little" is given, neo4j-rust-ext or numpy is used to speed up the internal byte flipping (if either package is installed). Use sys.byteorder if you want to use the system’s native endianness.

    This parameter is optional if data is of type bytes or bytearray. Otherwise, it must be omitted.

Raises:

  • ValueError –

    Depending on the type of data:
    • Iterable[float], Iterable[int] (excluding byte types):

      • If the dtype is not supported.

    • bytes, bytearray:

      • If the dtype is not supported or data’s size is not a multiple of dtype’s size.

      • If byteorder is not one of "big" or "little".

    • numpy.ndarray:

      • If the dtype is not supported.

      • If the array is not one-dimensional.

    • pyarrow.Array:

      • If the array’s type is not supported.

      • If the array contains null values.

  • TypeError –

    Depending on the type of data:
    • Iterable[float], Iterable[int] (excluding byte types):

      • If data’s elements don’t match the expected type depending on dtype.

  • OverflowError –

    Depending on the type of data:
    • Iterable[float], Iterable[int] (excluding byte types):

      • If the value is out of range for the given type.

raw(*, byteorder='big')

Get the raw bytes of the vector.

The data is a continuous block of memory, containing an array of the vector’s data type. The data is stored in big-endian order. Pass another byte-order to this method to get the converted data.

Parameters:

byteorder (VectorEndian | Literal['big', 'little']) – The endianness the data should be returned in. If the data’s byte-order needs flipping, this method tries to use neo4j-rust-ext or numpy, if installed, to speed up the process. Use sys.byteorder if you want to use the system’s native endianness.

Returns:

The raw bytes of the vector.

Raises:

ValueError – If byteorder is not one of "big" or "little".

Return type:

bytes

set_raw(data, /, *, byteorder='big')

Set the raw bytes of the vector.

Parameters:

  • data (bytes) – The new raw bytes of the vector.

  • byteorder (VectorEndian | Literal['big', 'little']) – The endianness of data. The data will always be stored in big-endian order. If passed-in byte-order needs flipping, this method tries to use neo4j-rust-ext or numpy, if installed, to speed up the process. Use sys.byteorder if you want to use the system’s native endianness.

Raises:

  • ValueError –

    • If data’s size is not a multiple of dtype’s size.

    • If byteorder is not one of "big" or "little".

  • TypeError – If the data is not of type bytes.

Return type:

None

property dtype: VectorDType

Get the type of the vector.

Returns:

The type of the vector.

classmethod from_bytes(data, dtype, /, *, byteorder='big')

Create a Vector instance from raw bytes.

Parameters:

  • data (bytes) – The raw bytes to create the vector from.

  • dtype (VectorDType | Literal['f32', 'f64', 'i8', 'i16', 'i32', 'i64']) – The type of the vector. See also dtype.

  • byteorder (VectorEndian | Literal['big', 'little']) – The endianness of the data. If "little", the bytes in data will be flipped to big-endian. If installed, neo4j-rust-ext or numpy will be used to speed up the byte flipping. Use sys.byteorder if you want to use the system’s native endianness.

Raises:

  • ValueError –

    • If data’s size is not a multiple of dtype’s size.

    • If byteorder is not one of "big" or "little".

  • TypeError – If the data is not of type bytes.

Return type:

Self

classmethod from_native(data: Iterable[float], dtype: Literal[VectorDType.F32, VectorDType.F64, 'f32', 'f64'], /) → Self
classmethod from_native(data: Iterable[int], dtype: Literal[VectorDType.I8, VectorDType.I16, VectorDType.I32, VectorDType.I64, 'i8', 'i16', 'i32', 'i64'], /) → Self

Create a Vector instance from an iterable of values.

Parameters:

  • data – The list, tuple, or other iterable of values to create the vector from.

  • dtype – The type of the vector. See also dtype.

data must contain values that match the expected type given by dtype:

  • dtype == "f32": float

  • dtype == "f64": float

  • dtype == "i8": int

  • dtype == "i16": int

  • dtype == "i32": int

  • dtype == "i64": int

Raises:

  • ValueError – If the dtype is not supported.

  • TypeError – If data’s elements don’t match the expected type depending on dtype.

  • OverflowError – If the value is out of range for the given type.

to_native()

Convert the vector to a native Python list.

The type of the elements in the list depends on the dtype of the vector. See Vector.from_native() for details.

Returns:

A list of values representing the vector.

Return type:

list[object]

classmethod from_numpy(data, /)

Create a Vector instance from a numpy array.

Parameters:

data (ndarray) – The numpy array to create the vector from. The array must be one-dimensional and have a dtype that is supported by Neo4j vectors: float64, float32, int64, int32, int16, or int8. See also VectorDType.

Raises:

  • ValueError –

    • If the dtype is not supported.

    • If the array is not one-dimensional.

  • ImportError – If numpy is not installed.

Returns:

A Vector instance constructed from the numpy array.

Return type:

Self

to_numpy()

Convert the vector to a numpy array.

The array’s dtype depends on the dtype of the vector. However, it will always be in big-endian order.

Returns:

A numpy array representing the vector.

Raises:

ImportError – If numpy is not installed.

Return type:

ndarray

classmethod from_pyarrow(data, /)

Create a Vector instance from a pyarrow array.

PyArrow stores data in little endian. Therefore, the byte-order needs to be swapped. If neo4j-rust-ext or numpy is installed, it will be used to speed up the byte flipping.

Parameters:

data (Array) – The pyarrow array to create the vector from. The array must have a type that is supported by Neo4j. See also VectorDType.

Raises:

  • ValueError –

    • If the array’s type is not supported.

    • If the array contains null values.

  • ImportError – If pyarrow is not installed.

Returns:

A Vector instance constructed from the pyarrow array.

Return type:

Self

to_pyarrow()

Convert the vector to a pyarrow array.

Returns:

A pyarrow array representing the vector.

Raises:

ImportError – If pyarrow is not installed.

Return type:

Array

class neo4j.vector.VectorEndian(*values)

Bases: str, Enum

Data endianness (i.e., byte order) of the elements in a Vector.

Inherits from str and enum.Enum. Every driver API accepting a VectorEndian value will also accept a string:

>>> VectorEndian.BIG == "big"
True
>>> VectorEndian.LITTLE == "little"
True

See also

Vector.raw

Added in version 6.0.

BIG = 'big'
LITTLE = 'little'
class neo4j.vector.VectorDType(*values)

Bases: str, Enum

The data type of the elements in a Vector.

Currently supported types are:

  • f32: 32-bit floating point number (single)

  • f64: 64-bit floating point number (double)

  • i8: 8-bit integer

  • i16: 16-bit integer

  • i32: 32-bit integer

  • i64: 64-bit integer

Inherits from str and enum.Enum. Every driver API accepting a VectorDType value will also accept a string:

>>> VectorDType.F32 == "f32"
True
>>> VectorDType.I8 == "i8"
True

See also

Vector.dtype

Added in version 6.0.

F32 = 'f32'
F64 = 'f64'
I8 = 'i8'
I16 = 'i16'
I32 = 'i32'
I64 = 'i64'