数据模型与排序契约

贯穿全教程的例子是一个多租户 RAG 系统的文档块表。每段被切碎的文档（chunk）存一行，连同它的 embedding 和几个元数据字段：

CREATE EXTENSION IF NOT EXISTS vector;   -- 0.5.0+ 自带 HNSW

CREATE TABLE doc_chunks (
    id          bigint PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    doc_id      bigint      NOT NULL,
    tenant_id   int         NOT NULL,          -- 多租户：每个客户只能搜自己的
    lang        text        NOT NULL,          -- 'zh' / 'en' ...
    content     text        NOT NULL,
    embedding   vector(1536) NOT NULL,         -- text-embedding-3-small
    created_at  timestamptz NOT NULL DEFAULT now()
);

整本教程的查询都长这一个样子——它把"向量检索"和"关系过滤"焊在同一条 SQL 里，而这恰恰是 pgvector 全部难点的来源：

SELECT id, content
FROM   doc_chunks
WHERE  tenant_id = 42 AND lang = 'zh'      -- 关系过滤
ORDER  BY embedding <=> $1                  -- 向量排序（$1 是查询向量）
LIMIT  10;                                 -- 取最近 10 段

记住这条 SQL 的形状。这一章解释它的每一个零件；后面四章解释当数据量、并发写入和过滤选择性变化时，这条 SQL 的行为如何随之改变。

1.1向量列：把 embedding 存成一列

向量是一个定长 float 数组，作为关系表里的一个原子列存储，PG 把它当成一个有距离运算的类型。

pgvector 提供 4 种向量类型，差别在于"一个分量用几个字节"，这直接决定了能存多少维、能不能建索引：

1.2距离运算符：相似度变成一个标量表达式

pgvector 用 4 个中缀运算符表达"两个向量有多远"，每个对应一种度量。

底层机制（比文档深一层）：为什么 <#> 返回的是负内积，而不是内积本身？因为内积是"越大越相似"，要把最相似的排前面就得降序；可是 Postgres 的索引扫描只能升序吐结果（最小值先出）。pgvector 的解法很直接：把内积取负。于是"内积最大 / 最相似"变成"负内积最小"，升序扫描自然把最相似的放最前面。代价是你查出来的"相似度"是 -0.83 这种负数——要展示给人看就乘 -1，但排名本身已经是对的。这个"为了迁就升序索引而取负"的小动作，是 §1.4 那条排序契约的第一个具体痕迹。

1.3opclass：把运算符绑到索引上

opclass（operator class）是建索引时写进 DDL 的一句声明，告诉索引"该用哪种距离"。

底层机制（比文档深一层）：opclass 在运算符（<=>）和索引内部的距离函数之间建立绑定。建索引时把 opclass 写进 DDL，索引就按这种距离建图；查询时，ORDER BY 用的运算符必须和索引的 opclass 同属一类，planner 才会考虑用这个索引。对不上号——比如索引建的是 vector_cosine_ops，查询却写 <->（L2）——planner 直接放弃索引，退化成全表暴力计算。在百万行上这是 30 秒 vs 5 毫秒 的差距，而且不报任何错，只是慢。这是 §1.2 表里"运算符那一列必须和 opclass 那一列配套"的实际后果。

-- 建 cosine 索引：opclass 决定按余弦建图
CREATE INDEX ON doc_chunks
    USING hnsw (embedding vector_cosine_ops);

-- 查询用 <=>（cosine）—— 和 opclass 同类，planner 认它
SELECT id FROM doc_chunks ORDER BY embedding <=> $1 LIMIT 10;

-- 查询误用 <->（L2）—— 和 opclass 不同类，索引用不上，全表扫描
SELECT id FROM doc_chunks ORDER BY embedding <-> $1 LIMIT 10;  -- 慢，但不报错

1.4排序契约：amcanorderbyop——这一章的钥匙

HNSW / IVFFlat 是"按距离排序并取前 k"的索引（amcanorderbyop），不是过滤索引——它只认 ORDER BY 距离 ... LIMIT k。

底层机制（比文档深一层）：Postgres 的索引访问方法（access method）有一个标志位 amcanorderbyop。普通 B-tree 索引用它回答"等值和范围"（WHERE x = 5、WHERE x < 10）。HNSW 和 IVFFlat 不一样——它们把 amcanorderbyop 设成 true，意思是"它能按一个运算符返回有序的结果流"。于是 planner 只在看到 ORDER BY <距离运算符> ... LIMIT k 时才考虑用它：索引的工作就是"流式吐出离查询向量最近的那几个，吐够 k 个就停"。

这句话的每个部分都是硬约束：

• 必须有 ORDER BY 距离：没有排序表达式，索引无事可做。WHERE embedding <=> $1 < 0.3（按距离阈值过滤、不排序）——用不上索引。
• 必须有 LIMIT：没有 LIMIT，等于要求全部有序输出，planner 算下来还不如全表排序划算，于是放弃索引。
• 不能加 DESC：索引只能升序吐。ORDER BY ... DESC 要降序，索引服务不了。