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: numpy.ndarray, /)

class neo4j.vector.Vector(data: pyarrow.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. This corresponds to Neo4j 2025.08 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.
- 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.
- pyarrow.Array: Use a pyarrow array to construct the vector. No further parameters are accepted.
dtype –
The type of the vector. See dtype for currently supported inner data types.

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 (_T_VectorDType) – The type of the vector. See also dtype.
byteorder (_T_VectorEndian) – 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:

_t.Self

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 (numpy.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 dtype.

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:

_t.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:: numpy.ndarray

classmethod from_pyarrow(data, /)¶

Create a Vector instance from a pyarrow array.

Parameters:: data (pyarrow.Array) – The pyarrow array to create the vector from. The array must have a type that is supported by Neo4j. See also dtype.
Return type:: _t.Self

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.

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.

Parameters:

data (pyarrow.Array)

Return type:

_t.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:: pyarrow.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