ドキュメントを書き込む - 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	`A-Z a-z 0-9 . _ : -` からなる最大 256 文字。省略すると生成されます。既存の ID に書き込むと置換されます
`text`	string、必須	リクエストの 32 MiB の本文に収まれば長さは自由です。長いテキストも 1 つのドキュメントです
`metadata`	object	フィルターに使う値(ルール)
`user`	string	ドキュメントの所有者(ユーザー)
`seq`	integer	独自のバージョン番号(0〜2^53)。保存済みより小さい `seq` はスキップされます
`if_version`	integer	保存済みの `version` と一致する場合のみ書き込みます。`0` は新規ドキュメントのみ書き込みます

完全なスキーマ: ドキュメントを追加する。

レスポンス

フィールド	意味
`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 個。各キーは `A-Z a-z 0-9 _ . -` からなる 1〜64 文字で、英字で始まります
予約済みキー	`id`、`text`、`vector`、`ttl_at_ms`
文字列	最大 4 KiB
配列	最大 256 個の文字列
ドキュメントあたりの異なる値	合計 256。数値または 222 バイト以下の文字列は 2 として数え、配列の要素、ブール値、それより長い文字列は 1 として数えます。`user` は 1 に加えて `:` ごとに 1 です

ユーザー

1 つのネームスペースに多数のユーザーのドキュメントを保持する場合は user を設定し、user または user_prefix で検索します。

ルール
形式	`A-Z a-z 0-9 . _ : @ -` からなる最大 128 文字。英字または数字で始まり、`:` は最大 8 個
グループ	`tenant-7:u_42` と書き込み、`user_prefix: "tenant-7:"` で検索するとテナント全体が対象になります
フィルター	フィルターは `user` に一致できません。`user` と `user_prefix` を使ってください

スループット

埋め込みが混雑しているとき、書き込みは待機して Conare-Degraded: embed-busy を返します。同時に送る書き込みを減らしてください。
約 30 秒後には Retry-After 付きで 503 を返します。
失敗したリクエストでも一部のドキュメントが書き込まれている場合があります。同じ Idempotency-Key で再試行してください。