다음을 통해 공유

Azure AI 검색의 단순 쿼리 구문

  • 아티클

전체 텍스트 검색 시나리오의 경우 Azure AI 검색은 두 개의 Lucene 기반 쿼리 언어를 구현하며 각 언어는 쿼리 파서에 맞춰 정렬됩니다. 단순 쿼리 파서가 기본값입니다. 일반적인 사용 사례를 다루며 요청이 완벽하게 구성되지 않은 경우에도 요청을 해석하려고 시도합니다. 다른 파서는 Lucene 쿼리 파서이며 고급 쿼리 구성을 지원합니다.

이 문서는 간단한 쿼리 파서에 대한 쿼리 구문 참조입니다.

두 파서에 대한 쿼리 구문은 동일한 요청에서 filter 및 orderby 식에 대한 자체 구문 및 규칙을 사용하여 OData 구문과 혼동하지 않도록 쿼리 요청의 search 매개 변수에 전달된 쿼리 식에 적용됩니다.

단순 파서는 Apache Lucene 단순 쿼리 파서 클래스를 기준으로 하지만 Azure AI 검색의 구현에서는 유사 항목 검색이 제외됩니다. 유사 항목 검색을 수행해야 하는 경우 대체 전체 Lucene 쿼리 구문을 대신 사용해 보세요.

예(단순 구문)

이 예제에서는 "queryType": "simple" 및 유효한 구문으로 구분된 간단한 쿼리를 보여줍니다. 아래에는 쿼리 형식이 설정되어 있지만 기본값이므로 대체 형식에서 원래로 되돌리지 않는 한, 생략할 수 있습니다. 다음 예에서는 일치하는 모든 문서에 "pool"이 포함되어야 한다는 요구 사항에 따라 독립적인 용어를 검색합니다.

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2024-07-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

searchMode 매개 변수가 이 예제에 해당 합니다. 쿼리에서 부울 연산자를 사용할 때마다 일반적으로 searchMode=all을 설정하여 모든 조건이 일치하는지 확인해야 합니다. 그렇지 않은 경우 정밀도보다 재현율을 고려하는 기본 searchMode=any를 사용할 수 있습니다.

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

용어 및 구에 대한 키워드 검색

search 매개 변수에 전달되는 문자열에는 지원되는 언어의 용어나 구, 부울 연산자, 선행 연산자, 와일드카드 또는 접두사 문자("시작" 쿼리, 이스케이프 문자 및 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 검색의 쿼리 실행 측면이 있습니다. 이 확장이 실제로 발생하는지 여부는 AND 또는 OR 동작 측면에서 NOT이 해석되는 방식을 결정하는 searchMode 매개 변수 설정과 결합된 NOT 연산자의 포함에 따라 달라집니다. 자세한 내용은 부울 연산자에서 NOT 연산자를 참조하세요.

부울 연산자

쿼리 문자열에 부울 연산자를 포함하여 일치하는 항목의 정밀도를 높일 수 있습니다. 단순 구문에서 부울 연산자는 문자를 기준으로 합니다. 단어 AND와 같은 텍스트 연산자는 지원되지 않습니다.

캐릭터 예시 사용
+ pool + ocean AND 연산. 예를 들어 pool + ocean은 문서에 두 용어를 모두 포함해야 한다고 규정합니다.
| pool | ocean OR 연산은 두 용어 중 하나가 발견되면 일치하는 항목을 찾습니다. 이 예제에서 쿼리 엔진은 pool 또는 ocean 양쪽 모두를 포함하는 문서에 일치하는 항목을 반환합니다. OR은 기본 결합 연산자이므로 pool ocean이 pool | ocean과 동일한 것처럼 생략할 수도 있습니다.
- pool – ocean NOT 연산은 해당 용어를 제외한 문서에 일치하는 항목을 반환합니다.

쿼리 요청의 searchMode 매개 변수는 NOT 연산자를 사용하는 용어가 쿼리의 다른 용어와 함께 ANDed 또는 ORed 여부를 제어합니다(다른 용어에 부울 연산자가 없다고 가정). 유효한 값은 any나 all입니다.

searchMode=any를 사용하는 경우 더 많은 결과를 포함하여 쿼리 재현율을 높이고, 기본값으로 -는 “OR NOT”으로 해석됩니다. 예를 들어, pool - ocean는 용어 pool를 포함하는 문서 또는 용어 ocean를 포함하지 않는 문서를 검색합니다.

searchMode=all은 더 작은 결과를 포함하여 쿼리의 정밀도를 늘리고, 기본값으로 -는 “AND NOT”으로 해석됩니다. 예를 들어 searchMode=any를 사용하면 쿼리 pool - ocean은 “pool”이라는 용어가 포함된 문서와 “ocean”이라는 용어가 포함되지 않은 모든 문서와 일치합니다. 이러한 동작이 - 연산자의 좀 더 간단한 동작일 것입니다. 따라서 searchMode=all을 searchMode=any 대신 사용하는 것이 재현율이 아니라 정밀도에 따라 최적화하고자 하거나 사용자가 검색에서 - 연산자를 자주 사용하는 경우 좋습니다.

searchMode 설정을 결정할 때 다양한 애플리케이션의 쿼리에 대한 사용자 상호 작용 패턴을 고려합니다. 정보를 검색하는 사용자는 더 많은 기본 제공 탐색 구조를 포함하는 전자상거래 사이트와는 달리 쿼리에 연산자를 포함할 가능성이 높습니다.

접두사 쿼리

"다음으로 시작함" 쿼리의 경우 접미사 연산자(*)를 용어의 나머지에 대한 자리 표시자로 추가합니다. 접미사 연산자를 추가하려면 접두사 쿼리를 하나 이상의 영숫자 문자로 시작해야 합니다.

캐릭터 예시 사용
* lingui*는 "linguistic" 또는 "linguini"를 일치 항목으로 간주합니다. 별표(*)는 대/소문자를 무시하는 임의 길이를 갖는 하나 이상의 문자를 나타냅니다.

필터와 마찬가지로 접두사 쿼리는 정확히 일치하는 항목을 찾습니다. 따라서 관련성 점수 매기기는 없습니다(모든 결과가 1.0의 검색 점수를 받음). 특히 인덱스가 크고 접두사가 적은 수의 문자로 구성된 경우 접두사 쿼리 속도가 느려질 수 있습니다. 에지 n-Gram 토큰화와 같은 대체 방법은 더 빠르게 작동할 수 있습니다. 접두사 검색을 사용하는 용어는 1000자를 초과할 수 없습니다.

단순 구문은 접두사 일치만 지원합니다. 용어 끝 또는 중간에 대해 접미사 또는 중위 일치를 사용하는 경우 와일드카드 검색의 전체 Lucene 구문을 사용합니다.

검색 연산자 이스케이프

단순 구문에서 검색 연산자는 + | " ( ) ' \ 문자를 포함합니다.

이러한 문자가 인덱스에 있는 토큰의 일부인 경우 쿼리에서 단일 백슬래시(\)를 접두사로 추가하여 이스케이프합니다. 예를 들어, 전체 용어 토큰화를 위해 사용자 지정 분석기를 사용했으며 인덱스에 "Luxury+Hotel" 문자열이 포함되어 있다고 가정합니다. 이 토큰과 정확히 일치하는 항목을 가져오려면 이스케이프 문자 search=luxury\+hotel을 삽입합니다.

좀 더 일반적인 경우에서 좀 더 간단히 나타내기 위해 이스케이프가 필요하지 않은 다음과 같은 예외 규칙 2가지를 살펴보겠습니다.

  • NOT 연산자 -은 공백 뒤의 첫 번째 문자인 경우에만 이스케이프해야 합니다. -이 중간에 나타나면(예: 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD) 이스케이프를 건너뛸 수 있습니다.

  • 접미사 연산자 *는 공백 앞의 마지막 문자인 경우에만 이스케이프해야 합니다. *가 중간에 나타나면(예: 4*4=16) 이스케이프가 필요하지 않습니다.

참고 항목

기본적으로 표준 분석기는 어휘 분석 동안 하이픈, 공백, 앰퍼샌드 및 기타 문자에서 단어를 삭제하고 끊습니다. 쿼리 문자열에 특수 문자를 유지해야 할 경우 인덱스에 해당 문자가 유지되는 분석기가 필요할 수 있습니다. 일부 옵션에는 하이픈을 넣은 단어를 유지하는 Microsoft 자연어 분석기또는 보다 복잡한 패턴을 위한 사용자 지정 분석기가 포함됩니다. 자세한 내용은 부분 용어, 패턴 및 특수 문자를 참조하세요.

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

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

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

특수 문자

특수 문자는 ‘$’ 또는 ‘€’와 같은 통화 기호에서 이모지까지 다양할 수 있습니다. 기본 표준 분석기를 포함한 많은 분석기는 인덱싱 중에 특수 문자를 제외하므로 인덱스에 표시되지 않습니다.

특수 문자 표현이 필요한 경우 이를 유지하는 분석기를 할당할 수 있습니다.

  • 공백 분석기는 공백으로 구분된 문자 시퀀스를 토큰으로 간주하므로 ‘❤’ 이모지는 토큰으로 간주됩니다.

  • Microsoft English analyzer(en.microsoft)와 같은 언어 분석기는 ‘$’ 또는 ‘€’ 문자열을 토큰으로 사용합니다.

확인을 위해 분석기를 테스트하여 지정된 문자열에 대해 생성된 토큰을 확인할 수 있습니다. 예상한 대로 단일 분석기에서 전체 토큰화를 얻지 못할 수 있습니다. 해결 방법은 동일한 콘텐츠를 포함하지만 다른 분석기 할당(예: 언어 분석기에 대해 description_en, description_fr 등)을 사용하여 여러 필드를 만드는 것입니다.

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

우선 순위(그룹화)

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

쿼리 크기 제한

애플리케이션이 검색 쿼리를 프로그래밍 방식으로 생성하는 경우 쿼리가 제한 없는 크기로 생성되지 않도록 디자인하는 것이 좋습니다.

  • GET의 경우 URL의 길이는 8KB를 초과할 수 없습니다.

  • 요청의 본문에 search 및 다른 매개 변수(예: filter 및 orderby)가 포함되는 POST (및 다른 요청)의 경우, 최대 크기는 16MB입니다. 추가 제한은 다음과 같습니다.

    • 검색 절의 최대 길이는 100,000자입니다.
    • search의 최대 절 수(AND 또는 OR로 구분된 식)는 1024개입니다.
    • 접두사 검색에 대한 최대 검색어 크기는 1000자입니다.
    • 또한 한 쿼리의 개별 용어 크기도 약 32KB로 제한됩니다.

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

다음 단계

프로그래밍 방식으로 쿼리를 생성하는 경우 Azure AI 검색의 전체 텍스트 검색을 검토하여 쿼리 처리 스테이지와 텍스트 분석의 의미를 이해합니다.

다음 문서를 검토하여 쿼리 생성에 대해 자세히 알아볼 수도 있습니다.