Azure Cognitive Search의 Lucene 쿼리 구문

Azure Cognitive Search 쿼리를 만들 때 와일드카드, 유사 항목 검색, 근접 검색, 정규식 등 특수 쿼리 양식에 대한 전체 Lucene 쿼리 파서 구문을 선택할 수 있습니다. Lucene 쿼리 파서 구문의 대부분은 식을 통해 $filter 생성되는 *범위 검색을 제외하고 Azure Cognitive Search 그대로 구현됩니다.

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

예(전체 구문)

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

POST /indexes/hotels-sample-index/docs/search?api-version=2020-06-30
{
  "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 Cognitive Search 값을 지정할 때 예약된 문자의 예입니다. 자세한 내용은 RFC1738: URL(Uniform Resource Locators) 을 참조하세요.

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

부울 연산자

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

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

NOT 연산자(NOT, !또는 -)는 단순 구문과 전체 구문에서 다르게 동작한다는 점에 유의해야 합니다. 전체 구문에서 부정은 매개 변수가 또는 all로 설정되어 any 있는지 searchMode 여부에 관계없이 "wifi AND NOT luxury"로 해석되는 쿼리 wifi -luxury 에 항상 AND가 됩니다. 이렇게 하면 기본적으로 부정에 대한 보다 직관적인 동작이 표시됩니다.

쿼리 -luxury 와 같은 단일 부정은 전체 검색 구문에서 허용되지 않으며 항상 빈 결과 집합을 반환합니다.

1 문자는 | OR 작업에 지원되지 않습니다.

필드 지정 검색

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

  • genre:jazz NOT history

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

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

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

참고

필드 지정 검색 식을 사용할 때 각 필드 지정 검색 식에 명시적으로 지정된 필드 이름이 있으므로 searchFields 매개 변수를 사용할 필요는 없습니다. 그러나 일부 부분의 범위가 특정 필드로 지정되고 나머지는 여러 필드에 적용될 수 있는 쿼리를 실행하려는 경우에도 searchFields 매개 변수를 사용할 수 있습니다. 예를 들어 search=genre:jazz NOT history&searchFields=description 쿼리는 jazzgenre 필드에서만 일치하지만 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 예제장르와 같이 특정 필드에서 일치 항목을 향상시키는 점수 매기기 프로필이 있다고 가정합니다. 용어 상승은 일부 검색어를 다른 것보다 높게 더 상승시키는 데 사용될 수 있습니다. 예를 들어, rock^2 electronic은 genre 필드에 검색어가 있는 문서를 인덱스의 다른 검색 가능 필드보다 높게 상승시킵니다. 또한, 용어 상승 값(2)의 결과로 rock이라는 검색어가 포함된 문서는 electronic이라는 다른 검색어보다 높은 순위로 매겨집니다.

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

정규식 검색

정규식 검색은 RegExp 클래스에 설명된 대로 Apache Lucene에서 유효한 패턴을 기준으로 일치하는 항목을 찾습니다. Azure Cognitive Search에서 정규식은 슬래시(/)로 묶여 있습니다.

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

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

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

와일드카드 검색

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

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

접미사 형식 설명 및 예제
접두사 용어 조각은 * 또는 ? 앞에 옵니다. 예를 들어 search=alpha*의 쿼리 식은 “영숫자” 또는 “사전순”을 반환합니다. 접두사 일치는 단순 구문 및 전체 구문 모두에서 지원됩니다.
suffix 용어 조각은 구문을 구분하는 슬래시와 함께 또는 ?뒤에 * 옵니다. 예를 들어 는 search=/.*numeric/ "영숫자"를 반환합니다.
중위 용어 조각은 * 또는 ?를 묶습니다. 예를 들어 는 search=non*al "숫자가 아닌" 및 "무의미한"을 반환합니다.

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

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

참고

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

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

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

검색 쿼리 ‘terminat*’에서 ‘terminate’, ‘termination’ 및 ‘terminates’와 같은 용어를 포함하는 결과를 반환하도록 하려는 경우를 가정해봅니다.

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

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

와일드카드 및 정규식 쿼리 점수 매기기

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

특수 문자

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

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

유니코드 문자를 사용하는 경우 쿼리 URL에서 기호가 제대로 이스케이프되었는지 확인합니다. 예를 들어 “❤”는 이스케이프 시퀀스 %E2%9D%A4+를 사용합니다. Postman은 이 변환을 자동으로 수행합니다.

우선 순위(그룹화)

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

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

쿼리 크기 제한

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

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

참고 항목