الكتابات والاستيعاب المجمّع

دورة حياة الصف

ثلاث خطوات تغطي دورة الحياة المُفتاحة بالمُعرّف، وكلها عبر POST /v1/namespaces/{ns}/query:

{"UpsertN": {"id": "chunk-123", "label": "chunk", "props": {"text": "..."}, "vector": [0.1]}}
{"SetProps": {"props": {"project": "v2", "stale_key": null}}}
{"DeleteN": {"ids": ["chunk-123"]}}

UpsertN — استبدال كامل للصف مُفتاحه id الخارجي. تُحذف الصفوف الموجودة بذلك المُعرّف، ثم يُدرج الصف الجديد. استبدال، لا دمج: عملية upsert بدون متجه لصف يحمل متجهاً تُسقط المتجه.
SetProps — الكتابة فوق مفاتيح محددة على تدفق مطابق (ابدأ الاستعلام بـ NWhere)؛ قيمة null تُزيل المفتاح. لا يمكن تغيير id نفسه — يتطلب ذلك UpsertN. مناسب لإعادة كتابات السمات العرضية، غير مناسب لعدّادات لكل استعلام.
DeleteN — حذف تدفق مطابق (NWhere → DeleteN)، أو مرِّر ids لحذف مباشر عبر المُعرّفات الخارجية.

تشفيرات المتجهات

لكل صف، أحد تشفيرين على السلك (إرسال كليهما يُنتج 400):

{"vector": [0.0123, -0.0456]}
{"vector_b64": "zcxMPZqZmb4K16M8..."}

vector_b64 هو base64 للمتجه كمصفوفة f32 بترتيب little-endian — أصغر بحوالي 4× على السلك ويُفكّ باستخدام memcpy بدلاً من تحليل أعداد JSON. مُشفِّر Python:

base64.b64encode(np.asarray(vec, dtype="<f4").tobytes()).decode("ascii")

يُنتج كلا التشفيرين متجهات مخزنة متطابقة بت-بت ونتائج بحث متطابقة. البُعد ثابت من أول عملية كتابة تحمل متجهاً؛ عدم التطابق يُنتج 400.

الاستيعاب المجمّع: `POST /v1/namespaces/{ns}/bulk-vectors`

مسار البذر عالي الإنتاجية — إطار ثنائي واحد لكل طلب (Content-Type: application/octet-stream): ترويسة JSON صغيرة (dims, label, ids, خصائص مشتركة) يليها قيم fp16 موحّدة L2 بترتيب رئيسي حسب الصف. مقارنة بـ JSON+base64، يتجنب هذا إعادة تشفير حمولات بحجم عدة جيجابايت عدة مرات.

تحميل آمن عند إعادة التشغيل

تمرر المحمّلات القابلة للاستئناف ?expected_generation=<G>&expected_rows=<N>. يُقبل الإطار فقط عندما تكون مساحة الأسماء بالضبط في تلك الحالة:

تم بالفعل تثبيت الإطار نفسه → 200 مع "replayed": true وrequest_fingerprint المطابق — لا صفوف مكررة.
حمولة مختلفة في الموضع نفسه → 409 write_conflict.
تُعيد الكتابات الشرطية الناجحة request_fingerprint, rows_before, rows_after — سجّل نقطة تحقق دفعتك فقط بعد استلام أحد هذه الإيصالات.

هذا يجعل “تعطُّل، إعادة تشغيل، إعادة إرسال” هي قصة الاستئناف بأكملها: لا مهام استيراد لمتابعتها.

الدمج

الدمج التلقائي هندسي، لذا يظل إجمالي عمل الدمج خطياً بالنسبة للبايتات المُستوعبة. أنهِ أي تحميل مجمّع بدمج صريح — أرسل "compact": true على المستوى الأعلى من آخر طلب كتابة:

{"request_type": "write", "compact": true, "query": {"...": "..."}}

تُبلّغ الاستجابة عن "compacted": true/false. يبني الدمج أيضاً فهرس ANN بمجرد أن يصبح الجدول كبيراً بما فيه الكفاية؛ الصفوف المكتوبة بعد لقطة الفهرس تُدمج في النتائج بالقوة الغاشمة، لذا لا يُضحَّى بالحداثة أبداً.

إزالة تكرار مصدر مجمّع

تُضاف الإطارات المجمّعة بشكل أعمى بحكم التصميم — مصدر يحمل مُعرّفات مكررة يُنزلها بصمت، والتكرارات تحرق فتحات top-k. {"DedupN": {}} يوفّق مخزناً مع عقد تفرد المُعرّف الخارجي (يحتفظ بآخر صف مكتوب لكل مُعرّف)، و{"DedupN": {"dry_run": true}} هو تدقيق تعدادي فقط يجب على أي تحميل مجمّع تشغيله عندما لا يستطيع مصدره إثبات تفرد المُعرّف — إجمالي عدد صفوف مطابق لا يمكن أن يكشف التكرارات المختبئة داخله.

قواعد إعادة المحاولة

يمكن دائماً إعادة محاولة القراءات بعد فشل النقل. بالنسبة للكتابات، فقط الإطارات المجمّعة الشرطية قابلة لإعادة المحاولة تلقائياً (إطار متطابق + معاملات CAS → الإيصال الأصلي أو replayed: true). لا تُعِد أبداً كتابة غير مشروطة بشكل أعمى بعد فقدان الاستجابة — وفّق الحالة أولاً.

البدء

المرجع

الأدلة

الكتابات والاستيعاب المجمّع

دورة حياة الصف

تشفيرات المتجهات

الاستيعاب المجمّع: `POST /v1/namespaces/{ns}/bulk-vectors`

تحميل آمن عند إعادة التشغيل

الدمج

إزالة تكرار مصدر مجمّع

قواعد إعادة المحاولة

​دورة حياة الصف

​تشفيرات المتجهات

​الاستيعاب المجمّع: POST /v1/namespaces/{ns}/bulk-vectors

​تحميل آمن عند إعادة التشغيل

​الدمج

​إزالة تكرار مصدر مجمّع

​قواعد إعادة المحاولة

دورة حياة الصف

تشفيرات المتجهات

الاستيعاب المجمّع: `POST /v1/namespaces/{ns}/bulk-vectors`

تحميل آمن عند إعادة التشغيل

الدمج

إزالة تكرار مصدر مجمّع

قواعد إعادة المحاولة