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

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

ثلاثة أنواع من الخطوات تغطي دورة الحياة المُفهرَسة بالمعرِّف، جميعها عبر 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. مُرمِّز بايثون:

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 وprops مشتركة) متبوعاً بقيم 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`

التحميل الآمن للاستئناف

الضغط

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

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