전체 텍스트 검색 시나리오의 경우 Azure AI 검색 각각 쿼리 파서에 정렬된 두 개의 Lucene 기반 쿼리 언어를 구현합니다. 단순 쿼리 파서가 기본값입니다. 일반적인 사용 사례를 다루며 완벽하게 구성되지 않은 경우에도 요청을 해석하려고 시도합니다. 다른 파서는 Lucene 쿼리 파서 이며 고급 쿼리 생성을 지원합니다.
이 문서는 간단한 쿼리 파서에 대한 쿼리 구문 참조입니다.
두 파서의 쿼리 구문은 search의 매개 변수에 전달된 쿼리 식에 적용됩니다. 이는 OData 구문과는 구분되며, 동일한 요청 내에서 filter 및 orderby 표현 식에 대해 자체 구문 및 규칙을 따릅니다.
단순 파서는 Apache Lucene Simple Query Parser 클래스를 기반으로 하지만, Azure AI 검색의 구현에서는 퍼지 검색을 포함하지 않습니다. 퍼지 검색이 필요한 경우, 대신 전체 Lucene 쿼리 구문을 고려하세요.
예제(단순 구문)
이 예제에서는 유효한 구문으로 "queryType": "simple"로 구별되는 간단한 쿼리를 보여줍니다. 쿼리 형식은 아래에 설정되어 있지만 기본값이며 대체 형식에서 되돌리지 않는 한 생략할 수 있습니다. 다음 예제는 일치하는 모든 문서에 "pool"이 포함되어야 하는 독립 용어를 검색하는 것입니다.
POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2025-09-01
{
"queryType": "simple",
"search": "budget hotel +pool",
"searchMode": "all"
}
매개 searchMode 변수는 이 예제에서 관련이 있습니다. 부울 연산자가 쿼리에 있을 때마다 일반적으로 searchMode=all 조건이 일치하도록 설정 해야 합니다. 그렇지 않으면 정밀도보다 재현율을 선호하는 기본값 searchMode=any 을 사용할 수 있습니다.
자세한 예제는 단순 쿼리 구문 예제를 참조하세요. 쿼리 요청 및 매개 변수에 대한 자세한 내용은 문서 검색(REST API)을 참조하세요.
용어와 구문에 대한 키워드 검색
매개 변수에 search 전달된 문자열에는 지원되는 언어, 부울 연산자, 우선 순위 연산자, "starts with" 쿼리, 이스케이프 문자 및 URL 인코딩 문자에 대한 와일드카드 또는 접두사 문자의 용어 또는 구가 포함될 수 있습니다. 매개 변수는 search 선택 사항입니다. 지정되지 않은 검색(search=* 또는 search=" ")은 상위 50개 문서를 임의(순위가 지정되지 않은) 순서로 반환합니다.
용어 검색은 하나 이상의 용어를 쿼리하는 것으로, 용어 중 하나가 일치하는 것으로 간주됩니다.
구문 검색은 따옴표
" "로 묶인 정확한 구문입니다. 예를 들어(따옴표가 없으면) 순서에 관계없이Roach Motel및/또는Roach임의의 순서로 문서를 검색하는 반면Motel("Roach Motel"따옴표 포함)는 해당 전체 구를 함께 포함하는 문서와 해당 순서로 일치하는 문서만 일치합니다(어휘 분석은 계속 적용됨).
검색 클라이언트에 따라 구문 검색에서 따옴표를 이스케이프해야 할 수 있습니다. 예를 들어 POST 요청에서 요청 본문에 있는 "Roach Motel"에 대한 구문 검색은 "\"Roach Motel\""와 같이 지정될 수 있습니다. Azure SDK들을 사용하는 경우, 검색 클라이언트는 검색 텍스트를 직렬화할 때 따옴표를 이스케이프 처리합니다. 검색 구를 "Roach Motel"으로 보낼 수 있습니다.
기본적으로 매개 변수에 전달된 모든 문자열은 search 어휘 분석을 거칩니다. 사용 중인 분석기의 토큰화 동작을 이해해야 합니다. 쿼리 결과가 예기치 않은 경우가 많을 때 쿼리 시간에 용어가 토큰화되는 방식을 추적할 수 있습니다.
특정 문자열에 대한 토큰화를 테스트하여 출력을 확인할 수 있습니다.
하나 이상의 용어가 있는 텍스트 입력은 쿼리 실행을 위한 유효한 시작점으로 간주됩니다. Azure AI 검색는 텍스트를 분석하는 동안 발견된 변형을 포함하여, 용어가 하나라도 포함되거나 모든 용어가 포함된 문서를 찾습니다.
이것이 간단해 보일 수 있지만, Azure AI 검색의 쿼리 실행 한 측면은 입력 문자열에 더 많은 용어와 연산자가 추가되었을 때 검색 결과가 감소하기보다 오히려 증가하는 예기치 않은 결과를 초래할 수 있습니다. 이 확장이 실제로 발생하는지는 NOT 연산자의 포함 여부와 searchMode 또는 OR 동작을 기준으로 NOT이 어떻게 해석되는지를 결정하는 매개변수 설정에 따라 달라집니다. 자세한 내용은 NOT를 부울 연산자 아래에서 참조하세요.
부울 연산자
쿼리 문자열에 부울 연산자를 포함시켜 일치의 정밀도를 향상시킬 수 있습니다. 단순 구문에서 부울 연산자는 문자 기반입니다. AND라는 단어와 같은 텍스트 연산자는 지원되지 않습니다.
| 문자 | 예제 | 사용 |
|---|---|---|
+ |
pool + ocean |
AND 작업입니다. 예를 들어 pool + ocean 문서에 두 용어가 모두 포함되어야 한다고 규정합니다. |
| |
pool | ocean |
OR 작업은 두 용어 중 하나가 발견될 때 일치 항목을 찾습니다. 예제에서 쿼리 엔진은 pool 또는 ocean 또는 둘 다를 포함하는 문서에서 일치 항목을 반환합니다.
OR 기본 결합 연산자이므로 그대로 둘 수도 있습니다. 이 연산자는 다음과 pool ocean 같습니다pool | ocean. |
- |
pool – ocean |
연산은 NOT 용어를 제외하는 문서에서 일치하는 항목을 반환합니다. 쿼리 요청의 매개 변수는 searchMode 연산자가 있는 NOT 용어가 ANDOR쿼리의 다른 용어로 처리되는지 여부를 제어합니다(다른 용어에는 부울 연산자가 없다고 가정). 유효한 값은 any 또는 all입니다.
searchMode=any 는 더 많은 결과를 포함하여 쿼리 회수를 증가시키고, 기본적으로 - "OR NOT"으로 해석됩니다. 예를 들어, pool - ocean는 용어 pool가 포함된 문서 또는 용어 ocean가 포함되지 않은 문서와 일치합니다.
searchMode=all 는 더 적은 결과를 포함함으로써 쿼리의 정확성을 높이고, 기본 설정으로는 - "AND NOT"으로 해석됩니다. 예를 들어 쿼리 searchMode=anypool - ocean 는 "pool"이라는 용어가 포함된 문서와 "ocean"이라는 용어가 포함되지 않은 모든 문서와 일치합니다. 이는 틀림 없는 연산자에 대한 보다 직관적인 동작입니다 - . 재현율보다는 정밀도를 중시하여 검색을 최적화하려는 경우, searchMode=any 대신 searchMode=all을 사용하는 것을 고려해야 하며, 사용자가 검색에서 - 연산자를 자주 사용합니다. 설정을 결정할 searchMode 때 다양한 애플리케이션의 쿼리에 대한 사용자 상호 작용 패턴을 고려합니다. 정보를 검색하는 사용자는 기본 제공 탐색 구조가 더 많은 전자 상거래 사이트와 달리 쿼리에 운영자를 포함할 가능성이 더 높습니다. |
접두사 쿼리
"starts with" 쿼리의 경우 용어의 나머지 부분에 대한 자리 표시자로 접미사 연산자(*)를 추가합니다. 접두사 연산자를 추가하려면 접두사 쿼리를 하나 이상의 일반 텍스트 문자로 시작해야 합니다.
| 문자 | 예제 | 사용 |
|---|---|---|
* |
lingui*는 "linguistic" 또는 "linguini"에서 일치합니다. |
별표(*)는 임의의 길이의 하나 이상의 문자를 나타내며, 대/소문자는 무시됩니다. |
필터와 마찬가지로 접두사 쿼리는 정확히 일치하는 항목을 찾습니다. 따라서 관련성 점수는 없습니다(모든 결과는 검색 점수 1.0을 받습니다). 특히 인덱스가 크고 접두사는 적은 수의 문자로 구성된 경우 접두사 쿼리가 느려질 수 있습니다. 에지 n-gram 토큰화와 같은 대체 방법론이 더 빠르게 수행될 수 있습니다. 접두사 검색을 사용하는 용어는 1000자를 초과할 수 없습니다.
단순 구문은 접두사 일치만 지원합니다. 용어의 끝이나 중간에 대해 접미사 또는 중간 일치를 수행하려면 와일드카드 검색을 위한 전체 Lucene 구문을 사용하세요.
검색 연산자 이스케이프
단순 구문에서 검색 연산자는 다음 문자를 포함합니다. + | " ( ) ' \
이러한 문자 중 하나라도 인덱스의 토큰에 포함된 경우 쿼리에 단일 백슬래시(\)를 접두사로 추가하여 이스케이프합니다. 예를 들어 전체 용어 토큰화에 사용자 지정 분석기를 사용했으며 인덱스에 "Luxury+Hotel" 문자열이 포함되어 있다고 가정합니다. 이 토큰과 정확히 일치하려면 이스케이프 문자를 search=luxury\+hotel삽입합니다.
보다 일반적인 경우에 대해 작업을 간단하게 하기 위해 이스케이프가 필요하지 않은 이 규칙에는 두 가지 예외가 있습니다.
NOT 연산자
-는 공백 뒤에 오는 첫 번째 문자일 경우에만 이스케이프되어야 합니다.-가 중간에 나타나는 경우(예:3352CDD0-EF30-4A2E-A512-3B30AF40F3FD에서), 이스케이프를 생략할 수 있습니다.접미사 연산자
*는 공백 앞의 마지막 문자인 경우에만 이스케이프해야 합니다.*중간에 나타나는 경우(예: in4*4=16) 이스케이프가 필요하지 않습니다.
참고
기본적으로 표준 분석기는 어휘 분석 중에 하이픈, 공백, 앰퍼샌드 및 기타 문자를 기준으로 단어를 삭제하고 분리합니다. 쿼리 문자열에 특수 문자를 유지해야 하는 경우 인덱스에 해당 문자를 유지하는 분석기가 필요할 수 있습니다. 일부 선택 항목으로는 하이픈을 넣은 단어를 보존하는 Microsoft 자연 언어 분석기 또는 더 복잡한 패턴에 대한 사용자 지정 분석기가 포함됩니다. 자세한 내용은 부분 용어, 패턴 및 특수 문자를 참조하세요.
URL에서 안전하지 않고 예약된 문자 인코딩
안전하지 않은 문자와 예약된 문자가 모두 URL로 인코딩되었는지 확인합니다. 예를 들어 '#'은 URL의 조각/앵커 식별자이므로 안전하지 않은 문자입니다. URL에 사용되는 경우 문자를 인코딩 %23 해야 합니다. '(&S) '와 '='는 매개 변수를 구분하고 Azure AI 검색 값을 지정하는 예약 문자의 예입니다. 자세한 내용은 RFC1738: URL(Uniform Resource Locators)을 참조하세요.
안전하지 않은 문자는 다음과 같습니다 " ` < > # % { } | \ ^ ~ [ ]. 예약 문자는 ; / ? : @ = + &입니다.
특수 문자
특수 문자는 '$' 또는 '€'와 같은 통화 기호에서 이모지까지 다양할 수 있습니다. 기본 표준 분석기를 포함한 많은 분석기는 인덱싱 중에 특수 문자를 제외하므로 인덱스로 표시되지 않습니다.
특수 문자 표현이 필요한 경우 이를 유지하는 분석기를 할당할 수 있습니다.
공백 분석기는 공백으로 구분된 문자 시퀀스를 토큰으로 간주합니다('❤' 이모지는 토큰으로 간주됨).
Microsoft 영어 분석기()와 같은
en.microsoft는 '$' 또는 '€' 문자열을 토큰으로 사용합니다.
확인을 위해 분석기를 테스트 하여 지정된 문자열에 대해 생성된 토큰을 확인할 수 있습니다. 예상한 대로 단일 분석기에서 전체 토큰화를 가져오지 못할 수 있습니다. 해결 방법은 동일한 콘텐츠를 포함하지만 다른 분석기 할당(예description_endescription_fr: 언어 분석기의 경우 등)을 포함하는 여러 필드를 만드는 것입니다.
유니코드 문자를 사용하는 경우 쿼리 URL에서 기호가 제대로 이스케이프되었는지 확인합니다(예: '❤'은 이스케이프 시퀀스를 %E2%9D%A4+사용). 일부 웹 클라이언트는 이 번역을 자동으로 수행합니다.
우선 순위(그룹화)
괄호를 사용하여 괄호 문 내의 연산자를 포함하여 하위 쿼리를 만들 수 있습니다. 예를 들어 motel+(wifi|luxury) "motel" 용어와 "wifi" 또는 "luxury"(또는 둘 다)가 포함된 문서를 검색합니다.
쿼리 크기 제한
애플리케이션이 프로그래밍 방식으로 검색 쿼리를 생성하는 경우 바인딩되지 않은 크기의 쿼리를 생성하지 않는 방식으로 디자인하는 것이 좋습니다.
GET의 경우 URL 길이는 8KB를 초과할 수 없습니다.
요청 본문에
search와 같은 매개 변수(filter,orderby등)가 포함된 POST(및 기타 요청)의 경우, 최대 크기가 16 MB입니다. 추가 제한은 다음과 같습니다.- 검색 절의 최대 길이는 100,000자입니다.
- 최대 절의 수
search(AND 또는 OR로 구분된 표현)는 1024입니다. - 최대 검색어 크기는 접두사 검색의 경우 1000자입니다.
- 쿼리의 개별 용어 크기에는 약 32KB의 제한이 있습니다.
쿼리 제한에 대한 자세한 내용은 API 요청 제한을 참조하세요.
다음 단계
프로그래밍 방식으로 쿼리를 생성하는 경우 Azure AI 검색의 텍스트 검색을 검토하여 쿼리 처리 단계와 텍스트 분석의 의미를 이해합니다.
다음 문서를 검토하여 쿼리 생성에 대해 자세히 알아볼 수도 있습니다.