إنشاء حقل StructArray

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

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

قبل البدء

تستخدم هذه الصفحة مجموعة باسم « tech_articles ». يمثل كل كيان مقالًا تقنيًا واحدًا، ويخزن حقل « chunks » البيانات على مستوى المجموعات كعناصر Struct.

الحقل	النوع	الغرض
doc_id	INT64	المفتاح الأساسي للمقالة.
title	VARCHAR	عنوان المقالة.
category	VARCHAR	فئة على مستوى المقالة.
title_vector	FLOAT_VECTOR	حقل متجه على مستوى المقالة، يُستخدم لاحقًا في أمثلة البحث المختلط.
chunks	ARRAY	حقل StructArray الذي يخزن النص على مستوى المقطع، والبيانات الوصفية، والتضمينات.

يحتوي حقل StructArray الخاص بـ « chunks » على الحقول الفرعية التالية.

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

أنواع بيانات الحقول الفرعية المدعومة

يخزن حقل StructArray قيمة مصفوفة واحدة لكل حقل فرعي من نوع Struct. عند تعريف مخطط Struct، اختر أنواع الحقول الفرعية من مجموعات القيم القياسية والمتجهة المدعومة.

النوع الفعلي للحقول الفرعية لـ Struct	الدعم	ملاحظات
Array	مدعوم	حدد الحقل الفرعي على النحو التالي: DataType.BOOL.
Array	مدعوم	حدد الحقل الفرعي على أنه DataType.INT8 أو DataType.INT16 أو DataType.INT32 أو DataType.INT64.
Array	مدعوم	حدد الحقل الفرعي على أنه DataType.FLOAT أو DataType.DOUBLE.
Array	مدعوم	حدد الحقل الفرعي على أنه DataType.VARCHAR وقم بتعيين max_length.
ArrayOfVector	مدعوم	حدد الحقل الفرعي على أنه DataType.FLOAT_VECTOR وقم بتعيين dim.
ArrayOfVector	مدعوم	حدد الحقل الفرعي على أنه DataType.FLOAT16_VECTOR وقم بتعيين dim.
ArrayOfVector	مدعوم	حدد الحقل الفرعي على أنه DataType.BFLOAT16_VECTOR وقم بتعيين dim.
ArrayOfVector	مدعوم	حدد الحقل الفرعي على أنه DataType.INT8_VECTOR وقم بتعيين dim.
ArrayOfVector	مدعوم	حدد الحقل الفرعي على أنه DataType.BINARY_VECTOR وقم بتعيين dim.
ArrayOfVector	غير مدعوم	لا يتم دعم الحقول الفرعية للمتجهات المتفرقة في حقول StructArray.
Array	غير مدعوم	استخدم VARCHAR ، وليس String.
Array	غير مدعوم	الحقول الفرعية JSON غير مدعومة في حقول StructArray.
Array	غير مدعوم	الحقول الفرعية للهندسة ووظائف نظم المعلومات الجغرافية (GIS) غير مدعومة في حقول StructArray.
Array	غير مدعوم	الحقول الفرعية النصية غير مدعومة في حقول StructArray.
Array	غير مدعوم	الحقول الفرعية من نوع Timestamptz والتعبيرات المرتبطة بوقت محدد غير مدعومة في حقول StructArray.
Array أو ArrayOfVector أو Struct أو ArrayOfStruct	غير مدعوم	لا يمكن أن يحتوي حقل StructArray على مصفوفات متداخلة، أو مصفوفات متجهة متداخلة، أو حقول Struct متداخلة، أو حقول Array-of-Struct متداخلة.

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

إنشاء مجموعة تحتوي على حقل StructArray

لإنشاء حقل StructArray، قم أولاً بتعريف مخطط Struct الذي يستخدمه كل عنصر. ثم أضف حقل Array وقم بتعيين نوع العنصر الخاص به إلى Struct.

1. قم بإنشاء مخطط المجموعة.

2. أضف حقول على مستوى المجموعة، مثل المفتاح الأساسي والحقول على مستوى المقالة.

3. قم بإنشاء مخطط Struct للعناصر المخزنة داخل حقل StructArray.

4. أضف حقول فرعية قياسية ومتجهة إلى مخطط Struct.

5. أضف حقل Array باستخدام " element_type=DataType.STRUCT".

6. تعيين " struct_schema " إلى مخطط Struct.

7. قم بتعيين " max_capacity " لتحديد عدد عناصر Struct التي يمكن لكل كيان تخزينها في الحقل.

from pymilvus import MilvusClient, DataType

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

schema = client.create_schema(
    auto_id=False,
    enable_dynamic_field=False,
)

# Collection-level fields.
schema.add_field(
    field_name="doc_id",
    datatype=DataType.INT64,
    is_primary=True,
)
schema.add_field(
    field_name="title",
    datatype=DataType.VARCHAR,
    max_length=512,
)
schema.add_field(
    field_name="category",
    datatype=DataType.VARCHAR,
    max_length=128,
)
schema.add_field(
    field_name="title_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Struct schema used by each element in the StructArray field.
chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=65535,
)
chunk_schema.add_field(
    field_name="section",
    datatype=DataType.VARCHAR,
    max_length=128,
)
chunk_schema.add_field(
    field_name="page",
    datatype=DataType.INT64,
)
chunk_schema.add_field(
    field_name="quality_score",
    datatype=DataType.FLOAT,
)
chunk_schema.add_field(
    field_name="has_code",
    datatype=DataType.BOOL,
)

# Vector subfield for EmbeddingList search.
chunk_schema.add_field(
    field_name="emb_list_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Vector subfield for element-level search.
chunk_schema.add_field(
    field_name="emb",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Add the StructArray field.
schema.add_field(
    field_name="chunks",
    datatype=DataType.ARRAY,
    element_type=DataType.STRUCT,
    struct_schema=chunk_schema,
    max_capacity=1000,
)

client.create_collection(
    collection_name="tech_articles",
    schema=schema,
)

فهم مسارات حقل StructArray

بعد إنشاء حقل StructArray، قم بالإشارة إلى حقوله الفرعية باستخدام صيغة مسار structArray[subfield]. استخدم هذه الصيغة عند إنشاء الفهارس، أو البحث في الحقول الفرعية المتجهة، أو إخراج الحقول الفرعية، أو إنشاء عوامل تصفية سكالارية.

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

جعل حقل StructArray قابلاً للقيمة الفارغة

يدعم Milvus v3.0.x حقول StructArray القابلة للقيمة الفارغة. يسمح حقل StructArray القابل للقيمة الفارغة للكيان بتخزين null لحقل StructArray بأكمله.

schema.add_field(
    field_name="chunks",
    datatype=DataType.ARRAY,
    element_type=DataType.STRUCT,
    struct_schema=chunk_schema,
    max_capacity=1000,
    nullable=True,
)

إضافة حقل StructArray إلى مجموعة موجودة

يدعم Milvus v3.0.x إضافة حقل StructArray إلى مجموعة موجودة. يجب أن يكون حقل StructArray المضاف قابلاً للقيمة null، لأن الكيانات الموجودة بالفعل في المجموعة لا تحتوي على قيم للحقل الجديد.

لإضافة حقل StructArray إلى مجموعة موجودة، قم أولاً بتعريف مخطط Struct. ثم استدعِ add_collection_struct_field() وقم بتعيين nullable=True.

chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=65535,
)
chunk_schema.add_field(
    field_name="section",
    datatype=DataType.VARCHAR,
    max_length=128,
)
chunk_schema.add_field(
    field_name="page",
    datatype=DataType.INT64,
)
chunk_schema.add_field(
    field_name="quality_score",
    datatype=DataType.FLOAT,
)
chunk_schema.add_field(
    field_name="has_code",
    datatype=DataType.BOOL,
)
chunk_schema.add_field(
    field_name="emb_list_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)
chunk_schema.add_field(
    field_name="emb",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

client.add_collection_struct_field(
    collection_name="tech_articles",
    field_name="chunks",
    struct_schema=chunk_schema,
    max_capacity=1000,
    nullable=True,
)

بعد إضافة حقل StructArray، تُرجع الكيانات الموجودة القيمة null للحقل الجديد عبر جميع حقوله الفرعية.

بعد إنشاء حقل StructArray، لا يمكنك إضافة حقول فرعية جديدة إلى حقل StructArray الموجود. إذا احتجت إلى سمات عناصر إضافية لاحقًا، فاستدعِ drop_collection_field() لإسقاط حقل StructArray، ثم أضف حقل StructArray جديدًا باستخدام مخطط Struct المحدث.

client.drop_collection_field(
    collection_name="tech_articles",
    field_name="chunks",
)

client.add_collection_struct_field(
    collection_name="tech_articles",
    field_name="chunks",
    struct_schema=updated_chunk_schema,
    max_capacity=1000,
    nullable=True,
)

قواعد المخطط

القاعدة	التفسير
يُستخدم Struct كنوع عنصر Array.	قم بإنشاء حقل StructArray كحقل Array باستخدام element_type=STRUCT. لا تقم بإنشاء Struct كحقل تجميع من المستوى الأعلى.
تشترك جميع العناصر في مخطط واحد.	يتبع كل عنصر Struct في حقل StructArray نفسه مخطط Struct المحدد لذلك الحقل.
max_capacity مطلوب.	وهو يحدد عدد عناصر Struct التي يمكن لكل كيان تخزينها في حقل StructArray.
يُسمح فقط بأنواع الحقول الفرعية المدعومة.	استخدم أنواع الحقول الفرعية القياسية والمتجهة التي يدعمها StructArray. لا تقم بتعريف الحقول الفرعية من أنواع JSON أو Geometry أو Text أو Timestamptz أو SparseFloatVector أو الحقول الفرعية المتداخلة من نوع Struct / Array.
تحتاج الحقول الفرعية المتجهة إلى فهارس قبل البحث.	قم بإنشاء فهارس على مسارات مثل chunks[emb_list_vector] أو chunks[emb] قبل تشغيل البحث المتجهي.
يحتوي كل حقل فرعي متجه على فهرس واحد.	إذا كنت بحاجة إلى كل من البحث في EmbeddingList والبحث على مستوى العناصر، فأنشئ حقلين فرعيين متجهين منفصلين.
الحقول الفرعية StructArray الموجودة ثابتة.	بعد إنشاء حقل StructArray، لا تتوقع إضافة المزيد من الحقول الفرعية إلى نفس حقل StructArray هذا.
لا يتم دعم الدوال داخل Struct.	لا تقم بتعريف وظائف للحقول أو الحقول الفرعية داخل حقل StructArray.
يجب أن تتوافق الحقول الفرعية القياسية مع متطلبات التصفية.	أضف حقولًا مثل section أو quality_score أو has_code فقط عندما تحتاج إلى تصفية هذه الحقول أو تجميعها أو إخراجها لاحقًا.

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

• إنشاء DataType.STRUCT كحقل تجميع من المستوى الأعلى بدلاً من استخدامه كنوع عنصر لحقل Array.

• نسيان تعيين max_capacity في حقل StructArray.

• تحديد أنواع الحقول الفرعية غير المدعومة، مثل JSON أو Geometry أو Text أو Timestamptz أو SparseFloatVector أو Array المتداخلة أو Struct المتداخلة أو Array-of-Struct.

• استخدام String كنوع حقل فرعي. استخدم VARCHAR وقم بتعيين max_length.

• استخدام حقل فرعي متجه واحد لكل من البحث في EmbeddingList والبحث على مستوى العناصر.

• إضافة الحقول الفرعية المتجهة فقط وتجاهل الحقول الفرعية القياسية اللازمة للتصفية، مثل section أو quality_score أو has_code.

• معاملة الحقول الفرعية المتجهة كمدخلات للمسندات القياسية $[...]. استخدام الحقول الفرعية المتجهة للبحث المتجه، والحقول الفرعية القياسية للمسندات القياسية.

• افتراض إمكانية إضافة حقول فرعية جديدة إلى حقل StructArray موجود بعد إنشاء الحقل.

• استخدام chunks.emb أو chunks.emb_list_vector بدلاً من صيغة المسار المطلوبة chunks[emb] أو chunks[emb_list_vector].

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

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

1. لإدراج بيانات متداخلة في حقل StructArray، اقرأ " إدراج البيانات في حقول StructArray".

2. لإنشاء فهارس متجهة وقيمية، اقرأ «فهرسة حقول StructArray».

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

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