Astra DB 提供原生 JSON API，支持在存储结构化 JSON 文档的同时，为字段嵌入向量（$vector），并直接通过近似最近邻（ANN）查询实现语义搜索，无需额外向量数据库。
astra db 提供原生 json api，支持在存储结构化 json 文档的同时，为字段嵌入向量（`$vector`），并直接通过近似最近邻（ann）查询实现语义搜索，无需额外向量数据库。
在 Astra DB 中融合 JSON 数据建模与向量搜索能力，关键在于使用其 JSON API（非 CQL 或 GraphQL 接口），该接口专为开发者友好型文档操作设计，并原生支持向量嵌入的存储与 ANN 检索。虽然你当前使用 Mongoose（面向 MongoDB 的 ODM），但需注意：Astra DB 不兼容 MongoDB 协议，因此不能直接复用 Mongoose 连接或 Schema；你应改用 Astra DB 官方推荐的 HTTP/REST 方式（即 JSON API）进行交互。
✅ 正确集成方式：基于 JSON API 的向量化文档操作
所有操作均通过标准 HTTPS 请求完成，需提供以下认证头：
- X-Cassandra-Token: 应用令牌（Application Token），在 Astra 控制台生成；
- Content-Type: application/json 与 Accept: application/json。
▪ 插入带向量的 JSON 文档
向量必须以 $vector 字段名显式声明，值为浮点数数组（长度需与集合创建时指定的维度一致）：
curl -s --location \
--request POST "https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection" \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"insertOne": {
"document": {
"_id": "4",
"name": "Coded Cleats Copy",
"description": "ChatGPT integrated sneakers that talk to you",
"$vector": [0.25, 0.25, 0.25, 0.25, 0.25]
}
}
}'⚠️ 注意：vector_collection 必须是已启用向量搜索的集合（创建时需指定 vector 选项及维度，例如 {"dimension": 5}）。未配置向量支持的集合将拒绝含 $vector 的写入请求。
▪ 执行向量相似度搜索（ANN）
使用 find 命令 + sort: {"$vector": [...]} 触发近似最近邻检索，配合 options.limit 控制返回数量：
curl -s --location \
--request POST "https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection" \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"find": {
"sort": {"$vector": [0.15, 0.1, 0.1, 0.35, 0.55]},
"options": {"limit": 10}
}
}'该查询将按余弦相似度（默认）或欧氏距离（取决于集合配置）对 $vector 字段排序，返回最相似的 10 条 JSON 文档，完整保留原始字段（如 name、description 等）。
? 在 JavaScript 应用中调用建议
避免裸写 curl，推荐封装为可复用的工具函数：
// utils/astra-json-api.js
const axios = require('axios');
const ASTRA_BASE_URL = `https://${process.env.ASTRA_DB_ID}-${process.env.ASTRA_DB_REGION}.apps.astra.datastax.com`;
const TOKEN = process.env.ASTRA_DB_APPLICATION_TOKEN;
async function insertVectorDoc(collection, doc) {
const res = await axios.post(
`${ASTRA_BASE_URL}/api/json/v1/${process.env.ASTRA_DB_KEYSPACE}/${collection}`,
{ insertOne: { document: doc } },
{
headers: {
'X-Cassandra-Token': TOKEN,
'Content-Type': 'application/json',
Accept: 'application/json',
},
}
);
return res.data;
}
async function findSimilar(collection, queryVector, limit = 10) {
const res = await axios.post(
`${ASTRA_BASE_URL}/api/json/v1/${process.env.ASTRA_DB_KEYSPACE}/${collection}`,
{
find: {
sort: { $vector: queryVector },
options: { limit },
},
},
{
headers: {
'X-Cassandra-Token': TOKEN,
'Content-Type': 'application/json',
Accept: 'application/json',
},
}
);
return res.data.data?.documents || [];
}? 关键注意事项
- 向量维度必须严格匹配集合定义（如创建时设为 dimension: 384，则每次 $vector 数组长度必须为 384）；
- $vector 是保留字段名，不可用于普通索引或业务逻辑字段；
- JSON API 不支持事务、聚合管道或复杂嵌套查询，适合“文档+向量”轻量级语义检索场景；
- 如需类型安全与开发体验，可结合 TypeScript 定义文档接口，并用 Zod 验证 $vector 格式；
- 生产环境务必轮换应用令牌、限制 IP 白名单，并对敏感向量源（如用户 Embedding）做脱敏处理。
通过 JSON API，你能在 Astra DB 中真正实现「一库双模」——既享受 JSON 的灵活建模，又获得低延迟向量检索能力，为 AI 原生应用（如智能商品推荐、语义客服知识库）提供简洁可靠的后端支撑。
