Azure Cognitive Search의 $filter, $orderby, $select에 대한 OData 언어 개요
이 문서에서는 Azure Cognitive Search $filter, $order 및 $select 식에 사용되는 OData 식 언어에 대한 개요를 제공합니다. 언어는 가장 기본적인 요소로 시작하여 "상향식"으로 표시됩니다. 쿼리 요청에서 생성할 수 있는 OData 식은 단순에서 매우 복잡한 것까지 다양하지만 모두 공통 요소를 공유합니다. 공유 요소는 다음과 같습니다.
- 필드 경로 - 인덱스의 특정 필드를 참조합니다.
- 상수 - 특정 데이터 형식의 리터럴 값입니다.
이러한 일반적인 개념을 이해한 후에는 각 식에 대한 최상위 구문을 계속 사용할 수 있습니다.
- $filter 식은 쿼리 구문 분석, 특정 필드로 검색 제한 또는 인덱스 검색 중에 사용되는 일치 조건을 추가하는 동안 평가됩니다.
- $orderby 식은 반환되는 문서를 정렬하기 위해 결과 집합에 대한 사후 처리 단계로 적용됩니다.
- $select 식은 결과 집합에 포함되는 문서 필드를 결정합니다.
이러한 식의 구문은 검색 매개 변수에 사용되는 단순 또는 전체 쿼리 구문과 구별되지만 필드를 참조하는 구문에는 몇 가지 중복이 있습니다.
참고
Azure Cognitive Search 용어와 OData 표준 간에는 몇 가지 차이가 있습니다. Azure Cognitive Search의 필드는 OData의 속성에 해당하고 필드 경로는 속성 경로에 해당합니다. Azure Cognitive Search에서 문서를 포함하는 인덱스를 OData에서는 더 일반적으로 엔터티를 포함하는 엔터티 집합이라고 합니다. 이 참조에서는 전체적으로 Azure Cognitive Search 용어가 사용되었습니다.
필드 경로
다음 EBNF(Extended Backus-Naur Form)는 필드 경로의 문법을 정의합니다.
field_path ::= identifier('/'identifier)*
identifier ::= [a-zA-Z_][a-zA-Z_0-9]*
다음과 같은 대화형 구문 다이어그램도 사용할 수 있습니다.
참고
전체 EBNF는 Azure Cognitive Search의 OData 식 구문 참조를 참조하세요.
필드 경로는 슬래시로 구분된 하나 이상의 식별자로 구성됩니다. 각 식별자는 ASCII 문자 또는 밑줄로 시작하고 ASCII 문자, 숫자 또는 밑줄만 포함해야 하는 문자 시퀀스입니다. 문자는 대문자나 소문자일 수 있습니다.
식별자는 필드 이름 또는 필터의 컬렉션 식 컨텍스트에서 사용된 범위 변수(any 또는 all)를 참조할 수 있습니다. 범위 변수는 컬렉션의 현재 요소를 나타내는 루프 변수와 유사합니다. 복합 컬렉션의 경우 해당 변수는 개체를 나타내기 때문에 필드 경로를 사용하여 변수의 하위 필드를 참조할 수 있습니다. 대부분의 프로그래밍 언어에서 사용되는 점 표기법과 유사합니다.
다음 표에는 필드 경로 예제가 나와 있습니다.
| 필드 경로 | 설명 |
|---|---|
HotelName |
인덱스의 최상위 필드를 참조합니다. |
Address/City |
인덱 Address 스에 City 있는 복합 필드의 하위 필드를 참조합니다. 이 예제에서는 형식 Edm.ComplexType 입니다. |
Rooms/Type |
인덱 Rooms 스에서 Type 복합 컬렉션 필드의 하위 필드를 참조합니다. 이 예제에서는 형식 Collection(Edm.ComplexType) 입니다. |
Stores/Address/Country |
인덱 Stores 스에 있는 Country 복합 컬렉션 필드의 Address 하위 필드 하위 필드를 나타냅니다. 형식 Collection(Edm.ComplexType) 이며 Address 이 예제에서는 형식 Edm.ComplexType 입니다. |
room/Type |
범위 변수의 Typeroom 하위 필드(예: 필터 식)를 참조합니다. Rooms/any(room: room/Type eq 'deluxe') |
store/Address/Country |
Country 범위 변수의 Address 하위 필드(예: 필터 식)의 하위 필드를 store 참조합니다.Stores/any(store: store/Address/Country eq 'Canada') |
필드 경로의 의미는 컨텍스트에 따라 달라집니다. 필터에서 필드 경로는 현재 문서에 있는 필드의 ‘단일 인스턴스’ 값을 나타냅니다. $orderby, $select 또는 전체 Lucene 구문의 필드 지정 검색과 같은 다른 컨텍스트에서 필드 경로는 필드 자체를 참조합니다. 이 차이는 필터에서 필드 경로를 사용하는 방법에 영향을 줍니다.
필드 경로 Address/City를 고려해 보세요. 필터에서 이 경로는 “샌프란시스코”와 같은 현재 문서의 단일 도시를 참조합니다. 반면, 은 Rooms/Type 많은 회의실의 Type 하위 필드를 나타냅니다(예: 첫 번째 방의 경우 "표준", 두 번째 방의 경우 "디럭스" 등). Rooms/Type 는 하위 필드Type의 단일 인스턴스를 참조하지 않으므로 필터에서 직접 사용할 수 없습니다. 대신, 객실 유형을 필터링하려면 다음과 같이 범위 변수와 함께 람다 식을 사용합니다.
Rooms/any(room: room/Type eq 'deluxe')
예제에서는 범위 변수 room이 room/Type 필드 경로에 표시됩니다. 이런 방식으로 room/Type은 현재 문서의 현재 객실 유형을 참조합니다. 이 인스턴스는 하위 필드의 Type 단일 인스턴스이므로 필터에서 직접 사용할 수 있습니다.
필드 경로 사용
필드 경로는 Azure Cognitive Search REST API의 많은 매개 변수에서 사용됩니다. 다음 표에는 필드 경로를 사용할 수 있는 모든 위치 및 사용 제한 사항이 나와 있습니다.
| API | 매개 변수 이름 | 제한 |
|---|---|---|
| 인덱스 만들기 또는 업데이트 | suggesters/sourceFields |
없음 |
| 인덱스 만들기 또는 업데이트 | scoringProfiles/text/weights |
검색 가능한 필드만 참조할 수 있습니다. |
| 인덱스 만들기 또는 업데이트 | scoringProfiles/functions/fieldName |
필터링 가능한 필드만 참조할 수 있습니다. |
| 검색 | queryType이 full인 경우 search |
검색 가능한 필드만 참조할 수 있습니다. |
| 검색 | facet |
패싯 가능한 필드만 참조할 수 있습니다. |
| 검색 | highlight |
검색 가능한 필드만 참조할 수 있습니다. |
| 검색 | searchFields |
검색 가능한 필드만 참조할 수 있습니다. |
| 제안 및 자동 완성 | searchFields |
제안기의 일부인 필드만 참조할 수 있습니다. |
| 검색, 제안, 자동 완성 | $filter |
필터링 가능한 필드만 참조할 수 있습니다. |
| 검색 및 제안 | $orderby |
정렬 가능한 필드만 참조할 수 있습니다. |
| 검색, 제안, 조회 | $select |
검색 가능한 필드만 참조할 수 있습니다. |
상수
OData의 상수는 지정된 EDM(엔터티 데이터 모델) 형식의 리터럴 값입니다. Azure Cognitive Search에서 지원되는 형식 목록은 지원되는 데이터 형식을 참조하세요. 컬렉션 형식의 상수는 지원되지 않습니다.
다음 표에는 Azure Cognitive Search에서 지원되는 각 데이터 형식의 상수 예제가 나와 있습니다.
| 데이터 형식 | 예제 상수 |
|---|---|
Edm.Boolean |
true, false |
Edm.DateTimeOffset |
2019-05-06T12:30:05.451Z |
Edm.Double |
3.14159, -1.2e7, NaN, INF, -INF |
Edm.GeographyPoint |
geography'POINT(-122.131577 47.678581)' |
Edm.GeographyPolygon |
geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))' |
Edm.Int32 |
123, -456 |
Edm.Int64 |
283032927235 |
Edm.String |
'hello' |
문자열 상수에서 특수 문자 이스케이프
OData의 문자열 상수는 작은따옴표로 구분됩니다. 작은따옴표가 포함될 수 있는 문자열 상수로 쿼리를 생성해야 하는 경우 포함된 따옴표를 두 개 사용하여 이스케이프할 수 있습니다.
예를 들어 “Alice's car”와 같이 서식이 지정되지 않은 아포스트로피를 사용하는 구는 OData에서 문자열 상수 'Alice''s car'로 표시됩니다.
중요
프로그래밍 방식으로 필터를 생성하는 경우 사용자 입력에서 제공된 문자열 상수를 이스케이프해야 합니다. 이 작업은 특히 필터를 사용하여 보안 트리밍을 구현할 때 삽입 공격의 가능성을 완화하기 위한 것입니다.
상수 구문
다음 EBNF(Extended Backus-Naur Form)는 위의 표에 있는 대부분의 상수의 문법을 정의합니다. 지리 공간적 형식의 문법은 Azure Cognitive Search의 OData 지리 공간적 함수에서 확인할 수 있습니다.
constant ::=
string_literal
| date_time_offset_literal
| integer_literal
| float_literal
| boolean_literal
| 'null'
string_literal ::= "'"([^'] | "''")*"'"
date_time_offset_literal ::= date_part'T'time_part time_zone
date_part ::= year'-'month'-'day
time_part ::= hour':'minute(':'second('.'fractional_seconds)?)?
zero_to_fifty_nine ::= [0-5]digit
digit ::= [0-9]
year ::= digit digit digit digit
month ::= '0'[1-9] | '1'[0-2]
day ::= '0'[1-9] | [1-2]digit | '3'[0-1]
hour ::= [0-1]digit | '2'[0-3]
minute ::= zero_to_fifty_nine
second ::= zero_to_fifty_nine
fractional_seconds ::= integer_literal
time_zone ::= 'Z' | sign hour':'minute
sign ::= '+' | '-'
/* In practice integer literals are limited in length to the precision of
the corresponding EDM data type. */
integer_literal ::= digit+
float_literal ::=
sign? whole_part fractional_part? exponent?
| 'NaN'
| '-INF'
| 'INF'
whole_part ::= integer_literal
fractional_part ::= '.'integer_literal
exponent ::= 'e' sign? integer_literal
boolean_literal ::= 'true' | 'false'
다음과 같은 대화형 구문 다이어그램도 사용할 수 있습니다.
참고
전체 EBNF는 Azure Cognitive Search의 OData 식 구문 참조를 참조하세요.
필드 경로 및 상수에서 식 작성
필드 경로와 상수는 OData 식의 가장 기본적인 부분이지만 이미 전체 식이기도 합니다. 실제로 Azure Cognitive Search의 $select 매개 변수는 쉼표로 구분된 필드 경로 목록일 뿐이고 $orderby도 $select보다 많이 복잡하지 않습니다. 인덱스에 Edm.Boolean 형식의 필드가 있다면 해당 필드의 경로인 필터를 작성할 수도 있습니다. 마찬가지로 true 및 false 상수도 유효한 필터입니다.
그러나 대체로 둘 이상의 필드와 상수를 참조하는 더 복잡한 식이 필요합니다. 해당 식은 매개 변수에 따라 다양한 방식으로 빌드됩니다.
다음 EBNF(Extended Backus-Naur Form)는 $filter, $orderby, $select 매개 변수의 문법을 정의합니다. 세 매개 변수는 필드 경로와 상수를 참조하는 더 간단한 식에서 빌드되었습니다.
filter_expression ::= boolean_expression
order_by_expression ::= order_by_clause(',' order_by_clause)*
select_expression ::= '*' | field_path(',' field_path)*
다음과 같은 대화형 구문 다이어그램도 사용할 수 있습니다.
참고
전체 EBNF는 Azure Cognitive Search의 OData 식 구문 참조를 참조하세요.
다음 단계
$orderby 및 $select 매개 변수는 더 간단한 식의 쉼표로 구분된 목록입니다. $filter 매개 변수는 더 간단한 하위 식으로 구성된 부울 식입니다. 이러한 하위 식은 , , or및 와 같은and 논리 연산자와 not, 등과 같은eqltgt 비교 연산자 및 및 all와 같은any 컬렉션 연산자를 사용하여 결합됩니다.
$filter, $orderby, $select 매개 변수는 다음 문서에서 자세히 설명합니다.