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) 을 사용하여 StructArray 필드의 Struct 요소를 일치시킵니다.
술어 내에서 $[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 요소가 술어를 만족함을 나타낼 수 있습니다. 행 수준 필터링만 필요한 경우 를 사용하십시오. 요소 수준 벡터 검색에 참여하는 Struct 요소를 필터링하는 등 요소 수준 제약 조건이 필요한 경우 를 사용하십시오. MATCH_ANY element_filter
MATCH_ANY
MATCH_ANY StructArray의 요소 중 적어도 하나가 술어를 만족하면 true 로 평가됩니다.
MATCH_ANY(chunks, $[section] == "index")
빈 StructArray의 경우, ` MATCH_ANY `는 ` false`를 반환합니다.
MATCH_ALL
MATCH_ALL StructArray의 모든 요소가 술어를 만족하는 경우, true 로 평가됩니다.
MATCH_ALL(chunks, $[has_code] == true)
빈 StructArray의 경우, MATCH_ALL 는 true 를 반환합니다.
MATCH_LEAST
MATCH_LEAST 는 술어를 만족하는 요소의 수가 threshold 이상일 때 true 로 평가됩니다.
MATCH_LEAST(chunks, $[quality_score] > 0.9, threshold=2)
MATCH_LEAST 의 경우, threshold 는 양의 정수여야 합니다.
MATCH_MOST는 술어를 만족하는 요소의 개수가 xml-ph-0001@deepl.internal보다 작거나 같을 때 xml-ph-0000@deepl.internal로 평가됩니다.
MATCH_MOST 술어를 만족하는 요소의 개수가 threshold 이하인 경우, true 로 평가됩니다.
MATCH_MOST(chunks, $[has_code] == true, threshold=1)
MATCH_MOST 의 경우, threshold 는 0이거나 양의 정수일 수 있습니다.
MATCH_EXACT
MATCH_EXACT 는 술어를 만족하는 요소의 개수가 threshold 와 정확히 일치할 때 true 로 평가됩니다.
MATCH_EXACT(chunks, $[section] == "filter", threshold=1)
MATCH_EXACT 의 경우, threshold 는 0이거나 양의 정수일 수 있습니다.
지원되는 술어
$[...] 구문은 현재 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] 대신 !($[has_code] == true) 를 작성하십시오.
지원되지 않는 술어
요소 수준 $[...] 술어는 다음을 지원하지 않습니다:
text_match(field, "...")이나phrase_match(field, "...")과 같은 텍스트 일치 함수.JSON 경로 구문, JSON 경로에 대한
exists, 또는json_contains,json_contains_all,json_contains_any과 같은 JSON 함수.array_contains,array_contains_all,array_contains_any또는array_length과 같은 배열 컨테이너 함수.$[subfield] is null또는$[subfield] is not null.기하학/GIS 함수.
timestamptz 표현식.
random_sample(...).필드 수준 벡터 술어.
특정 함수 시그니처 및 실행 경로가 StructArray 요소 수준 술어를 명시적으로 지원하지 않는 한, 일반 필터 함수 호출.
구문 규칙
MATCH_*연산자 이름은 대소문자를 구분하지 않습니다.$[subfield]는element_filter또는MATCH_*술어 내에서만 사용하십시오.$[subfield]를 JSON 경로, 배열 컨테이너 또는 벡터 필드 참조로 사용하지 마십시오.element_filter또는MATCH_*를 다른 StructArray 연산자 안에 중첩하지 마십시오.MATCH_LEAST,MATCH_MOST및MATCH_EXACT의 경우 이름이 지정된threshold=N를 사용하십시오.MATCH_ANY빈 StructArray에 대해 호출하면false를 반환합니다.MATCH_ALL빈 StructArray에 대해 호출하면true를 반환합니다.
