ScyllaDB是用C++重写的Cassandra兼容NoSQL数据库，凭借共享皆无架构和对硬件的深度优化，在写入吞吐和延迟控制上表现突出。从5.2版本开始，ScyllaDB原生支持向量数据类型，并提供了基于SAI的向量索引能力，这让它在AI语义检索、RAG知识库、推荐召回等场景中成为Milvus、Qdrant之外的一个务实选择。对于Node.js技术栈的团队来说，由于ScyllaDB兼容CQL协议，可以直接使用cassandra-driver连接操作，向量数据的写入和相似度检索都可以通过CQL语句完成，整体接入成本并不高。本文将从驱动接入、表结构设计、向量写入编码和相似度检索几个方面，完整讲解Node.js环境下ScyllaDB向量方案的落地过程。
一、Node.js连接ScyllaDB：驱动选择与分片感知路由
ScyllaDB兼容CQL二进制协议，因此Node.js生态中成熟的cassandra-driver可以直接使用。需要注意的是，向量类型是ScyllaDB在CQL层面的扩展，旧版本驱动遇到vector类型可能无法正确序列化，建议使用cassandra-driver 4.6.4以上版本，或者选用Scylla官方维护的scylla-driver分支，后者针对ScyllaDB的分片感知路由做了专门优化。
安装依赖非常简单，通过npm执行一条命令即可：
npm install cassandra-driver
连接时建议显式指定localDataCenter。ScyllaDB默认的数据中心名称是datacenter1，如果配置不一致，驱动会退化为随机连接节点，失去分片感知带来的低延迟优势：
const cassandra = require('cassandra-driver');
const client = new cassandra.Client({
contactPoints: ['192.168.0.1:9042', '192.168.0.2:9042'],
localDataCenter: 'datacenter1',
keyspace: 'vector_demo'
});
client.connect()
.then(() => console.log('已成功连接 ScyllaDB 集群'))
.catch(err => console.error('连接失败:', err));
除了连接配置，驱动还支持请求级负载均衡策略。ScyllaDB将每个节点的CPU核心划分为独立分片，令牌感知的驱动会把请求直接路由到持有对应数据的目标节点，避免集群内部的二次转发。在写入向量这类较大载荷的数据时，合理利用prepared statement还能减少每次请求的序列化开销，对高并发场景的提升相当明显。
二、设计向量表：CQL语法与维度约束
ScyllaDB在CQL中扩展了vector数据类型，声明方式是指定元素类型和固定维度，例如VECTOR<FLOAT, 4>表示一个4维浮点向量。这里的维度必须和所使用的embedding模型输出保持一致，比如OpenAI的text-embedding-3-small输出1536维，建表时就要写成1536，写入维度不匹配的数据会直接报错。
创建keyspace和向量表的完整语句如下：
CREATE KEYSPACE IF NOT EXISTS vector_demo
WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 1};
CREATE TABLE IF NOT EXISTS vector_demo.documents (
id UUID PRIMARY KEY,
content TEXT,
embedding VECTOR<FLOAT, 4>
);
在Cassandra中原生并不存在这种向量类型，这属于ScyllaDB的扩展语法。如果你的表需要同时被Cassandra集群读取，向量列就无法兼容，这一点在混合架构中要提前评估。此外，向量维度在建表后无法修改，更换embedding模型导致维度变化时，只能新建表并迁移数据，因此设计阶段要慎重确定维度。
向量字段本身不能作为主键，也不能建传统的二级索引用于精确匹配，它主要配合SAI存储附加索引实现相似度检索。可以在业务字段上建立普通索引，实现标量过滤与向量检索的组合查询，这在推荐场景中非常常见。
三、向量数据的写入与编码处理
cassandra-driver对vector类型的支持依赖于版本。在较新版本中可以直接传入JavaScript数组，驱动会自动完成序列化；如果版本较旧不支持，可以手动将向量编码为Buffer，按每个float占4字节的规则逐个写入。
下面是一段完整的向量写入示例：
const cassandra = require('cassandra-driver');
const client = require('./db-client'); // 复用前面创建的连接
async function insertDocument(content, embedding) {
const query = 'INSERT INTO documents (id, content, embedding) VALUES (?, ?, ?)';
const params = [cassandra.types.Uuid.random(), content, embedding];
await client.execute(query, params, { prepare: true });
}
(async () => {
await insertDocument('ScyllaDB 是兼容 Cassandra 的高性能数据库', [0.1, 0.2, 0.3, 0.4]);
await insertDocument('Node.js 是基于 V8 的 JavaScript 运行时', [0.5, 0.6, 0.7, 0.8]);
await insertDocument('向量检索用于语义搜索场景', [0.1, 0.25, 0.3, 0.42]);
console.log('向量数据写入完成');
})();
实际业务中，向量通常由embedding服务生成，比如调用OpenAI接口把文本转为1536维向量后再写入。这个流程建议做成异步任务队列，避免embedding接口的限流影响主业务写入。同时批量写入可以使用驱动提供的batch功能，一次提交多条记录，减少网络往返开销。
需要注意的一点是，向量列占用的存储与维度成正比，1536维float32的向量单条就超过6KB，大量存储时要评估磁盘和内存成本，必要时可以考虑量化压缩或者选择输出维度更小的模型。
四、实现余弦相似度检索与ANN索引
向量检索的核心是相似度计算，ScyllaDB支持欧氏距离和余弦相似度两种度量方式。要获得高性能的近似最近邻检索能力，需要在向量列上创建SAI向量索引：
CREATE CUSTOM INDEX IF NOT EXISTS documents_embedding_idx ON vector_demo.documents(embedding) USING 'scylla_sai';
创建索引后，就可以使用ScyllaDB扩展的CQL语法执行相似度检索。下面这段Node.js代码演示了如何查询与给定向量最相似的3条记录：
async function searchSimilar(queryVector, topK = 3) {
const query = `
SELECT id, content, embedding
FROM documents
ORDER BY embedding ANN OF ? LIMIT ?`;
const params = [queryVector, topK];
const result = await client.execute(query, params, { prepare: true });
return result.rows.map(row => ({
id: row.id.toString(),
content: row.content
}));
}
(async () => {
const hits = await searchSimilar([0.1, 0.2, 0.3, 0.4], 3);
hits.forEach(h => console.log(h.id, h.content));
})();
其中ORDER BY embedding ANN OF ?是ScyllaDB特有的语法，表示按向量列与查询向量的近似最近邻排序，配合LIMIT即可实现TopK召回。如果没有创建向量索引，这条语句会退化为全表扫描并逐一计算距离，数据量大时性能会急剧下降，因此生产环境务必先建好SAI索引。
关于精度与性能的权衡也要了解。ScyllaDB的ANN索引基于内存量化技术，属于近似检索，召回率无法达到百分之百，但延迟稳定且可控。对召回率要求极高的场景，可以通过增大索引构建时的候选集参数来提升精度，代价是占用更多内存。建议在上线前用真实数据做一轮召回率评测，找到适合业务的平衡点。
五、与Elasticsearch、Milvus的方案对比
在向量检索领域，Elasticsearch的dense_vector字段和Milvus的专用索引都是常见方案。Elasticsearch的优势在于标量过滤和全文检索能力强，适合搜索场景中关键词与向量混合召回的需求；Milvus则是专为向量设计的数据库，索引类型丰富，超大规模数据下的性能表现更好。
ScyllaDB方案的独特价值在于Cassandra兼容性。如果团队已有基于Cassandra的数据管道和运维体系，向量数据可以和业务数据存放在同一集群，避免多套系统之间的数据同步问题，架构复杂度显著降低。同时ScyllaDB本身的高写入吞吐特性，让embedding批量更新这类高频写入场景也能从容应对。
从成本角度看，ScyllaDB可以部署在普通SSD服务器上，对内存的要求相对宽松，而Milvus等方案通常依赖较大的内存资源。综合来说，对于已有Cassandra技术栈、向量规模在千万到亿级之间、希望快速落地语义检索的团队，Node.js加ScyllaDB的组合是一条值得认真评估的路线。落地过程中重点关注的细节包括：驱动版本对vector类型的支持、localDataCenter配置的正确性、向量维度与embedding模型的一致性，以及SAI索引创建后的内存占用监控。把这些环节处理好，这套方案完全可以支撑生产级的语义搜索服务。