Skip to content

Commit da19096

Browse files
sim-wangyansim-wangyan
committed
docs: prepare documentation for v1.1.0 release
- Add Custom interface examples to README.md - Create CHANGELOG.md with full v1.1.0 release notes - Add v1.0.0 → v1.1.0 migration guide to MIGRATION.md
1 parent e66da7a commit da19096

File tree

3 files changed

+265
-5
lines changed

3 files changed

+265
-5
lines changed

‎CHANGELOG.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.1.0] - 2025-01-XX
9+
10+
### Added
11+
- **Custom Interface**: Unified abstraction for database-specific features
12+
- `Custom` interface with single `Generate(built *Built) (interface{}, error)` method
13+
- Supports both SQL databases (returns `*SQLResult`) and vector databases (returns `string` JSON)
14+
- **Full CRUD for Vector Databases**:
15+
- `JsonOfInsert()` - Generate INSERT JSON for vector databases
16+
- `JsonOfUpdate()` - Generate UPDATE JSON for vector databases
17+
- `JsonOfDelete()` - Generate DELETE JSON for vector databases
18+
- `JsonOfSelect()` - Existing SELECT JSON (now unified through Custom interface)
19+
- **Official Custom Implementations**:
20+
- `QdrantCustom` - Full CRUD support for Qdrant (Insert/Update/Delete/Search)
21+
- `MySQLCustom` - MySQL-specific features (UPSERT, INSERT IGNORE)
22+
- **Public API Additions**:
23+
- `SqlData()` - Generate data query SQL (public, for Custom implementations)
24+
- `SqlCount()` - Generate COUNT SQL (public, for Custom implementations)
25+
- `SqlInsert()` - Generate INSERT SQL (public, for Custom implementations)
26+
- `SQLResult` struct - Encapsulates SQL, Args, CountSQL, and Meta map
27+
- **Meta Map Enhancement**:
28+
- `Meta map[string]string` in `SQLResult` for ORM field mapping
29+
- Supports alias mapping (`AS xxx`) and table prefixes (`table.field`)
30+
31+
### Changed
32+
- **Breaking**: `PageCondition` fields are now public:
33+
- `page` → `Page`
34+
- `rows` → `Rows`
35+
- `last` → `Last`
36+
- `isTotalRowsIgnored` → `IsTotalRowsIgnored`
37+
- `Custom()` method renamed from `WithCustom()` for more fluent API
38+
- `SqlOfPage()`, `SqlOfSelect()`, `SqlOfInsert()`, `SqlOfUpdate()`, `SqlOfDelete()` now check `built.Custom` and delegate to Custom implementation if available
39+
40+
### Deprecated
41+
- None (all existing APIs remain compatible)
42+
43+
### Documentation
44+
- Added comprehensive Custom interface guides:
45+
- `CUSTOM_INTERFACE_README.md` - Overview and navigation
46+
- `CUSTOM_INTERFACE_PHILOSOPHY.md` - Design philosophy
47+
- `CUSTOM_QUICKSTART.md` - Quick start guide
48+
- `CUSTOM_VECTOR_DB_GUIDE.md` - Vector database implementation guide
49+
- `XB_ORM_PHILOSOPHY.md` - xb's role as ORM complement
50+
- `QDRANT_FULL_CRUD_SUMMARY.md` - Qdrant CRUD implementation summary
51+
52+
### Tests
53+
- Added 8 new tests for Qdrant CRUD operations (all passing)
54+
- Total: 130+ tests, all passing
55+
- Validated Custom interface architecture through complete CRUD implementation
56+
57+
---
58+
59+
## [1.0.0] - 2024-XX-XX
60+
61+
### Added
62+
- Production-ready release
63+
- Stable API for SQL and vector database queries
64+
- Full support for PostgreSQL, MySQL, Qdrant
65+
- Comprehensive documentation and examples
66+
67+
---
68+
69+
## [0.10.0] - 2024-XX-XX
70+
71+
### Added
72+
- **Qdrant Advanced API**:
73+
- Recommend API for personalized recommendations
74+
- Discover API for theme exploration
75+
- Scroll API for large dataset traversal
76+
- Functional parameters for unified builder style
77+
- 100% backward compatibility with existing features
78+
79+
---
80+
81+
## [0.9.0] - 2024-XX-XX
82+
83+
### Added
84+
- Vector database support (PostgreSQL pgvector, Qdrant)
85+
- `VectorSearch()` method for vector similarity search
86+
- Diversity strategies (MMR, min-distance, hash-based)
87+
- Qdrant-specific parameters (`QdrantX()`, `QdrantBuilderX`)
88+
89+
---
90+
91+
## Earlier Versions
92+
93+
See git history for earlier version changes.
94+
95+
[1.1.0]: https://github.com/fndome/xb/compare/v1.0.0...v1.1.0
96+
[1.0.0]: https://github.com/fndome/xb/compare/v0.10.0...v1.0.0
97+
[0.10.0]: https://github.com/fndome/xb/compare/v0.9.0...v0.10.0
98+
[0.9.0]: https://github.com/fndome/xb/releases/tag/v0.9.0
99+

‎MIGRATION.md‎

Lines changed: 109 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,114 @@
1-
# 从 sqlxb 迁移到 xb
1+
# xb 迁移指南
22

3-
## 🔄 项目重命名通知
3+
## 🔄 版本迁移
44

5-
**最新版本**: v0.11.0
5+
### v1.0.0 → v1.1.0 (Custom Interface)
6+
7+
**最新版本**: v1.1.0
8+
**发布日期**: 2025-01-XX
9+
10+
#### 重要变更
11+
12+
**✅ 新功能**:
13+
- Custom 接口：统一的数据库专属功能抽象
14+
- 完整 CRUD：向量数据库的 Insert/Update/Delete 支持
15+
- 官方实现：QdrantCustom（完整 CRUD）, MySQLCustom（UPSERT）
16+
17+
**⚠️ 破坏性变更**:
18+
- `PageCondition` 字段改为 public（`page` → `Page`, `rows` → `Rows`, `last` → `Last`, `isTotalRowsIgnored` → `IsTotalRowsIgnored`）
19+
20+
#### 迁移步骤
21+
22+
##### 1. 更新依赖
23+
24+
```bash
25+
go get github.com/fndome/[email protected]
26+
go mod tidy
27+
```
28+
29+
##### 2. 修改 PageCondition 访问（如果使用了）
30+
31+
**修改前（v1.0.0）**:
32+
```go
33+
// ❌ 这些 getter 方法已移除
34+
page := condition.Page()
35+
rows := condition.Rows()
36+
last := condition.Last()
37+
```
38+
39+
**修改后（v1.1.0）**:
40+
```go
41+
// ✅ 直接访问公共字段
42+
page := condition.Page
43+
rows := condition.Rows
44+
last := condition.Last
45+
```
46+
47+
##### 3. 使用新的 Custom 功能（可选）
48+
49+
**MySQL UPSERT**:
50+
```go
51+
// v1.1.0 新功能
52+
built := xb.Of(user).
53+
Custom(xb.MySQLWithUpsert()).
54+
Insert(user)
55+
sql, args := built.SqlOfInsert()
56+
// INSERT ... ON DUPLICATE KEY UPDATE ...
57+
```
58+
59+
**Qdrant Full CRUD**:
60+
```go
61+
// v1.1.0 新功能
62+
qdrant := xb.NewQdrantCustom()
63+
64+
// Insert
65+
built := xb.X().Custom(qdrant)
66+
built.inserts = &[]xb.Bb{{Value: point}}
67+
json, _ := built.Build().JsonOfInsert()
68+
69+
// Update
70+
built := xb.X().Custom(qdrant).Eq("id", 123)
71+
built.updates = &[]xb.Bb{{Key: "status", Value: "active"}}
72+
json, _ := built.Build().JsonOfUpdate()
73+
74+
// Delete
75+
built := xb.X().Custom(qdrant).Eq("id", 123)
76+
built.Build().Delete = true
77+
json, _ := built.JsonOfDelete()
78+
```
79+
80+
##### 4. 验证迁移
81+
82+
```bash
83+
# 运行测试
84+
go test ./...
85+
86+
# 构建项目
87+
go build ./...
88+
```
89+
90+
#### 常见问题
91+
92+
**Q: v1.0.0 的代码还能用吗？**
93+
94+
A: 可以！除了 `PageCondition` 字段访问方式改变外，所有 v1.0.0 的 API 都完全兼容。
95+
96+
**Q: 我需要立即使用 Custom 接口吗？**
97+
98+
A: 不需要。Custom 接口是可选的。如果你不使用数据库专属功能（如 MySQL UPSERT、Qdrant CRUD），现有代码无需修改。
99+
100+
**Q: 如何实现我自己的数据库 Custom？**
101+
102+
A: 参考文档：
103+
- [CUSTOM_INTERFACE_README.md](./doc/CUSTOM_INTERFACE_README.md)
104+
- [CUSTOM_QUICKSTART.md](./doc/CUSTOM_QUICKSTART.md)
105+
- [MILVUS_TEMPLATE.go](./doc/MILVUS_TEMPLATE.go)
106+
107+
---
108+
109+
### 项目重命名历史（sqlxb → xb）
110+
111+
**版本**: v0.11.0
6112
**日期**: 2025-10-28
7113

8114
### 变更历史

‎README.md‎

Lines changed: 57 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,66 @@ or build condition sql for some orm framework, like [xorm](https://github.com/go
1313
also can build json for some json parameter db, like [Qdrant](https://github.com/qdrant/qdrant) ....
1414

1515

16-
> 🎉 **v1.0.0 Released**: Production-ready! See [VISION.md](./VISION.md) for our approach to rapid tech iteration.
16+
> 🎉 **v1.1.0 Released**: Custom Interface for Database-Specific Features! Full CRUD support for vector databases.
1717
1818
---
1919

20-
## 🚀 NEW: Qdrant Advanced API (since v0.10.0)
20+
## 🚀 NEW: Custom Interface (v1.1.0)
21+
22+
**Unified abstraction for SQL and Vector Databases with database-specific features!**
23+
24+
**✨ New in v1.1.0**:
25+
- 🎯 **Custom Interface** - Unified abstraction for all database types
26+
- 📝 **Full CRUD** - Insert/Update/Delete support for vector databases
27+
- 🔧 **Official Implementations** - QdrantCustom (full CRUD), MySQLCustom (UPSERT)
28+
- 🏗️ **Extensible Architecture** - One `Generate()` method handles all operations
29+
- 📚 **Complete Documentation** - Templates and guides for custom implementations
30+
31+
```go
32+
// MySQL with UPSERT (v1.1.0)
33+
built := xb.Of(user).
34+
Custom(xb.MySQLWithUpsert()).
35+
Insert(user)
36+
sql, args := built.SqlOfInsert()
37+
// INSERT ... ON DUPLICATE KEY UPDATE ...
38+
39+
// Qdrant Full CRUD (v1.1.0)
40+
qdrant := xb.NewQdrantCustom()
41+
42+
// Insert
43+
built := xb.X().Custom(qdrant)
44+
built.inserts = &[]xb.Bb{{Value: point}}
45+
json, _ := built.Build().JsonOfInsert()
46+
47+
// Update
48+
built := xb.X().Custom(qdrant).Eq("id", 123)
49+
built.updates = &[]xb.Bb{{Key: "status", Value: "active"}}
50+
json, _ := built.Build().JsonOfUpdate()
51+
52+
// Delete
53+
built := xb.X().Custom(qdrant).Eq("id", 123)
54+
built.Build().Delete = true
55+
json, _ := built.JsonOfDelete()
56+
57+
// Search (existing)
58+
built := xb.Of(&CodeVector{}).
59+
Custom(qdrant).
60+
VectorSearch("embedding", queryVector, 10).
61+
Build()
62+
json, _ := built.JsonOfSelect()
63+
```
64+
65+
📖 **[Read the Custom Interface Guide →](./doc/CUSTOM_INTERFACE_README.md)**
66+
67+
**Architecture Highlights**:
68+
- ✅ One interface method for all operations (Select/Insert/Update/Delete)
69+
- ✅ Supports both SQL databases (MySQL, Oracle) and vector databases (Qdrant, Milvus)
70+
- ✅ Type-safe: `SQLResult` for SQL, `string` for JSON
71+
- ✅ Easy to extend: Implement your own database in minutes
72+
73+
---
74+
75+
## 🔍 Qdrant Advanced API (since v0.10.0)
2176

2277
**The first unified ORM for both Relational and Vector Databases!**
2378

0 commit comments

Comments
 (0)