كتابة المستندات - 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 . _ : -`؛ يُولَّد إذا لم يُحدَّد. كتابة معرّف موجود تستبدله
`text`	string، مطلوب	أي طول ضمن جسم الطلب البالغ 32 MiB؛ ويبقى النص الطويل مستندًا واحدًا
`metadata`	object	قيم للتصفية بها (القواعد)
`user`	string	المستخدم الذي ينتمي إليه المستند (المستخدمون)
`seq`	integer	رقم الإصدار الخاص بك، من 0 إلى 2^53؛ يُتخطّى `seq` الأقل من المخزَّن
`if_version`	integer	الكتابة فقط إذا طابق `version` المخزَّن؛ `0` يكتب مستندًا جديدًا فقط

المخطط الكامل: إضافة المستندات.

الاستجابة

الحقل	المعنى
`ids`، `versions`	معرّف كل مستند وإصداره، بترتيب الطلب
`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 نفسه.