写入文档 - Conare

POST /namespaces/:namespace/documents 将文档写入命名空间：Conare 会对其进行分块、嵌入和索引，首次写入时会创建该命名空间。

curl https://api.conare.ai/namespaces/docs/documents \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "id": "refunds", "text": "Refunds are available for 30 days.", "metadata": { "team": "support" } },
      { "id": "shipping", "text": "Orders ship within two days.", "metadata": { "team": "ops" } }
    ]
  }'

await docs.write([
  { id: "refunds", text: "Refunds are available for 30 days.", metadata: { team: "support" } },
  { id: "shipping", text: "Orders ship within two days.", metadata: { team: "ops" } },
]);

Response

{
  "ids": ["refunds", "shipping"],
  "results": [
    { "id": "refunds", "result": "created", "version": 1, "chunks": 1, "chunks_embedded": 1 },
    { "id": "shipping", "result": "created", "version": 1, "chunks": 1, "chunks_embedded": 1 }
  ],
  "versions": [1, 1]
}

选项

选项	类型	作用
`documents`	array，必填	1-100 个文档
`id`	string	最多 256 个 `A-Z a-z 0-9 . _ : -` 字符；省略时自动生成。写入已有 id 会替换该文档
`text`	string，必填	在请求 32 MiB 的正文内长度不限；长文本仍是一个文档
`metadata`	object	用于过滤的值（规则）
`user`	string	文档所属的用户（用户）
`seq`	integer	你自己的版本号，0 到 2^53；`seq` 低于已存储值的写入会被跳过
`if_version`	integer	仅当已存储的 `version` 匹配时才写入；`0` 表示仅写入新文档

完整 schema：添加文档。

响应

字段	含义
`ids`, `versions`	每个文档的 id 和版本，按请求顺序排列
`results[].result`	`created`、`updated`、`unchanged`（文本、元数据和用户均相同）或 `stale`（已存储更高的 `seq`）
`results[].chunks`	文档包含的段落数
`results[].chunks_embedded`	本次写入嵌入的段落数；未变更的段落不会重新嵌入
`results[].stored_seq`	结果为 `stale` 时，已存储的 `seq`

if_version 不匹配时返回 409 version_conflict。

元数据

{ "team": "support", "year": 2025, "public": true, "tags": ["billing", "refunds"] }

规则	限制
值	字符串、数字、布尔值或字符串数组
键	最多 32 个，每个为 1-64 个 `A-Z a-z 0-9 _ . -` 字符，以字母开头
保留键	`id`、`text`、`vector`、`ttl_at_ms`
单个字符串	最多 4 KiB
单个数组	最多 256 个字符串
每个文档的不同值数量	总计 256：数字或不超过 222 字节的字符串计为两个；数组元素、布尔值或更长的字符串计为一个；`user` 计为一个，每个 `:` 再加一个

用户

当一个命名空间存放多个用户的文档时，请设置 user，然后使用 user 或 user_prefix 进行搜索。

规则
格式	最多 128 个 `A-Z a-z 0-9 . _ : @ -` 字符，以字母或数字开头，最多 8 个 `:`
分组	写入 `tenant-7:u_42`，搜索 `user_prefix: "tenant-7:"` 即可覆盖整个租户
过滤条件	过滤条件无法匹配 `user`；请使用 `user` 和 `user_prefix`

吞吐量

嵌入繁忙时，写入会等待并返回 Conare-Degraded: embed-busy：请减少并发写入。
约 30 秒后，会返回 503 及 Retry-After。
失败的请求可能已写入部分文档：请使用相同的 Idempotency-Key 重试。