Foundry IQ(Azure AI 검색)에서
참고
Foundry IQ (Azure AI 검색)는 관리 검색을 위해 고급 수준의 지식 원본 API 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.
이 문서에서는 숫자 및 $select 문자열(비벡터) 필드에 대한 foundry IQ(Azure AI 검색)의 키워드 검색에 사용되는 $filter$order-byOData 식 언어 및 식에 대한 개요를 제공합니다.
언어는 가장 기본적인 요소로 시작하는 “상향식”으로 표시됩니다. 쿼리 요청에서 생성할 수 있는 OData 식은 단순한 것에서 매우 복잡한 것까지 다양하지만 모두 공통 요소를 공유합니다. 공유 요소는 다음과 같습니다.
- 인덱스의 특정 필드를 참조하는 필드 경로입니다.
- 특정 데이터 형식의 리터럴 값인 상수입니다.
이러한 일반적인 개념을 이해한 후에는 각 식에 대한 최상위 구문을 계속 사용할 수 있습니다.
- $filter 식은 쿼리 구문 분석 중에 평가되며, 특정 필드로 검색을 제한하거나 인덱스 스캔 중에 사용되는 일치 조건을 추가합니다.
- $orderby 식은 반환되는 문서를 정렬하기 위해 결과 집합에 대한 사후 처리 단계로 적용됩니다.
- $select 식은 결과 집합에 포함되는 문서 필드를 결정합니다.
필드 참조 구문에 겹치는 부분이 있기는 하지만 search 매개 변수에서 사용되는 simple 또는 full 쿼리 구문과 위의 식 구문은 구분됩니다.
Python 또는 C#과 같은 다른 언어의 예제는 azure-search-vector-samples 리포지토리의 예제를 참조하세요.
참고
Foundry IQ의 용어는 몇 가지 방법으로 OData 표준 과 다릅니다. Foundry IQ에서 필드라고 부르는 것은 OData에서는 속성이라고 하며, 필드 경로도 마찬가지로 OData에서는 속성 경로라고 합니다. Foundry IQ의 인덱스는 문서를 포함하며, OData에서는 더 일반적으로 엔터티 집합이 엔터티를 포함하는 것으로 지칭됩니다. Foundry IQ 용어는 이 참조 전체에서 사용됩니다.
필드 경로
다음 EBNF(Extended Backus-Naur Form)는 필드 경로의 문법을 정의합니다.
field_path ::= identifier('/'identifier)*
identifier ::= [a-zA-Z_][a-zA-Z_0-9]*
다음과 같은 대화형 구문 다이어그램도 사용할 수 있습니다.
참고
전체 EBNF 에 대한 Foundry IQ에 대한 OData 식 구문 참조 를 참조하세요.
필드 경로는 슬래시로 구분된 하나 이상의 식별자로 구성됩니다. 각 식별자는 ASCII 문자 또는 밑줄로 시작하고 ASCII 문자, 숫자 또는 밑줄만 포함해야 하는 문자 시퀀스입니다. 문자는 대문자나 소문자일 수 있습니다.
식별자는 필드 이름 또는 필터의 컬렉션 식 컨텍스트에서 사용된 범위 변수(any 또는 all)를 참조할 수 있습니다. 범위 변수는 컬렉션의 현재 요소를 나타내는 루프 변수와 유사합니다. 복합 컬렉션에서 해당 변수는 개체를 나타내며, 필드 경로를 사용하여 변수의 하위 필드를 참조할 수 있는 이유는 이 때문입니다. 대부분의 프로그래밍 언어에서 사용되는 점 표기법과 유사합니다.
다음 표에는 필드 경로 예제가 나와 있습니다.
| 필드 경로 | 설명 |
|---|---|
HotelName |
인덱스의 최상위 필드를 참조합니다. |
Address/City |
인덱스의 복합 필드에서 City 하위 필드를 참조합니다. 예제에서 Address는 Edm.ComplexType 형식입니다. |
Rooms/Type |
인덱스의 복합 컬렉션 필드에서 Type 하위 필드를 참조합니다. 예제에서 Rooms는 Collection(Edm.ComplexType) 형식입니다. |
Stores/Address/Country |
인덱스의 복합 컬렉션 필드에서 Country 하위 필드의 Address 하위 필드를 참조합니다. 예제에서 Stores는 Collection(Edm.ComplexType) 형식이고 Address는 Edm.ComplexType 형식입니다. |
room/Type |
Type 범위 변수의 room 하위 필드를 참조합니다(예: 필터 식 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 하위 필드를 참조합니다(예: 첫 번째 객실은 “standard”, 두 번째 객실은 “deluxe”).
Rooms/Type은 하위 필드 에 있는 단일 인스턴스를 참조하지 않으므로 필터에서 직접 사용할 수 없습니다. 대신, 객실 유형을 필터링하려면 다음과 같이 범위 변수와 함께 람다 식을 사용합니다.
Rooms/any(room: room/Type eq 'deluxe')
예제에서는 범위 변수 room이 room/Type 필드 경로에 표시됩니다. 이런 방식으로 room/Type은 현재 문서의 현재 객실 유형을 참조합니다.
Type 하위 필드의 단일 인스턴스이므로 필터에서 직접 사용할 수 있습니다.
필드 경로 사용
필드 경로는 Foundry IQ REST API의 많은 매개 변수에서 사용됩니다. 다음 표에는 이를 사용할 수 있는 모든 위치와 사용 제한 사항이 나와 있습니다.
| 응용 프로그램 인터페이스 (API) | 매개 변수 이름 | 제한 사항 |
|---|---|---|
| 인덱스 만들기 또는 인덱스 업데이트 | suggesters/sourceFields |
없음 |
| 만들기 또는 업데이트 인덱스 | scoringProfiles/text/weights |
검색 가능한 필드만 참조할 수 있습니다. |
| 인덱스 만들기 또는 업데이트 | scoringProfiles/functions/fieldName |
필터링 가능한 필드만 참조할 수 있습니다. |
| 검색 |
search
queryType이 full일 때 |
검색 가능한 필드만 참조할 수 있습니다. |
| 검색 | facet |
분류 가능 필드만 참조할 수 있습니다. |
| 검색 | highlight |
검색 가능한 필드만 참조할 수 있습니다. |
| 검색 | searchFields |
검색 가능한 필드만 참조할 수 있습니다. |
| Suggest 및 Autocomplete | searchFields |
제안기의 일부인 필드만 참조할 수 있습니다. |
| 검색, 제안 및 자동 완성 | $filter |
필터링 가능한 필드만 참조할 수 있습니다. |
| 검색 및 Suggest | $orderby |
정렬 가능한 필드만 참조할 수 있습니다. |
| 검색, 제안 및 조회 | $select |
검색 가능한 필드만 참조할 수 있습니다. |
상수
OData의 상수는 지정된 EDM(엔터티 데이터 모델) 형식의 리터럴 값입니다. Foundry IQ에서 지원되는 데이터 형식 목록은 지원되는 데이터 형식을 참조하세요. 컬렉션 형식의 상수는 지원되지 않습니다.
다음 표에는 OData 식을 지원하는 각 비벡터 데이터 형식의 상수 예제가 나와 있습니다.
| 데이터 형식 | 예제 상수 |
|---|---|
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)는 위의 표에 있는 대부분의 상수의 문법을 정의합니다. 지역 공간 형식에 대한 문법은 Foundry IQ의 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는 Foundry IQ용 OData 식 구문 참조를 참조하세요.
필드 경로 및 상수에서 식 작성
필드 경로와 상수는 OData 식의 가장 기본적인 부분이지만 이미 전체 식이기도 합니다. 실제로 Foundry IQ의 $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는 Foundry IQ용 OData 식 구문 참조를 참조하세요.
다음 단계
$orderby 및 $select 매개 변수는 더 간단한 식의 쉼표로 구분된 목록입니다.
$filter 매개 변수는 더 간단한 하위 식으로 구성된 부울 식입니다. 하위 식은 논리 연산자(예: and, or, not), 비교 연산자(예: eq, lt, gt), 컬렉션 연산자(예: any, all)를 사용하여 결합됩니다.
$filter, $orderby, $select 매개 변수는 다음 문서에서 자세히 설명합니다.