# 编译安装
git clone --branch v0.8.1 https://github.com/pgvector/pgvector.git
cd pgvector
make
make install

# 在数据库中启用扩展
CREATE EXTENSION vector;

-- 创建包含向量列的表
CREATE TABLE items (
    id bigserial PRIMARY KEY, 
    embedding vector(3)  -- 3维向量
);

-- 插入向量数据
INSERT INTO items (embedding) VALUES 
    ('[1,2,3]'), 
    ('[4,5,6]'), 
    ('[7,8,9]');

-- 最近邻搜索（L2距离）
SELECT * FROM items 
ORDER BY embedding <-> '[3,1,2]' 
LIMIT 5;

-- 内积搜索
SELECT * FROM items 
ORDER BY embedding <#> '[3,1,2]' 
LIMIT 5;

-- 余弦距离搜索
SELECT * FROM items 
ORDER BY embedding <=> '[3,1,2]' 
LIMIT 5;

-- 创建 HNSW 索引（推荐）
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);

-- 创建 IVFFlat 索引
CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) 
WITH (lists = 100);

-- 创建文档表，存储文档和其向量表示
CREATE TABLE documents (
    id BIGSERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    embedding vector(1536),  -- OpenAI text-embedding-ada-002 的维度
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 插入示例文档数据
INSERT INTO documents (title, content, embedding) VALUES 
    ('机器学习基础', '机器学习是人工智能的一个分支...', '[0.1, 0.2, 0.3, ...]'),
    ('深度学习概述', '深度学习是机器学习的一个子领域...', '[0.2, 0.3, 0.4, ...]'),
    ('自然语言处理', 'NLP是计算机科学和人工智能的交叉领域...', '[0.3, 0.4, 0.5, ...]');

-- 创建向量索引以提高查询性能
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops) 
WITH (m = 16, ef_construction = 64);

-- 相似文档搜索查询
SELECT 
    id,
    title,
    content,
    1 - (embedding <=> '[0.15, 0.25, 0.35, ...]') AS similarity_score
FROM documents 
WHERE 1 - (embedding <=> '[0.15, 0.25, 0.35, ...]') > 0.8  -- 相似度阈值
ORDER BY embedding <=> '[0.15, 0.25, 0.35, ...]'
LIMIT 10;

-- 用户表
CREATE TABLE users (
    user_id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    user_embedding vector(128)  -- 用户偏好向量
);

-- 商品表
CREATE TABLE products (
    product_id BIGSERIAL PRIMARY KEY,
    product_name TEXT NOT NULL,
    category VARCHAR(50),
    price DECIMAL(10,2),
    product_embedding vector(128)  -- 商品特征向量
);

-- 用户行为表
CREATE TABLE user_interactions (
    interaction_id BIGSERIAL PRIMARY KEY,
    user_id BIGINT REFERENCES users(user_id),
    product_id BIGINT REFERENCES products(product_id),
    interaction_type VARCHAR(20), -- 'view', 'purchase', 'like'
    rating INTEGER CHECK (rating BETWEEN 1 AND 5),
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 创建向量索引
CREATE INDEX ON users USING hnsw (user_embedding vector_cosine_ops);
CREATE INDEX ON products USING hnsw (product_embedding vector_cosine_ops);

-- 为特定用户推荐商品
WITH user_profile AS (
    SELECT user_embedding 
    FROM users 
    WHERE user_id = 12345
),
similar_products AS (
    SELECT 
        p.product_id,
        p.product_name,
        p.category,
        p.price,
        1 - (p.product_embedding <=> u.user_embedding) AS similarity
    FROM products p, user_profile u
    WHERE 1 - (p.product_embedding <=> u.user_embedding) > 0.6
)
SELECT * FROM similar_products
ORDER BY similarity DESC
LIMIT 20;

-- 图像表
CREATE TABLE images (
    image_id BIGSERIAL PRIMARY KEY,
    filename VARCHAR(255) NOT NULL,
    file_path TEXT NOT NULL,
    image_hash VARCHAR(64),
    feature_vector vector(2048),  -- 图像特征向量（如 ResNet 特征）
    metadata JSONB,
    upload_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 图像标签表
CREATE TABLE image_tags (
    tag_id BIGSERIAL PRIMARY KEY,
    image_id BIGINT REFERENCES images(image_id),
    tag_name VARCHAR(50),
    confidence FLOAT CHECK (confidence BETWEEN 0 AND 1)
);

-- 创建多种索引以支持不同查询模式
CREATE INDEX ON images USING hnsw (feature_vector vector_l2_ops) 
WITH (m = 32, ef_construction = 128);  -- 高精度配置

CREATE INDEX ON images USING gin (metadata);  -- 元数据查询
CREATE INDEX ON image_tags (tag_name);  -- 标签查询

-- 以图搜图功能
CREATE OR REPLACE FUNCTION find_similar_images(
    query_vector vector(2048),
    similarity_threshold FLOAT DEFAULT 0.7,
    max_results INTEGER DEFAULT 50
)
RETURNS TABLE (
    image_id BIGINT,
    filename VARCHAR(255),
    file_path TEXT,
    similarity_score FLOAT,
    tags TEXT[]
) AS $$
BEGIN
    RETURN QUERY
    SELECT 
        i.image_id,
        i.filename,
        i.file_path,
        (1 - (i.feature_vector <-> query_vector))::FLOAT AS similarity_score,
        ARRAY_AGG(DISTINCT t.tag_name) AS tags
    FROM images i
    LEFT JOIN image_tags t ON i.image_id = t.image_id
    WHERE (1 - (i.feature_vector <-> query_vector)) >= similarity_threshold
    GROUP BY i.image_id, i.filename, i.file_path, i.feature_vector
    ORDER BY i.feature_vector <-> query_vector
    LIMIT max_results;
END;
$$ LANGUAGE plpgsql;

-- 使用函数进行图像检索
SELECT * FROM find_similar_images(
    '[0.1, 0.2, 0.3, ...]'::vector(2048),
    0.8,  -- 相似度阈值
    10    -- 最大结果数
);

-- 多模态内容表
CREATE TABLE multimodal_content (
    content_id BIGSERIAL PRIMARY KEY,
    title TEXT,
    description TEXT,
    content_type VARCHAR(20), -- 'text', 'image', 'video', 'audio'
    file_url TEXT,
    
    -- 不同模态的向量表示
    text_embedding vector(768),    -- 文本向量（BERT/RoBERTa）
    image_embedding vector(512),   -- 图像向量（CLIP）
    audio_embedding vector(256),   -- 音频向量
    
    -- 融合向量
    multimodal_embedding vector(1024), -- 多模态融合向量
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 为不同模态创建索引
CREATE INDEX ON multimodal_content USING hnsw (text_embedding vector_cosine_ops);
CREATE INDEX ON multimodal_content USING hnsw (image_embedding vector_cosine_ops);
CREATE INDEX ON multimodal_content USING hnsw (multimodal_embedding vector_cosine_ops);

-- 多模态搜索函数
CREATE OR REPLACE FUNCTION multimodal_search(
    query_text_vector vector(768) DEFAULT NULL,
    query_image_vector vector(512) DEFAULT NULL,
    content_type_filter VARCHAR(20) DEFAULT NULL,
    limit_count INTEGER DEFAULT 20
)
RETURNS TABLE (
    content_id BIGINT,
    title TEXT,
    content_type VARCHAR(20),
    text_similarity FLOAT,
    image_similarity FLOAT,
    combined_score FLOAT
) AS $$
BEGIN
    RETURN QUERY
    SELECT 
        mc.content_id,
        mc.title,
        mc.content_type,
        CASE 
            WHEN query_text_vector IS NOT NULL AND mc.text_embedding IS NOT NULL 
            THEN (1 - (mc.text_embedding <=> query_text_vector))::FLOAT 
            ELSE 0.0 
        END AS text_similarity,
        CASE 
            WHEN query_image_vector IS NOT NULL AND mc.image_embedding IS NOT NULL 
            THEN (1 - (mc.image_embedding <=> query_image_vector))::FLOAT 
            ELSE 0.0 
        END AS image_similarity,
        (
            COALESCE(1 - (mc.text_embedding <=> query_text_vector), 0) * 0.6 +
            COALESCE(1 - (mc.image_embedding <=> query_image_vector), 0) * 0.4
        )::FLOAT AS combined_score
    FROM multimodal_content mc
    WHERE 
        (content_type_filter IS NULL OR mc.content_type = content_type_filter)
        AND (
            (query_text_vector IS NOT NULL AND mc.text_embedding IS NOT NULL) OR
            (query_image_vector IS NOT NULL AND mc.image_embedding IS NOT NULL)
        )
    ORDER BY combined_score DESC
    LIMIT limit_count;
END;
$$ LANGUAGE plpgsql;

-- 使用示例：文本+图像联合搜索
SELECT * FROM multimodal_search(
    '[0.1, 0.2, ...]'::vector(768),  -- 文本查询向量
    '[0.3, 0.4, ...]'::vector(512),  -- 图像查询向量
    NULL,  -- 不限制内容类型
    15     -- 返回15个结果
);

// 位置：src/vector.c
// 功能：将文本格式的向量输入转换为内部 Vector 结构
// 参数：
//   - lit: 输入的字符串，如 '[1,2,3]'
//   - typmod: 类型修饰符，包含维度信息
// 返回值：Vector* 指向新创建的向量结构
// 调用关系：被 PostgreSQL 类型系统调用，用于处理向量输入
// 性能特征：O(n) 时间复杂度，n为向量维度
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(vector_in);
Datum
vector_in(PG_FUNCTION_ARGS)
{
    char       *lit = PG_GETARG_CSTRING(0);      // 获取输入字符串
    int32       typmod = PG_GETARG_INT32(2);     // 获取类型修饰符
    float       x[VECTOR_MAX_DIM];               // 临时存储向量元素
    int         dim = 0;                         // 向量维度计数器
    char       *pt = lit;                        // 字符串解析指针
    Vector     *result;                          // 结果向量指针

    // 跳过前导空白字符
    while (vector_isspace(*pt))
        pt++;

    // 检查向量开始标记 '['
    if (*pt != '[')
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
                 errmsg("invalid input syntax for type vector: \"%s\"", lit),
                 errdetail("Vector contents must start with \"[\".")));

    pt++; // 跳过 '['

    // 跳过 '[' 后的空白字符
    while (vector_isspace(*pt))
        pt++;

    // 检查空向量（不允许）
    if (*pt == ']')
        ereport(ERROR,
                (errcode(ERRCODE_DATA_EXCEPTION),
                 errmsg("vector must have at least 1 dimension")));

    // 解析向量元素的主循环
    for (;;)
    {
        float       val;                         // 当前元素值
        char       *stringEnd;                   // 数值解析结束位置

        // 检查维度限制
        if (dim == VECTOR_MAX_DIM)
            ereport(ERROR,
                    (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                     errmsg("vector cannot have more than %d dimensions", VECTOR_MAX_DIM)));

        // 跳过元素前的空白字符
        while (vector_isspace(*pt))
            pt++;

        // 检查意外的字符串结束
        if (*pt == '\0')
            ereport(ERROR,
                    (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
                     errmsg("invalid input syntax for type vector: \"%s\"", lit)));

        errno = 0;

        // 使用 strtof 解析浮点数（避免双重舍入问题）
        val = strtof(pt, &stringEnd);

        // 检查解析是否成功
        if (stringEnd == pt)
            ereport(ERROR,
                    (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
                     errmsg("invalid input syntax for type vector: \"%s\"", lit)));

        // 检查数值范围错误
        if (errno == ERANGE && isinf(val))
            ereport(ERROR,
                    (errcode(ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE),
                     errmsg("\"%s\" is out of range for type vector", 
                            pnstrdup(pt, stringEnd - pt))));

        // 检查元素有效性（NaN、无穷大等）
        CheckElement(val);
        x[dim++] = val;                          // 存储元素并增加维度计数

        pt = stringEnd;                          // 移动解析指针

        // 跳过元素后的空白字符
        while (vector_isspace(*pt))
            pt++;

        // 处理分隔符和结束符
        if (*pt == ',')
            pt++;                                // 跳过逗号，继续解析下一个元素
        else if (*pt == ']')
        {
            pt++;                                // 跳过 ']'，结束解析
            break;
        }
        else
            ereport(ERROR,
                    (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
                     errmsg("invalid input syntax for type vector: \"%s\"", lit)));
    }

    // 检查 ']' 后只允许空白字符
    while (vector_isspace(*pt))
        pt++;

    if (*pt != '\0')
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
                 errmsg("invalid input syntax for type vector: \"%s\"", lit)));

    // 验证维度
    CheckDim(dim);
    CheckExpectedDim(typmod, dim);

    // 创建结果向量并复制数据
    result = InitVector(dim);
    for (int i = 0; i < dim; i++)
        result->x[i] = x[i];

    PG_RETURN_VECTOR_P(result);
}

SQL输入 → PostgreSQL解析器 → vector_in → CheckDim → CheckExpectedDim → InitVector → Vector结构体

// 位置：src/vector.c
// 功能：将 PostgreSQL 数组类型转换为 Vector 类型
// 参数：
//   - array: PostgreSQL 数组类型指针
//   - typmod: 类型修饰符，包含期望的维度信息
// 返回值：Vector* 指向新创建的向量结构
// 调用关系：被类型转换系统调用，支持 ARRAY[1,2,3]::vector 语法
// 性能特征：O(n) 时间复杂度，支持多种数值类型转换
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(array_to_vector);
Datum
array_to_vector(PG_FUNCTION_ARGS)
{
    ArrayType  *array = PG_GETARG_ARRAYTYPE_P(0);   // 获取输入数组
    int32       typmod = PG_GETARG_INT32(1);         // 获取类型修饰符
    Vector     *result;                              // 结果向量指针
    int16       typlen;                              // 元素类型长度
    bool        typbyval;                            // 元素是否按值传递
    char        typalign;                            // 元素对齐方式
    Datum      *elemsp;                              // 数组元素指针数组
    int         nelemsp;                             // 数组元素数量

    // 检查数组维度（只支持一维数组）
    if (ARR_NDIM(array) > 1)
        ereport(ERROR,
                (errcode(ERRCODE_DATA_EXCEPTION),
                 errmsg("array must be 1-D")));

    // 检查数组是否包含 NULL 值（不允许）
    if (ARR_HASNULL(array) && array_contains_nulls(array))
        ereport(ERROR,
                (errcode(ERRCODE_NULL_VALUE_NOT_ALLOWED),
                 errmsg("array must not contain nulls")));

    // 获取数组元素类型信息
    get_typlenbyvalalign(ARR_ELEMTYPE(array), &typlen, &typbyval, &typalign);
    
    // 解构数组，获取元素数据
    deconstruct_array(array, ARR_ELEMTYPE(array), typlen, typbyval, typalign, 
                     &elemsp, NULL, &nelemsp);

    // 验证维度
    CheckDim(nelemsp);
    CheckExpectedDim(typmod, nelemsp);

    // 初始化结果向量
    result = InitVector(nelemsp);

    // 根据数组元素类型进行转换
    if (ARR_ELEMTYPE(array) == INT4OID)
    {
        // 整数类型转换
        for (int i = 0; i < nelemsp; i++)
            result->x[i] = DatumGetInt32(elemsp[i]);
    }
    else if (ARR_ELEMTYPE(array) == FLOAT8OID)
    {
        // 双精度浮点数转换
        for (int i = 0; i < nelemsp; i++)
            result->x[i] = DatumGetFloat8(elemsp[i]);
    }
    else if (ARR_ELEMTYPE(array) == FLOAT4OID)
    {
        // 单精度浮点数转换
        for (int i = 0; i < nelemsp; i++)
            result->x[i] = DatumGetFloat4(elemsp[i]);
    }
    else if (ARR_ELEMTYPE(array) == NUMERICOID)
    {
        // NUMERIC 类型转换
        for (int i = 0; i < nelemsp; i++)
            result->x[i] = DatumGetFloat4(DirectFunctionCall1(numeric_float4, elemsp[i]));
    }
    else
    {
        // 不支持的数组类型
        ereport(ERROR,
                (errcode(ERRCODE_DATA_EXCEPTION),
                 errmsg("unsupported array type")));
    }

    // 释放解构数组时分配的内存
    pfree(elemsp);

    // 检查所有元素的有效性
    for (int i = 0; i < result->dim; i++)
        CheckElement(result->x[i]);

    PG_RETURN_POINTER(result);
}

// 位置：src/vector.c
// 功能：对向量进行 L2 标准化（单位向量化）
// 参数：
//   - a: 输入向量指针
// 返回值：Vector* 指向标准化后的新向量
// 调用关系：被 SQL 函数 l2_normalize() 调用
// 性能特征：O(n) 时间复杂度，包含两次向量遍历
// 算法：result = a / ||a||_2，其中 ||a||_2 = sqrt(sum(a_i^2))
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(l2_normalize);
Datum
l2_normalize(PG_FUNCTION_ARGS)
{
    Vector     *a = PG_GETARG_VECTOR_P(0);           // 获取输入向量
    float      *ax = a->x;                           // 输入向量数据指针
    double      norm = 0;                            // L2 范数累积器
    Vector     *result;                              // 结果向量指针
    float      *rx;                                  // 结果向量数据指针

    // 初始化结果向量
    result = InitVector(a->dim);
    rx = result->x;

    // 计算 L2 范数的平方（自动向量化优化）
    for (int i = 0; i < a->dim; i++)
        norm += (double) ax[i] * (double) ax[i];

    // 计算 L2 范数
    norm = sqrt(norm);

    // 处理零向量情况（返回零向量）
    if (norm > 0)
    {
        // 标准化：每个元素除以范数
        for (int i = 0; i < a->dim; i++)
            rx[i] = ax[i] / norm;

        // 检查溢出情况
        for (int i = 0; i < a->dim; i++)
        {
            if (isinf(rx[i]))
                float_overflow_error();
        }
    }

    PG_RETURN_POINTER(result);
}

// 位置：src/vector.c
// 功能：计算两个向量的元素级加法
// 参数：
//   - a: 第一个向量指针
//   - b: 第二个向量指针
// 返回值：Vector* 指向相加结果的新向量
// 调用关系：被 SQL 操作符 + 调用
// 性能特征：O(n) 时间复杂度，自动向量化优化
// 算法：result[i] = a[i] + b[i]
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(vector_add);
Datum
vector_add(PG_FUNCTION_ARGS)
{
    Vector     *a = PG_GETARG_VECTOR_P(0);           // 获取第一个向量
    Vector     *b = PG_GETARG_VECTOR_P(1);           // 获取第二个向量
    float      *ax = a->x;                           // 第一个向量数据指针
    float      *bx = b->x;                           // 第二个向量数据指针
    Vector     *result;                              // 结果向量指针
    float      *rx;                                  // 结果向量数据指针

    // 检查向量维度是否匹配
    CheckDims(a, b);

    // 初始化结果向量
    result = InitVector(a->dim);
    rx = result->x;

    // 执行元素级加法（自动向量化优化）
    for (int i = 0, imax = a->dim; i < imax; i++)
        rx[i] = ax[i] + bx[i];

    // 检查溢出情况
    for (int i = 0, imax = a->dim; i < imax; i++)
    {
        if (isinf(rx[i]))
            float_overflow_error();
    }

    PG_RETURN_POINTER(result);
}

// 位置：src/vector.c
// 功能：将向量量化为二进制向量（每个元素变为 0 或 1）
// 参数：
//   - a: 输入向量指针
// 返回值：VarBit* 指向二进制向量结构
// 调用关系：被 SQL 函数 binary_quantize() 调用
// 性能特征：O(n) 时间复杂度，8倍空间压缩
// 算法：result[i] = (a[i] > 0) ? 1 : 0
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(binary_quantize);
Datum
binary_quantize(PG_FUNCTION_ARGS)
{
    Vector     *a = PG_GETARG_VECTOR_P(0);           // 获取输入向量
    float      *ax = a->x;                           // 输入向量数据指针
    VarBit     *result = InitBitVector(a->dim);      // 初始化二进制向量
    unsigned char *rx = VARBITS(result);             // 二进制数据指针
    int         i = 0;                               // 循环计数器
    int         count = (a->dim / 8) * 8;            // 8的倍数部分

    // 处理8的倍数部分（自动向量化优化）
    for (; i < count; i += 8)
    {
        unsigned char result_byte = 0;               // 当前字节结果

        // 将8个浮点数打包成1个字节
        for (int j = 0; j < 8; j++)
            result_byte |= (ax[i + j] > 0) << (7 - j);

        rx[i / 8] = result_byte;                     // 存储字节
    }

    // 处理剩余元素
    for (; i < a->dim; i++)
        rx[i / 8] |= (ax[i] > 0) << (7 - (i % 8));

    PG_RETURN_VARBIT_P(result);
}

// 位置：src/vector.c
// 功能：计算两个向量之间的欧几里得距离（L2距离）
// 参数：
//   - a: 第一个向量指针
//   - b: 第二个向量指针
// 返回值：double 类型的 L2 距离值
// 调用关系：被 SQL 操作符 <-> 调用
// 性能特征：O(n) 时间复杂度，支持 SIMD 优化
// 算法：sqrt(sum((a[i] - b[i])^2))
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(l2_distance);
Datum
l2_distance(PG_FUNCTION_ARGS)
{
    Vector     *a = PG_GETARG_VECTOR_P(0);           // 获取第一个向量
    Vector     *b = PG_GETARG_VECTOR_P(1);           // 获取第二个向量

    // 检查向量维度是否匹配
    CheckDims(a, b);

    // 调用优化的 L2 距离计算函数并开方
    PG_RETURN_FLOAT8(sqrt((double) VectorL2SquaredDistance(a->dim, a->x, b->x)));
}

// L2 平方距离的内部实现（支持 SIMD 优化）
VECTOR_TARGET_CLONES static float
VectorL2SquaredDistance(int dim, float *ax, float *bx)
{
    float       distance = 0.0;                      // 距离累积器

    // 自动向量化优化的主循环
    for (int i = 0; i < dim; i++)
    {
        float       diff = ax[i] - bx[i];            // 计算每维差值
        distance += diff * diff;                     // 累积平方差
    }

    return distance;                                 // 返回平方距离
}

// 位置：src/vector.c
// 功能：计算两个向量的内积（点积）
// 参数：
//   - a: 第一个向量指针
//   - b: 第二个向量指针
// 返回值：double 类型的内积值
// 调用关系：被 SQL 函数 inner_product() 调用
// 性能特征：O(n) 时间复杂度，支持 SIMD 优化
// 算法：sum(a[i] * b[i])
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(inner_product);
Datum
inner_product(PG_FUNCTION_ARGS)
{
    Vector     *a = PG_GETARG_VECTOR_P(0);           // 获取第一个向量
    Vector     *b = PG_GETARG_VECTOR_P(1);           // 获取第二个向量

    // 检查向量维度是否匹配
    CheckDims(a, b);

    // 调用优化的内积计算函数
    PG_RETURN_FLOAT8((double) VectorInnerProduct(a->dim, a->x, b->x));
}

// 内积的内部实现（支持 SIMD 优化）
VECTOR_TARGET_CLONES static float
VectorInnerProduct(int dim, float *ax, float *bx)
{
    float       distance = 0.0;                      // 内积累积器

    // 自动向量化优化的主循环
    for (int i = 0; i < dim; i++)
        distance += ax[i] * bx[i];                   // 累积乘积

    return distance;                                 // 返回内积值
}

// 位置：src/vector.c
// 功能：计算两个向量的负内积（用于 PostgreSQL 升序排序）
// 参数：
//   - a: 第一个向量指针
//   - b: 第二个向量指针
// 返回值：double 类型的负内积值
// 调用关系：被 SQL 操作符 <#> 调用
// 性能特征：O(n) 时间复杂度，支持 SIMD 优化
// 设计原因：PostgreSQL 默认升序排序，负内积使得相似度高的排在前面
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(vector_negative_inner_product);
Datum
vector_negative_inner_product(PG_FUNCTION_ARGS)
{
    Vector     *a = PG_GETARG_VECTOR_P(0);           // 获取第一个向量
    Vector     *b = PG_GETARG_VECTOR_P(1);           // 获取第二个向量

    // 检查向量维度是否匹配
    CheckDims(a, b);

    // 返回负内积值
    PG_RETURN_FLOAT8((double) -VectorInnerProduct(a->dim, a->x, b->x));
}

// 位置：src/vector.c
// 功能：计算两个向量之间的余弦距离
// 参数：
//   - a: 第一个向量指针
//   - b: 第二个向量指针
// 返回值：double 类型的余弦距离值 (1 - 余弦相似度)
// 调用关系：被 SQL 操作符 <=> 调用
// 性能特征：O(n) 时间复杂度，包含范数计算
// 算法：1 - (a·b) / (||a|| * ||b||)
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(cosine_distance);
Datum
cosine_distance(PG_FUNCTION_ARGS)
{
    Vector     *a = PG_GETARG_VECTOR_P(0);           // 获取第一个向量
    Vector     *b = PG_GETARG_VECTOR_P(1);           // 获取第二个向量
    double      similarity;                          // 余弦相似度

    // 检查向量维度是否匹配
    CheckDims(a, b);

    // 计算余弦相似度
    similarity = VectorCosineSimilarity(a->dim, a->x, b->x);

#ifdef _MSC_VER
    // Microsoft 编译器的 /fp:fast 可能不传播 NaN
    if (isnan(similarity))
        PG_RETURN_FLOAT8(NAN);
#endif

    // 将相似度限制在 [-1, 1] 范围内（处理浮点精度误差）
    if (similarity > 1)
        similarity = 1.0;
    else if (similarity < -1)
        similarity = -1.0;

    // 返回余弦距离：1 - 余弦相似度
    PG_RETURN_FLOAT8(1.0 - similarity);
}

// 余弦相似度的内部实现（支持 SIMD 优化）
VECTOR_TARGET_CLONES static double
VectorCosineSimilarity(int dim, float *ax, float *bx)
{
    float       similarity = 0.0;                    // 内积累积器
    float       norma = 0.0;                         // 向量a的范数平方
    float       normb = 0.0;                         // 向量b的范数平方

    // 一次遍历计算内积和两个向量的范数平方（自动向量化优化）
    for (int i = 0; i < dim; i++)
    {
        similarity += ax[i] * bx[i];                 // 累积内积
        norma += ax[i] * ax[i];                      // 累积a的范数平方
        normb += bx[i] * bx[i];                      // 累积b的范数平方
    }

    // 使用 sqrt(a * b) 而不是 sqrt(a) * sqrt(b) 以提高数值稳定性
    return (double) similarity / sqrt((double) norma * (double) normb);
}

// 位置：src/vector.c
// 功能：计算两个向量之间的 L1 距离（曼哈顿距离）
// 参数：
//   - a: 第一个向量指针
//   - b: 第二个向量指针
// 返回值：double 类型的 L1 距离值
// 调用关系：被 SQL 操作符 <+> 调用
// 性能特征：O(n) 时间复杂度，支持 SIMD 优化
// 算法：sum(|a[i] - b[i]|)
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(l1_distance);
Datum
l1_distance(PG_FUNCTION_ARGS)
{
    Vector     *a = PG_GETARG_VECTOR_P(0);           // 获取第一个向量
    Vector     *b = PG_GETARG_VECTOR_P(1);           // 获取第二个向量

    // 检查向量维度是否匹配
    CheckDims(a, b);

    // 调用优化的 L1 距离计算函数
    PG_RETURN_FLOAT8((double) VectorL1Distance(a->dim, a->x, b->x));
}

// L1 距离的内部实现（支持 SIMD 优化）
VECTOR_TARGET_CLONES static float
VectorL1Distance(int dim, float *ax, float *bx)
{
    float       distance = 0.0;                      // 距离累积器

    // 自动向量化优化的主循环
    for (int i = 0; i < dim; i++)
        distance += fabsf(ax[i] - bx[i]);            // 累积绝对差值

    return distance;                                 // 返回 L1 距离
}

// 位置：src/hnswbuild.c
IndexBuildResult *hnswbuild(Relation heap, Relation index, IndexInfo *indexInfo)
{
    HnswBuildState buildstate;
    IndexBuildResult *result;
    
    // 初始化构建状态
    InitBuildState(&buildstate, heap, index, indexInfo);
    
    // 扫描堆表并构建图结构
    table_index_build_scan(heap, index, indexInfo,
                          true, true, HnswBuildCallback,
                          (void *) &buildstate, NULL);
    
    // 更新元数据页
    HnswUpdateMetaPage(index, HNSW_UPDATE_ENTRY_ALWAYS,
                      buildstate.graph->entryPoint, 
                      InvalidBlockNumber, MAIN_FORKNUM, true);
    
    return result;
}

CREATE INDEX → PostgreSQL索引管理器 → hnswbuild → 图构建算法 → 磁盘存储

// 位置：src/hnswscan.c
bool hnswgettuple(IndexScanDesc scan, ScanDirection dir)
{
    HnswScanOpaque so = (HnswScanOpaque) scan->opaque;
    
    if (so->first)
    {
        // 第一次扫描：初始化搜索
        Datum value = scan->orderByData->sk_argument;
        so->w = HnswSearchLayer(NULL, &so->q, 
                               list_make1(entryCandidate),
                               hnsw_ef_search, 0, scan->indexRelation,
                               &so->support, so->m, false, NULL,
                               &so->v, &so->discarded, true, &so->tuples);
        so->first = false;
    }
    
    // 返回下一个最近邻
    return GetNextNeighbor(scan);
}

// 位置：src/vector.c
FUNCTION_PREFIX PG_FUNCTION_INFO_V1(vector_l2_squared_distance);
Datum vector_l2_squared_distance(PG_FUNCTION_ARGS)
{
    Vector *a = PG_GETARG_VECTOR_P(0);
    Vector *b = PG_GETARG_VECTOR_P(1);
    float distance = 0.0;
    int i;
    
    CheckDims(a, b);
    
    // 计算平方距离（避免开方运算提高性能）
    for (i = 0; i < a->dim; i++)
    {
        float diff = a->x[i] - b->x[i];
        distance += diff * diff;
    }
    
    PG_RETURN_FLOAT8(distance);
}

graph TB
    subgraph "客户端层 (Client Layer)"
        A1[应用程序] --> A2[SQL客户端]
        A2 --> A3[连接池]
        A3 --> A4[网络协议]
    end
    
    subgraph "SQL处理层 (SQL Processing Layer)"
        A4 --> B1[PostgreSQL解析器]
        B1 --> B2[语法分析器]
        B2 --> B3[语义分析器]
        B3 --> B4[查询重写器]
        B4 --> B5[查询优化器]
        B5 --> B6[执行计划生成器]
        B6 --> B7[执行器]
    end
    
    subgraph "pgvector扩展层 (Extension Layer)"
        B7 --> C1[向量操作符处理器]
        B7 --> C2[索引访问方法接口]
        B7 --> C3[类型转换系统]
        
        C1 --> C4[距离计算引擎]
        C2 --> C5[HNSW索引管理器]
        C2 --> C6[IVFFlat索引管理器]
        C3 --> C7[向量类型处理器]
        
        C4 --> C8[SIMD优化模块]
        C5 --> C9[图构建算法]
        C5 --> C10[图搜索算法]
        C6 --> C11[K-means聚类算法]
        C6 --> C12[聚类搜索算法]
        C7 --> C13[内存管理器]
    end
    
    subgraph "存储抽象层 (Storage Abstraction Layer)"
        C9 --> D1[图结构序列化器]
        C10 --> D2[图结构反序列化器]
        C11 --> D3[聚类数据序列化器]
        C12 --> D4[聚类数据反序列化器]
        C13 --> D5[向量数据管理器]
        
        D1 --> D6[页面管理接口]
        D2 --> D6
        D3 --> D6
        D4 --> D6
        D5 --> D6
    end
    
    subgraph "PostgreSQL存储层 (Storage Layer)"
        D6 --> E1[缓冲区管理器]
        E1 --> E2[页面管理器]
        E2 --> E3[文件管理器]
        E3 --> E4[磁盘I/O子系统]
        
        E1 --> E5[WAL日志系统]
        E5 --> E6[检查点管理器]
        E6 --> E7[恢复管理器]
    end
    
    subgraph "并发控制层 (Concurrency Control)"
        F1[锁管理器] --> F2[MVCC控制器]
        F2 --> F3[事务管理器]
        F3 --> F4[死锁检测器]
    end
    
    subgraph "监控与管理层 (Monitoring & Management)"
        G1[性能统计收集器] --> G2[查询计划分析器]
        G2 --> G3[索引使用统计器]
        G3 --> G4[内存使用监控器]
        G4 --> G5[系统健康检查器]
    end
    
    %% 跨层连接
    B5 -.-> F1
    C2 -.-> F1
    C13 -.-> E1
    C4 -.-> G1
    C5 -.-> G3
    C6 -.-> G3
    
    %% 样式定义
    classDef clientLayer fill:#e1f5fe
    classDef sqlLayer fill:#f3e5f5
    classDef extensionLayer fill:#e8f5e8
    classDef storageAbsLayer fill:#fff3e0
    classDef storageLayer fill:#fce4ec
    classDef concurrencyLayer fill:#f1f8e9
    classDef monitoringLayer fill:#e0f2f1
    
    class A1,A2,A3,A4 clientLayer
    class B1,B2,B3,B4,B5,B6,B7 sqlLayer
    class C1,C2,C3,C4,C5,C6,C7,C8,C9,C10,C11,C12,C13 extensionLayer
    class D1,D2,D3,D4,D5,D6 storageAbsLayer
    class E1,E2,E3,E4,E5,E6,E7 storageLayer
    class F1,F2,F3,F4 concurrencyLayer
    class G1,G2,G3,G4,G5 monitoringLayer

sequenceDiagram
    participant Client as 客户端应用
    participant Parser as SQL解析器
    participant Optimizer as 查询优化器
    participant IndexMgr as 索引管理器
    participant HnswBuilder as HNSW构建器
    participant MemMgr as 内存管理器
    participant Storage as 存储管理器
    participant BufferMgr as 缓冲区管理器
    participant WAL as WAL日志系统
    
    Note over Client,WAL: HNSW索引构建完整流程
    
    Client->>Parser: CREATE INDEX USING hnsw (embedding vector_l2_ops)
    Parser->>Parser: 语法分析和语义检查
    Parser->>Optimizer: 生成索引构建计划
    Optimizer->>IndexMgr: 调用索引构建接口
    
    IndexMgr->>HnswBuilder: hnswbuild(heap, index, indexInfo)
    HnswBuilder->>MemMgr: 初始化构建状态和内存上下文
    MemMgr-->>HnswBuilder: 返回内存分配器
    
    HnswBuilder->>Storage: table_index_build_scan()
    Note over HnswBuilder,Storage: 扫描堆表中的所有向量数据
    
    loop 对每个向量元组
        Storage->>HnswBuilder: HnswBuildCallback(tid, values)
        HnswBuilder->>HnswBuilder: 解析向量值
        HnswBuilder->>HnswBuilder: 创建HnswElement节点
        HnswBuilder->>HnswBuilder: 确定节点层级(概率分布)
        HnswBuilder->>HnswBuilder: 搜索最近邻居
        HnswBuilder->>HnswBuilder: 建立双向连接
        HnswBuilder->>MemMgr: 检查内存使用情况
        
        alt 内存不足
            MemMgr->>Storage: 刷写部分图结构到磁盘
            Storage->>BufferMgr: 分配新的缓冲区页面
            BufferMgr->>WAL: 记录页面修改日志
        end
    end
    
    HnswBuilder->>Storage: HnswUpdateMetaPage()
    Storage->>BufferMgr: 更新索引元数据页
    BufferMgr->>WAL: 记录元数据修改
    WAL-->>BufferMgr: 确认日志写入
    
    HnswBuilder-->>IndexMgr: 返回IndexBuildResult
    IndexMgr-->>Optimizer: 构建完成统计信息
    Optimizer-->>Parser: 索引构建成功
    Parser-->>Client: CREATE INDEX成功响应

sequenceDiagram
    participant Client as 客户端应用
    participant Parser as SQL解析器
    participant Planner as 查询规划器
    participant Executor as 执行器
    participant IndexScan as 索引扫描器
    participant HnswSearch as HNSW搜索器
    participant DistCalc as 距离计算器
    participant BufferMgr as 缓冲区管理器
    participant LockMgr as 锁管理器
    
    Note over Client,LockMgr: 向量相似性查询完整流程
    
    Client->>Parser: SELECT * FROM items ORDER BY embedding <-> '[1,2,3]' LIMIT 5
    Parser->>Parser: 解析SQL并识别向量操作符
    Parser->>Planner: 生成查询计划
    
    Planner->>Planner: 评估索引使用成本
    Planner->>Planner: 选择HNSW索引扫描
    Planner->>Executor: 生成执行计划
    
    Executor->>IndexScan: hnswbeginscan(index, nkeys, norderbys)
    IndexScan->>LockMgr: 获取索引访问锁
    LockMgr-->>IndexScan: 锁获取成功
    
    IndexScan->>IndexScan: 初始化HnswScanOpaque
    IndexScan->>BufferMgr: 读取索引元数据页
    BufferMgr-->>IndexScan: 返回入口点信息
    
    Executor->>IndexScan: hnswgettuple(scan, ForwardScanDirection)
    
    alt 首次扫描
        IndexScan->>HnswSearch: HnswSearchLayer(entryPoint, queryVector)
        HnswSearch->>BufferMgr: 读取入口点页面
        BufferMgr-->>HnswSearch: 返回入口点数据
        
        loop 从高层到低层搜索
            HnswSearch->>HnswSearch: 在当前层执行贪心搜索
            HnswSearch->>BufferMgr: 读取邻居节点页面
            BufferMgr-->>HnswSearch: 返回邻居数据
            HnswSearch->>DistCalc: 计算查询向量与邻居的距离
            DistCalc->>DistCalc: SIMD优化的距离计算
            DistCalc-->>HnswSearch: 返回距离值
            HnswSearch->>HnswSearch: 更新候选集合
        end
        
        HnswSearch-->>IndexScan: 返回排序的候选列表
        IndexScan->>IndexScan: 设置first=false
    end
    
    IndexScan->>IndexScan: GetNextNeighbor()
    IndexScan-->>Executor: 返回下一个最近邻的TID
    
    Executor->>BufferMgr: 根据TID读取堆表数据
    BufferMgr-->>Executor: 返回完整的元组数据
    Executor-->>Client: 返回查询结果行
    
    Note over Client,LockMgr: 重复gettuple直到获取足够结果或扫描完成
    
    Executor->>IndexScan: hnswendscan(scan)
    IndexScan->>LockMgr: 释放索引访问锁
    IndexScan->>IndexScan: 清理扫描状态
    IndexScan-->>Executor: 扫描结束
    Executor-->>Client: 查询完成

sequenceDiagram
    participant Client1 as 客户端1(查询)
    participant Client2 as 客户端2(插入)
    participant LockMgr as 锁管理器
    participant IndexScan as 索引扫描
    participant IndexInsert as 索引插入
    participant MVCC as MVCC控制器
    participant BufferMgr as 缓冲区管理器
    participant WAL as WAL系统
    
    Note over Client1,WAL: 并发查询和插入操作
    
    par 并发操作开始
        Client1->>IndexScan: 开始向量查询
        and
        Client2->>IndexInsert: 开始向量插入
    end
    
    IndexScan->>LockMgr: 请求索引共享锁
    IndexInsert->>LockMgr: 请求索引排他锁
    
    LockMgr->>LockMgr: 检查锁兼容性
    LockMgr-->>IndexScan: 授予共享锁
    LockMgr->>IndexInsert: 等待排他锁
    
    IndexScan->>BufferMgr: 读取索引页面
    BufferMgr->>MVCC: 检查页面可见性
    MVCC-->>BufferMgr: 返回可见版本
    BufferMgr-->>IndexScan: 返回页面数据
    
    IndexScan->>IndexScan: 执行向量搜索
    IndexScan-->>Client1: 返回查询结果
    
    IndexScan->>LockMgr: 释放共享锁
    LockMgr-->>IndexInsert: 授予排他锁
    
    IndexInsert->>BufferMgr: 读取索引页面进行修改
    BufferMgr-->>IndexInsert: 返回页面数据
    
    IndexInsert->>IndexInsert: 插入新向量到HNSW图
    IndexInsert->>BufferMgr: 标记页面为脏页
    BufferMgr->>WAL: 记录页面修改日志
    WAL-->>BufferMgr: 确认日志写入
    
    IndexInsert->>LockMgr: 释放排他锁
    IndexInsert-->>Client2: 插入操作完成