및 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 문자, 숫자 또는 밑줄만 포함해야 하는 문자 시퀀스입니다. 문자는 대문자 또는 소문자일 수 있습니다.

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

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

필드 경로 설명
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고려합니다. 필터에서 이것은 현재 문서의 단일 도시(예: "San Francisco")를 나타냅니다. 반면, 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 when queryType is full 검색 가능한 필드만 참조할 수 있습니다.
검색 facet 패싯 가능 필드만 참조할 수 있습니다 .
검색 highlight 검색 가능한 필드만 참조할 수 있습니다.
검색 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 매개 변수는 다음 문서에서 자세히 설명합니다.