전체 Lucene 검색 구문의 예(고급 쿼리)

아티클
10/31/2024

Azure AI 검색에 대한 쿼리를 생성하는 경우 기본 단순 쿼리 파서를 좀 더 강력한 Lucene 쿼리 파서로 바꾸어 특수 및 고급 쿼리 식을 작성할 수 있습니다.

Lucene 쿼리 파서는 필드 범위 쿼리, 유사 항목 검색, 중위 및 접미사, 와일드카드 검색, 근접 검색, 용어 상승, 정규식 검색 등의 복잡한 쿼리 형식을 지원합니다. 추가 성능에는 더 많은 처리 요구 사항이 따르므로 실행 시간이 약간 더 길어질 것으로 예상해야 합니다. 이 문서에서는 전체 구문을 기반으로 쿼리 작업을 보여 주는 예제를 단계별로 실행할 수 있습니다.

참고 항목

전체 Lucene 쿼리 구문을 통해 사용하도록 설정된 특수화된 쿼리 구문 대부분이 텍스트 분석되지 않으므로 형태소 분석 또는 기본형 분석을 예상한 경우에 당황할 수 있습니다. 어휘 분석은 완전한 용어(용어 쿼리 또는 구 쿼리)에만 수행됩니다. 불완전한 용어가 있는 쿼리 형식(접두사 쿼리, 와일드카드 쿼리, regex 쿼리, 유사 항목 쿼리)은 분석 단계를 건너뛰고 쿼리 트리에 직접 추가됩니다. 부분적인 쿼리 용어에서는 소문자 변환만 수행됩니다.

호텔 샘플 인덱스

다음 쿼리는 이 빠른 시작의 지침에 따라 만들 수 있는 호텔 샘플 인덱스를 기반으로 합니다.

예제 쿼리는 REST API 및 POST 요청을 사용하여 설명됩니다. REST 클라이언트에서 붙여넣고 실행할 수 있습니다. 또는 Azure Portal에서 검색 탐색기의 JSON 보기를 사용합니다. JSON 보기에서는 이 문서에 표시된 쿼리 예제를 붙여넣을 수 있습니다.

요청 헤더의 값은 다음과 같아야 합니다.

키	값
콘텐츠-형식	application/json
api-key	`<your-search-service-api-key>`, 쿼리 또는 관리자 키 중 하나

URI 매개 변수는 다음 예제와 유사하게 인덱스 이름, docs 컬렉션, 검색 명령 및 API 버전을 포함하는 검색 서비스 엔드포인트를 포함해야 합니다.

https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01

요청 본문은 유효한 JSON으로 구성되어야 합니다.

{
    "search": "*",
    "queryType": "full",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "count": true
}

search *로 설정은 null 또는 빈 검색에 해당하는 지정되지 않은 쿼리입니다. 특별히 유용한 것은 아니지만 할 수 있는 것 중 가장 간단한 검색이며, 모든 값을 사용하여 인덱스에서 조회 가능 필드를 모두 표시합니다.
queryType전체로 설정하면 전체 Lucene 쿼리 파서가 호출되며 이 구문에 필요합니다.
select 쉼표로 구분된 필드 목록으로 설정하면 검색 결과 컨텍스트에서 유용한 필드만 포함하여 검색 결과 컴퍼지션에 사용됩니다.
count 는 검색 조건과 일치하는 문서 수를 반환합니다. 빈 검색 문자열에서 개수는 인덱스의 모든 문서입니다(hotels-sample-index의 경우 50개).

예제 1: 필드 지정 검색

필드 검색은 특정 필드에 포함된 개별 검색 식을 범위로 지정합니다. 이 예제에서는 호텔 이름이 모텔이 아닌 호텔 이름을 검색합니다. 를 사용하여 AND여러 필드를 지정할 수 있습니다.

이 쿼리 구문을 사용하면 쿼리하려는 필드가 검색 식 자체에 있는 경우 searchFields 매개 변수를 생략할 수 있습니다. 필드 검색에 searchFields를 포함하면 fieldName:searchExpression이 항상 searchFields보다 우선합니다.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "HotelName:(hotel NOT motel) AND Category:'Boutique'",
    "queryType": "full",
    "select": "HotelName, Category",
    "count": true
}

이 쿼리에 대한 응답은 이름에 모텔이 포함된 결과를 제외하고 이름에 호텔이 포함된 호텔을 반환하는 부티크에서 필터링된 다음 예제와 유사해야 합니다.

{
  "@odata.count": 5,
  "value": [
    {
      "@search.score": 2.2289815,
      "HotelName": "Stay-Kay City Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.3862944,
      "HotelName": "City Skyline Antiquity Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.355046,
      "HotelName": "Old Century Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.355046,
      "HotelName": "Sublime Palace Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.355046,
      "HotelName": "Red Tide Hotel",
      "Category": "Boutique"
    }
  ]
}

검색 식은 단일 용어 또는 구 또는 괄호 안의 좀 더 복잡한 식일 수 있습니다. 선택적으로 부울 연산자를 사용할 수 있습니다. 몇 가지 예는 다음과 같습니다.

HotelName:(hotel NOT motel)
Address/StateProvince:("WA" OR "CA")
Tags:("free wifi" NOT "free parking") AND "coffee in lobby"

두 문자열을 단일 엔터티로 평가하려면 이 경우 필드에서 두 개의 고유한 위치를 Address/StateProvince 검색하는 경우 따옴표 안에 구를 넣어야 합니다. 클라이언트에 따라 (\) 큰따옴표를 이스케이프 해야 할 수도 있습니다.

fieldName:searchExpression지정한 필드는 검색 가능한 필드여야 합니다. 필드 정의의 특성을 알아보려면 인덱스 만들기(REST API)를 참조하세요.

예제 2: 유사 항목 검색

유사 항목 검색은 철자가 잘못된 단어를 포함하여 비슷한 용어와 일치합니다. 유사 항목 검색을 수행하려면 편집 거리를 지정하는 0과 2 사이의 값을 선택적 매개 변수로 포함하여 단일 단어의 끝에 물결표~ 기호를 추가합니다. 예를 들어, blue~ 또는 blue~1은 blue, blues 및 glue를 반환합니다.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "Tags:conserge~",
    "queryType": "full",
    "select": "HotelName, Category, Tags",
    "searchFields": "HotelName, Category, Tags",
    "count": true
}

이 쿼리에 대한 응답은 일치하는 문서의 컨시어지로 확인되며 간결하게 잘립니다.

{
  "@odata.count": 9,
  "value": [
    {
      "@search.score": 1.4947624,
      "HotelName": "Twin Vortex Hotel",
      "Category": "Luxury",
      "Tags": [
        "bar",
        "restaurant",
        "concierge"
      ]
    },
    {
      "@search.score": 1.1685618,
      "HotelName": "Stay-Kay City Hotel",
      "Category": "Boutique",
      "Tags": [
        "view",
        "air conditioning",
        "concierge"
      ]
    },
    {
      "@search.score": 1.1465473,
      "HotelName": "Old Century Hotel",
      "Category": "Boutique",
      "Tags": [
        "pool",
        "free wifi",
        "concierge"
      ]
    },
. . .
  ]
}

구는 직접 지원되지 않지만 search=Tags:landy~ AND sevic~과 같이 여러 부분으로 구성된 구의 각 용어에 유사 항목 일치를 지정할 수 있습니다. 이 쿼리 식은 세탁 서비스에서 15개 일치 항목을 찾습니다.

참고 항목

유사 항목 쿼리는 분석되지 않습니다. 불완전한 용어가 있는 쿼리 형식(접두사 쿼리, 와일드카드 쿼리, regex 쿼리, 유사 항목 쿼리)은 분석 단계를 건너뛰고 쿼리 트리에 직접 추가됩니다. 불완전한 쿼리 용어에서는 소문자 변환만 수행됩니다.

예제 3: 근접 검색

근접 검색은 문서에서 서로 가까이 있는 용어를 찾습니다. 구 끝에 물결표(~) 기호, 그리고 근접 경계를 생성하는 단어 수를 넣습니다.

이 쿼리는 문서에서 서로의 5단어 내에서 호텔과 공항이라는 용어를 검색합니다. 따옴표는 구를 유지하기 위해 (\")을 이스케이프합니다.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "Description: \"hotel airport\"~5",
    "queryType": "full",
    "select": "HotelName, Description",
    "searchFields": "HotelName, Description",
    "count": true
}

이 쿼리에 대한 응답은 다음 예제와 유사해야 합니다.

{
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 0.69167054,
      "HotelName": "Trails End Motel",
      "Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport."
    }
  ]
}

예제 4: 용어 상승

용어 상승은 해당 용어가 포함되지 않은 문서에 비해 상승된 용어가 포함된 경우 문서에 더 높은 순위를 지정하는 것을 의미합니다. 용어를 상승시키려면 검색 중인 용어 끝 부분에 상승 계수(숫자)와 함께 캐럿 ^ 기호를 사용합니다. 상승 계수 기본값은 1이고 양수여야 하지만 1보다 작은 값(예: 0.2)일 수 있습니다. 용어 상승은 평가 프로필은 특정 용어가 아닌 특정 필드를 상승시킨다는 점에서 평가 프로필과는 다릅니다.

쿼리하기 전에 해변 액세스를 검색하고 하나 또는 두 용어에 일치하는 6개의 문서가 있는지 확인합니다.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "beach access",
    "queryType": "full",
    "select": "HotelName, Description, Tags",
    "searchFields": "HotelName, Description, Tags",
    "count": true
}

실제로 액세스에서 일치하는 문서는 두 개뿐입니다. 문서에 beach라는 용어 가 없더라도 첫 번째 인스턴스는 두 번째 위치에 있습니다.

{
  "@odata.count": 6,
  "value": [
    {
      "@search.score": 1.068669,
      "HotelName": "Johnson's Family Resort",
      "Description": "Family oriented resort located in the heart of the northland. Operated since 1962 by the Smith family, we have grown into one of the largest family resorts in the state. The home of excellent Smallmouth Bass fishing with 10 small cabins, we're a home not only to fishermen but their families as well. Rebuilt in the early 2000's, all of our cabins have all the comforts of home. Sporting a huge **beach** with multiple water toys for those sunny summer days and a Lodge full of games for when you just can't swim anymore, there's always something for the family to do. A full marina offers watercraft rentals, boat launch, powered dock slips, canoes (free to use), & fish cleaning facility. Rent pontoons, 14' fishing boats, 16' fishing rigs or jet ski's for a fun day or week on the water. Pets are accepted in the lakeside cottages.",
      "Tags": [
        "24-hour front desk service",
        "pool",
        "coffee in lobby"
      ]
    },
    {
      "@search.score": 1.0162708,
      "HotelName": "Campus Commander Hotel",
      "Description": "Easy **access** to campus and steps away from the best shopping corridor in the city. From meetings in town or gameday, enjoy our prime location between the union and proximity to the university stadium.",
      "Tags": [
        "free parking",
        "coffee in lobby",
        "24-hour front desk service"
      ]
    },
    {
      "@search.score": 0.9050383,
      "HotelName": "Lakeside B & B",
      "Description": "Nature is Home on the **beach**. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "Tags": [
        "laundry service",
        "concierge",
        "free parking"
      ]
    },
    {
      "@search.score": 0.8955848,
      "HotelName": "Windy Ocean Motel",
      "Description": "Oceanfront hotel overlooking the **beach** features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
      "Tags": [
        "pool",
        "air conditioning",
        "bar"
      ]
    },
    {
      "@search.score": 0.83636594,
      "HotelName": "Happy Lake Resort & Restaurant",
      "Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value! What can you enjoy while at the resort, aside from the mile-long sandy **beaches** of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
      "Tags": [
        "pool",
        "bar",
        "restaurant"
      ]
    },
    {
      "@search.score": 0.7808502,
      "HotelName": "Swirling Currents Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking **access** to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. ",
      "Tags": [
        "air conditioning",
        "laundry service",
        "24-hour front desk service"
      ]
    }
  ]
}

후 쿼리에서 검색을 반복합니다. 이번에는 용어 액세스에 대한 beach라는 용어로 결과를 높입니다. 사람이 읽을 수 있는 쿼리 버전은 search=Description:beach^2 access입니다. 클라이언트에 따라, ^2을 %5E2로 표현해야 할 수도 있습니다.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "Description:beach^2 access",
    "queryType": "full",
    "select": "HotelName, Description, Tags",
    "searchFields": "HotelName, Description, Tags",
    "count": true
}

당신이 용어 해변을 강화 한 후, 캠퍼스 사령관 호텔의 경기는 5 위로 이동합니다.

{
  "@odata.count": 6,
  "value": [
    {
      "@search.score": 2.137338,
      "HotelName": "Johnson's Family Resort",
      "Description": "Family oriented resort located in the heart of the northland. Operated since 1962 by the Smith family, we have grown into one of the largest family resorts in the state. The home of excellent Smallmouth Bass fishing with 10 small cabins, we're a home not only to fishermen but their families as well. Rebuilt in the early 2000's, all of our cabins have all the comforts of home. Sporting a huge beach with multiple water toys for those sunny summer days and a Lodge full of games for when you just can't swim anymore, there's always something for the family to do. A full marina offers watercraft rentals, boat launch, powered dock slips, canoes (free to use), & fish cleaning facility. Rent pontoons, 14' fishing boats, 16' fishing rigs or jet ski's for a fun day or week on the water. Pets are accepted in the lakeside cottages.",
      "Tags": [
        "24-hour front desk service",
        "pool",
        "coffee in lobby"
      ]
    },
    {
      "@search.score": 1.8100766,
      "HotelName": "Lakeside B & B",
      "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "Tags": [
        "laundry service",
        "concierge",
        "free parking"
      ]
    },
    {
      "@search.score": 1.7911696,
      "HotelName": "Windy Ocean Motel",
      "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
      "Tags": [
        "pool",
        "air conditioning",
        "bar"
      ]
    },
    {
      "@search.score": 1.6727319,
      "HotelName": "Happy Lake Resort & Restaurant",
      "Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value! What can you enjoy while at the resort, aside from the mile-long sandy beaches of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
      "Tags": [
        "pool",
        "bar",
        "restaurant"
      ]
    },
    {
      "@search.score": 1.0162708,
      "HotelName": "Campus Commander Hotel",
      "Description": "Easy access to campus and steps away from the best shopping corridor in the city. From meetings in town or gameday, enjoy our prime location between the union and proximity to the university stadium.",
      "Tags": [
        "free parking",
        "coffee in lobby",
        "24-hour front desk service"
      ]
    },
    {
      "@search.score": 0.7808502,
      "HotelName": "Swirling Currents Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. ",
      "Tags": [
        "air conditioning",
        "laundry service",
        "24-hour front desk service"
      ]
    }
  ]
}

예제 5: 정규식

정규식 검색은 RegExp 클래스에 설명된 대로 슬래시 / 와 소문자 문자열 간의 내용을 기반으로 일치 항목을 찾습니다.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "HotelName:/(Mo|Ho)tel/",
    "queryType": "full",
    "select": "HotelName",
    "count": true
}

이 쿼리에 대한 응답은 다음 예제와 유사해야 합니다(간결하게 트리밍됨).

{
  "@odata.count": 25,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Country Residence Hotel"
    },
    {
      "@search.score": 1,
      "HotelName": "Downtown Mix Hotel"
    },
    {
      "@search.score": 1,
      "HotelName": "Gastronomic Landscape Hotel"
    },
    . . . 
    {
      "@search.score": 1,
      "HotelName": "Trails End Motel"
    },
    {
      "@search.score": 1,
      "HotelName": "Nordick's Valley Motel"
    },
    {
      "@search.score": 1,
      "HotelName": "King's Cellar Hotel"
    }
  ]
}

참고 항목

정규식 쿼리는 분석되지 않습니다. 불완전한 쿼리 용어에서는 소문자 변환만 수행됩니다.

예제 5: 와일드카드 검색

일반적으로 다중(*) 또는 단일(?) 문자 와일드카드 검색에 인식된 구문을 사용할 수 있습니다. Lucene 쿼리 파서는 구가 아닌 단일 용어로 이러한 기호의 사용을 지원합니다.

이 쿼리에서 접두 사 sc가 포함된 호텔 이름을 검색합니다. 검색의 첫 번째 문자로 * 또는 ? 기호를 사용할 수 없습니다.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "HotelName:sc*",
    "queryType": "full",
    "select": "HotelName",
    "count": true
}

이 쿼리에 대한 응답은 다음 예제와 유사해야 합니다.

{
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Waterfront Scottish Inn"
    }
  ]
}

참고 항목

와일드카드 쿼리는 분석되지 않습니다. 불완전한 쿼리 용어에서는 소문자 변환만 수행됩니다.

코드에서 쿼리를 지정해 보세요. 다음 링크에서는 Azure SDK를 사용하여 검색 쿼리를 설정하는 방법을 설명합니다.

빠른 시작: Azure SDK를 사용하여 전체 텍스트 검색

다음 문서에서 더 많은 구문 참조, 쿼리 아키텍처 및 예제를 찾을 수 있습니다.

다음을 통해 공유

전체 Lucene 검색 구문의 예(고급 쿼리)

호텔 샘플 인덱스

예제 1: 필드 지정 검색

예제 2: 유사 항목 검색

예제 3: 근접 검색

예제 4: 용어 상승

예제 5: 정규식

예제 5: 와일드카드 검색

피드백

추가 리소스

다음을 통해 공유

전체 Lucene 검색 구문의 예(고급 쿼리)

호텔 샘플 인덱스

예제 1: 필드 지정 검색

예제 2: 유사 항목 검색

예제 3: 근접 검색

예제 4: 용어 상승

예제 5: 정규식

예제 5: 와일드카드 검색

관련 콘텐츠

피드백

추가 리소스