텍스트 쿼리의 필터

  • 아티클

필터는 쿼리 실행 전에 콘텐츠를 포함하거나 제외하기 위한 값 기반 조건을 제공합니다. 예를 들어 날짜, 위치 또는 언어에 따라 문서를 포함하거나 제외합니다. 필터는 개별 필드에 지정됩니다. 필드 정의를 필터 식에 사용하려면 필드 정의를 "필터링 가능"으로 특성화해야 합니다.

OData 필터 식 구문을 사용하여 필터를 지정합니다. 전체 텍스트 검색과 달리 일치 항목이 정확한 경우에만 필터가 성공합니다.

필터를 사용하는 경우

필터는 "내 주변 찾기" 지리 공간적 검색, 패싯 탐색 및 사용자가 볼 수 있는 문서만 표시하는 보안 필터를 비롯한 여러 검색 환경의 기초입니다. 이러한 환경 중 하나를 구현하는 경우 필터가 필요합니다. 지리적 위치 좌표, 사용자가 선택한 패싯 범주 또는 요청자의 보안 ID를 제공하는 검색 쿼리에 연결된 필터입니다.

일반적인 시나리오는 다음과 같습니다.

  • 인덱스 내용에 따라 검색 결과를 조각화합니다. 호텔 위치, 범주 및 편의 시설이 있는 스키마가 지정된 경우 조건(시애틀, 물, 보기 포함)에 명시적으로 일치하도록 필터를 만들 수 있습니다.

  • 검색 환경 구현에는 다음과 같은 필터 종속성이 수반됩니다.

    • 패싯 탐색 은 필터를 사용하여 사용자가 선택한 패싯 범주를 다시 전달합니다.
    • 지리 공간적 검색은 필터를 사용하여 "내 근처 찾기" 앱 및 영역 내에서 또는 거리별로 일치하는 함수에서 현재 위치의 좌표를 전달합니다.
    • 보안 필터는 보안 식별자를 필터 조건으로 전달하고, 여기서 인덱스의 일치 항목은 문서에 액세스할 수 있는 권한을 위한 프록시 역할을 합니다.

  • "숫자 검색"을 수행합니다. 숫자 필드는 문서에서 검색할 수 있고 검색 결과에 표시되기도 하지만, 개별적으로 검색할 수는 없습니다(전체 텍스트 검색의 대상). 숫자 데이터를 기반으로 선택 조건이 필요한 경우 필터를 사용합니다.

필터 실행 방법

쿼리 시 필터 파서는 조건을 입력으로 수락하고, 식을 트리로 표현되는 원자성 부울 식으로 변환한 다음, 인덱스의 필터링 가능한 필드에 대해 필터 트리를 평가합니다.

필터링은 검색과 함께 수행되며 문서 검색 및 관련성 점수 매기기를 위해 다운스트림 처리에 포함할 문서를 한정합니다. 검색 문자열과 쌍을 이루는 경우 필터는 후속 검색 작업의 회수 집합을 효과적으로 줄입니다. 단독으로 사용하는 경우(예: 쿼리 문자열이 비어 있는 경우), search=*필터 조건은 유일한 입력입니다.

필터 정의

필터는 Azure AI Search에서 지원하는 필터 구문에 설명된 OData 식입니다.

각 검색 작업에 대해 하나의 필터를 지정할 수 있지만 필터 자체에는 여러 필드, 여러 조건 및 함수를 ismatch 사용하는 경우 여러 개의 전체 텍스트 검색 식이 포함될 수 있습니다. 여러 부분으로 구성된 필터 식에서 조건자를 순서대로 지정할 수 있습니다(연산자 우선 순위 규칙에 따라 다함). 특정한 순서로 조건자를 다시 정렬해도 성능에 별다른 도움은 되지 않습니다.

필터 식에 대한 한도는 요청에 대한 최대 크기 제한입니다. 필터를 포함한 전체 요청은 POST의 경우 최대 16MB, GET의 경우 최대 8KB가 될 수 있습니다. 필터 식의 절 개수에도 제한이 있습니다. 엄지 손가락의 좋은 규칙은 절의 수백이있는 경우, 당신은 한계에 실행의 위험이 있다는 것입니다. 제한 없는 크기의 필터를 생성하지 않도록 애플리케이션을 설계하는 것이 좋습니다.

다음 예제는 여러 API의 정형화된 필터 정의를 나타냅니다.

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2020-06-30
{
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate lt 150.0)",
    "select": "HotelId, HotelName, Rooms/Description, Rooms/BaseRate"
}

    parameters =
        new SearchParameters()
        {
            Filter = "Rooms/any(room: room/BaseRate lt 150.0)",
            Select = new[] { "HotelId", "HotelName", "Rooms/Description" ,"Rooms/BaseRate"}
        };

    var results = searchIndexClient.Documents.Search("*", parameters);

필터 패턴

다음 예제에는 필터 시나리오에 대한 여러 디자인 패턴이 나와 있습니다. 자세한 내용은 OData 식 구문 > 예제를 참조하세요.

  • 쿼리 문자열이 없는 독립 실행형 $filter 필터 식이 관심 있는 문서를 완전히 한정할 수 있는 경우에 유용합니다. 쿼리 문자열이 없으면 어휘 또는 언어 분석, 점수 매기기 및 순위 지정 등이 없습니다. 검색 문자열은 "모든 문서 일치"를 의미하는 별표일 뿐입니다.

    {
  "search": "*",
  "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Honolulu"
}

  • 필터가 하위 집합을 만들고 쿼리 문자열이 필터링된 하위 집합을 통해 전체 텍스트 검색에 대한 용어 입력을 제공하는 쿼리 문자열과 $filter 조합합니다. 용어(도보 거리 극장)를 추가하면 결과에 검색 점수가 도입되며, 용어와 가장 일치하는 문서가 더 높은 순위를 차지합니다. 쿼리 문자열과 함께 필터를 사용하는 것이 가장 일반적인 사용 패턴입니다.

    {
  "search": "walking distance theaters",
  "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Seattle'"
}

  • "or"로 구분된 복합 쿼리는 각각 자체 필터 조건을 사용합니다(예: 'dog'의 'beagles', 'cat'의 'siamese'). or와 결합된 식은 개별적으로 평가되며, 응답에서 다시 전송된 각 식과 일치하는 문서의 공용 구조체가 있습니다. 이 사용 패턴은 search.ismatchscoring 함수를 통해 구현됩니다. 점수가 지정하지 않는 버전을 search.ismatch사용할 수도 있습니다.

    # Match on hostels rated higher than 4 OR 5-star motels.
$filter=search.ismatchscoring('hostel') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 5

# Match on 'luxury' or 'high-end' in the description field OR on category exactly equal to 'Luxury'.
$filter=search.ismatchscoring('luxury | high-end', 'Description') or Category eq 'Luxury'&$count=true

    search.ismatchscoring을 통해 전체 텍스트 검색을 or 대신 and를 사용하는 필터와 결합할 수도 있지만 이는 검색 요청에서 search 및 $filter 매개 변수를 사용하는 것과 기능적으로 동일합니다. 예를 들어 다음 두 쿼리는 같은 결과를 산출합니다.

    $filter=search.ismatchscoring('pool') and Rating ge 4

search=pool&$filter=Rating ge 4

필터링에 대한 필드 요구 사항

REST API에서는 필터링 가능이 기본적으로 단순 필터에 대해 설정되어 있습니다. 필터링 가능한 필드는 인덱스 크기를 증가합니다. 필터에서 실제로 사용하지 않으려는 필드에 대해 설정 "filterable": false 해야 합니다. 필드 정의에 대한 설정에 대한 자세한 내용은 인덱스 만들기를 참조하세요.

.NET SDK에서 필터링 가능은 기본적으로 꺼져 있습니다. 해당 SearchField 개체의 IsFilterable 속성을 true로 설정하여 필드를 필터링할 수 있습니다. 다음 예제에서는 인덱스 정의에 BaseRate 매핑되는 모델 클래스의 속성에 특성이 설정됩니다.

[IsFilterable, IsSortable, IsFacetable]
public double? BaseRate { get; set; }

기존 필드를 필터링 가능으로 만들기

기존 필드를 필터링할 수 있도록 수정할 수 없습니다. 대신 새 필드를 추가하거나 인덱스 다시 작성해야 합니다. 인덱스 다시 작성 또는 필드를 다시 채우려면 Azure AI Search 인덱스 다시 작성 방법을 참조하세요.

텍스트 필터 기본 사항

텍스트 필터는 필터에서 제공하는 리터럴 문자열과 문자열 필드를 일치합니다. $filter=Category eq 'Resort and Spa'

문자열로 구성된 텍스트 필터의 경우와 달리 어휘 분석 또는 단어 분리가 없으므로 정확한 일치 항목만 비교합니다. 예를 들어, 필드 f에 "sunny day"가 포함되어 있다고 가정하고 $filter=f eq 'sunny'는 일치하지 않지만 $filter=f eq 'sunny day'는 일치합니다.

텍스트 문자열은 대/소문자를 구분하므로 텍스트 필터는 기본적으로 대/소문자를 구분합니다. 예를 들어 $filter=f eq 'Sunny day'는 "화창한 날"을 찾을 수 없습니다. 그러나 노멀라이저를 사용하여 필터링이 대/소문자를 구분하지 않도록 할 수 있습니다.

텍스트 필터링 방법

접근법 설명 사용 시기
search.in 구분된 문자열 목록에 대해 필드와 일치하는 함수입니다. 문자열 필드와 일치해야 하는 원시 텍스트 값이 많은 필터 및 보안 필터에 권장됩니다. search.in 함수는 속도를 위해 디자인되었으며, eq 및 or를 사용하여 각 문자열과 필드를 명시적으로 비교하는 것 보다 훨씬 빠릅니다.
search.ismatch 전체 텍스트 검색 작업을 동일한 필터 식의 엄격하게 부울 필터 작업과 혼합할 수 있는 함수입니다. 하나의 요청에서 여러 검색 필터 조합을 사용하려면 search.ismatch (또는 해당하는 해당 점수, search.ismatchscoring)를 사용합니다. 더 큰 문자열 내의 부분 문자열을 필터링하는 포함 필터에 사용할 수도 있습니다.
$filter=field operator string 필드, 연산자 및 값으로 구성된 사용자 정의 식입니다. 문자열 필드와 문자열 값 사이에 정확히 일치하는 항목을 찾으려면 이를 사용합니다.

숫자 필터 기본 사항

숫자 필드는 전체 텍스트 검색의 컨텍스트에서 searchable이 아닙니다. 문자열만 전체 텍스트 검색이 적용됩니다. 예를 들어, 검색어로 99.99를 입력하면 $99.99로 책정된 항목이 반환되지 않고 문서의 문자열 필드에 숫자 99가 있는 항목이 표시됩니다. 따라서 숫자 데이터가 있는 경우 범위, 패싯, 그룹 등을 포함하여 필터에 사용한다고 가정합니다.

숫자 필드(가격, 크기, SKU, ID)가 포함된 문서는 필드가 표시된 retrievable경우 검색 결과에 해당 값을 제공합니다. 여기서 핵심은 전체 텍스트 검색 자체가 숫자 필드 유형에는 적용되지 않는다는 것입니다.

다음 단계

먼저 포털에서 검색 탐색기를 시도하여 $filter 매개 변수를 사용하여 쿼리를 제출합니다. 필터링된 다음 쿼리를 검색 창에 붙여넣으면 부동산 샘플 인덱스에서 해당 쿼리에 대한 흥미로운 결과를 제공합니다.

# Geo-filter returning documents within 5 kilometers of Redmond, Washington state
# Use $count=true to get a number of hits returned by the query
# Use $select to trim results, showing values for named fields only
# Use search=* for an empty query string. The filter is the sole input

search=*&$count=true&$select=description,city,postCode&$filter=geo.distance(location,geography'POINT(-122.121513 47.673988)') le 5

# Numeric filters use comparison like greater than (gt), less than (lt), not equal (ne)
# Include "and" to filter on multiple fields (baths and bed)
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=baths gt 3 and beds gt 4

# Text filters can also use comparison operators
# Wrap text in single or double quotes and use the correct case
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=city gt 'Seattle'

더 많은 예제를 사용하려면 OData 필터 식 구문 > 예제를 참조하세요.

참고 항목