텍스트 쿼리의 필터

  • 아티클

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

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

필터를 사용하는 경우

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

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

  • 인덱스에서 내용에 따라 검색 결과를 조각화합니다. 호텔 위치, 카테고리 및 편의 시설을 포함하는 스키마가 제공되면, 조건(시애틀에서, 물가에서, 뷰가 있는)에서 명시적으로 일치하는 필터를 만들 수 있습니다.

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

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

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

필터 실행 방법

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

필터링은 검색과 함께 수행되며, 문서 검색 및 관련성 평가를 위해 다운스트림 처리에 포함할 문서를 선별합니다. 필터가 검색 문자열과 함께 사용되면 필터는 후속 검색 작업의 호출 세트를 효과적으로 줄입니다. 단독으로 사용되면(예를 들어 search=* 같이 쿼리 문자열이 비어 있는 경우) 필터 조건이 유일한 입력입니다.

필터 정의

필터는 Azure AI 검색에서 지원하는 필터 구문으로 표현된 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"
}

options = new SearchOptions()
{
    Filter = "Rating gt 4",
    OrderBy = { "Rating desc" }
};

필터 패턴

다음 예제에는 필터 시나리오에 대한 여러 디자인 패턴이 나와 있습니다. 자세한 내용은 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"로 구분된 복합 쿼리에서는 각각 자체 필터 조건이 있습니다. 예를 들어, '개'는 '비글', '고양이'는 '샤미즈' 등입니다. 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로 설정합니다. 필드 정의 설정에 대한 자세한 내용은 Create Index(인덱스 만들기)를 참조하세요.

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

[SearchField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
public double? Rating { get; set; }

필터링 가능한 기존 필드 만들기

필터링 가능하도록 기존 필드를 수정할 수 없습니다. 대신 새 필드를 추가하거나 인덱스를 다시 작성해야 합니다. 인덱스를 다시 빌드하거나 필드를 다시 채우는 방법에 대한 자세한 내용은 Azure AI 검색 인덱스를 다시 빌드하는 방법을 참조하세요.

텍스트 필터 기본 사항

텍스트 필터는 필터에 제공하는 리터럴 문자열과 문자열 필드를 일치시킵니다.: $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)를 사용합니다. 크기가 더 큰 문자열 내에서 부분적으로 문자열을 필터링하기 위해 contains 필터에 대해 이를 사용할 수도 있습니다.
$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 필터 식 구문 > 예제를 참조하세요.

참고 항목