本文介绍如何利用 Astra DB 的 JSON API，在 JavaScript 应用中无缝融合结构化 JSON 数据与向量相似性搜索，支持 Mongoose 集成场景，无需切换数据库或手动管理嵌入向量。
本文介绍如何利用 astra db 的 json api，在 javascript 应用中 seamlessly 融合结构化 json 数据与向量相似性搜索，支持 mongoose 集成场景，无需切换数据库或手动管理嵌入向量。
Astra DB 提供原生支持 JSON 文档模型的 JSON API（非 CQL 或 GraphQL），专为开发者设计，尤其适合希望以 RESTful 方式操作半结构化数据并启用向量搜索的应用场景。该 API 允许你在同一文档中同时存储常规字段（如 name、description）和向量嵌入（通过 $vector 字段），并在查询时直接执行近似最近邻（ANN）搜索——所有操作均通过标准 HTTP 请求完成，天然兼容 Node.js、Express 和 Mongoose 等生态工具。
✅ 核心能力一览
- 单文档支持混合结构：普通 JSON 字段 + $vector 数组（长度需固定，如 512 维）
- 插入/更新时自动索引向量（无需额外建表或配置）
- 查询时通过 sort: { "$vector": [x1, x2, ...] } 触发 ANN 检索
- 返回结果按余弦相似度（默认）或欧氏距离自动排序
? 示例：插入带向量的 JSON 文档
以下 curl 命令演示如何向名为 vector_collection 的集合插入一条含语义嵌入的商品记录：
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 必须是浮点数数组，且所有文档维度必须一致；建议在应用层统一调用嵌入模型（如 OpenAI text-embedding-3-small）生成后写入。
? 示例：基于向量的语义检索
要查找与给定查询向量最相似的前 100 条记录，只需将目标向量传入 sort.$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 '{
"find": {
"sort": {"$vector": [0.15, 0.1, 0.1, 0.35, 0.55]},
"options": {"limit": 100}
}
}'响应体将包含按相似度降序排列的完整 JSON 文档（含 _id, name, description 等原始字段），可直接映射至 Mongoose Schema 或前端状态。
⚙️ 在 Mongoose 应用中集成提示
虽然 Mongoose 原生不支持 Astra DB 的 JSON API，但你可通过封装 HTTP 客户端（如 axios）实现轻量适配：
// utils/astraClient.ts
import axios from 'axios';
const astra = axios.create({
baseURL: `https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1`,
headers: {
'X-Cassandra-Token': ASTRA_DB_APPLICATION_TOKEN,
'Content-Type': 'application/json',
},
});
export const insertVectorDoc = (db: string, collection: string, doc: any) =>
astra.post(`/${db}/${collection}`, {
insertOne: { document: doc }
});
export const findSimilar = (db: string, collection: string, queryVector: number[], limit = 10) =>
astra.post(`/${db}/${collection}`, {
find: {
sort: { $vector: queryVector },
options: { limit }
}
});然后在业务逻辑中调用：
await insertVectorDoc('purchase_database', 'vector_collection', {
_id: 'prod_101',
name: 'Smart Jacket',
description: 'Heated jacket with real-time weather translation',
$vector: await getEmbedding('Heated jacket with real-time weather translation')
});
const results = await findSimilar('purchase_database', 'vector_collection', [0.12, 0.88, 0.05, 0.91, 0.44]);✅ 总结
Astra DB 的 JSON API 是连接 JSON 灵活性与向量搜索能力的理想桥梁：它消除了传统向量数据库对 schema 强约束的依赖，又避免了在关系型或文档数据库上自行构建 ANN 索引的复杂性。对于使用 Mongoose 构建的 JavaScript 应用，只需引入标准 HTTP 客户端即可快速启用语义搜索能力——无需改造数据模型，不增加运维负担，真正实现“开箱即搜”。详细配置与限制请参考 官方 JSON API 文档。
