مشغلات StructArray
تقوم مشغلات StructArray بتصفية الكيانات من خلال تقييم المسندات على الحقول الفرعية القياسية داخل حقل StructArray. استخدم هذه الصفحة كمرجع لصيغة المشغل " element_filter " ومجموعة مشغلات " MATCH_* ".
يحتوي تصفية StructArray على مجموعتين من العوامل:
| مجموعة العوامل | الغرض الرئيسي | سلوك النتيجة |
|---|---|---|
element_filter | مطابقة عناصر Struct التي تستوفي شرطًا قياسيًا. | في البحث على مستوى العناصر، يمكن أن تتضمن النتائج المطابقة إزاحات العناصر. في الاستعلام على مستوى الصفوف أو البحث المُصفى، يعتمد شكل النتيجة على واجهة برمجة التطبيقات (API) وحقول الإخراج. |
MATCH_* | تحديد الكيانات حسب عدد عناصر Struct التي تستوفي شرطًا قياسيًا. | التصفية على مستوى الصفوف. لا تُرجع هذه العوامل إزاحات العناصر من تلقاء نفسها. |
استخدم الحقول الفرعية القياسية في عوامل StructArray. تُستخدم الحقول الفرعية المتجهة في مسارات البحث المتجهة ولا تُعد مدخلات لشروط قياسية.
متى تستخدم أي عامل
| الهدف | الاستخدام |
|---|---|
| تقييد البحث المتجهي على مستوى العناصر ليقتصر على العناصر التي تتطابق مع الشروط القياسية. | element_filter |
| مطابقة شروط سكالارية متعددة داخل نفس عنصر Struct. | element_filter |
| إرجاع الكيانات التي يفي فيها عنصر Struct واحد على الأقل بشرط ما فقط. | MATCH_ANY |
| إرجاع الكيانات التي تستوفي جميع عناصر Struct فيها الشرط فقط. | MATCH_ALL |
إرجاع الكيانات التي يستوفي فيها ما لا يقل عن أو ما لا يزيد عن أو بالضبط N من عناصر Struct شرطًا ما. | MATCH_LEAST، أو MATCH_MOST ، أو MATCH_EXACT |
مرشح العناصر
استخدم element_filter(structArrayField, predicate) لمطابقة عناصر Struct في حقل StructArray.
داخل الشرط، استخدم $[subfield] للإشارة إلى حقل فرعي قياسي لعنصر Struct الحالي.
element_filter(chunks, $[section] == "index")
عند استخدام شروط متعددة داخل الشرط، تنطبق جميع إشارات $[subfield] على نفس عنصر Struct:
element_filter(chunks, $[section] == "index" && $[quality_score] > 0.9)
عند دمج شرط على مستوى الكيان مع element_filter ، ضع element_filter في نهاية التعبير:
# Correct
category == "index" && element_filter(chunks, $[quality_score] > 0.9)
# Incorrect
element_filter(chunks, $[quality_score] > 0.9) && category == "index"
element_filter لا يمكن أن يظهر إلا مرة واحدة في تعبير التصفية. لا تقم بتداخل element_filter أو MATCH_* داخل element_filter آخر.
مشغلات عائلة المطابقة
استخدم عوامل التشغيل MATCH_* عندما يتعين تحديد كيان بناءً على عدد عناصر Struct التي تستوفي شرطًا ما.
| المُشغِّل | المعنى |
|---|---|
MATCH_ANY(field, predicate) | يستوفي عنصر Struct واحد على الأقل الشرط. |
MATCH_ALL(field, predicate) | تستوفي جميع عناصر Struct الشرط. |
MATCH_LEAST(field, predicate, threshold=N) | يستوفي ما لا يقل عن N عنصر من عناصر Struct الشرط. |
MATCH_MOST(field, predicate, threshold=N) | يستوفي ما لا يزيد عن N عن عناصر Struct الشرط. |
MATCH_EXACT(field, predicate, threshold=N) | يستوفي N عنصرًا من عناصر Struct بالضبط الشرط. |
MATCH_ANY ويمكن لكل من element_filter التعبير عن أن عنصر Struct واحد على الأقل يستوفي الشرط. استخدم MATCH_ANY عندما تحتاج فقط إلى التصفية على مستوى الصف. استخدم element_filter عندما تحتاج إلى قيود على مستوى العنصر، مثل تصفية عناصر Struct التي تشارك في البحث المتجهي على مستوى العنصر.
MATCH_ANY
MATCH_ANY يُقيَّم إلى true إذا كان عنصر واحد على الأقل في StructArray يستوفي الشرط.
MATCH_ANY(chunks, $[section] == "index")
بالنسبة لـ StructArray فارغ، يُرجع MATCH_ANY القيمة false.
MATCH_ALL
MATCH_ALL يُقيَّم إلى true إذا كان كل عنصر في StructArray يستوفي الشرط.
MATCH_ALL(chunks, $[has_code] == true)
بالنسبة إلى StructArray فارغ، تُرجع الدالة MATCH_ALL القيمة true.
تُقيّم MATCH_LEAST
MATCH_LEAST يُقيَّم إلى true إذا كان عدد العناصر التي تستوفي الشرط أكبر من أو يساوي threshold.
MATCH_LEAST(chunks, $[quality_score] > 0.9, threshold=2)
بالنسبة لـ MATCH_LEAST ، يجب أن يكون threshold عددًا صحيحًا موجبًا.
MATCH_MOST
MATCH_MOST تُحسب قيمتها بـ true إذا كان عدد العناصر التي تستوفي الشرط أقل من أو يساوي threshold.
MATCH_MOST(chunks, $[has_code] == true, threshold=1)
بالنسبة لـ MATCH_MOST ، يمكن أن يكون threshold صفرًا أو عددًا صحيحًا موجبًا.
MATCH_EXACT
MATCH_EXACT تُقيَّم إلى true إذا كان عدد العناصر التي تستوفي الشرط يساوي بالضبط threshold.
MATCH_EXACT(chunks, $[section] == "filter", threshold=1)
بالنسبة لـ MATCH_EXACT ، يمكن أن يكون threshold صفرًا أو عددًا صحيحًا موجبًا.
الشرطيات المدعومة
تمثل صيغة $[...] القيمة القياسية لعنصر Struct الحالي. يعتمد دعم الشرط على نوع الحقل الفرعي القياسي.
| نوع الحقل الفرعي | دعم المسندات على مستوى العنصر |
|---|---|
BOOL | المسلمات القياسية مثل $[has_code] == true أو !($[has_code] == true). تجنب التعبيرات المنطقية المجردة مثل $[has_code]. |
INT8، INT16 ، INT32 ، INT64 | المقارنة، النطاق المتسلسل، in ، not in ، التعبيرات الحسابية التي تحتوي على + ، - ، * ، / ، أو % متبوعة بمقارنة، والتركيبات المنطقية. |
FLOAT، DOUBLE | المقارنة، النطاق المتسلسل، in ، not in ، التعبيرات الحسابية التي تحتوي على + ، - ، * ، أو / متبوعة بمقارنة، والتركيبات المنطقية. لا يُدعم عامل التشغيل % للحقول الفرعية ذات العلامة العائمة. |
VARCHAR | مقارنة السلاسل، والنطاق المتسلسل، و in ، و not in ، و like ، و =~ ، و !~ ، والتركيبات المنطقية. |
| الحقول الفرعية للمتجهات | غير مدعومة كمدخلات للمسندات القياسية $[...]. استخدم الحقول الفرعية للمتجهات بدلاً من ذلك من خلال البحث في EmbeddingList أو البحث المتجهي على مستوى العنصر. |
تنطبق العوامل المنطقية مثل && و \|\| و ! على تعبيرات المسندات. على سبيل المثال، اكتب !($[has_code] == true) بدلاً من !$[has_code].
المسندات غير المدعومة
لا تدعم المسندات على مستوى العناصر $[...] ما يلي:
وظائف مطابقة النص، مثل
text_match(field, "...")أوphrase_match(field, "...").صيغة مسار JSON، و
existsعلى مسارات JSON، أو دوال JSON مثلjson_containsأوjson_contains_allأوjson_contains_any.دوال حاويات المصفوفات مثل
array_containsأوarray_contains_allأوarray_contains_anyأوarray_length.$[subfield] is nullأو$[subfield] is not null.وظائف الهندسة / نظم المعلومات الجغرافية (GIS).
تعبيرات الطابع الزمني tz.
random_sample(...).المسندات المتجهة على مستوى الحقل.
استدعاءات وظائف التصفية العامة ما لم تدعم توقيعات الوظائف المحددة ومسارات التنفيذ صراحةً المسندات على مستوى عناصر StructArray.
قواعد بناء الجمل
MATCH_*أسماء العوامل لا تميز بين الأحرف الكبيرة والصغيرة.استخدم
$[subfield]فقط داخل المسنداتelement_filterأوMATCH_*.لا تستخدم
$[subfield]كمسار JSON أو حاوية صفيف أو مرجع لحقل متجه.لا تقم بتداخل
element_filterأوMATCH_*داخل عامل StructArray آخر.استخدم
threshold=Nالمسمى لـMATCH_LEASTوMATCH_MOSTوMATCH_EXACT.MATCH_ANYعند استدعاءه على StructArray فارغ، يُرجعfalse.MATCH_ALLعند استدعاءه على StructArray فارغ، يُرجعtrue.
