إدراج البيانات في حقول StructArray

قم بإدراج البيانات في حقل StructArray عندما تحتوي كل كيان على قائمة مرتبة من العناصر المنظمة. في حمولة الإدراج، يتم تمثيل حقل StructArray كمصفوفة من الكائنات. يمثل كل كائن عنصر Struct واحدًا ويستخدم أسماء الحقول الفرعية لـ Struct المحددة في مخطط المجموعة.

تستخدم هذه الصفحة مجموعة « tech_articles » من «إنشاء حقل StructArray». كل كيان هو مقال تقني، ويخزن حقل « chunks » أجزاء المقال كعناصر Struct.

قبل البدء

تأكد من أن مخطط المجموعة يحتوي بالفعل على حقل StructArray المسمى « chunks ».

الحقل	النوع	إدراج القيمة
doc_id	INT64	معرف المقالة.
title	VARCHAR	عنوان المقالة.
category	VARCHAR	فئة المقالة.
title_vector	FLOAT_VECTOR	التضمين على مستوى المقالة.
chunks	ARRAY	قائمة بكائنات المقتطفات.

يجب أن يتبع كل كائن في " chunks " مخطط Struct.

الحقل الفرعي	النوع	قيمة الإدراج
text	VARCHAR	نص المقطع.
section	VARCHAR	اسم القسم، مثل index أو search أو filter.
page	INT64	رقم الصفحة أو الموضع المنطقي.
quality_score	FLOAT	النتيجة على مستوى الجزء.
has_code	BOOL	ما إذا كانت المقطوعة تحتوي على كود أم لا.
emb_list_vector	FLOAT_VECTOR	المتجه المكتوب للبحث في EmbeddingList.
emb	FLOAT_VECTOR	المتجه المكتوب للبحث على مستوى العنصر.

فهم شكل حمولة الإدراج

تعد قيمة chunks مصفوفة من عناصر Struct. كل عنصر هو كائن تكون مفاتيحه أسماء حقول فرعية.

{
  "doc_id": 1,
  "title": "StructArray indexing patterns",
  "category": "index",
  "title_vector": [0.12, 0.08, 0.32, 0.48],
  "chunks": [
    {
      "text": "Create one index for each vector subfield.",
      "section": "index",
      "page": 1,
      "quality_score": 0.96,
      "has_code": false,
      "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
      "emb": [0.10, 0.20, 0.30, 0.40]
    },
    {
      "text": "Use MAX_SIM metrics for EmbeddingList search.",
      "section": "index",
      "page": 2,
      "quality_score": 0.91,
      "has_code": true,
      "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
      "emb": [0.16, 0.24, 0.35, 0.45]
    }
  ]
}

emb_list_vector و emb هما حقلان فرعيان متجهان منفصلان لأنهما يدعمان أوضاع بحث مختلفة. يعامل البحث باستخدام EmbeddingList جميع المتجهات في حقل StructArray كقائمة تضمين واحدة ويعرض نتائج على مستوى الكيان باستخدام مقاييس MAX_SIM*. أما البحث على مستوى العنصر فيبحث في كل عنصر Struct بشكل مستقل ويمكنه عرض إزاحة العنصر المطابق. يخزن هذا المثال نفس قيم المتجهات في كلا الحقلين للتبسيط. في تطبيق الإنتاج، يمكنك تخزين نفس التضمينات في كلا الحقلين الفرعيين عندما يستخدم كلا وضعي البحث نفس تضمين المقطع، أو تخزين تضمينات مختلفة عندما يستخدم وضعي البحث تمثيلات مختلفة.

إدراج الصفوف

استخدم ` client.insert() ` لإدراج صفوف تحتوي على قيم StructArray.

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus",
)

data = [
    {
        "doc_id": 1,
        "title": "StructArray indexing patterns",
        "category": "index",
        "title_vector": [0.12, 0.08, 0.32, 0.48],
        "chunks": [
            {
                "text": "Create one index for each vector subfield.",
                "section": "index",
                "page": 1,
                "quality_score": 0.96,
                "has_code": False,
                "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
                "emb": [0.10, 0.20, 0.30, 0.40],
            },
            {
                "text": "Use MAX_SIM metrics for EmbeddingList search.",
                "section": "index",
                "page": 2,
                "quality_score": 0.91,
                "has_code": True,
                "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
                "emb": [0.16, 0.24, 0.35, 0.45],
            },
        ],
    },
    {
        "doc_id": 2,
        "title": "Filtered StructArray search",
        "category": "filter",
        "title_vector": [0.20, 0.18, 0.22, 0.40],
        "chunks": [
            {
                "text": "Use element_filter to match scalar conditions within the same Struct element.",
                "section": "filter",
                "page": 1,
                "quality_score": 0.93,
                "has_code": True,
                "emb_list_vector": [0.21, 0.18, 0.33, 0.44],
                "emb": [0.21, 0.18, 0.33, 0.44],
            },
            {
                "text": "MATCH_LEAST checks how many elements satisfy a predicate.",
                "section": "filter",
                "page": 2,
                "quality_score": 0.88,
                "has_code": False,
                "emb_list_vector": [0.24, 0.22, 0.31, 0.39],
                "emb": [0.24, 0.22, 0.31, 0.39],
            },
        ],
    },
    {
        "doc_id": 3,
        "title": "Element-level search with offsets",
        "category": "search",
        "title_vector": [0.33, 0.11, 0.29, 0.37],
        "chunks": [
            {
                "text": "Element-level search can return the offset of the matched Struct element.",
                "section": "search",
                "page": 1,
                "quality_score": 0.95,
                "has_code": False,
                "emb_list_vector": [0.32, 0.14, 0.28, 0.41],
                "emb": [0.32, 0.14, 0.28, 0.41],
            }
        ],
    },
]

result = client.insert(
    collection_name="tech_articles",
    data=data,
)

print(result)

الإدراج في حقول StructArray القابلة للقيمة الفارغة

إذا كان حقل ` chunks ` قابلاً للقيمة `null`، فيمكن للكيان تعيين حقل ` chunks ` بأكمله إلى `null`. في لغة Python، استخدم ` None ` لتمثيل قيمة `null`.

client.insert(
    collection_name="tech_articles",
    data=[
        {
            "doc_id": 10,
            "title": "Article without chunks yet",
            "category": "draft",
            "title_vector": [0.05, 0.10, 0.15, 0.20],
            "chunks": None,
        }
    ],
)

عندما يحتوي حقل StructArray القابل للقيمة الفارغة على قيمة StructArray صالحة، يجب أن تكون جميع الحقول الفرعية في تلك القيمة إما فارغة أو ذات قيم صالحة. يؤدي إدراج كيان مع تعيين بعض الحقول الفرعية على القيمة الفارغة وتعيين أخرى على قيم صالحة إلى حدوث خطأ.

التحقق من صحة البيانات المُدرجة

يمكنك الاستعلام عن المجموعة وإرجاع حقل StructArray أو الحقول الفرعية المحددة.

rows = client.query(
    collection_name="tech_articles",
    filter="doc_id in [1, 2, 3]",
    output_fields=[
        "doc_id",
        "title",
        "chunks[text]",
        "chunks[section]",
        "chunks[quality_score]",
    ],
)

for row in rows:
    print(row)

استخدم مسارات حقول StructArray، مثل chunks[text] ، فقط عند الاستعلام أو البحث أو التصفية أو إنشاء الفهارس. يجب أن تستمر حمولات الإدراج في استخدام الكائنات المتداخلة ضمن chunks.

قواعد الإدراج

القاعدة	الشرح
استخدم مصفوفة من الكائنات لحقل StructArray.	قيمة chunks هي قائمة، وكل عنصر في القائمة هو عنصر Struct.
استخدم أسماء الحقول الفرعية داخل كل عنصر من عناصر Struct.	أدخل {"text": "...", "emb": [...]} داخل chunks ، وليس {"chunks[text]": "..."}.
تأكد من مطابقة مخطط Struct.	يجب أن يستخدم كل عنصر من عناصر Struct الحقول الفرعية المحددة في مخطط Struct.
تطابق أبعاد المتجه.	يجب أن تتطابق قيم المتجهات مع dim المُعدة لحقولها الفرعية المتجهة.
يجب مراعاة " max_capacity".	يجب ألا يتجاوز عدد عناصر Struct في كيان واحد الحد الأقصى المسموح به ( max_capacity ) لحقل StructArray.
استخدم حقول فرعية متجهة منفصلة لأوضاع البحث المنفصلة.	إذا كان كل من البحث في EmbeddingList والبحث على مستوى العنصر مطلوبين، فاكتب قيم المتجهات في كل من الحقول الفرعية للمتجهات.
استخدم null فقط عندما يكون الحقل قابلاً للقيمة الفارغة.	تتطلب حقول StructArray غير القابلة للقيمة الفارغة قيم StructArray صالحة.

الأخطاء الشائعة

• استخدام مسارات الحقول مثل chunks[text] في حمولات الإدراج.

• إغفال الحقول الفرعية المطلوبة من عنصر Struct.

• إدراج متجهات ذات أبعاد خاطئة.

• إدراج عناصر Struct أكثر مما يسمح به max_capacity.

• تعيين حقل فرعي واحد فقط إلى null بينما تكون الحقول الفرعية الأخرى في نفس قيمة StructArray صالحة.

• كتابة المتجهات إلى emb_list_vector فقط ثم محاولة إجراء بحث على مستوى العناصر في chunks[emb].

• كتابة المتجهات إلى emb فقط ثم محاولة إجراء بحث EmbeddingList على chunks[emb_list_vector].

الخطوات التالية

1. لإنشاء فهارس لـ chunks[emb_list_vector] و chunks[emb] والحقول الفرعية القياسية، اقرأ «فهرسة حقول StructArray».

2. للبحث في الحقول الفرعية المتجهة لـ StructArray، اقرأ " البحث المتجه الأساسي باستخدام StructArray".

3. لمراجعة سلوك القيم الفارغة والقيود الخاصة بالإصدارات، اقرأ " حدود StructArray".