@clickzetta/cz-cli-darwin-x64 0.3.75 → 0.3.78

package/bin/skills/lakehouse-doc/references/vector_data_process_guide.md

@@ -1,952 +0,0 @@
-# Lakehouse VECTOR数据处理使用指南
-
-## 向量数据的原生支持与实践
-
-***
-
-## 写在前面
-
-### 您可能遇到的向量数据处理场景
-
-#### 场景1：文档相似度检索系统
-
-**当前在 Hive/Spark 中的常见做法**：
-
-```sql
--- 在Hive中存储文档向量
-CREATE TABLE document_embeddings (
-    doc_id STRING,
-    title STRING, 
-    content STRING,
-    embedding ARRAY<DOUBLE>  -- 存储LLM生成的向量
-) PARTITIONED BY (dt STRING);
-
--- 相似度计算需要复杂的UDF
-CREATE FUNCTION cosine_similarity_udf(vec1 ARRAY<DOUBLE>, vec2 ARRAY<DOUBLE>) 
-RETURNS DOUBLE
-LANGUAGE PYTHON AS $
-import numpy as np
-def cosine_similarity_udf(vec1, vec2):
-    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))
-$;
-
--- 查询需要手动维度检查和UDF调用
-SELECT doc_id, title,
-    cosine_similarity_udf(embedding, array(0.1, 0.2, 0.3, ...)) as score
-FROM document_embeddings 
-WHERE size(embedding) = 1536  -- 手动维度检查
-    AND dt >= '2024-01-01'
-ORDER BY score DESC 
-LIMIT 10;
-```
-
-**面临的技术挑战**：
-
-* **实现复杂**：需要自定义UDF实现距离计算函数
-* **无专门索引**：数组类型无法建立针对相似度的索引
-* **类型安全问题**：数组长度不固定，容易出现维度不匹配错误
-* **性能限制**：大规模向量计算时缺乏专门优化
-
-#### 场景2：推荐系统用户特征匹配
-
-**在 Spark 中的典型实现**：
-
-```python
-# Spark中的用户向量相似度计算
-from pyspark.sql.functions import *
-from pyspark.ml.linalg import Vectors
-
-# 需要自定义函数实现相似度计算
-def cosine_similarity_udf(vec1, vec2):
-    from pyspark.ml.linalg import Vectors
-    import numpy as np
-    v1 = np.array(vec1)
-    v2 = np.array(vec2)
-    return float(np.dot(v1, v2) / (np.linalg.norm(v1) * np.linalg.norm(v2)))
-
-# 注册UDF
-cosine_udf = udf(cosine_similarity_udf, DoubleType())
-
-# 查询相似用户
-similar_users = user_features.crossJoin(user_features.alias("other")) \
-    .filter(col("user_id") != col("other.user_id")) \
-    .withColumn("similarity", cosine_udf(col("features"), col("other.features"))) \
-    .filter(col("similarity") > 0.8) \
-    .orderBy(desc("similarity"))
-```
-
-**常见的技术痛点**：
-
-* **架构复杂**：向量计算与数据存储分离，增加系统复杂度
-* **开发成本**：需要实现和维护自定义的相似度计算逻辑
-* **性能瓶颈**：大规模向量计算时缺乏专门的加速机制
-* **错误处理**：缺乏对向量维度的编译时检查
-
-### 为什么需要向量数据类型
-
-基于以上场景中的技术挑战，VECTOR数据类型的设计目标是：
-
-**解决类型安全问题**：
-
-* 提供固定维度的向量类型定义
-* 编译时进行维度匹配检查
-* 避免运行时的维度不匹配错误
-
-**简化开发流程**：
-
-* 内置常用的向量距离计算函数
-* 无需编写和维护自定义UDF
-* 与标准SQL语法完全兼容
-
-**提升查询性能**：
-
-* 支持专门的向量索引
-* 针对向量计算进行优化
-* 支持高效的相似度检索
-
-### 如何使用这份指南
-
-| 读者角色    | 建议阅读重点             | 预期收获            |
-| ------- | ------------------ | --------------- |
-| 数据工程师   | 类型定义 → 函数使用 → 避坑指南 | 掌握VECTOR的正确使用方法 |
-| 系统架构师   | 应用场景 → 性能优化 → 迁移策略 | 获得架构设计和迁移规划参考   |
-| AI应用开发者 | 快速开始 → 应用模式 → 查询限制 | 了解AI场景下的最佳实践    |
-
-***
-
-## ⚡ 快速开始
-
-### 基本使用流程
-
-```sql
--- 1. 创建包含向量列的表
-CREATE TABLE document_embeddings (
-    id BIGINT,
-    content STRING,
-    embedding VECTOR(FLOAT, 1536)  -- 1536维浮点向量
-);
-
--- 2. 插入向量数据
-INSERT INTO document_embeddings VALUES 
-(1, '人工智能技术发展', vector(0.1, 0.2, 0.3, ...));  -- 需要提供完整的1536维数据
-
--- 3. 创建向量索引
-CREATE VECTOR INDEX embedding_idx ON TABLE document_embeddings(embedding) 
-PROPERTIES(
-    "distance.function" = "cosine_distance",
-    "scalar.type" = "f32"
-);
-
--- 4. 构建索引（对已有数据）
-BUILD INDEX embedding_idx ON document_embeddings;
-
--- 5. 执行相似度查询（推荐模式）
-SELECT id, content FROM document_embeddings 
-WHERE COSINE_DISTANCE(embedding, vector(0.1, 0.2, 0.3, ...)) < 0.8
-ORDER BY id LIMIT 10;
-```
-
-***
-
-## 🆚 技术对比：ARRAY vs VECTOR
-
-### 传统ARRAY实现方式
-
-```sql
--- 使用ARRAY存储向量
-CREATE TABLE docs_array (
-    content STRING,
-    embedding ARRAY<DOUBLE>
-);
-
--- 需要自定义函数实现相似度计算
-CREATE FUNCTION cosine_similarity(vec1 ARRAY<DOUBLE>, vec2 ARRAY<DOUBLE>) 
-RETURNS DOUBLE
-LANGUAGE PYTHON AS $$
-def cosine_similarity(vec1, vec2):
-    import numpy as np
-    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))
-$$;
-
--- 查询需要函数调用，且需要手动检查维度
-SELECT doc_id, cosine_similarity(embedding, array(0.1, 0.2, ...)) as score
-FROM docs_array
-WHERE array_size(embedding) = 1536  -- 需要手动维度检查
-ORDER BY score DESC;
-```
-
-### VECTOR原生实现方式
-
-```sql
--- 使用VECTOR类型
-CREATE TABLE docs_vector (
-    content STRING,
-    embedding VECTOR(FLOAT, 1536),  -- 类型和维度明确定义
-    
-    INDEX embedding_idx (embedding) USING VECTOR PROPERTIES (
-        "distance.function" = "cosine_distance"
-    )
-);
-
--- 使用内置函数，维度自动检查
-SELECT doc_id FROM docs_vector 
-WHERE COSINE_DISTANCE(embedding, vector(0.1, 0.2, ...)) < 0.8
-ORDER BY doc_id LIMIT 10;
-```
-
-### 功能特性对比
-
-| 特性    | ARRAY方案   | VECTOR方案 | 对用户的影响    |
-| ----- | --------- | -------- | --------- |
-| 类型安全  | 运行时检查     | 编译时检查    | 减少生产环境错误  |
-| 维度控制  | 手动验证      | 类型定义保证   | 避免维度不匹配问题 |
-| 距离计算  | 自定义UDF    | 内置函数     | 减少代码开发和维护 |
-| 索引支持  | 无专门索引     | 向量索引     | 改善大规模查询性能 |
-| 开发复杂度 | 需要实现计算逻辑  | 直接使用内置函数 | 降低技术门槛    |
-| 维护成本  | 需要维护UDF代码 | 数据库原生支持  | 减少运维工作量   |
-
-### 从Spark MLlib迁移的对照
-
-| Spark MLlib API          | CloudZetta VECTOR               | 迁移复杂度 | 说明           |
-| ------------------------ | ------------------------------- | ----- | ------------ |
-| `Vectors.dense(array)`   | `vector(v1, v2, ...)`           | 简单    | 直接函数替换       |
-| `Vectors.norm(v, 2)`     | `L2_DISTANCE(v, vector(0,...))` | 中等    | 需要提供零向量      |
-| 自定义cosine UDF            | `COSINE_DISTANCE(v1, v2)`       | 简单    | 删除UDF，使用内置函数 |
-| 自定义normalize UDF         | `L2_NORMALIZE(v)`               | 简单    | 删除UDF，使用内置函数 |
-| `Vectors.sqdist(v1, v2)` | `POW(L2_DISTANCE(v1, v2), 2)`   | 简单    | 组合内置函数       |
-
-***
-
-## 📊 VECTOR数据类型规范
-
-### 类型定义语法
-
-```sql
-VECTOR(scalar_type, dimension)
-```
-
-### 支持的标量类型
-
-| 标量类型    | 存储大小  | 数值范围       | 适用场景              | 索引支持  |
-| ------- | ----- | ---------- | ----------------- | ----- |
-| FLOAT   | 4字节/维 | 32位浮点数     | 通用向量存储，如embedding | ✅ f32 |
-| INT     | 4字节/维 | 32位整数      | 整数特征向量，如计数        | ❌     |
-| TINYINT | 1字节/维 | -128 到 127 | 压缩存储，如二进制向量       | ✅ i8  |
-
-> **💡 建议**：生产环境推荐使用FLOAT类型，兼容性和性能最佳
-
-### 向量创建方法
-
-```sql
--- 直接创建向量
-SELECT vector(1.0, 2.0, 3.0);              -- 创建3维浮点向量
-SELECT vector(1, 2, 3);                     -- 创建3维整数向量
-
--- 从其他类型转换
-SELECT cast(array(1,2,3) as VECTOR(INT, 3));     -- 数组转向量
-SELECT cast('[1,2,3]' as VECTOR(INT, 3));        -- JSON字符串转向量
-
--- 在表定义中使用
-CREATE TABLE feature_vectors (
-    id BIGINT,
-    dense_features VECTOR(FLOAT, 128),       -- 稠密特征
-    sparse_features VECTOR(INT, 1000)        -- 稀疏特征
-);
-```
-
-***
-
-## 🧮 向量函数
-
-### 距离计算函数
-
-#### L2\_DISTANCE - 欧几里得距离
-
-```sql
-SELECT L2_DISTANCE(vector(1,2,3), vector(4,5,6)) as euclidean_distance;
--- 结果：5.196152210235596
-```
-
-**计算公式**：√(Σ(ai - bi)²)
-**适用场景**：空间数据分析、聚类算法、图像特征匹配
-
-#### COSINE\_DISTANCE - 余弦距离
-
-```sql
-SELECT COSINE_DISTANCE(vector(1,2,3), vector(4,5,6)) as cosine_distance;
--- 结果：0.025368213653564453
-```
-
-**计算公式**：1 - (a·b)/(|a|×|b|)
-**适用场景**：文本语义相似度、推荐系统、信息检索
-
-#### DOT\_PRODUCT - 点积
-
-```sql
-SELECT DOT_PRODUCT(vector(1,2,3), vector(4,5,6)) as dot_product;
--- 结果：32.0
-```
-
-**计算公式**：Σ(ai × bi)
-**适用场景**：相关性计算、神经网络权重计算
-
-### 向量处理函数
-
-#### L2\_NORMALIZE - 向量归一化
-
-```sql
--- ⚠️ 重要：必须使用浮点数向量
-SELECT L2_NORMALIZE(vector(3.0, 4.0)) as normalized_vector;
--- 结果：[0.6, 0.8]
-
--- ❌ 错误示例：整数向量可能导致精度问题
-SELECT L2_NORMALIZE(vector(3, 4)) as normalized_vector;
--- 可能结果：[0, 0]
-```
-
-**功能**：将向量标准化为单位长度（L2范数为1）
-**适用场景**：余弦相似度计算的预处理
-
-### 函数使用注意事项
-
-* 所有距离函数要求输入向量维度相同，否则会报编译时错误
-* 函数支持向量类型与数组类型的混合计算
-* 归一化函数返回相同维度的向量类型
-* **L2\_NORMALIZE函数对数据类型敏感，建议使用浮点数向量**
-
-***
-
-## 🔄 类型转换与兼容性
-
-### 自动类型转换
-
-```sql
--- 向量可以隐式转换为数组用于数组操作
-SELECT array_size(vector(1,2,3,4)) as vector_size;
--- 结果：4
-
--- 数组可以在向量函数中使用
-SELECT L2_DISTANCE(array(1,2,3), vector(1,2,3)) as distance;
--- 结果：0.0
-```
-
-### 显式类型转换
-
-```sql
--- 数组转向量（维度必须匹配）
-SELECT cast(array(1.0, 2.0, 3.0) as VECTOR(FLOAT, 3));
--- 结果：[1.0, 2.0, 3.0]
-
--- JSON字符串转向量
-SELECT cast('[1,2,3]' as VECTOR(INT, 3));
--- 结果：[1, 2, 3]
-
--- 维度不匹配时返回NULL
-SELECT cast(array(1,2) as VECTOR(INT, 3));  -- 返回NULL
-```
-
-### SQL操作支持
-
-向量类型支持标准的SQL操作：
-
-```sql
--- 排序
-SELECT * FROM vectors ORDER BY feature_vector;
-
--- 分组
-SELECT feature_vector, COUNT(*) FROM vectors GROUP BY feature_vector;
-
--- 比较
-SELECT * FROM vectors WHERE feature_vector = vector(1,2,3);
-
--- 去重
-SELECT DISTINCT feature_vector FROM vectors;
-```
-
-***
-
-## 🏗️ 向量索引
-
-### 索引配置参数
-
-| 参数名称              | 可选值                                                                  | 默认值              | 说明           |
-| ----------------- | -------------------------------------------------------------------- | ---------------- | ------------ |
-| distance.function | cosine\_distance, l2\_distance, jaccard\_distance, hamming\_distance | cosine\_distance | 距离函数类型       |
-| scalar.type       | f32, f16, i8, b1                                                     | f32              | 索引中向量元素的存储类型 |
-| M                 | 正整数                                                                  | 16               | HNSW算法的最大连接数 |
-| ef\_construction  | 正整数                                                                  | 200              | 索引构建时的候选集大小  |
-
-> **⚠️ 重要**：参数名称必须使用完整形式，如`cosine_distance`而非`cosine`
-
-### 索引创建和管理
-
-```sql
--- 创建向量索引（推荐语法）
-CREATE VECTOR INDEX embedding_idx ON TABLE table_name(vector_column) 
-PROPERTIES(
-    "distance.function" = "cosine_distance",  -- 完整函数名
-    "scalar.type" = "f32",                   -- 标准类型名
-    "M" = 16,
-    "ef_construction" = 200
-);
-
--- 为已有数据构建索引
-BUILD INDEX embedding_idx ON table_name;
-
--- 查看索引状态
-SHOW INDEXES ON table_name;
-
--- 删除索引
-DROP INDEX embedding_idx ON table_name;
-```
-
-### 索引性能调优
-
-不同参数配置的性能特点：
-
-| 配置场景 | M值 | ef\_construction | scalar.type | 特点              |
-| ---- | -- | ---------------- | ----------- | --------------- |
-| 快速检索 | 8  | 64               | f16         | 较低的构建时间和内存使用    |
-| 平衡配置 | 16 | 200              | f32         | 平衡的精度和性能        |
-| 高精度  | 32 | 400              | f32         | 更高的检索精度，较高的资源消耗 |
-
-***
-
-## 🚀 主流AI模型适配
-
-### 常见Embedding模型的向量维度
-
-| 模型提供商  | 模型名称                       | 维度   | 建议配置                |
-| ------ | -------------------------- | ---- | ------------------- |
-| OpenAI | text-embedding-3-small     | 1536 | VECTOR(FLOAT, 1536) |
-| OpenAI | text-embedding-3-large     | 3072 | VECTOR(FLOAT, 3072) |
-| Google | Universal Sentence Encoder | 512  | VECTOR(FLOAT, 512)  |
-| 百度     | ERNIE-Embed                | 768  | VECTOR(FLOAT, 768)  |
-| 智谱     | GLM-Embedding              | 1024 | VECTOR(FLOAT, 1024) |
-
-### 多模态模型支持
-
-| 模型类型               | 典型维度     | 应用场景       |
-| ------------------ | -------- | ---------- |
-| CLIP               | 512/768  | 图文匹配、多模态检索 |
-| BLIP               | 768      | 图像问答、视觉理解  |
-| Vision Transformer | 768/1024 | 图像分类、特征提取  |
-
-***
-
-## 💡 应用场景设计
-
-### 文档检索系统
-
-```sql
--- 知识库表设计
-CREATE TABLE knowledge_base (
-    doc_id BIGINT PRIMARY KEY,
-    title STRING,
-    content STRING,
-    embedding VECTOR(FLOAT, 1536),
-    created_at TIMESTAMP,
-    
-    INDEX doc_embedding_idx (embedding) USING VECTOR PROPERTIES (
-        "scalar.type" = "f32",
-        "distance.function" = "cosine_distance"
-    )
-);
-
--- 语义检索查询（推荐模式）
-SELECT doc_id, title FROM knowledge_base 
-WHERE COSINE_DISTANCE(embedding, ?) < 0.7
-ORDER BY doc_id LIMIT 10;
-```
-
-### 推荐系统
-
-```sql
--- 用户特征表
-CREATE TABLE user_profiles (
-    user_id BIGINT PRIMARY KEY,
-    behavior_vector VECTOR(FLOAT, 128),
-    preference_vector VECTOR(FLOAT, 64),
-    last_updated TIMESTAMP,
-    
-    INDEX behavior_idx (behavior_vector) USING VECTOR PROPERTIES (
-        "distance.function" = "cosine_distance"
-    )
-);
-
--- 物品特征表
-CREATE TABLE item_features (
-    item_id BIGINT PRIMARY KEY,
-    content_vector VECTOR(FLOAT, 256),
-    category_vector VECTOR(INT, 50),
-    
-    INDEX content_idx (content_vector) USING VECTOR PROPERTIES (
-        "distance.function" = "cosine_distance"
-    )
-);
-
--- 相似用户查找（推荐查询模式）
-SELECT target.user_id as similar_user FROM user_profiles source
-CROSS JOIN user_profiles target
-WHERE source.user_id = ?
-    AND target.user_id != source.user_id
-    AND COSINE_DISTANCE(source.behavior_vector, target.behavior_vector) < 0.6
-ORDER BY target.user_id LIMIT 20;
-```
-
-### 图像特征匹配
-
-```sql
--- 图像特征库
-CREATE TABLE image_features (
-    image_id BIGINT PRIMARY KEY,
-    image_path STRING,
-    visual_features VECTOR(FLOAT, 2048),
-    semantic_features VECTOR(FLOAT, 512),
-    upload_time TIMESTAMP,
-    
-    INDEX visual_idx (visual_features) USING VECTOR PROPERTIES (
-        "distance.function" = "l2_distance",
-        "scalar.type" = "f16"
-    ),
-    INDEX semantic_idx (semantic_features) USING VECTOR PROPERTIES (
-        "distance.function" = "cosine_distance"
-    )
-);
-
--- 相似图像检索
-SELECT image_id, image_path FROM image_features
-WHERE L2_DISTANCE(visual_features, ?) < 100.0
-ORDER BY image_id LIMIT 50;
-```
-
-***
-
-## ⚠️ 重要避坑指南
-
-### 🚨 向量查询限制
-
-经过UAT环境实际测试，发现两种不同的错误模式：
-
-#### 1. 维度不匹配错误（预期行为）
-
-```sql
--- ❌ 错误示例：使用5维向量查询128维数据
-SELECT id FROM embeddings_table 
-WHERE COSINE_DISTANCE(embedding_128d, vector(0.1, 0.2, 0.3, 0.4, 0.5)) < 0.8;
-
--- 错误信息：
--- function 'COSINE_DISTANCE' cannot be resolved, 
--- expect 'vector shall have the same dimension'
-```
-
-**解决方法**：确保查询向量与表中向量维度完全一致
-
-#### 2. Generated Column内部错误（当前限制）
-
-```sql
--- ❌ 问题查询：在SELECT中返回距离计算
-SELECT id, content,
-    COSINE_DISTANCE(embedding, vector(...)) as distance
-FROM embeddings_table 
-ORDER BY distance LIMIT 10;
-
--- 可能错误：
--- Generated column 4292967295(generated_field_4292967295) is not filled for VECTOR
-```
-
-**当前可用的查询模式**：
-
-```sql
--- ✅ 推荐：WHERE子句中的向量过滤
-SELECT id, content FROM embeddings_table 
-WHERE COSINE_DISTANCE(embedding, vector(...)) < 0.8
-ORDER BY id LIMIT 10;
-
--- ✅ 可用：简单的向量函数
-SELECT COSINE_DISTANCE(embedding, embedding) as self_distance
-FROM embeddings_table;
-
--- ❌ 避免：复杂的SELECT返回距离计算并排序
-```
-
-### 🛠️ 函数使用避坑
-
-#### L2\_NORMALIZE函数类型要求
-
-```sql
--- ✅ 正确：使用浮点数向量
-SELECT L2_NORMALIZE(vector(3.0, 4.0)) as normalized;
--- 结果：[0.6, 0.8]
-
--- ❌ 错误：使用整数向量
-SELECT L2_NORMALIZE(vector(3, 4)) as normalized;
--- 可能结果：[0, 0] （精度丢失）
-```
-
-#### 索引参数规范
-
-```sql
--- ✅ 正确：使用完整参数名
-CREATE VECTOR INDEX idx ON TABLE t(col) PROPERTIES(
-    "distance.function" = "cosine_distance",  -- 完整函数名
-    "scalar.type" = "f32"                    -- 标准类型名
-);
-
--- ❌ 错误：使用简化名称
-CREATE VECTOR INDEX idx ON TABLE t(col) PROPERTIES(
-    "distance.function" = "cosine",          -- 会报错
-    "scalar.type" = "float"                  -- 会报错
-);
-```
-
-### 🎯 最佳实践建议
-
-#### 查询模式选择
-
-| 使用场景    | 推荐模式                                     | 避免模式                            |
-| ------- | ---------------------------------------- | ------------------------------- |
-| 相似度过滤   | `WHERE COSINE_DISTANCE(...) < threshold` | `ORDER BY COSINE_DISTANCE(...)` |
-| Top-K检索 | WHERE过滤 + 简单排序                           | 距离计算 + 排序                       |
-| 批量计算    | 分步骤查询                                    | 复杂嵌套查询                          |
-
-#### 性能优化策略
-
-```sql
--- ✅ 推荐：利用索引的过滤查询
-SELECT doc_id, title FROM knowledge_base 
-WHERE COSINE_DISTANCE(embedding, ?) < 0.7
-ORDER BY doc_id LIMIT 10;
-
--- ✅ 可选：分步骤的Top-K检索
--- 步骤1：过滤候选
-CREATE VIEW candidates AS 
-SELECT doc_id, title FROM knowledge_base 
-WHERE COSINE_DISTANCE(embedding, ?) < 0.8;
-
--- 步骤2：精确排序（如需要）
-SELECT doc_id, title FROM candidates ORDER BY doc_id LIMIT 10;
-```
-
-***
-
-## 🔄 迁移策略
-
-### 迁移价值评估
-
-在决定是否迁移到VECTOR类型之前，建议先评估您的使用场景：
-
-#### 高价值迁移场景
-
-* **频繁的向量相似度计算**：如推荐系统、文档检索、图像匹配
-* **大规模向量数据**：超过百万级别的向量数据查询
-* **复杂的UDF维护**：当前需要维护多个自定义向量计算函数
-* **性能要求高**：对查询响应时间有严格要求的应用
-
-#### 可选迁移场景
-
-* **偶尔的向量计算**：向量计算不是核心业务流程
-* **小规模数据**：向量数据量较小，性能压力不大
-* **稳定的现有系统**：当前系统运行稳定，改动风险大于收益
-
-### 针对不同用户的迁移建议
-
-#### Spark用户迁移路径
-
-**如果您主要使用Spark MLlib进行向量计算**：
-
-```python
-# 原Spark代码
-from pyspark.ml.linalg import Vectors, VectorUDT
-from pyspark.sql.functions import udf
-
-# 自定义相似度函数
-def cosine_similarity(v1, v2):
-    # 复杂的实现逻辑
-    pass
-
-# 注册UDF
-cosine_udf = udf(cosine_similarity, DoubleType())
-```
-
-**迁移到CloudZetta VECTOR后**：
-
-```sql
--- 直接使用内置函数和推荐查询模式
-SELECT user_id FROM user_features
-WHERE COSINE_DISTANCE(user_vector, target_vector) < 0.8;
-```
-
-**迁移收益**：
-
-* 删除自定义UDF代码
-* 利用向量索引加速查询
-* 统一在SQL中处理向量计算
-
-#### Hive用户迁移路径
-
-**如果您在Hive中使用ARRAY存储向量**：
-
-```sql
--- 原Hive表结构
-CREATE TABLE user_embeddings (
-    user_id BIGINT,
-    features ARRAY<DOUBLE>
-) PARTITIONED BY (dt STRING);
-
--- 需要复杂的UDF
-SELECT user_id, my_cosine_udf(features, target_array) as score
-FROM user_embeddings 
-WHERE size(features) = 128;  -- 手动维度检查
-```
-
-**迁移到 VECTOR 类型**：
-
-```sql
--- 新的表结构
-CREATE TABLE user_embeddings_v2 (
-    user_id BIGINT,
-    features VECTOR(FLOAT, 128)  -- 类型安全
-) PARTITIONED BY (dt STRING);
-
--- 使用内置函数和推荐模式
-SELECT user_id FROM user_embeddings_v2
-WHERE COSINE_DISTANCE(features, vector(...)) < 0.8;  -- 无需手动维度检查
-```
-
-### 评估现有系统
-
-#### 数据规模评估
-
-```sql
--- 统计现有向量数据的规模和维度
-SELECT 
-    table_name,
-    column_name,
-    COUNT(*) as record_count,
-    AVG(size(array_column)) as avg_dimension,
-    MIN(size(array_column)) as min_dimension,
-    MAX(size(array_column)) as max_dimension,
-    COUNT(DISTINCT size(array_column)) as dimension_variants
-FROM (
-    SELECT 'user_features' as table_name, 'embedding' as column_name, embedding as array_column FROM user_features
-    UNION ALL
-    SELECT 'product_vectors' as table_name, 'features' as column_name, features as array_column FROM product_vectors
-    -- 添加其他需要评估的表
-) all_vectors
-GROUP BY table_name, column_name;
-```
-
-#### UDF复杂度评估
-
-```sql
--- 识别当前使用的向量相关UDF
-SHOW FUNCTIONS LIKE '*similarity*';
-SHOW FUNCTIONS LIKE '*distance*';
-SHOW FUNCTIONS LIKE '*cosine*';
-SHOW FUNCTIONS LIKE '*euclidean*';
-```
-
-#### 查询频率评估
-
-```sql
--- 分析向量计算查询的频率（如果有查询日志）
-SELECT 
-    DATE(query_time) as query_date,
-    COUNT(*) as vector_query_count
-FROM query_logs 
-WHERE query_text LIKE '%cosine%' 
-    OR query_text LIKE '%similarity%'
-    OR query_text LIKE '%distance%'
-GROUP BY DATE(query_time)
-ORDER BY query_date DESC
-LIMIT 30;
-```
-
-### 并行构建新表
-
-```sql
--- 创建新的向量表
-CREATE TABLE embeddings_new (
-    id BIGINT,
-    content STRING,
-    embedding VECTOR(FLOAT, 768),
-    migrated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP(),
-    
-    INDEX embedding_idx (embedding) USING VECTOR PROPERTIES (
-        "distance.function" = "cosine_distance"
-    )
-);
-
--- 数据迁移
-INSERT INTO embeddings_new (id, content, embedding)
-SELECT 
-    id,
-    content,
-    CASE 
-        WHEN size(embedding_array) = 768 
-        THEN cast(embedding_array as VECTOR(FLOAT, 768))
-        ELSE NULL
-    END as embedding
-FROM embeddings_old
-WHERE size(embedding_array) = 768;
-
--- 构建索引
-BUILD INDEX embedding_idx ON embeddings_new;
-```
-
-### 验证迁移结果
-
-```sql
--- 对比查询结果的一致性（使用推荐查询模式）
-WITH old_results AS (
-    SELECT id FROM embeddings_old 
-    WHERE your_cosine_udf(embedding_array, ?) > 0.8
-    ORDER BY id LIMIT 10
-),
-new_results AS (
-    SELECT id FROM embeddings_new 
-    WHERE COSINE_DISTANCE(embedding, ?) < 0.2  -- 注意距离vs相似度的转换
-    ORDER BY id LIMIT 10
-)
-SELECT 
-    COALESCE(o.id, n.id) as id,
-    CASE WHEN o.id IS NOT NULL THEN 'OLD' ELSE NULL END as in_old,
-    CASE WHEN n.id IS NOT NULL THEN 'NEW' ELSE NULL END as in_new
-FROM old_results o
-FULL OUTER JOIN new_results n ON o.id = n.id
-ORDER BY id;
-```
-
-***
-
-## 🚀 性能优化
-
-### 查询优化
-
-```sql
--- ✅ 推荐：使用阈值过滤提升查询效率
-SELECT id, content FROM embeddings_table 
-WHERE COSINE_DISTANCE(embedding, ?) < 0.8  -- 利用向量索引过滤
-ORDER BY id LIMIT 10;
-
--- ✅ 可选：分步骤处理复杂查询
-CREATE VIEW filtered_candidates AS
-SELECT id, content FROM embeddings_table 
-WHERE COSINE_DISTANCE(embedding, ?) < 0.8;
-
-SELECT id, content FROM filtered_candidates 
-ORDER BY id LIMIT 10;
-```
-
-### 存储优化
-
-```sql
--- 大规模数据使用半精度存储
-CREATE TABLE large_embeddings (
-    id BIGINT,
-    embedding VECTOR(FLOAT, 1536),
-    
-    INDEX embedding_idx (embedding) USING VECTOR PROPERTIES (
-        "scalar.type" = "f16",  -- 半精度存储节省内存
-        "distance.function" = "cosine_distance"
-    )
-);
-```
-
-### 索引调优
-
-根据应用需求选择合适的索引参数：
-
-* **实时查询场景**：较小的M值和ef\_construction，使用f16类型
-* **批量分析场景**：较大的M值和ef\_construction，使用f32类型
-* **存储优化场景**：使用f16或i8类型减少内存占用
-
-***
-
-## ⚠️ 注意事项
-
-### 功能限制
-
-* 向量维度在创建时确定，不支持动态调整
-* 向量不能用作分区键
-* JACCARD\_DISTANCE和HAMMING\_DISTANCE函数有特殊的类型要求
-* **当前版本的复杂 SELECT 查询存在限制，建议使用 WHERE 过滤模式**
-
-### 索引管理
-
-* CREATE INDEX只对新增数据生效，已有数据需要执行BUILD INDEX
-* 向量索引的性能与内存缓存密切相关
-* 建议为向量查询使用专门的Virtual Cluster
-
-### 故障排除
-
-| 问题                 | 可能原因         | 解决方法                     |
-| ------------------ | ------------ | ------------------------ |
-| 查询性能差              | 索引未生效        | 检查索引状态，执行BUILD INDEX     |
-| 维度不匹配错误            | 向量维度不一致      | 检查VECTOR类型定义和输入数据维度      |
-| Generated column错误 | 复杂SELECT查询限制 | 使用WHERE过滤模式替代            |
-| L2\_NORMALIZE返回零向量 | 使用整数向量       | 改用浮点数向量：vector(3.0, 4.0) |
-| 索引参数错误             | 参数名称不规范      | 使用完整参数名：cosine\_distance |
-| 内存不足               | 向量索引占用过多内存   | 调整索引参数或增加集群资源            |
-
-***
-
-## 📊 总结
-
-### VECTOR数据类型的核心价值
-
-**类型安全**：通过固定维度定义避免运行时的维度不匹配错误
-
-**开发简化**：提供内置的向量距离计算函数，减少自定义代码
-
-**性能优化**：支持专门的向量索引，提升大规模向量查询的效率
-
-**标准兼容**：兼容SQL语法，支持排序、分组等标准操作
-
-### 适用场景
-
-**推荐使用VECTOR的情况**：
-
-* 需要频繁进行向量相似度计算
-* 向量维度固定且明确
-* 希望利用向量索引提升查询性能
-* 新开发的AI应用项目
-
-**继续使用ARRAY的情况**：
-
-* 主要进行数组操作而非向量计算
-* 向量维度经常变化
-* 改造现有系统成本较高
-* 需要复杂的向量排序查询（当前限制）
-
-### 实施建议
-
-**评估阶段**：分析现有向量数据的规模和维度特征
-
-**试点验证**：选择小规模场景验证VECTOR的效果
-
-**逐步迁移**：采用并行构建的方式平滑迁移现有系统
-
-**持续优化**：根据实际使用情况调整索引参数和查询策略
-
-### 查询模式推荐
-
-**优先使用**：
-
-* WHERE子句中的向量过滤：`WHERE COSINE_DISTANCE(...) < threshold`
-* 简单的向量函数计算：`COSINE_DISTANCE(v1, v2)`
-
-**谨慎使用**：
-
-* 复杂的 SELECT 返回距离计算并排序
-* 大型向量的嵌套查询
-
-**替代方案**：
-
-* 分步骤查询：先过滤再排序
-* 预计算：批量计算距离后存储
-
-***
-
-**注意**：本文档基于Lakehouse 2025年6月的产品文档整理，建议定期查看官方文档获取最新更新。在生产环境中使用前，请务必在测试环境中验证所有操作的正确性和性能影响。