# xugu-vector-jdbc-demo

**Repository Path**: XuguDB/xugu-vector-jdbc-demo

## Basic Information

- **Project Name**: xugu-vector-jdbc-demo
- **Description**: java语言访问虚谷向量数据库程序示例。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xugu-vector-jdbc-demo

基于 **虚谷数据库 JDBC** 的向量类型使用示例工程，演示如何通过 Java 连接数据库、写入 `vector` / `halfvec` / `sparsevec`、调用存储过程，以及 **批量插入 + TopK 相似检索** 等常见用法。

---

## 目录

- [功能概览](#功能概览)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [示例代码说明](#示例代码说明)
- [项目结构](#项目结构)
- [注意事项与排错](#注意事项与排错)
- [联系与支持](#联系与支持)

---

## 功能概览

| 示例 | 说明 |
|------|------|
| **test1** | 使用 **SQL 字面量** 插入向量相关类型并查询 |
| **test2** | 使用 **`PreparedStatement` 参数绑定** 插入 |
| **test3** | 使用驱动提供的 **`DBvector` / `DBhalfvec` / `DBsparsevec`** 封装类型插入 |
| **test4** | 调用带向量参数的 **存储过程** 写入 |
| **test5** | 存储过程 **`OUT` 参数** 返回向量类型（`registerOutParameter`） |
| **test6** | **`addBatch` / `executeBatch` 批量插入**，并按可配置 SQL 做 **TopK** 检索 |

入口类：`com.xugu.vector.TestVector`（`main` 中按顺序执行上述示例，最后清理表与存储过程）。

---

## 环境要求

| 项目 | 说明 |
|------|------|
| **JDK** | 8+（与 `pom.xml` 中 `maven.compiler.source/target` 一致） |
| **Maven** | 3.6+ 推荐 |
| **虚谷数据库** | 已部署且网络可达；示例会 **建表 / 建存储过程 / 删表**，请使用**可测试**的库与用户 |
| **JDBC 驱动** | `com.xugudb:xugu-jdbc`（版本见 `pom.xml`，当前为 **12.3.7**） |

---

## 快速开始

### 1. 获取代码

```bash
git clone <你的仓库地址>
cd xugu-vector-jdbc-demo
```

### 2. 编译

```bash
mvn -q -DskipTests compile
```

### 3. 配置连接

按 [配置说明](#配置说明) 编辑 **`config.txt`**（或设置环境变量）。连接信息不必再改 Java 源码。

### 4. 运行

在 **IntelliJ IDEA**（或其他 IDE）中打开工程，运行：

`com.xugu.vector.TestVector#main`

程序将依次执行 **test1～test6**，并在结束时删除演示用表与存储过程。

> **提示**：若需在命令行运行，可自行配置 `exec-maven-plugin`，或使用 `mvn dependency:build-classpath` 组装 `classpath` 后执行 `java com.xugu.vector.TestVector`。

---

## 配置说明

### 配置文件 `config.txt`

程序启动时会加载 **JDBC 连接** 相关配置。文件采用 Java `Properties` 风格（`key=value`），以 **`#`** 开头的行为注释，编码为 **UTF-8**。

**读取顺序（由高到低）：**

1. **与运行产物同目录下的 `config.txt`（优先）**  
   - 使用 `java -jar your-app.jar` 时：将 `config.txt` 放在 **该 JAR 所在目录**，与 JAR 同级即可，**无需修改 JAR 内部文件**。  
   - 在 IDE 中直接运行 `main` 时：代码一般来自 `target/classes`，程序会在 **`target/config.txt`** 查找外部配置（与 Maven 打出的 `target/*.jar` 同级，与线上部署习惯一致）。

2. **Classpath 中的默认文件**  
   - 若上述外部文件不存在，则读取打包在 **`src/main/resources/config.txt`** 中的默认配置，便于克隆代码后即可本地运行。

**`config.txt` 中与连接相关的键：**

| 键 | 含义 |
|----|------|
| `url` | JDBC URL |
| `username` | 数据库用户名 |
| `password` | 数据库密码 |

**示例：**

```properties
# JDBC 连接
url=jdbc:xugu://127.0.0.1:5138/SYSTEM
username=SYSDBA
password=SYSDBA
```

**与默认值、环境变量的关系：** 每个连接项的最终取值优先级为 **环境变量 → `config.txt` → 程序内建默认值**。因此可在服务器上用环境变量覆盖配置文件，无需改文件。

---

### 环境变量（可选覆盖）

除 `config.txt` 外，仍可通过环境变量覆盖连接与 TopK SQL（适合容器、CI 等场景）。

| 环境变量 | 含义 | 说明 |
|----------|------|------|
| `XUGU_JDBC_URL` | JDBC URL | 未设置则使用 `config.txt` 中的 `url`，再否则使用程序内建默认值 |
| `XUGU_JDBC_USER` | 用户名 | 对应 `config.txt` 的 `username` |
| `XUGU_JDBC_PASSWORD` | 密码 | 对应 `config.txt` 的 `password` |
| `XUGU_TOPK_SQL` | TopK 查询 SQL | **仅支持环境变量**，未设置则使用程序内默认 SQL；需包含 **两个占位符**：第 1 个为查询向量，第 2 个为 `LIMIT` 的整型 TopK |

**默认 TopK SQL（可被 `XUGU_TOPK_SQL` 覆盖）：**

```sql
select c_v from tb_vhs order by c_v <-> ? limit ?
```

不同数据库版本对 **距离运算符**（如 `<->`）、**排序与 LIMIT 语法** 可能有差异；若 **test6** 报错，请根据实际版本调整 `XUGU_TOPK_SQL`，程序会在失败时打印当前使用的 SQL 便于排查。

### 配置示例（Windows PowerShell）

```powershell
$env:XUGU_JDBC_URL = "jdbc:xugu://127.0.0.1:5138/SYSTEM"
$env:XUGU_JDBC_USER = "SYSDBA"
$env:XUGU_JDBC_PASSWORD = "SYSDBA"
# 可选：自定义 TopK 语句
# $env:XUGU_TOPK_SQL = "select c_v from tb_vhs order by c_v <-> ? fetch first ? rows only"
```

### 配置示例（Linux / macOS）

```bash
export XUGU_JDBC_URL="jdbc:xugu://127.0.0.1:5138/SYSTEM"
export XUGU_JDBC_USER="SYSDBA"
export XUGU_JDBC_PASSWORD="SYSDBA"
```

---

## 示例代码说明

- **建表**：`tb_vhs`，列 `c_v vector`、`c_h halfvec`、`c_s sparsevec`。
- **存储过程**：`p_vhs_in`（插入）、`p_vhs_out`（将入参赋给 OUT 向量参数）。
- **资源管理**：使用 `try-with-resources` 管理 `Connection` / `Statement` / `PreparedStatement` / `ResultSet`，避免连接与结果集泄漏。
- **test6**：先批量插入多行，再对 `c_v` 做 TopK；查询向量与 K 值在代码中写死为示例，实际项目可改为入参或配置。

向量字面量格式以虚谷当前类型定义为准（示例中出现如 `'[1,2,3]'`、`'{1:1,2:2,4:1}/10'` 等）。

---

## 项目结构

```
xugu-vector-jdbc-demo/
├── pom.xml
├── README.md
├── src/main/resources/
│   └── config.txt                   # 默认 JDBC 配置（外部无 config.txt 时从 classpath 加载）
└── src/main/java/com/xugu/vector/
    └── TestVector.java              # 示例入口：外部/target 同级 config.txt → classpath 回退
```

---

## 注意事项与排错

1. **权限**：执行用户需具备创建/删除表与存储过程的权限；生产环境请谨慎执行 `drop` 逻辑。
2. **网络与防火墙**：确保 JDBC URL 中的主机、端口对运行示例的机器可达。
3. **TopK 失败**：检查 `XUGU_TOPK_SQL` 是否与当前库版本匹配；占位符顺序须与 `test6` 中 `setObject(1, …)`、`setInt(2, …)` 一致。
4. **找不到配置**：若既无 JAR/`target` 同级的 `config.txt`，又未将 `config.txt` 打进 classpath，程序会报错；打包部署时请在与 JAR 同目录放置 `config.txt`，或保留 `src/main/resources/config.txt` 作为默认。

---

## 联系与支持

| 方式 | 信息 |
|------|------|
| **QQ** | 240370218 |
| **Email** | xugu@vip.163.com |

---

*本文档与示例代码旨在帮助快速上手虚谷向量相关 JDBC 用法，具体 SQL 与类型语法请以官方文档与当前数据库版本为准。*