Azure AI Search의 $filter, $orderby, $select에 대한 OData 언어 개요

  • 아티클

이 문서에서는 Azure AI Search의 $filter, $order 및 $select 식에서 사용되는 OData 식 언어에 대해 개괄적으로 설명합니다. 언어는 가장 기본적인 요소로 시작하는 “상향식”으로 표시됩니다. 쿼리 요청에서 생성할 수 있는 OData 식은 단순한 것에서 매우 복잡한 것까지 다양하지만 모두 공통 요소를 공유합니다. 공유 요소는 다음과 같습니다.

  • 필드 경로 - 인덱스의 특정 필드를 참조합니다.
  • 상수 - 특정 데이터 형식의 리터럴 값입니다.

이러한 일반적인 개념을 이해한 후에는 각 식에 대한 최상위 구문을 계속 사용할 수 있습니다.

  • $filter 식은 쿼리 구문 분석 때 평가되고, 검색을 특정 필드로 제한하거나 인덱스 검색 때 사용되는 일치 조건을 추가합니다.
  • $orderby 식은 반환된 문서를 정렬하기 위해 결과 집합에 대한 사후 처리 단계로 적용됩니다.
  • $select 식은 결과 집합에 포함되는 문서 필드를 결정합니다.

필드 참조 구문에 겹치는 부분이 있기는 하지만 search 매개 변수에서 사용되는 simple 또는 full 쿼리 구문과 위의 식 구문은 구분됩니다.

참고 항목

Azure AI Search 용어와 OData 표준 간에는 몇 가지 차이가 있습니다. Azure AI Search의 필드는 OData의 속성에 해당하고 필드 경로는 속성 경로에 해당합니다. Azure AI Search에서 문서를 포함하는 인덱스를 OData에서는 더 일반적으로 엔터티를 포함하는 엔터티 집합이라고 합니다. 이 참조에서는 전체적으로 Azure AI Search 용어가 사용되었습니다.

필드 경로

다음 EBNF(Extended Backus-Naur Form)는 필드 경로의 문법을 정의합니다.

field_path ::= identifier('/'identifier)*

identifier ::= [a-zA-Z_][a-zA-Z_0-9]*

다음과 같은 대화형 구문 다이어그램도 사용할 수 있습니다.

Azure AI Search의 OData 구문 다이어그램

참고 항목

전체 EBNF는 Azure AI Search의 OData 식 구문 참조를 참조하세요.

필드 경로는 슬래시로 구분된 하나 이상의 식별자로 구성됩니다. 각 식별자는 ASCII 문자 또는 밑줄로 시작하고 ASCII 문자, 숫자 또는 밑줄만 포함해야 하는 문자 시퀀스입니다. 문자는 대문자나 소문자일 수 있습니다.

식별자는 필드 이름 또는 필터의 컬렉션 식 컨텍스트에서 사용된 범위 변수(any 또는 all)를 참조할 수 있습니다. 범위 변수는 컬렉션의 현재 요소를 나타내는 루프 변수와 유사합니다. 복합 컬렉션에서 해당 변수는 개체를 나타내며, 필드 경로를 사용하여 변수의 하위 필드를 참조할 수 있는 이유는 이 때문입니다. 대부분의 프로그래밍 언어에서 사용되는 점 표기법과 유사합니다.

다음 표에는 필드 경로 예제가 나와 있습니다.

필드 경로 설명
HotelName 인덱스의 최상위 필드를 참조합니다.
Address/City 인덱스의 복합 필드에서 City 하위 필드를 참조합니다. 예제에서 Address는 Edm.ComplexType 형식입니다.
Rooms/Type 인덱스의 복합 컬렉션 필드에서 Type 하위 필드를 참조합니다. 예제에서 Rooms는 Collection(Edm.ComplexType) 형식입니다.
Stores/Address/Country 인덱스의 복합 컬렉션 필드에서 Address 하위 필드의 Country 하위 필드를 참조합니다. 예제에서 Stores는 Collection(Edm.ComplexType) 형식이고 Address는 Edm.ComplexType 형식입니다.
room/Type room 범위 변수의 Type 하위 필드를 참조합니다(예: 필터 식 Rooms/any(room: room/Type eq 'deluxe')).
store/Address/Country store 범위 변수에서 Address 하위 필드의 Country 하위 필드를 참조합니다(예: 필터 식 Stores/any(store: store/Address/Country eq 'Canada')).

필드 경로의 의미는 컨텍스트에 따라 달라집니다. 필터에서 필드 경로는 현재 문서에 있는 필드의 ‘단일 인스턴스’ 값을 나타냅니다. $orderby, $select 또는 전체 Lucene 구문의 필드 지정 검색과 같은 다른 컨텍스트에서 필드 경로는 필드 자체를 참조합니다. 이 차이는 필터에서 필드 경로를 사용하는 방법에 영향을 줍니다.

필드 경로 Address/City를 고려해 보세요. 필터에서 이 경로는 “샌프란시스코”와 같은 현재 문서의 단일 도시를 참조합니다. 반면, Rooms/Type은 여러 객실의 Type 하위 필드를 참조합니다(예: 첫 번째 객실은 “standard”, 두 번째 객실은 “deluxe”). Rooms/Type은 하위 필드 Type의 단일 인스턴스를 참조하지 않으므로 필터에서 직접 사용할 수 없습니다. 대신, 객실 유형을 필터링하려면 다음과 같이 범위 변수와 함께 람다 식을 사용합니다.

Rooms/any(room: room/Type eq 'deluxe')

예제에서는 범위 변수 room이 room/Type 필드 경로에 표시됩니다. 이런 방식으로 room/Type은 현재 문서의 현재 객실 유형을 참조합니다. Type 하위 필드의 단일 인스턴스이므로 필터에서 직접 사용할 수 있습니다.

필드 경로 사용

필드 경로는 Azure AI Search REST API의 많은 매개 변수에서 사용됩니다. 다음 표에는 필드 경로를 사용할 수 있는 모든 위치 및 사용 제한 사항이 나와 있습니다.

API 매개 변수 이름 제한 사항
인덱스 만들기 또는 업데이트 suggesters/sourceFields 없음
인덱스 만들기 또는 업데이트 scoringProfiles/text/weights 검색 가능한 필드만 참조할 수 있습니다.
인덱스 만들기 또는 업데이트 scoringProfiles/functions/fieldName 필터링 가능한 필드만 참조할 수 있습니다.
Search queryType이 full인 경우 search 검색 가능한 필드만 참조할 수 있습니다.
Search facet 패싯 가능한 필드만 참조할 수 있습니다.
Search highlight 검색 가능한 필드만 참조할 수 있습니다.
Search searchFields 검색 가능한 필드만 참조할 수 있습니다.
제안 및 자동 완성 searchFields 제안기의 일부인 필드만 참조할 수 있습니다.
검색, 제안, 자동 완성 $filter 필터링 가능한 필드만 참조할 수 있습니다.
검색 및 제안 $orderby 정렬 가능한 필드만 참조할 수 있습니다.
검색, 제안, 조회 $select 검색 가능한 필드만 참조할 수 있습니다.

상수

OData의 상수는 지정된 EDM(엔터티 데이터 모델) 형식의 리터럴 값입니다. Azure AI Search에서 지원되는 형식 목록은 지원되는 데이터 형식을 참조하세요. 컬렉션 형식의 상수는 지원되지 않습니다.

다음 표에는 Azure AI 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'로 표시됩니다.

Important

프로그래밍 방식으로 필터를 생성하는 경우 사용자 입력에서 제공된 문자열 상수를 이스케이프해야 합니다. 이 작업은 특히 필터를 사용하여 보안 트리밍을 구현할 때 삽입 공격의 가능성을 완화하기 위한 것입니다.

상수 구문

다음 EBNF(Extended Backus-Naur Form)는 위의 표에 있는 대부분의 상수의 문법을 정의합니다. 지리 공간적 형식의 문법은 Azure AI 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'

다음과 같은 대화형 구문 다이어그램도 사용할 수 있습니다.

Azure AI Search의 OData 구문 다이어그램

참고 항목

전체 EBNF는 Azure AI Search의 OData 식 구문 참조를 참조하세요.

필드 경로 및 상수에서 식 작성

필드 경로와 상수는 OData 식의 가장 기본적인 부분이지만 이미 전체 식이기도 합니다. 실제로 Azure AI 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)*

다음과 같은 대화형 구문 다이어그램도 사용할 수 있습니다.

Azure AI Search의 OData 구문 다이어그램

참고 항목

전체 EBNF는 Azure AI Search의 OData 식 구문 참조를 참조하세요.

다음 단계

$orderby 및 $select 매개 변수는 더 간단한 식의 쉼표로 구분된 목록입니다. $filter 매개 변수는 더 간단한 하위 식으로 구성된 부울 식입니다. 하위 식은 논리 연산자(예: and, or, not), 비교 연산자(예: eq, lt, gt), 컬렉션 연산자(예: any, all)를 사용하여 결합됩니다.

$filter, $orderby, $select 매개 변수는 다음 문서에서 자세히 설명합니다.