# vector_demo_for_java

**Repository Path**: dbalyy_dbalyy/vector_demo_for_java

## Basic Information

- **Project Name**: vector_demo_for_java
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vastbase/VexDB 向量数据库 Java Demo

这是一个通过 Java 访问 Vastbase/VexDB 向量数据库的示例项目，展示了如何使用 MyBatis 进行向量数据的存储、查询和相似度搜索。

## 功能特性

- **向量数据 CRUD 操作**：支持创建、查询、更新、删除向量文档
- **批量插入**：支持批量导入向量数据
- **向量相似度搜索**：
  - 余弦相似度搜索 (Cosine Similarity)
  - 欧几里得距离搜索 (Euclidean Distance)
  - 内积距离搜索 (Inner Product)
- **全文检索**：支持 BM25 全文检索和关键字匹配

## 技术栈

- **Java 版本**: 11
- **数据库**: Vastbase/VexDB (兼容 PostgreSQL)
- **ORM 框架**: MyBatis 3 + MyBatis-Plus
- **向量类型处理**: PGvector
- **测试框架**: JUnit 5

## 项目结构

```
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   ├── cn/com/vastbase/
│   │   │   │   └── PGvectorTypeHandler.java    # 向量类型处理器
│   │   │   ├── generator/
│   │   │   │   ├── domain/
│   │   │   │   │   └── VectorDocument.java     # 向量文档实体
│   │   │   │   ├── mapper/
│   │   │   │   │   └── VectorDocumentMapper.java # 数据访问层
│   │   │   │   └── service/
│   │   │   │       └── VectorDocumentService.java # 业务逻辑层
│   │   │   └── org/example/
│   │   │       └── MainDemo.java                # 示例主程序
│   │   └── resources/
│   │       ├── generator/mapper/
│   │       │   └── VectorDocumentMapper.xml     # MyBatis Mapper 配置
│   │       └── mybatis-config.xml               # MyBatis 主配置
│   └── test/
│       └── java/
│           └── generator/service/
│               └── VectorDocumentServiceTest.java # 单元测试
├── pom.xml                                       # Maven 配置
└── README.md                                     # 项目说明
```

## 环境要求

- JDK 11 或更高版本
- Maven 3.6+
- Vastbase/VexDB 数据库 (推荐版本 2.0+)

## 快速开始

### 1. 数据库配置

在 `src/main/resources/mybatis-config.xml` 中配置数据库连接信息：

```xml
<dataSource type="POOLED">
    <property name="driver" value="org.postgresql.Driver"/>
    <property name="url" value="jdbc:postgresql://localhost:5432/test"/>
    <property name="username" value="test"/>
    <property name="password" value="your_password"/>
</dataSource>
```

### 2. 创建数据库表

执行以下 SQL 语句创建向量文档表：

```sql
CREATE TABLE vector_documents (
    id BIGSERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    vector FLOATVECTOR(128),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 创建向量索引（可选但建议）
CREATE INDEX ON vector_documents USING graph_index (vector floatvector_l2_ops) WITH (m=32, ef_construction=200, parallel_workers=8);
CREATE INDEX ON vector_documents USING graph_index (vector floatvector_ip_ops) WITH (m=32, ef_construction=200, parallel_workers=8);
CREATE INDEX ON vector_documents USING graph_index (vector floatvector_cosine_ops) WITH (m=32, ef_construction=200, parallel_workers=8);

-- 创建全文索引（可选）
CREATE INDEX ON vector_documents USING fulltext(title, content);
```

### 3. 编译项目

```bash
mvn clean compile
```

### 4. 运行示例

```bash
mvn exec:java -Dexec.mainClass="org.example.MainDemo"
```

## API 接口

### VectorDocumentService

| 方法 | 功能 | 参数 | 返回值 |
|------|------|------|--------|
| `createDocument` | 创建文档 | `VectorDocument document` | `Long` - 文档ID |
| `getDocument` | 根据ID查询文档 | `Long id` | `VectorDocument` |
| `getAllDocuments` | 查询所有文档 | `int limit` | `List<VectorDocument>` |
| `updateDocument` | 更新文档 | `VectorDocument document` | `boolean` |
| `deleteDocument` | 删除文档 | `Long id` | `boolean` |
| `batchCreateDocuments` | 批量创建文档 | `List<VectorDocument> documents` | `int` - 插入数量 |
| `searchByCosineDistance` | 余弦相似度搜索 | `float[] queryVector, int limit` | `List<VectorDocument>` |
| `searchByEuclideanDistance` | 欧几里得距离搜索 | `float[] queryVector, int limit` | `List<VectorDocument>` |
| `searchByInnerProduct` | 内积距离搜索 | `float[] queryVector, int limit` | `List<VectorDocument>` |
| `matchByFulltext` | 关键字匹配 | `List<String> queries, int limit` | `List<VectorDocument>` |
| `searchByFulltext` | BM25全文检索 | `List<String> queries, int limit` | `List<VectorDocument>` |

## 向量搜索说明

### 距离度量方式

| 操作符 | 距离类型 | 说明 |
|--------|----------|------|
| `<=>` | 余弦距离 | 返回范围 [0, 2]，值越小越相似 |
| `<->` | 欧几里得距离 | 返回非负值，值越小越相似 |
| `<#>` | 内积距离 | 返回实数，值越大越相似 |

### 全文检索语法

```sql
-- 关键字匹配（精确匹配）
title @-@ '关键词'
content @-@ '关键词'

-- BM25 全文检索（模糊匹配）
title @~@ '关键词'
content @~@ '关键词'
```

## 运行测试

```bash
mvn test
```

测试用例覆盖：
- 文档创建、查询、更新、删除
- 批量插入
- 三种向量相似度搜索
- 全文检索
- 边界情况处理

## 注意事项

1. 向量维度需与数据库表定义一致（默认 128 维）
2. 建议为向量字段创建索引以提高搜索性能
3. 全文检索需要先创建全文索引
4. 数据库连接信息需根据实际环境配置

## License

MIT License