Операторы 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] ` относятся к одному и тому же элементу структуры:
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 элементов структуры удовлетворяют предикату. |
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 может быть равно нулю или представлять собой положительное целое число.
Поддерживаемые предикаты
Синтаксис $[...] представляет скалярное значение текущего элемента структуры. Поддержка предикатов зависит от типа скалярного подполя.
| Тип подполя | Поддержка предикатов на уровне элементов |
|---|---|
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] напишите !($[has_code] == true).
Неподдерживаемые предикаты
Предикаты на уровне элементов $[...] не поддерживают:
Функции сопоставления текста, такие как
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.Функции геометрии / ГИС.
Выражения с временными метками 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.
