VECTOR 类型

VECTOR 是云器 Lakehouse 的原生向量数据类型，用于存储和计算高维浮点数组。它是 AI 应用的核心数据结构——文本、图片、音频经过 Embedding 模型处理后，都会转化为向量，存入 VECTOR 列，再通过向量相似度搜索找到语义最接近的内容。

功能概述

什么时候用 VECTOR：

构建 RAG（检索增强生成）知识库，存储文档 Embedding
图片/音频相似度搜索
推荐系统中的用户/物品特征向量
任何需要"语义相似"而非"精确匹配"的查询场景

与 ARRAY 的区别：

特性	VECTOR	ARRAY
用途	专为向量相似度搜索优化	通用集合类型
维度	固定维度	动态长度
元素类型	仅数值 ( `float` float , `int` int , `tinyint` tinyint )	任意类型
索引支持	支持 HNSW 向量索引加速	不支持

语法与定义

vector(scalar_type, dimension) vector(dimension)

```
scalar_type
```
scalar_type
：向量元素类型，可选，默认
```
float
```
float
。支持
```
tinyint
```
tinyint
、
```
int
```
int
、
```
float
```
float
```
dimension
```
dimension
：向量维度（元素个数），必填

建表示例：

CREATE TABLE doc_embeddings ( doc_id BIGINT, content STRING, vec_1536 vector(float, 1536), -- OpenAI text-embedding-3-small 输出维度 vec_512 vector(512), -- 默认 float，维度 512 vec_int8 vector(tinyint, 128) -- 量化向量，节省存储 );

向量运算与函数

Lakehouse 提供了一系列内置函数用于向量计算。

1. 距离与相似度计算

这是向量搜索的核心，用于衡量两个向量的接近程度。

函数	说明	适用场景
`L2_DISTANCE(v1, v2)` L2_DISTANCE(v1, v2)	欧氏距离，值越小越相似	图像、音频特征匹配
`COSINE_DISTANCE(v1, v2)` COSINE_DISTANCE(v1, v2)	余弦距离，值越小越相似	文本语义相似度（最常用）
`INNER_PRODUCT(v1, v2)` INNER_PRODUCT(v1, v2)	内积，值越大越相似	归一化向量的相似度

示例：

SELECT l2_distance(vector(1, 2), vector(3, 4)) AS l2_dist, -- 结果: 2.828 cosine_distance(vector(1, 2), vector(3, 4)) AS cos_dist; -- 结果: 0.016

2. 向量归一化

l2_normalize(v)

l2_normalize(v)

将向量缩放为单位向量（模为 1）。

⚠️ 注意：归一化函数需要浮点数输入。如果传入

int

int

类型向量，结果可能会被截断为 0。

-- 正确写法：确保输入是 float 类型 SELECT l2_normalize(vector(3.0, 4.0)); -- 结果: [0.6, 0.8] -- 错误写法：int 向量归一化后变为 [0, 0] SELECT l2_normalize(vector(3, 4));

3. 点积运算

dot_product(v1, v2)

dot_product(v1, v2)

计算两个向量的点积。

SELECT dot_product(vector(1, 2), vector(3, 4)); -- 结果: 1*3 + 2*4 = 11

高级查询实战

场景 1：语义相似度搜索

找出与查询向量最相似的 Top K 文档。

-- 假设 query_vec 是用户输入经 Embedding 后的向量 SELECT doc_id, content, COSINE_DISTANCE(vec_1536, CAST('[0.12, 0.34, ...]' AS vector(1536))) AS dist FROM doc_embeddings WHERE COSINE_DISTANCE(vec_1536, CAST('[0.12, 0.34, ...]' AS vector(1536))) < 0.3 ORDER BY dist LIMIT 5;

场景 2：从 JSON 中提取向量

如果 Embedding 结果以 JSON 格式存储或传输，可以使用

json_extract

json_extract

提取并转换为 VECTOR。

-- 注意：直接查询 VECTOR 列可能会报错，建议 CAST 为 STRING 查看 SELECT CAST( CAST(json_extract_string(parse_json('{"vec": [0.1, 0.2, 0.3]}'), '$.vec') AS vector(3)) AS STRING) AS vec_from_json;

场景 3：结合 AI_EMBEDDING 实时生成

使用

ai_embedding

ai_embedding

函数将文本直接转为向量，实现端到端的语义搜索。

-- 实时计算查询文本的向量并进行搜索 SELECT doc_id, content, COSINE_DISTANCE(vec_1536, ai_embedding('endpoint:my_model', '用户查询文本')) AS dist FROM doc_embeddings ORDER BY dist LIMIT 5;

⚠️ 使用

ai_embedding

ai_embedding

需要预先配置 AI 模型端点。

类型转换

转换方向	方式	说明
STRING → VECTOR	`CAST('[1,2,3]' AS vector(3))` CAST('[1,2,3]' AS vector(3))	字符串格式为 `[v1, v2, ...]` [v1, v2, ...] ，多余空格忽略
ARRAY → VECTOR	`CAST(arr AS vector(n))` CAST(arr AS vector(n))	数组长度必须与维度 n 一致，否则返回 NULL
VECTOR → ARRAY	隐式转换	可直接传入接受 ARRAY 参数的函数
VECTOR → STRING	`CAST(vec AS STRING)` CAST(vec AS STRING)	输出格式为 `[1, 2, 3]` [1, 2, 3] （逗号后带空格）

转换示例：

-- ARRAY → VECTOR（维度匹配） SELECT CAST(array(1.0, 2.0, 3.0) AS vector(3)); -- 成功 -- ARRAY → VECTOR（维度不匹配，返回 NULL） SELECT CAST(array(1.0, 2.0) AS vector(3)); -- NULL -- VECTOR 隐式转为 ARRAY 参与计算 SELECT array_append(vector(1, 2, 3), 4); -- [1, 2, 3, 4]

向量索引加速

对大规模向量数据，建议创建向量索引以加速 ANN（近似最近邻）搜索：

-- 创建 HNSW 向量索引 CREATE VECTOR INDEX idx_vec ON doc_embeddings (vec_1536) USING HNSW PROPERTIES ( "metric_type" = "cosine" );

详见创建向量索引。

性能优化建议

量化存储：对于存储敏感场景，可以使用
```
tinyint
```
tinyint
类型的量化向量（如
```
vector(tinyint, 128)
```
vector(tinyint, 128)
），存储空间仅为
```
float
```
float
的 1/4，且计算速度更快。
标量预过滤：在向量搜索前先使用标量条件过滤（如
```
WHERE category = 'AI'
```
WHERE category = 'AI'
），减少参与距离计算的向量数量，提升查询效率。
查询限制：
- VECTOR 列本身不支持
```
ORDER BY
```
  ORDER BY
  、
```
GROUP BY
```
  GROUP BY
  、
```
DISTINCT
```
  DISTINCT
  。
- 直接
```
SELECT vector_col
```
  SELECT vector_col
  可能会报错，建议使用
```
CAST(vector_col AS STRING)
```
  CAST(vector_col AS STRING)
  查看数据。