en

QdrantBuilder.api.only

**Release Date**: 2025-11-15

---

v1.3.0 完成了向量方言的统一入口：所有 Qdrant 查询（包括 Recommend / Discover / Scroll）都通过 `JsonOfSelect()` 输出，再无 `ToQdrant*JSON()` 记忆负担。配套的文档、迁移指南、测试与发布资产也同步更新。

**Core Theme**: **Single Entry Vector Builder** — 一个 API 覆盖全部高级场景。

---

- `ToQdrantJSON`, `ToQdrantRecommendJSON`, `ToQdrantDiscoverJSON`, `ToQdrantScrollJSON` 退役为内部函数。
- `JsonOfSelect()` 自动识别 `QdrantCustom` 的 Recommend / Discover / Scroll 配置并输出正确的 JSON。
- 错误信息更明确：缺失 `Custom` 会直接返回提示，避免误用。

- `QdrantCustom.Recommend/Discover/ScrollID` 会自动往条件链注入隐藏字段，不需要手写 `Bb`。
- `applyAdvancedConfig()` 现在在 `Generate()` 入口调用，确保所有 JSON 构建路径都能识别高级配置。
- 推荐/探索/滚动的 JSON 生成器被收拢为私有实现，避免用户侧调用混乱。

- 新增 `TestJsonOfSelect_WithRecommendConfig/WithDiscoverConfig/WithScrollConfig`，覆盖三类高级请求。
- 旧测试文件（`qdrant_test.go`, `qdrant_nil_filter_test.go`, `empty_or_and_test.go`）同步切换为 `JsonOfSelect()`。
- `go test ./...` 通过，验证 CTE/UNION/向量/自定义拦截器等历史能力无回归。

- README 顶部 “Latest” 区块更新为 v1.3.0，插图示例改用 `JsonOfSelect()`。
- `MIGRATION.md` 新增 v1.2.x → v1.3.0 小节，附上替换表与示例代码。
- 所有 doc/ai_application 资料批量替换 `ToQdrant*` 为 `JsonOfSelect()`，保持叙述一致。

---

- `QdrantCustom.Generate()` 在 SELECT 分支新增推荐/探索/滚动路由。
- `ensureQdrantAdvanced()` 与 `mergeAndSerialize()` 保持复用，避免多份 JSON 拼装逻辑。
- 批量脚本清理文档中的旧 API 名称，减少未来维护成本。

---

- `README.md`、`MIGRATION.md`、doc/* 全量更新。
- 新增 `RELEASE_v1.3.0.md`, `TEST_REPORT_v1.3.0.md`, `RELEASE_COMMANDS_v1.3.0.md`。
- `commit_message/CHANGELOG.md` 将在发布提交时追加对应条目。

---

- `go test ./...` — ✅ Pass（包含新的 Qdrant JsonOfSelect 回归测试）
- **重点验证**
  - Recommend/Discover/Scroll JSON 结构
  - `applyAdvancedConfig` 对 `JsonOfSelect()` 的影响
  - 旧 SQL 构建功能（CTE、UNION、Meta）无回归

---

1. `go get github.com/fndome/[email protected]`
2. 将所有 `built.ToQdrant*JSON()` 替换为 `built.JsonOfSelect()`。
3. 保持 `QdrantCustom` 配置不变，`JsonOfSelect()` 会自动识别。

> 详见根目录 `MIGRATION.md`。

---

- 新增测试：`TestJsonOfSelect_WithRecommendConfig` / `WithDiscoverConfig` / `WithScrollConfig`
- 文档更新：README、MIGRATION、doc/*
- 发布资产：Release Notes、Test Report、Release Commands
- Bugfix：`QdrantCustom.Generate()` 正确路由高级 API

---

v1.3.0 让 Qdrant + xb 的体验回到“只记住一个 API”的初心：

- ✅ `JsonOfSelect()` 统一所有向量查询
- ✅ Qdrant 高级 API 插件化、免样板
- ✅ 文档与迁移指南全套同步
- ✅ 可靠的回归测试护航

**立即升级，减轻团队记忆负担，同时获得更强的高级检索能力。**

release: v1.2.3 - CTE & UNION fluent builders

🎯 Core Theme: Composable SQL pipelines without leaving BuilderX

✨ New Capabilities:
1. Common Table Expressions
   - `With(name, fn)` & `WithRecursive(name, fn)` for multi-stage query setup
   - Automatic alias normalization and parameter propagation
   - Regression coverage via `with_cte_test.go`

2. UNION chaining
   - `UNION(kind, fn)` with `ALL()` helper (default = DISTINCT)
   - Stack multiple unions while preserving ORDER BY / LIMIT semantics
   - New tests ensure DISTINCT/ALL correctness

3. Metadata injection
   - `Meta(func(meta *interceptor.Metadata))` enables inline TraceID/Tenant setup
   - Interceptors receive enriched metadata prior to Build()

🔧 Internal Improvements:
- Shared SQL core writer now feeds both base SELECT and UNION branches
- `DISTINCT` constant renamed to `DISTINCT_SCRIPT` to avoid helper collision
- Builder states cache CTE / UNION clauses to avoid duplicate builds

📖 Documentation:
- README updated with v1.2.3 highlight section, CTE/UNION examples, metadata usage
- CHANGELOG、Release Notes、Test Report 全面同步

🧪 Quality:
- `go test ./...` ✅ (~240 cases including new suites)
- No breaking changes; existing APIs continue to work unchanged

🚀 Summary:
v1.2.3 brings enterprise-grade analytics features—CTEs, recursive hierarchies, UNION composition, and observability—while keeping the fluent builder experience intact.

chore: add v1.2.2 release commands and checklist

v1.2.1 Release

Release v1.2.0: Complete API Unification

v1.2.0 - A major improvement over v1.1.0

Design Philosophy: Don't add concepts to solve problems. Less is more.

Major Changes:
- Complete API unification: One Insert(func) for SQL and vector databases
- Removed 5 preset constructors (QdrantHighPrecision/HighSpeed/Balanced, MySQLWithUpsert/WithIgnore)
- Removed InsertPoint/InsertPoints methods (not needed)
- JsonOfDelete() auto-sets Delete flag internally
- Smart format detection in QdrantCustom

New Features:
- Built.SqlOfUpsert() - MySQL UPSERT without Custom
- Built.SqlOfInsertIgnore() - MySQL INSERT IGNORE without Custom
- []float32/[]float64 support in InsertBuilder/UpdateBuilder

Why v1.2.0 (Not v1.1.1)?
v1.1.0 had design issues: too many presets, inconsistent API.
v1.2.0 achieves true simplicity: one API for all.

Architecture:
- Insert(func) works for both SQL and Qdrant
- Update(func) works for both SQL and Qdrant
- Only NewQdrantCustom() and NewMySQLCustom() constructors

Tests: 140+ tests, all passing
Breaking: Preset constructors removed (easy migration: use New* instead)

Release v1.1.0: Custom Interface for Database-Specific Features

Major Features:
- Custom interface: unified abstraction for SQL and vector databases
- Full CRUD support: JsonOfInsert/Update/Delete for vector databases
- Official implementations: QdrantCustom, MySQLCustom
- Public API: SqlData(), SqlCount(), SqlInsert() for custom builders
- Meta map: ORM field mapping for aliases and table prefixes

Architecture:
- One Generate() method handles all operations (Select/Insert/Update/Delete)
- Supports both SQL (MySQL/Oracle) and JSON (Qdrant/Milvus) databases
- Type-safe: SQLResult for SQL, string for JSON

Breaking Changes:
- PageCondition fields are now public (Page, Rows, Last, IsTotalRowsIgnored)
- Some internal methods exposed as public API

Tests: 130+ tests, all passing
Documentation: Complete guides and templates for custom implementations

🎉 Release v1.0.0: Production-Ready Release

## 🎯 Milestone

v1.0.0 marks xb as production-ready, featuring:
- ✅ Comprehensive unit tests (95%+ coverage)
- ✅ Fuzz testing for robustness
- ✅ Integration testing with real production projects
- ✅ Complete documentation and best practices

## 🧪 Integration Testing

### Verified in server-g Project (4 Production Services)

1. **prize-as-deposit** (Prize Pool Service)
   - ✅ Upgraded from sqlxb v0.7.4 to xb v0.11.1
   - ✅ Build passed
   - ✅ Uses Insert/Select/Update operations

2. **payment** (Payment Service)
   - ✅ Upgraded from sqlxb v0.7.4 to xb v0.11.1
   - ✅ Build passed
   - ✅ Uses CRUD operations

3. **im** (Instant Messaging Service)
   - ✅ Upgraded from sqlxb v0.7.4 to xb v0.11.1
   - ✅ Build passed
   - ✅ Supports dot import (. "xb")

4. **fndoai** (AI Configuration Service)
   - ✅ Upgraded from sqlxb v0.7.4 to xb v0.11.1
   - ✅ Build passed (with unit tests)
   - ✅ Uses CRUD operations

### API Compatibility

- ✅ 100% backward compatible with v0.7.4 ~ v0.11.1
- ✅ All production services require no business logic changes
- ✅ Only need to update imports and package names

## 📁 New Files

- **INTEGRATION_TEST_REPORT.md** - Detailed integration test report
- **RELEASE_NOTES_v1.0.0.md** - v1.0.0 release notes

## 📚 Documentation Status

### Core Documentation ✅
- README.md - Comprehensive project introduction
- MIGRATION.md - Migration guide
- ROADMAP_v1.0.0.md - Roadmap

### Best Practices ✅
- BUILDER_BEST_PRACTICES.md - Builder usage guide
- COMMON_ERRORS.md - Common errors troubleshooting
- USE_CASE_GUIDE_ZH.md - Use case decision guide

### Application Examples ✅
- examples/pgvector-app/ - PostgreSQL + pgvector complete example
- examples/qdrant-app/ - Qdrant integration example
- examples/rag-app/ - RAG application example
- examples/pageindex-app/ - PageIndex structured retrieval example

### AI Applications ✅
- LANGCHAIN_INTEGRATION.md - LangChain integration
- LLAMAINDEX_INTEGRATION.md - LlamaIndex integration
- RAG_BEST_PRACTICES.md - RAG best practices
- NL2SQL.md / PERFORMANCE.md / FAQ.md

## 🧪 Test Coverage

### Unit Tests (v0.11.0)
- **nil_able_test.go** - Pointer helper functions (60+ cases)
- **sort_test.go** - Sorting functionality
- **po_test.go** - Interface definitions
- **fuzz_test.go** - Fuzz testing (4 functions)

### Integration Tests (v1.0.0)
- **4 production services** integration testing
- **12 files** upgrade verification
- **100%** build pass rate

### Coverage
- Unit tests: **95%+**
- Integration tests: **4 production services**

## 🔧 Technical Specifications

### Supported Databases
- PostgreSQL (with pgvector extension)
- MySQL
- Qdrant (vector database)

### Go Version Requirement
- **Go 1.21+** (for Fuzz testing support)

### Core Features
1. **SQL Builder** - Relational database query builder
2. **Vector DB** - Qdrant/pgvector client
3. **Hybrid Query** - Vector search + relational filtering
4. **Auto Filtering** - Automatically filter nil/0/empty values
5. **Type Safe** - Compile-time type checking

## 📊 Project Statistics

- Lines of Code: ~5000+ lines
- Test Coverage: 95%+
- Documentation Pages: 20+ documents
- Example Apps: 4
- Production Verification: 4 services

## 🎉 Why Release v1.0.0?

### 1. Pragmatic Approach
- Core features are stable and verified
- API design is reasonable and backward compatible
- Documentation is complete with sufficient examples

### 2. Production Validation
- Verified in real production projects
- Maintained compatibility from v0.7.4 to v0.11.1
- Supports various complex business scenarios

### 3. Community Needs
- Need for a stable version number
- Facilitate enterprise adoption and promotion
- Clear API stability commitment

## 🚀 Future Plans

v1.1.0+:
- Performance benchmarking
- More integration tests
- Connection pool best practices
- Batch operation optimization

See ROADMAP_v1.0.0.md for details

---

**Major Milestone**: v1.0.0 🎉
**API Stability**: ✅ Committed to backward compatibility
**Production Ready**: ✅ Ready for production use
**License**: Apache License 2.0