فهرسة JSON

توفر حقول JSON طريقة مرنة لتخزين البيانات الوصفية المنظمة في Milvus. بدون الفهرسة، تتطلب الاستعلامات على حقول JSON إجراء عمليات مسح كاملة للمجموعة، مما يؤدي إلى بطء الأداء مع نمو مجموعة البيانات الخاصة بك. تعمل فهرسة JSON على إنشاء فهرس على مسار محدد داخل بيانات JSON الخاصة بك، بحيث يتم تنفيذ استعلامات المساواة والنطاق واستعلامات التصفية الأخرى على هذا المسار بسرعة.

تعد فهرسة JSON مثالية لما يلي:

• المخططات المنظمة ذات المفاتيح الثابتة والمعروفة

• استعلامات المساواة و IN والنطاق ومطابقة النص على مسارات JSON محددة

• السيناريوهات التي تحتاج فيها إلى تحكم دقيق في المفاتيح التي يتم فهرستها

بالنسبة لمستندات JSON المعقدة ذات أنماط الاستعلام المتنوعة، ضع في اعتبارك استخدام تقطيع JSON كبديل.

نظرة عامة على أنواع الفهرسة

يقدم Milvus أربعة أنواع من الفهارس لمسارات JSON. كل منها مناسب لنمط استعلام مختلف.

قبل اختيار نوع الفهرس، حدد نوع التحويل لمسار JSON. يحدد نوع التحويل كيفية تفسير Milvus للقيمة في ذلك المسار وأنواع الفهارس المتاحة.

فهم أنواع التحويل

json_cast_type هو نوع البيانات المستخدم لتفسير وفهرسة القيمة الموجودة في json_path. وهو يختلف عن نوع مخطط الحقل: يظل الحقل حقلًا من نوع « JSON »، ولكن يتم التعامل مع كل مسار مفهرس على أنه نوع محدد من القيم العددية أو المصفوفات أو كائنات JSON.

اختر نوع التحويل الذي يتطابق مع القيم المخزنة في المسار. للتحقق مما إذا كان نوع التحويل يعمل مع نوع فهرس معين، راجع مرجع التوافق.

إذا كانت القيم الموجودة في نفس المسار ذات أنواع غير متسقة، فسيتم فهرسة القيم التي تتطابق مع نوع التحويل فقط. على سبيل المثال، إذا كان metadata["price"] يحتوي على كل من 99.99 و "99.99" ، فإن الفهرس من نوع التحويل DOUBLE يتضمن القيمة الرقمية ويتخطى القيمة النصية. لتحويل القيم النصية أثناء الفهرسة، استخدم json_cast_function ؛ انظر المثال 5: تحويل نوع البيانات في وقت الفهرسة.

اختر نوع الفهرس

بعد اختيار نوع التحويل، اختر نوع الفهرس وفقًا لنمط الاستعلام الخاص بك.

في حالة الشك، ابدأ باستخدام AUTOINDEX للمسارات القياسية. استخدم INVERTED بشكل صريح لأنواع التحويل إلى المصفوفات واستعلامات مطابقة النص. لا يزال فهرسة JSON للكائن بأكمله باستخدام INVERTED أو AUTOINDEX مدعومة، ولكنها أصبحت مهملة بدءًا من Milvus 3.0.0.

AUTOINDEX

AUTOINDEX يعتمد على json_cast_type الذي تحدده. في Milvus 3.0، لم يعد AUTOINDEX يُحل دائمًا إلى INVERTED لفهارس مسارات JSON.

بالنسبة لأنواع التحويل القياسية (BOOL و DOUBLE و VARCHAR)، يُعد « AUTOINDEX » نقطة البداية الموصى بها عندما تريد أن يختار Milvus تخطيط الفهرس الداخلي. أثناء إنشاء الفهرس، يقيس Milvus عدد القيم في مسار JSON. ويشير «عدد القيم » إلى عدد القيم المتميزة في ذلك المسار.

بناءً على الكاردينالية، يختار Milvus أحد التخطيطين الداخليين التاليين:

• عدد القيم المنخفض: تتكرر القيم كثيرًا، مثل metadata["in_stock"] مع true و false ، أو metadata["status"] مع مجموعة صغيرة من سلاسل الحالة. يقوم Milvus بإنشاء فهرس BITMAP داخليًّا لتسريع عمليات المقارنة (equality) وعمليات التصفية ( IN ).

• عدد كبير من القيم: معظم القيم متمايزة، مثل metadata["price"] و metadata["created_at"] و metadata["product_id"]. يقوم Milvus بإنشاء فهرس STL_SORT داخليًا لتسريع عمليات التصفية حسب النطاق مثل > و < و >= و <=.

العتبة الافتراضية لـ BITMAP مقابلSTL_SORT هي 100 قيمة مميزة. يمكنك ضبط هذه العتبة باستخدام bitmap_cardinality_limit ؛ انظر كيف يمكنني ضبط عتبة BITMAP مقابل STL_SORT في AUTOINDEX؟.

يُعد الخيار

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

حدد INVERTED بشكل صريح في الحالات التالية:

• تحتاج إلى فهرسة القيم داخل مصفوفات JSON.

• تقوم بصيانة فهرس موجود على كائن JSON كامل أو كائن فرعي وترغب في جعل سلوك " INVERTED " صريحًا.

• ترغب في نوع فهرس واحد يتعامل مع استعلامات المساواة و IN والنطاق ومطابقة النص والمصفوفات. يظل دعم الكائن بأكمله متاحًا للتوافق، على حساب حجم فهرس أكبر.

بالنسبة للفهارس الموجودة على كائنات JSON بأكملها (json_cast_type="JSON")، يمكنك الاستمرار في استخدام إما INVERTED أو AUTOINDEX. يستخدم AUTOINDEX INVERTED لهذا النوع من التحويل. لم يعد يُنصح بفهرسة JSON للكائن بأكمله لأحمال العمل الجديدة.

للحصول على التفاصيل، راجع INVERTED.

STL_SORT

STL_SORT يخزن القيم من مسار JSON بترتيب مرتب. وقد تم تحسينه لمرشحات النطاق على القيم الرقمية أو قيم السلاسل القابلة للفرز.

STL_SORT يدعم فقط أنواع التحويل DOUBLE و VARCHAR. استخدمه في الحالات التالية:

• تقوم عوامل التصفية الخاصة بك بمقارنة القيم باستخدام > أو < أو >= أو <=.

• تتميز القيم المفهرسة بعدد كبير من العناصر، مثل الأسعار أو الطوابع الزمنية أو معرّفات الهوية أو الرموز القابلة للفرز.

• ترغب في فرض تخطيط مرتب بدلاً من ترك الاختيار لـ AUTOINDEX.

STL_SORT لا يدعم أنواع التحويل BOOL أو ARRAY_* أو JSON. استخدم INVERTED للمصفوفات. يمكن أن تستمر الفهارس الحالية للكائنات بأكملها في استخدام INVERTED أو AUTOINDEX ، ولكن فهرسة JSON للكائنات بأكملها أصبحت قديمة.

للحصول على التفاصيل، راجع STL_SORT.

BITMAP

BITMAP يُنشئ صورة نقطية مدمجة لكل قيمة مميزة في مسار JSON. وقد تم تحسينه لعمليات التصفية على أساس المساواة و IN للقيم التي تتكرر كثيرًا.

BITMAP يدعم فقط أنواع التحويل BOOL و VARCHAR. استخدمه عندما:

• تستخدم عوامل التصفية الخاصة بك == أو IN.

• تتميز القيم المفهرسة بعدد قليل من القيم، مثل القيم المنطقية أو قيم الحالة أو مجموعة صغيرة من الفئات.

• ترغب في فرض تخطيط صورة نقطية بدلاً من ترك الاختيار لـ AUTOINDEX.

BITMAP لا يدعم أنواع التحويل DOUBLE أو ARRAY_* أو JSON. بالنسبة للقيم الرقمية، استخدم بدلاً من ذلك AUTOINDEX أو STL_SORT أو INVERTED.

للحصول على التفاصيل، راجع BITMAP.

مرجع التوافق

استخدم المصفوفة التالية كمرجع سريع لتركيبات (cast type, index type) المدعومة.

بالنسبة للخلايا التي تحمل علامة " No"، يرفض Milvus الطلب عند إنشاء الفهرس. بالنسبة لأنواع التحويل إلى مصفوفة، استخدم " INVERTED " بشكل صريح (لا يغطي "AUTOINDEX " المصفوفات).

إنشاء فهرس JSON

يشرح هذا القسم كيفية فهرسة أشكال مختلفة من بيانات JSON. تستخدم جميع الأمثلة البنية النموذجية أدناه وتفترض أن لديك بالفعل مجموعة تتضمن حقل JSON باسم metadata.

هيكل JSON النموذجي

{
  "metadata": {
    "category": "electronics",
    "brand": "BrandA",
    "in_stock": true,
    "price": 99.99,
    "string_price": "99.99",
    "tags": ["clearance", "summer_sale"],
    "supplier": {
      "name": "SupplierX",
      "country": "USA",
      "contact": {
        "email": "support@supplierx.com",
        "phone": "+1-800-555-0199"
      }
    }
  }
}

الإعداد الأساسي

تفترض الأمثلة أدناه أن لديك MilvusClient باسم client متصل بنشر Milvus الخاص بك، ومجموعة تتضمن بالفعل حقل JSON باسم metadata. إذا كنت بحاجة إلى إعدادها من البداية، فقم بتوسيع المربع أدناه.

from pymilvus import DataType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

# Define a schema with a JSON field
schema = client.create_schema(enable_dynamic_field=False)
schema.add_field("pk", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("vec", DataType.FLOAT_VECTOR, dim=4)
schema.add_field("metadata", DataType.JSON, nullable=True)

# Minimal vector index so the collection can be loaded
vec_index = client.prepare_index_params()
vec_index.add_index(field_name="vec", index_type="AUTOINDEX", metric_type="L2")

client.create_collection(
    collection_name="your_collection_name",
    schema=schema,
    index_params=vec_index,
)

# Insert one row that matches the sample JSON structure above
client.insert(
    collection_name="your_collection_name",
    data=[{
        "pk": 1,
        "vec": [0.1, 0.2, 0.3, 0.4],
        "metadata": {
            "category": "electronics",
            "brand": "BrandA",
            "in_stock": True,
            "price": 99.99,
            "string_price": "99.99",
            "tags": ["clearance", "summer_sale"],
            "supplier": {
                "name": "SupplierX",
                "country": "USA",
                "contact": {
                    "email": "support@supplierx.com",
                    "phone": "+1-800-555-0199"
                }
            }
        }
    }],
)

قم بإعداد كائن index-params لجمع تعريفات الفهرس المضافة في الأمثلة أدناه:

index_params = client.prepare_index_params()

يُظهر كل مثال من الأمثلة التالية استدعاءً واحدًا لـ index_params.add_index(...). اختر الاستدعاءات التي تتطابق مع بياناتك وقم باستدعائها على نفس كائن index_params. ثم قم بتطبيق كل شيء في استدعاء واحد لـ client.create_index(...) في النهاية. لمزيد من التفاصيل، راجع تطبيق الفهرس.

المثال 1: فهرسة مفتاح من المستوى الأعلى باستخدام AUTOINDEX

قم بفهرسة حقل category للتصفية السريعة حسب فئة المنتج. باستخدام AUTOINDEX ، يختار Milvus بين BITMAP أو STL_SORT بناءً على عدد الفئات المتميزة الموجودة في بياناتك.

index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX",
    index_name="category_index",
    params={
        "json_path": 'metadata["category"]',
        "json_cast_type": "VARCHAR",
    }
)

المثال 2: فهرسة مفتاح متداخل

قم بفهرسة الحقل email المتداخل بعمق للبحث عن جهات اتصال الموردين. تقبل المعلمة json_path أي عمق لترميز الأقواس.

index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX",
    index_name="email_index",
    params={
        "json_path": 'metadata["supplier"]["contact"]["email"]',
        "json_cast_type": "VARCHAR",
    }
)

المثال 3: استعلامات النطاق باستخدام STL_SORT

عندما تعلم أن استعلاماتك على مسار ما ستكون مهيمنة عليها مقارنات النطاق (> ، < ، >= ، <=)، اختر STL_SORT مباشرةً. يؤدي ذلك إلى تجاوز قياس الكاردينالية وإنشاء التخطيط المصنف على الفور.

index_params.add_index(
    field_name="metadata",
    index_type="STL_SORT",
    index_name="price_index",
    params={
        "json_path": 'metadata["price"]',
        "json_cast_type": "DOUBLE",
    }
)

بعد الفهرسة، تستخدم استعلامات النطاق مثل metadata["price"] > 50 AND metadata["price"] < 100 البحث الثنائي بدلاً من المسح الكامل.

المثال 4: استعلامات المساواة باستخدام BITMAP

بالنسبة للمفاتيح ذات الكاردينالية المنخفضة، مثل رموز الحالة أو القيم المنطقية أو السلاسل الشبيهة بقوائم التعداد، اختر BITMAP مباشرةً. تصبح استعلامات المساواة و IN عمليات bitmap.

index_params.add_index(
    field_name="metadata",
    index_type="BITMAP",
    index_name="in_stock_index",
    params={
        "json_path": 'metadata["in_stock"]',
        "json_cast_type": "BOOL",
    }
)

BITMAP كما أنه مناسب تمامًا لحقول مثل عمود " status " الذي يحتوي على عدد قليل من قيم السلاسل المتميزة.

المثال 5: تحويل نوع البيانات عند إنشاء الفهرس

عندما يتم تخزين البيانات الرقمية عن طريق الخطأ كسلاسل نصية، استخدم STRING_TO_DOUBLE لتحويل القيمة إلى رقم أثناء إنشاء الفهرس.

index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX",
    index_name="string_to_double_index",
    params={
        "json_path": 'metadata["string_price"]',
        "json_cast_type": "DOUBLE",
        "json_cast_function": "STRING_TO_DOUBLE",
    }
)

إذا فشل التحويل لصف ما (على سبيل المثال، سلسلة غير رقمية مثل "invalid")، يتم تخطي هذا الصف أثناء الفهرسة.

المثال 6: فهرسة كائنات JSON بالكامل

بالنسبة لأحمال العمل الحالية المتوافقة، يؤدي تعيين " json_cast_type="JSON" " إلى فهرسة الهيكل الكامل في المسار المحدد. يقوم Milvus بتسوية الكائنات المتداخلة إلى مسارات ويستنتج نوع كل قيمة تلقائيًا. تصبح جميع المفاتيح الموجودة ضمن المسار قابلة للبحث.

AUTOINDEX يستخدم بشكل شفاف INVERTED لنوع التحويل JSON ، نظرًا لأن التسوية واستنتاج النوع هما من إمكانيات الفهرس المعكوس.

فهرسة كائن metadata بالكامل:

index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX",
    index_name="metadata_full_index",
    params={
        "json_path": "metadata",
        "json_cast_type": "JSON",
    }
)

أو فهرسة كائن فرعي، مثل جميع معلومات supplier:

index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX",
    index_name="supplier_index",
    params={
        "json_path": 'metadata["supplier"]',
        "json_cast_type": "JSON",
    }
)

يؤدي فهرسة الكائنات بالكامل إلى زيادة حجم الفهرس. بالنسبة لأحمال العمل الجديدة التي تحتوي على مستندات متداخلة بعمق وأنماط استعلام متنوعة، استخدم الفهارس الخاصة بالمسار أو ضع في اعتبارك تقطيع JSON.

تطبيق الفهرس

بعد إضافة جميع معلمات الفهرس، قم بتطبيقها على مجموعتك:

client.create_index(
    collection_name="your_collection_name",
    index_params=index_params
)

تتم عمليات إنشاء الفهرس بشكل غير متزامن. استخدم client.describe_index(...) للتحقق من حالة إنشاء فهرس معين. يُظهر الحقل state Finished بمجرد اكتمال الإنشاء، بينما تُظهر الحقول total_rows و indexed_rows و pending_index_rows التقدم المحرز خلال العملية.

client.describe_index(
    collection_name="your_collection_name",
    index_name="category_index",
)

نموذج للاستجابة:

{
  "json_path": "metadata[\"category\"]",
  "json_cast_type": "VARCHAR",
  "index_type": "AUTOINDEX",
  "field_name": "metadata",
  "index_name": "category_index",
  "total_rows": 20,
  "indexed_rows": 20,
  "pending_index_rows": 0,
  "state": "Finished"
}

بمجرد أن يُبلغ state عن Finished ، تستخدم الاستعلامات التي تُجرى على المسار المفهرس الفهرس الجديد تلقائيًا.

بالنسبة لمدخلات AUTOINDEX ، يتم الإبلاغ عن الحقل index_type في هذا الرد على أنه AUTOINDEX. لا يكشف Milvus حاليًا عن التخطيط الأساسي (BITMAP أو STL_SORT) الذي تم اختياره وقت الإنشاء. تعامل مع هذا الاختيار على أنه تحسين داخلي: ستعمل استعلامات المساواة و IN والنطاق على المسار بغض النظر عن التخطيط الذي تم اختياره.

الأسئلة الشائعة

كيف أختار بين AUTOINDEX ونوع الفهرس الصريح؟

ابدأ بـ AUTOINDEX. فهو يختار التخطيط المناسب بناءً على عدد عناصر البيانات، ويغطي معظم استعلامات المساواة، IN ، واستعلامات النطاق على مسارات JSON. اختر نوعًا صريحًا في الحالات التالية:

• كنت تعرف نمط الاستعلام الخاص بك (على سبيل المثال، استخدم دائمًا STL_SORT للاستعلامات النطاقية، و BITMAP للاستعلامات المساواة على القيم ذات الكاردينالية المنخفضة) وترغب في تخطي قياس الكاردينالية.

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

• كنت تقوم بفهرسة أنواع تحويل المصفوفات. استخدم INVERTED بشكل صريح.

• أنت تقوم بصيانة فهرس JSON لكامل الكائن موجود بالفعل. يظل كل من INVERTED و AUTOINDEX مدعومين من أجل التوافق، ولكن فهرسة JSON لكامل الكائن أصبحت مهملة بدءًا من Milvus 3.0.0.

ماذا يحدث إذا استخدم تعبير التصفية في الاستعلام نوعًا مختلفًا عن نوع التحويل المفهرس؟

إذا كان تعبير التصفية الخاص بك يستخدم نوعًا مختلفًا عن json_cast_type الخاص بالفهرس، فلن يستخدم Milvus الفهرس وقد يلجأ إلى مسح قوي أبطأ إذا سمحت البيانات بذلك. للحصول على أفضل أداء، قم دائمًا بمواءمة تعبير التصفية مع نوع التحويل الخاص بالفهرس. على سبيل المثال، إذا تم إنشاء فهرس رقمي باستخدام json_cast_type="DOUBLE" ، فلن تستفيد من الفهرس سوى شروط التصفية الرقمية.

ماذا لو احتوى مفتاح JSON على أنواع بيانات غير متسقة عبر كيانات مختلفة؟

قد تؤدي الأنواع غير المتسقة إلى فهرسة جزئية. على سبيل المثال، إذا تم تخزين metadata["price"] كرقم (99.99) وكسلسلة ("99.99") وقمت بإنشاء فهرس باستخدام json_cast_type="DOUBLE" ، فسيتم فهرسة القيم الرقمية فقط. يتم تخطي الإدخالات في شكل سلاسل ولن تظهر في نتائج التصفية. استخدم json_cast_function="STRING_TO_DOUBLE" لتحويل السلاسل إلى أرقام عند الفهرسة، أو قم بتعديل البيانات المصدر بحيث تكون جميع الإدخالات من نفس النوع.

هل يمكنني إنشاء فهارس متعددة على نفس مفتاح JSON؟

لا. يسمح Milvus بإنشاء فهرس واحد كحد أقصى لكل زوج من (field, json_path) ، بغض النظر عن نوع التحويل أو نوع الفهرس. لا يمكنك إنشاء كل من فهرس « INVERTED » وفهرس « BITMAP » على نفس المسار، أو إنشاء فهرسين على نفس المسار بنوعي تحويل مختلفين. ومع ذلك، يمكنك إنشاء فهرس على كائن JSON بأكمله وفهرس منفصل على مفتاح متداخل داخل هذا الكائن لأنهما مساران مختلفان.

كيف يمكنني ضبط عتبة BITMAP مقابل STL_SORT في AUTOINDEX؟

بشكل افتراضي، يختار AUTOINDEX خيار « BITMAP » عندما تحتوي القيم المفهرسة على 100 قيمة مميزة أو أقل، ويختار خيار « STL_SORT » في الحالات الأخرى. يمكنك تجاوز هذا الحد عن طريق إضافة "bitmap_cardinality_limit" إلى معلمات الفهرس (النطاق: 1-1000):

index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX",
    index_name="category_index",
    params={
        "json_path": 'metadata["category"]',
        "json_cast_type": "VARCHAR",
        "bitmap_cardinality_limit": 200,  # use BITMAP up to 200 distinct values
    }
)

لا يحتاج معظم المستخدمين إلى ضبط هذا الإعداد. قم برفع القيمة إذا كان لديك حقل ذو عدد عناصر معتدل تفضل معالجته بنظام الخرائط الثنائية؛ وقم بخفضها لدفع AUTOINDEX نحو STL_SORT في وقت أبكر. يتم تجاهل هذا الإعداد عند تحديد INVERTED أو STL_SORT أو BITMAP بشكل صريح.