Move Qdrant adanced API to Builder

1. Add Chinese doc

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.

xb v1.2.2 Release Notes

Release Date: 2025-11-5

🎉 Overview

v1.2.2 is a quality and documentation enhancement release that adds production safety features and comprehensive developer guidance while maintaining 100% backward compatibility.

Core Theme: Smart Condition Building - The three-layer architecture for real-world applications.

✨ What's New

1️⃣ Production Safety: InRequired() Method

Prevent accidental mass operations with explicit validation:

// ✅ Safe: User selected IDs
selectedIDs := []int64{1, 2, 3}
xb.Of("orders").InRequired("id", toInterfaces(selectedIDs)...).Build()

// ❌ Prevented: Empty selection
selectedIDs := []int64{}
xb.Of(&Order{}).InRequired("id", toInterfaces(selectedIDs)...).Build()
// panic: InRequired("id") received empty values, this would match all records.
//        Use In() if optional filtering is intended.

Use Cases:

• Admin batch delete/update operations
• Critical data modifications
• Any scenario requiring explicit selection

Test Coverage: 18 comprehensive test cases including real-world scenarios

2️⃣ Builder Parameter Validation

QdrantBuilder now validates parameters at build time:

// ✅ Valid
xb.NewQdrantBuilder().
    HnswEf(512).          // Valid: >= 1
    ScoreThreshold(0.8).  // Valid: [0, 1]
    Build()

// ❌ Invalid - immediate panic
xb.NewQdrantBuilder().
    HnswEf(0).            // panic: HnswEf must be >= 1, got: 0
    Build()

Benefits:

• Fail-fast with clear error messages
• Catch configuration errors at build time
• Guide users to correct usage

3️⃣ Smart Condition Building Architecture

Three-Layer Design for 99% of Scenarios:

// Layer 1: Auto-Filtering (90% cases)
xb.Of("users").
    Eq("age", age).              // age=0 → ignored
    In("status", statuses...).   // []    → ignored
    Build()

// Layer 2: Required (5% cases)
xb.Of("orders").
    InRequired("id", selectedIDs...). // [] → panic
    Build()

// Layer 3: Flexible (5% cases)
xb.Of("users").
    X("age = 0").              // Query age=0
    Sub("id IN ?", func(sb) {  // Type-safe subquery
        sb.Of(&VipUser{}).Select("id")
    }).
    Build()

4️⃣ Enhanced Documentation

New README Section: Smart Condition Building

• Three-layer architecture explained
• Usage statistics (90%/5%/5%)
• API comparison table
• Real-world examples

Method Documentation:

• X(): Zero-constraint design philosophy
• Sub(): Type-safe subquery examples
• InRequired(): Safety best practices

Examples Updated:

• Use Of(&Model{}) consistently
• Real-world scenario coverage
• Clear use case guidance

🔒 Internal Improvements

Field Encapsulation

// Before: Public field (could be misused)
type BuilderX struct {
    custom Custom
}

// After: Private field (enforces API)
type BuilderX struct {
    customImpl Custom  // Private
}

// Public API unchanged
builder.Custom(...)  // ✅ Still works

Benefits:

• Prevents direct field assignment
• Enforces use of Custom() method
• No breaking changes for users

🎯 Design Philosophy

eXtensible by Design

The "X" in xb represents:

1. eXtensible - Framework adaptability
2. X() method - Zero-constraint escape hatch
3. User freedom - "You know what you're doing"

// xb = eXtensible Builder
//      ↑
//      X() - Zero hardcoded constraints

Three-Layer Philosophy

1. Layer 1: Smart defaults (90% cases)

   • Auto-filtering nil/0/[]
   • User-friendly

2. Layer 2: Safety guards (5% cases)

   • InRequired validation
   • Prevent accidents

3. Layer 3: Ultimate flexibility (5% cases)

   • X() escape hatch
   • Zero constraints

📊 Testing

• Total Tests: 196+ test cases
• New Tests: 18 for InRequired
• Validation Tests: 15 for Builder validation
• Coverage: All new features tested

Test Focus:

• Real-world scenarios
• Edge cases
• Error messages
• Backward compatibility

🔄 Migration Guide

From v1.2.1 to v1.2.2: No migration needed! ✅

All changes are:

• ✅ New features (opt-in)
• ✅ Internal improvements (transparent)
• ✅ Documentation enhancements
• ✅ Zero breaking changes

Recommended Actions:

1. Update to v1.2.2
2. Review InRequired() for critical operations
3. Read Smart Condition Building guide
4. No code changes required

📦 What's Included

New Methods:

• InRequired() - Required validation for In clause
• BuilderX.InRequired() - Same for main builder

Enhanced Validation:

• QdrantBuilder.HnswEf() - Parameter validation
• QdrantBuilder.ScoreThreshold() - Range validation

Documentation:

• Smart Condition Building guide
• Enhanced method documentation
• Updated examples throughout

Internal:

• Field encapsulation
• Better error messages
• Code quality improvements

🎓 Learning Resources

Quick Start

// Simple query (auto-filtering)
users := xb.Of(&User{}).
    Eq("age", age).        // Filtered if age=0
    In("status", statuses...).  // Filtered if []
    Build()

// Safe batch operation
xb.Of("orders").
    InRequired("id", selectedIDs...).  // Panic if []
    Build()

// Special values
xb.Of("users").
    X("age = 0").          // Query age=0
    Build()

Documentation

• README - Smart Condition Building section
• CHANGELOG - Complete change history
• Method Docs - Inline documentation

🙏 Credits

Development Model: AI-First with Human Review

• AI Assistant: Claude (via Cursor)
• Human Maintainer: Code review and strategic decisions

This release demonstrates:

• Production-quality AI-generated code
• Comprehensive testing and documentation
• Real-world problem solving

🚀 Next Steps

After upgrading to v1.2.2:

1. ✅ Review critical operations - Consider InRequired()
2. ✅ Read documentation - Smart Condition Building guide
3. ✅ Update patterns - Use three-layer architecture
4. ✅ Share feedback - Help improve xb

📈 Version History

• v1.2.2 (Current) - Quality & documentation enhancements
• v1.2.1 - Unified Custom() API
• v1.2.0 - Custom interface redesign
• v1.1.0 - Vector database CRUD
• v1.0.0 - Initial stable release

🎉 Summary

v1.2.2 is the most polished xb release yet:

• ✅ Production safety features
• ✅ Comprehensive documentation
• ✅ Enhanced developer experience
• ✅ Zero breaking changes
• ✅ Battle-tested architecture

Ready for production use! 🚀

Download: go get github.com/fndome/[email protected]

Questions? Open an issue on GitHub

Happy Building! 🎊

1. Add interface Custom
2. Add API: func (x *BuilderX) Custom(custom Custom) *BuilderX
3. Support user custom for all database , like Milvus, Oracle, Clickhouse, Neo4j, Elastic Search ....

1. sql query builder for sqlx, gorm, xorm ....
2. json builder for Qdrant ....
3. custom sql, json supported