Azure AI Search의 Lucene 쿼리 구문

Azure AI Search에서 쿼리를 만들 때 특수 쿼리 형식(와일드카드, 유사 항목 검색, 근접 검색, 정규식)에 대해 전체 Lucene 쿼리 파서 구문을 선택할 수 있습니다. Lucene 쿼리 파서 구문의 상당 부분이 Azure AI 검색에서 그대로 구현됩니다. 범위 검색은 예외이며 이는 $filter 식을 통해 구성됩니다.

전체 Lucene 구문을 사용하려면 queryType을 full로 설정하고 와일드카드, 유사 항목 검색 또는 전체 구문에서 지원하는 다른 쿼리 형식 중 하나에 패턴이 지정된 쿼리 식을 전달합니다. REST에서는 쿼리 식은 문서 검색(REST API) 요청의 search 매개 변수에 제공됩니다.

예(전체 구문)

다음 예는 전체 구문을 사용하여 생성된 검색 요청입니다. 이 예제에서는 현장 검색 및 용어 부스트가 등장합니다. 카테고리 필드에 budget이라는 용어가 포함된 호텔을 찾습니다. 용어 상승 값 (3)의 결과로 "recently renovated" 문구가 포함된 문서가 더 높은 순위가 됩니다.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

이 예제에서는 특정 쿼리 유형과는 관련이 없지만 searchMode 매개 변수는 관련이 있습니다. 쿼리에서 연산자를 사용할 때마다 일반적으로 searchMode=all을 설정하여 모든 조건이 일치하는지 확인해야 합니다.

더 많은 예제는 Lucene 쿼리 구문 예제를 참조하세요. SearchMode를 비롯한 쿼리 요청 및 매개 변수에 대한 자세한 내용은 문서 검색(REST API)을 참조하세요.

구문 기본 사항

다음 구문 기본 사항은 Lucene 구문을 사용하는 모든 쿼리에 적용됩니다.

컨텍스트의 연산자 평가

배치에 따라 기호가 연산자로 해석될지 아니면 단지 문자열의 다른 문자로 해석될지가 결정됩니다.

예를 들어, Lucene 전체 구문의 경우, 유사 항목 검색 및 근접 검색에 물결표(~)를 사용합니다. 따옴표로 묶은 구 다음에 ~를 배치하면 근접 검색을 호출합니다. 용어 끝에 ~를 배치하면 유사 항목 검색을 호출합니다.

business~analyst와 같은 용어 내에서 해당 문자는 연산자로 평가되지 않습니다. 이 경우 쿼리가 단어 또는 구 쿼리라고 가정할 경우 어휘 분석을 사용한 전체 텍스트 검색은 ~를 제거하고 용어 business~analyst를 business OR analyst의 두 용어로 분할합니다.

위의 예제는 물결표(~)이지만 모든 연산자에 동일한 원칙이 적용됩니다.

특수 문자 이스케이프

검색 텍스트의 일부로 검색 연산자를 사용하려면 단일 백슬래시(\)를 접두사로 사용하여 문자를 이스케이프합니다. 예를 들어 https://에서 ://가 쿼리 문자열의 일부인 와일드카드 검색을 하려면 search=https\:\/\/*을 지정합니다. 마찬가지로 이스케이프된 전화번호 패턴은 \+1 \(800\) 642\-7676과 같을 수 있습니다.

이스케이프가 필요한 특수 문자는 다음과 같습니다.
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

참고 항목

이스케이프 처리하면 토큰이 함께 유지되지만 인덱싱 중 어휘 분석으로 토큰이 제거될 수 있습니다. 예를 들어, 표준 Lucene 분석기는 하이픈, 공백 및 기타 문자의 단어를 분리합니다. 쿼리 문자열에 특수 문자가 필요한 경우 인덱스에 해당 문자가 유지되는 분석기가 필요할 수 있습니다. 일부 옵션에는 하이픈을 넣은 단어를 유지하는 Microsoft 자연어 분석기 또는 보다 복잡한 패턴을 위한 사용자 지정 분석기가 포함됩니다. 자세한 내용은 부분 용어, 패턴 및 특수 문자를 참조하세요.

URL에서 안전하지 않은 문자 및 예약된 문자 인코딩

URL에서 안전하지 않은 문자 및 예약된 문자를 모두 인코딩하세요. 예를 들어 #은 URL에서 조각/앵커 식별자이므로 안전하지 않은 문자입니다. 이 문자는 URL에서 사용할 경우 %23으로 인코딩해야 합니다. & 및 =는 Azure AI Search에서 매개 변수를 구분하고 값을 지정하는 예약 문자의 예입니다. 자세한 내용은 RFC1738: URL(Uniform Resource Locator)을 참조하세요.

안전하지 않은 문자는 " ` < > # % { } | \ ^ ~ [ ]입니다. 예약된 문자는 ; / ? : @ = + &입니다.

부울 연산자

쿼리 문자열에 부울 연산자를 포함하여 일치하는 항목의 정밀도를 높일 수 있습니다. 전체 구문은 문자 연산자 외에도 텍스트 연산자를 지원합니다. 항상 텍스트 부울 연산자(AND, OR, NOT)는 모두 대문자로 지정합니다.

텍스트 연산자	캐릭터	예시	사용
AND	+	wifi AND luxury	일치 항목에 포함되어야 하는 용어를 지정합니다. 이 예에서 쿼리 엔진은 wifi 및 luxury를 모두 포함하는 문서를 찾습니다. 더하기 문자(+)를 용어 앞에 직접 사용하여 필수 문자로 만들 수도 있습니다. 예를 들어, +wifi +luxury는 두 용어가 단일 문서의 필드에 나타나야 한다고 명시합니다.
또는	(없음) 1	wifi OR luxury	용어 중 하나가 발견될 때 일치하는 항목을 찾습니다. 이 예제에서 쿼리 엔진은 wifi 또는 luxury 양쪽 모두를 포함하는 문서에 일치하는 항목을 반환합니다. OR은 기본 결합 연산자이므로 wifi luxury가 wifi OR luxury와 동일한 것처럼 생략할 수도 있습니다.
다음이 아님	!, -	wifi –luxury	용어를 제외한 문서에 일치하는 항목을 반환합니다. 예를 들어 wifi –luxury는 wifi라는 용어는 있지만 luxury는 없는 문서를 검색합니다.

¹ | 문자는 OR 연산에 지원되지 않습니다.

NOT 부울 연산자

Important

NOT 연산자(NOT, ! 또는 -)는 전체 구문에서 단순 구문에서와 다르게 동작합니다.

• 단순 구문에서 부정이 있는 쿼리에는 항상 와일드카드가 자동으로 추가됩니다. 예를 들어 쿼리 -luxury는 자동으로 -luxury *로 확장됩니다.
• 전체 구문에서는 부정이 있는 쿼리를 와일드카드와 결합할 수 없습니다. 예를 들어 쿼리 -luxury *는 허용되지 않습니다.
• 전체 구문에서는 단일 부정이 있는 쿼리는 허용되지 않습니다. 예를 들어 쿼리 -luxury는 허용되지 않습니다.
• 전체 구문에서 부정은 검색 모드에 관계없이 항상 쿼리에 AND로 연결된 것처럼 동작합니다.
  • 예를 들어, 전체 구문의 전체 구문 쿼리 wifi -luxury는 용어 wifi가 포함된 문서만 가져온 다음 해당 문서에 부정 -luxury를 적용합니다.
• 부정을 사용하여 인덱스의 모든 문서를 검색하려는 경우 any 검색 모드를 사용하는 간단한 구문을 사용하는 것이 좋습니다.
• 부정을 사용하여 인덱스의 문서 하위 집합을 검색하려는 경우 전체 구문 또는 모든 검색 모드의 간단한 구문을 사용하는 것이 좋습니다.

쿼리 유형	Search Mode	예제 쿼리	동작
단순	any	wifi -luxury	인덱스 내의 모든 문서를 반환합니다. "wifi"라는 용어가 있는 문서 또는 "luxury"라는 용어가 누락된 문서는 다른 문서보다 순위가 높습니다. 쿼리가 wifi OR -luxury OR *로 확장됩니다.
단순	all	wifi -luxury	"wifi"라는 용어가 들어 있고 "luxury"라는 용어가 포함되지 않은 인덱스의 문서만 반환합니다. 쿼리가 wifi AND -luxury AND *로 확장됩니다.
전체	any	wifi -luxury	"wifi"라는 용어가 포함된 인덱스의 문서만 반환하고 "luxury"라는 용어가 포함된 문서는 결과에서 제거됩니다.
전체	all	wifi -luxury	"wifi"라는 용어가 포함된 인덱스의 문서만 반환하고 "luxury"라는 용어가 포함된 문서는 결과에서 제거됩니다.

필드 지정 검색

fieldName:searchExpression 구문을 사용하여 필드 지정 검색 작업을 정의할 수 있습니다. 여기서 검색 식은 단일 단어나 구 또는 괄호 안의 보다 복잡한 식입니다. 선택적으로 부울 연산자를 사용할 수 있습니다. 몇 가지 예는 다음과 같습니다.

• genre:jazz NOT history

• artists:("Miles Davis" "John Coltrane")

두 문자열이 단일 엔터티로 평가되길 원하는 경우(이 경우에 artists 필드에서 두 개의 다른 예술가 검색) 여러 문자열을 인용 부호로 묶어야 합니다.

fieldName:searchExpression에 지정한 필드는 searchable 필드여야 합니다. 필드 정의에서 인덱스 특성이 사용되는 방법에 대한 자세한 내용은 인덱스 만들기를 참조하세요.

참고 항목

필드 지정 검색 식을 사용할 때 각 필드 지정 검색 식에 명시적으로 지정된 필드 이름이 있으므로 searchFields 매개 변수를 사용할 필요는 없습니다. 그러나 일부 부분의 범위가 특정 필드로 지정되고 나머지는 여러 필드에 적용될 수 있는 쿼리를 실행하려는 경우에도 searchFields 매개 변수를 사용할 수 있습니다. 예를 들어 search=genre:jazz NOT history&searchFields=description 쿼리는 jazz와 genre 필드에서만 일치하지만 NOT history와는 description 필드에서 일치합니다. fieldName:searchExpression에서 제공하는 필드 이름이 항상 searchFields 매개 변수보다 우선 순위를 지닙니다. 따라서 이 예제에서는 searchFields 매개 변수에 genre를 포함할 필요가 없습니다.

유사 항목 검색

유사 항목 검색은 유사한 구성이 있는 일치 항목을 찾아 두 개 이하의 거리 기준을 충족하는 최대 50개 용어로 확장합니다. 자세한 내용은 유사 항목 검색을 참조하세요.

유사 항목 검색을 수행하려면 한 단어의 끝에 물결표(~) 기호를 붙입니다. 그리고 선택적으로 편집 거리를 지정하는 0과 2(기본값) 사이의 수를 매개 변수로 붙입니다. 예를 들어, blue~ 또는 blue~1은 blue, blues 및 glue를 반환합니다.

유사 항목 검색은 따옴표로 묶인 구가 아닌 용어에만 적용할 수 있지만 각 용어에 물결표를 여러 부분으로 구성된 이름이나 구에 추가할 수 있습니다. 예를 들어, Unviersty~ of~ Wshington~은 University of Washington과 일치합니다.

근접 검색

근접 검색은 문서에서 서로 근접한 용어를 찾는 데 사용됩니다. 구 끝에 물결표(~) 기호, 그리고 근접 경계를 생성하는 단어 수를 넣습니다. 예를 들어, "hotel airport"~5는 문서에서 서로 5단어 내에 있는 hotel 및 airport라는 용어를 찾습니다.

용어 상승

용어 상승은 해당 용어가 포함되지 않은 문서에 비해 상승된 용어가 포함된 경우 문서에 더 높은 순위를 지정하는 것을 의미합니다. 이것은 평가 프로필은 특정 용어가 아닌 특정 필드를 상승시킨다는 점에서 평가 프로필과는 다릅니다.

다음 예제는 차이점을 설명하는 데 도움이 됩니다. musicstoreindex 예제에서 genre와 같이 특정 필드에서 일치 항목을 상승시키는 점수 매기기 프로필을 고려해 보세요. 용어 상승은 일부 검색어를 다른 것보다 높게 더 상승시키는 데 사용될 수 있습니다. 예를 들어, rock^2 electronic은 genre 필드에 검색어가 있는 문서를 인덱스의 다른 검색 가능 필드보다 높게 상승시킵니다. 또한, 용어 상승 값(2)의 결과로 rock이라는 검색어가 포함된 문서는 electronic이라는 다른 검색어보다 높은 순위로 매겨집니다.

용어를 상승시키려면 검색 중인 용어 끝 부분에 상승 계수(숫자)와 함께 캐럿 ^ 기호를 사용합니다. 또한 구를 상승시킬 수도 있습니다. 상승 계수가 높을수록 해당 용어는 다른 검색어에 비해 더 관련성이 높아집니다. 부스트 계수는 기본적으로 1입니다. 상승 계수는 양수여야 하지만, 1 미만일 수도 있습니다(예: 0.20).

정규식 검색

정규식 검색은 RegExp 클래스에 설명된 대로 Apache Lucene에서 유효한 패턴을 기준으로 일치하는 항목을 찾습니다.

Azure AI Search에서 정규식은 다음과 같습니다.

• 슬래시 사이에 묶입니다. /
• 소문자 전용

예를 들어 motel 또는 hotel가 포함된 문서를 찾으려면 /[mh]otel/을 지정합니다. 정규식 검색은 단일 단어를 기준으로 일치 항목을 찾습니다.

일부 도구 및 언어는 Azure AI Search에서 이스케이프 규칙을 초과하는 추가 이스케이프 문자 요구 사항을 적용합니다. JSON의 경우 슬래시를 포함하는 문자열은 백슬래시를 사용하여 이스케이프됩니다. microsoft.com/azure/는 search=/.*microsoft.com\/azure\/.*/가 됩니다. 여기서 search=/.* <string-placeholder>.*/는 정규식을 설정하며 microsoft.com\/azure\/는 이스케이프된 슬래시가 있는 문자열입니다.

정규식 쿼리의 두 가지 일반적인 기호는 . 및 *입니다. .는 임의의 한 문자와 일치하고 *는 이전 문자와 0번 이상 일치합니다. 예를 들어, /be./는 용어 bee 및 bet과 일치하지만 /be*/는 be, bee 및 beee와 일치하지만 bet과는 일치하지 않습니다. .*를 함께 사용하면 일련의 문자를 일치시킬 수 있으므로 /be.*/는 better와 같이 be로 시작하는 모든 용어와 일치합니다.

정규식에서 구문 오류가 발생하면 특수 문자에 대한 이스케이프 규칙을 검토합니다. 다른 클라이언트를 시도하여 문제가 도구별 문제인지 확인할 수도 있습니다.

와일드카드 검색

일반적으로 다중(*) 또는 단일(?) 문자 와일드카드 검색에 인식된 구문을 사용할 수 있습니다. Full Lucene 구문은 접두사 및 접두사 일치를 지원합니다. 접미사 일치에 정규식 구문을 사용합니다.

Lucene 쿼리 커서는 구가 아닌 단일 용어에 이러한 기호의 사용을 지원합니다.

접미사 형식	설명 및 예제
prefix	용어 조각은 * 또는 ? 앞에 옵니다. 예를 들어 search=alpha* 쿼리 식은 alphanumeric 또는 alphabetical을 반환합니다. 접두사 일치는 단순 구문 및 전체 구문 모두에서 지원됩니다.
접미사	용어 조각은 * 또는 ? 뒤에 오는 슬래시로 구문을 구분합니다. 예를 들어 search=/.*numeric/는 alphanumeric를 반환합니다.
중위	용어 조각은 * 또는 ?를 묶습니다. 예를 들어 search=non*al은 non-numerical 및 nonsensical을 반환합니다.

하나의 식에서 연산자를 결합할 수 있습니다. 예를 들어, 980?2*은 98072-1222 및 98052-1234와 일치합니다. 여기서 ?는 단일(필수) 문자와 일치하고, *는 뒤에 오는 임의 길이의 문자와 일치합니다.

접미사 일치에는 정규식 슬래시 / 구분 기호가 필요합니다. 일반적으로 /가 없으면 용어의 첫 번째 문자로 * 또는 ? 기호를 사용할 수 없습니다. 또한 정규식 쿼리 외부에서 사용될 때 *가 다르게 동작한다는 점에 유의해야 합니다. 정규식 슬래시 / 구분 기호 외부의 *는 와일드카드 문자이며 정규식의 .*와 같은 일련의 문자와 일치합니다. 예를 들어 search=/non.*al/은 search=non*al과 동일한 결과 집합을 생성합니다.

참고 항목

규칙으로서 패턴 일치는 속도가 느리므로 용어에서 문자 시퀀스에 대한 토큰을 만드는 edge n-gram 토큰화와 같은 대체 메서드를 탐색하는 것이 좋습니다. n-gram 토큰화를 사용하면 인덱스가 더 커지지만 인덱싱 중인 문자열의 길이와 패턴 구성에 따라 쿼리가 더 빠르게 실행될 수 있습니다. 자세한 내용은 특수 문자를 사용하는 부분 용어 검색 및 패턴을 참조하세요.

분석기가 와일드카드 쿼리에 끼치는 영향

쿼리 구문 분석 중에 접두사, 접미사, 와일드카드 또는 정규식으로 작성된 쿼리는 어휘 분석을 우회하여 쿼리 트리에 있는 그대로 전달됩니다. 쿼리에 지정된 형식의 문자열이 인덱스에 포함된 경우에만 일치가 검색됩니다. 대부분의 경우 부분 용어 및 패턴 일치가 성공하도록 문자열 무결성을 유지하는 인덱싱 중에 분석기가 필요합니다. 자세한 내용은 Azure AI Search 쿼리에서 부분 용어 검색을 참조하세요.

검색어 terminal*이 terminate, termination 및 terminates와 같은 용어가 포함된 결과를 반환하도록 하려는 상황을 고려해봅니다.

en.lucene(영어 Lucene) 분석기를 사용하는 경우 각 용어의 적극적 형태소 분석을 적용합니다. 예를 들어 terminate, termination, terminates는 모두 인덱스 내의 토큰 termi로 토큰화됩니다. 하지만 와일드카드 또는 유사 항목 검색을 사용하는 쿼리의 용어는 전혀 분석되지 않으므로 terminat* 쿼리와 일치하는 결과가 없습니다.

반면에 Microsoft 분석기(이 경우에는 en.microsoft 분석기)는 약간 더 고급형이며 형태소 분석 대신 분류 정리를 사용합니다. 그러므로 생성된 모든 토큰은 유효한 영어 단어여야 합니다. 예를 들어 terminate, terminates 및 termination은 대부분 인덱스에서 온전하게 유지되며 와일드카드 및 유사 항목 검색에 많은 영향을 주는 시나리오에 적합합니다.

와일드카드 및 정규식 쿼리 채점

Azure AI Search는 텍스트 쿼리에 대해 빈도 기반 채점(BM25)을 사용합니다. 그러나 용어 범위가 광범위할 수 있는 와일드카드 및 정규식 쿼리의 경우 순위 오류가 발생하여 더 드물게 나오는 용어가 검색되지 않도록 빈도 계수가 무시됩니다. 모든 일치 항목은 와일드카드 및 정규식에 대한 동일하게 처리됩니다.

특수 문자

경우에 따라 ‘❤’ 이모지 또는 ‘€’ 기호와 같은 특수 문자를 검색해야 할 수 있습니다. 이 경우 사용하는 분석기에서 해당 문자를 필터링하지 않는지 확인합니다. 표준 분석기는 인덱스에서 특수 문자를 제외하고 많은 특수 문자를 건너뜁니다.

특수 문자를 토큰화하는 분석기에는 공백 분석기가 포함됩니다. 이 분석기는 공백으로 구분되는 모든 문자 시퀀스를 토큰으로 간주하므로 ❤ 문자열은 토큰으로 간주됩니다. 또한 Microsoft English analyzer(“en.microsoft”)와 같은 언어 분석기는 “€” 문자열을 토큰으로 사용합니다. 분석기를 테스트하여 지정된 쿼리에 생성되는 토큰을 확인할 수 있습니다.

유니코드 문자를 사용하는 경우 쿼리 URL에서 기호가 제대로 이스케이프되었는지 확인합니다. 예를 들어 ❤는 이스케이프 시퀀스 %E2%9D%A4+를 사용합니다. 일부 REST 클라이언트는 이 번역을 자동으로 수행합니다.

우선 순위(그룹화)

괄호를 사용(괄호문 내에 연산자를 포함)하여 하위 쿼리를 만들 수 있습니다. 예를 들어, motel+(wifi|luxury)는 motel 용어와 wifi 또는 luxury(또는 둘 다)가 포함된 문서를 검색합니다.

필드 그룹화는 유사하지만 그룹화 범위가 단일 필드입니다. 예를 들어, hotelAmenities:(gym+(wifi|pool))은 hotelAmenities 필드에서 gym 및 wifi 또는 gym 및 pool을 검색합니다.

쿼리 크기 제한

제한되지 않은 쿼리는 검색 서비스를 불안정하게 만들 수 있으므로 Azure AI Search는 쿼리 크기 및 구성에 제한을 둡니다. 쿼리 크기 및 구성(절 수)에 제한이 있습니다. 접두사 검색 길이와 정규식 검색 및 와일드카드 검색의 복잡성에 대한 제한도 있습니다. 애플리케이션이 검색 쿼리를 프로그래밍 방식으로 생성하는 경우 쿼리가 제한 없는 크기로 생성되지 않도록 디자인하는 것이 좋습니다.

쿼리 제한에 대한 자세한 내용은 API 요청 제한을 참조하세요.

참고 항목

• 단순 검색 위한 쿼리 예제
• 전체 Lucene 검색 쿼리 예제
• 문서 검색
• 필터 및 정렬을 위한 OData 식 구문
• Azure AI Search의 단순 쿼리 구문