需选用何种JPA + Hibernate数据类型以支持PostgreSQL的vector扩展？

要在JPA实体中映射PostgreSQL的vector类型来存储embeddings，可通过以下两种方式实现：

1. 使用pgvector官方Hibernate适配 #

步骤1：添加依赖 #

如果用Maven，引入pgvector的Hibernate集成包：

<dependency>
    <groupId>com.github.pgvector</groupId>
    <artifactId>pgvector-hibernate</artifactId>
    <version>0.1.0</version> <!-- 建议使用最新版本 -->
</dependency>

步骤2：编写实体类 #

在实体类里用官方提供的VectorType映射embedding字段：

import com.github.pgvector.hibernate.VectorType;
import jakarta.persistence.*;
import org.hibernate.annotations.Type;

@Entity
@Table(name = "items")
public class Item {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Type(VectorType.class)
    @Column(columnDefinition = "vector(3)")
    private float[] embedding;

    // 构造方法、getter/setter
    public Item() {}

    public Item(float[] embedding) {
        this.embedding = embedding;
    }

    // 省略getter和setter
}

2. 自定义Hibernate类型（无需额外依赖） #

如果不想引入第三方包，可以自己实现Hibernate的UserType来处理vector类型：

import org.hibernate.engine.spi.SharedSessionContractImplementor;
import org.hibernate.usertype.UserType;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Types;
import java.util.Objects;

public class VectorType implements UserType<float[]> {
    @Override
    public int[] sqlTypes() {
        return new int[]{Types.OTHER};
    }

    @Override
    public Class<float[]> returnedClass() {
        return float[].class;
    }

    @Override
    public boolean equals(float[] x, float[] y) {
        return Objects.deepEquals(x, y);
    }

    @Override
    public int hashCode(float[] x) {
        return Objects.hash(x);
    }

    @Override
    public float[] nullSafeGet(ResultSet rs, String[] names, SharedSessionContractImplementor session, Object owner) throws SQLException {
        String value = rs.getString(names[0]);
        if (value == null) return null;
        // 解析PostgreSQL vector格式字符串为float数组
        value = value.replaceAll("[\\[\\]]", "");
        String[] parts = value.split(",");
        float[] result = new float[parts.length];
        for (int i = 0; i < parts.length; i++) {
            result[i] = Float.parseFloat(parts[i]);
        }
        return result;
    }

    @Override
    public void nullSafeSet(PreparedStatement st, float[] value, int index, SharedSessionContractImplementor session) throws SQLException {
        if (value == null) {
            st.setNull(index, Types.OTHER);
        } else {
            // 将float数组转为PostgreSQL vector格式字符串
            StringBuilder sb = new StringBuilder("[");
            for (int i = 0; i < value.length; i++) {
                sb.append(value[i]);
                if (i != value.length - 1) sb.append(",");
            }
            sb.append("]");
            st.setObject(index, sb.toString(), Types.OTHER);
        }
    }

    @Override
    public float[] deepCopy(float[] value) {
        return value == null ? null : value.clone();
    }

    @Override
    public boolean isMutable() {
        return true;
    }

    @Override
    public Serializable disassemble(float[] value) {
        return deepCopy(value);
    }

    @Override
    public float[] assemble(Serializable cached, Object owner) {
        return deepCopy((float[]) cached);
    }

    @Override
    public float[] replace(float[] original, float[] target, Object owner) {
        return deepCopy(original);
    }
}

之后在实体类中引用这个自定义类型即可：

@Type(VectorType.class)
@Column(columnDefinition = "vector(3)")
private float[] embedding;

验证使用 #

启动应用后，Hibernate会自动匹配或生成目标表结构。你可以直接通过实体类操作embedding字段：

Item item = new Item(new float[]{1.0f, 2.0f, 3.0f});
entityManager.persist(item);

// 查询示例
List<Item> items = entityManager.createQuery("FROM Item", Item.class).getResultList();

注意：确保PostgreSQL已安装pgvector扩展，可执行CREATE EXTENSION IF NOT EXISTS vector;开启。

内容的提问来源于stack exchange，提问作者user352290