必须使用oracle database 23ai+及官方oracle-vector-store连接器（23.4.0-preview）操作矢量功能，禁用原生sql；实体需用@embedding注解float[]字段，严格匹配维度，通过similaritysearch调用带vector_index hint的查询。
不能直接用 Spring Boot 的常规 JDBC 方式操作 Oracle 23c 的矢量功能——它不是普通表字段加个索引就能查向量相似度的。必须通过 Oracle 官方提供的 OracleVectorStore 连接器（预览版），且依赖 Oracle Database 23ai 或更高版本（23c beta 不支持矢量搜索）。
确认 Oracle 版本是否真正支持矢量能力
Oracle Database 23c（beta）本身不包含矢量搜索能力；官方明确要求使用 Oracle Database 23ai 或更新版本。运行以下 SQL 验证：
SELECT BANNER_FULL FROM V$VERSION;
输出中必须含 Oracle Database 23ai 字样。若显示 23c 或 23.4.0.0.0 等不含 ai 后缀的版本，矢量函数（如 COSINE_DISTANCE、HNSW 索引）将不可用，调用会报 ORA-00904: invalid identifier 或 ORA-30556 类错误。
Java 项目必须引入 Oracle Vector Store 连接器
Spring Boot 默认不带该能力，需手动引入 Oracle 提供的预览版 SDK：
- 对 Maven 项目，在
pom.xml中添加：
<dependency><groupid>com.oracle.database.ai</groupid><artifactid>oracle-vector-store</artifactid><version>23.4.0-preview</version></dependency>
注意：oracle-vector-store 是独立 artifact，不是 ojdbc8 或 spring-boot-starter-jdbc 的一部分；它封装了向量集合映射、嵌入写入、HNSW/IVF 索引创建及 CosineDistance 查询逻辑。
- 连接字符串需启用 Oracle AI 功能：在
application.yml中确保spring.datasource.url包含oracle.net.disableOob=true和oracle.jdbc.useFetchSizeWithLongColumn=true，否则向量批量写入可能失败
实体类必须按 Oracle Vector Store 规范声明向量字段
不能用 @Column 或 @JdbcTypeCode 直接映射 float 数组——Oracle 要求向量字段为 BINARY_FLOAT 数组类型，并显式标注 @Embedding 注解：
public class ProductEmbedding {
@Id
private String id;
<pre class="brush:php;toolbar:false;">@Embedding // ← 必须用这个注解，不是 JPA 的 @ElementCollection
private float[] vector; // ← 只支持 float[] / double[] / byte[]，不能是 List<float>
private String productName;</float>}
常见踩坑点：
-
vector字段长度必须与创建表时定义的维度严格一致（例如建表用VECTOR(1024, FLOAT32)，代码里就必须是float[1024]，错一位就抛ORA-40695 - 不支持
String类型字段参与向量查询条件；筛选子句只能用==、!=、List.contains()，不能用LIKE或全文检索 -
DistanceFunction必须显式传参，比如CosineDistance对应字符串"COSINE"，大小写敏感，拼错会静默降级为平面扫描
查询必须走 OracleVectorStore API，不能写原生 SQL
即使你知道 Oracle 23ai 支持 SELECT * FROM t ORDER BY COSINE_DISTANCE(vector, ?) FETCH FIRST 5 ROWS ONLY，也不要在 JdbcTemplate 或 MyBatis 里手写——因为：
- 缺少向量参数序列化逻辑，JDBC 驱动不认识
float[]到VECTOR类型的转换 - 无法自动绑定
HNSW索引 hint，查询会退化为全表扫描 - 没有内置的嵌入缓存和连接复用，高并发下易触发
ORA-12519
正确做法是注入 OracleVectorStore Bean，调用其 similaritySearch 方法：
var query = new SearchRequest()
.withQueryEmbedding(embedding)
.withTopK(5)
.withDistanceFunction("COSINE")
.withFilter("category == 'laptop'"); // ← 这里才支持简单过滤
vectorStore.similaritySearch(query);
该方法内部会生成带 /*+ VECTOR_INDEX(t.idx_vector) */ hint 的语句，并复用连接池中的已认证会话。
最后提醒：预览版连接器不支持事务内混合 DML + 向量操作（比如在 @Transactional 方法里先 INSERT 普通数据再 vectorStore.add()），会抛 ORA-02095；必须拆成两个独立事务，或改用存储过程封装。
