在用 FalkorDB（一个兼容 Redis 协议的图数据库）做 GraphRAG 或语义检索时，我们经常想用它自带的原生向量检索能力，也就是这个 API：
CALL db.idx.vector.queryNodes('Entity', 'embedding', 10, vecf32($query_vec))
理想很美好：一条 Cypher 就能拿到「和查询向量最相似的 10 个节点」，底层走的是高效的近似最近邻（ANN）检索。
但很多人第一次用的时候会发现：要么直接报错，要么返回空结果，要么退化成慢得离谱的全表扫描。明明数据都写进去了，为什么就是不工作？
这篇文章我们就来把 db.idx.vector.queryNodes 能正常工作的两个必要条件讲清楚，再拆解几个最容易踩的坑。
一、先看结论：两个必要条件缺一不可
要让原生向量检索真正生效，必须同时满足两点：
- embedding 数据是以原生 vector 类型存储的（用
vecf32() 这类函数转换过的向量）。
- 在对应属性上创建了向量索引（vector index）。
这两点是「与」的关系，不是「或」。少了任何一个，db.idx.vector.queryNodes 都不会按我们期望的方式工作。
我们可以打个比方：
- 条件一（vector 类型）好比「书里的内容确实是按拼音顺序排好的」。
- 条件二（vector index）好比「书前面有一份拼音目录」。
只有内容本身有序、又有目录，我们才能翻目录快速定位。如果内容根本不是按拼音排的，那目录就是假的；如果有序但没目录，那还是得一页页翻。两者缺一，”快速查找”都无从谈起。
下面我们分别说清楚这两个条件，以及为什么它们缺一不可。
二、条件一：数据必须是原生 vector 类型
FalkorDB 里有个很关键、但又很容易被忽略的区别：「一串数字」和「一个向量」在存储层面是完全不同的东西。
什么才算 vector 类型
在写入的时候，我们必须用 vecf32() 把数组显式转换成向量类型：
CREATE (:Entity {name: 'Alice', embedding: vecf32([0.1, 0.2, 0.3, 0.4])})
注意这里的 vecf32(...)。它把普通数组转成了 FalkorDB 内部的 32 位浮点向量类型。只有经过这一步，这个属性才是「真正的向量」，向量索引和 ANN 检索才认得它。
误区一：embedding 是普通 List，不是 vector 类型
这是最常见的坑。很多写入代码是这样的：
# 反例：直接把 4096 维数组写进去
graph.query(
"MATCH (n:entities {id: $id}) SET n.embedding = $vec",
{"id": doc_id, "vec": embedding_list}, # embedding_list 是 list[float]
)
embedding_list 是一个 4096 维的 Python list，通过 Redis / Cypher 传进去后，FalkorDB 把它存成原生 List 类型。
问题在于：
- List 看起来能存下所有浮点数，功能上”没报错”；
- 但向量索引不会收录 List 类型的属性；
- 于是
db.idx.vector.queryNodes 要么返回空，要么因为索引里没有条目而查不到目标节点。
正确做法是在 Cypher 里用 vecf32() 包一层：
# 正确
graph.query(
"MATCH (n:entities {id: $id}) SET n.embedding = vecf32($vec)",
{"id": doc_id, "vec": embedding_list},
)
判别小技巧：可以用 RETURN typeof(n.embedding) 检查属性类型。如果返回的不是向量类型，而是数组类型，说明我们踩了这个坑。
误区二：embedding 是 string，不是 vector 类型
第二个常见问题：向量被序列化成字符串再存进去。这在跨系统传输、JSON 序列化时特别容易发生：
# 反例：把向量 JSON 序列化成字符串存储
import json
graph.query(
"MATCH (n:entities {id: $id}) SET n.embedding = $vec",
{"id": doc_id, "vec": json.dumps(embedding_list)}, # 变成了 "[0.1, 0.2, ...]"
)
此时 n.embedding 是一个 string，内容是 "[0.1, 0.2, ...]"。
后果和误区一类似，甚至更隐蔽：
- 字符串完全无法被向量索引识别；
- 如果后续代码还需要读回向量做手工相似度计算，就得先
json.loads() 反序列化，多一层开销；
- 更糟的是，一旦一部分数据是 string、一部分是 vector，问题会很难排查。
根因通常是：数据在某个环节被 JSON 序列化（比如经过某个 API、缓存层、或错误的 ORM 映射），到了写库时忘了反序列化 + vecf32()。
正确做法是保证传入 Cypher 的是原始浮点数组，并用 vecf32() 转换：
# 正确：先确保是数组，再 vecf32()
vec = json.loads(raw) if isinstance(raw, str) else raw
graph.query(
"MATCH (n:entities {id: $id}) SET n.embedding = vecf32($vec)",
{"id": doc_id, "vec": vec},
)
怎么确认自己存对了
判断真假的关键，是看类型而不是看长相。我们可以用 Cypher 把属性的类型打出来确认：
MATCH (n:Entity {name: 'Alice'})
RETURN n.embedding, typeof(n.embedding)
如果返回的类型是 Vectorf32，说明存对了；如果是 Array（List）或 String，那就是踩了上面的坑。
这里有个很值得强调的点：普通 List 和 vector 打印出来几乎一模一样，都是 [0.1, 0.2, ...] 这种样子。所以肉眼看数据是骗不了自己的，必须看类型。很多人排查半天没头绪，就是因为一直盯着「值」看，而没去看「类型」。
三、条件二：必须在属性上创建向量索引
假设我们已经把 embedding 正确存成了 vector 类型，是不是就能查了？还不行。我们还需要为这个属性显式创建向量索引：
CREATE VECTOR INDEX FOR (n:Entity) ON (n.embedding)
OPTIONS {dimension: 4096, similarityFunction: 'cosine'}
这里有几个参数要特别注意：
dimension：必须和我们实际写入的向量维度完全一致。如果我们的模型输出是 4096 维，这里就得写 4096。维度对不上，索引要么建不成功，要么查询时匹配不上。similarityFunction：相似度函数，常见的是 cosine（余弦）或 euclidean（欧氏距离）。这个要和我们检索时的语义一致——如果 embedding 是为余弦相似度训练的，就该用 cosine。
为什么没有索引也「能查」，但等于没用
这里有个特别容易让人误判的现象：即使没建向量索引，有些写法下查询也不会直接报错，甚至能返回结果。这会让我们误以为「一切正常」。
但真相是：没有向量索引时，db.idx.vector.queryNodes 这个原生 ANN 入口根本用不了；就算我们改用别的方式（比如手动算距离再排序）勉强能查，走的也是全量线性扫描——把每个节点的向量都拿出来算一遍距离，再排序取 Top-K。
在几百个节点的玩具数据集上，这种全扫描感觉不出慢。可一旦数据涨到几十万、上百万节点，每次查询都要遍历所有向量，延迟会直接爆炸。我们本来指望的 ANN「近似最近邻、亚线性复杂度」的优势，一点都没享受到。
所以「能返回结果」和「向量检索生效」是两回事。真正生效的标志，是 db.idx.vector.queryNodes 能走索引，享受到 ANN 的加速。
四、把两个条件串起来：一个完整的正确流程
我们把整个正确的链路完整走一遍，方便对照检查：
第一步，建索引（可以先建，也可以数据写完再建）：
CREATE VECTOR INDEX FOR (n:Entity) ON (n.embedding)
OPTIONS {dimension: 4096, similarityFunction: 'cosine'}
第二步，写入数据时用 vecf32() 转成 vector 类型：
CREATE (:Entity {name: 'Alice', embedding: vecf32($vec_4096)})
第三步，用原生 API 做检索：
CALL db.idx.vector.queryNodes('Entity', 'embedding', 10, vecf32($query_vec))
YIELD node, score
RETURN node.name, score
ORDER BY score
注意查询向量本身也要用 vecf32() 包一层——查询侧和存储侧的类型必须对齐。
只要这三步都对，我们就能享受到真正的原生 ANN 检索了。
五、排查清单：当 queryNodes 不工作时
如果检索出问题，我们可以按下面这个顺序逐项排查，基本能定位到绝大多数情况：
- 查类型，别查值。 用
typeof(n.embedding) 确认属性是不是 Vectorf32。是 Array 或 String 就说明写入时没用 vecf32()，或者数据在导入时被序列化成了别的类型。
- 确认索引真的建成功了。 用
db.indexes 或对应命令列出所有索引，看目标属性上是不是真有一个 vector index。
- 核对维度。 索引声明的
dimension 必须和实际写入的向量维度一致。4096 维的向量配了个 1536 维的索引，肯定对不上。
- 核对相似度函数。 检索语义要和
similarityFunction 一致，别拿欧氏距离的索引去做余弦检索。
- 确认查询向量也转了类型。 查询侧传进去的向量也要经过
vecf32()。
这五步里，第 1 步是最高频的坑。因为普通 List、string 和 vector 打印出来长得几乎一样，只有看类型才能戳破伪装。
六、总结
FalkorDB 的原生向量检索 db.idx.vector.queryNodes 要工作，本质就是两个必要条件，缺一不可：
- 数据是真正的 vector 类型（用
vecf32() 转过），而不是长得像向量的普通 List 或 string。
- 属性上建了向量索引，且维度、相似度函数都对得上。
最容易让人栽跟头的地方，是「数据看起来没问题」这种错觉：List、string 和 vector 打印出来几乎无法区分，所以我们排查时一定要看类型、不要看值。同时也要记住，「查询能返回结果」不等于「向量索引生效」——只有走了索引的 ANN 检索，才能在大数据量下真正跑得快。
把这两个条件和这几个误区记牢，我们在 FalkorDB 上做向量检索时就能少踩很多坑。
如果觉得这篇文章对你有帮助，欢迎点赞、收藏加关注。后续持续分享更多有价值的内容。你的支持是我创作的最大动力！
