문서 쓰기 - 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 안에서 길이 제한 없음. 긴 텍스트도 문서 하나입니다
`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개를 더합니다

사용자

네임스페이스 하나에 여러 사용자의 문서를 담을 때 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로 재시도하세요.