Azure AI 검색 키워드 검색 필터

필터는 키워드 검색을 위해 쿼리를 실행하기 전이나 벡터 검색에 대한 쿼리 실행 전후에 콘텐츠를 포함하거나 제외하기 위한 값 기반 조건을 제공합니다. 필터는 비벡터 필드에 적용되지만 문서에 비벡터 필드가 포함된 경우 벡터 검색에 사용할 수 있습니다. 예를 들어, 청크화된 콘텐츠를 중심으로 구성된 인덱스의 경우, 필터링할 수 있는 상위 수준 필드나 메타데이터 필드가 있을 수 있습니다.

이 문서에서는 키워드 검색에 대한 필터링을 설명합니다. 벡터에 대한 자세한 내용은 벡터 쿼리에서 필터 추가를 참조하세요.

필터는 OData 필터 식 구문을 사용하여 지정됩니다. 키워드 및 벡터 검색과 달리 일치 항목이 정확한 경우에만 필터가 성공합니다.

필터를 사용하는 경우

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

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

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

• 필터 종속성과 함께 제공되는 검색 환경을 구현합니다.

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

• "숫자 검색"을 수행합니다. 숫자 필드는 검색할 수 있으며 검색 결과에 표시될 수 있지만 개별적으로 검색할 수 없습니다(전체 텍스트 검색에 따라 다름). 숫자 데이터를 기반으로 선택 조건이 필요한 경우 필터를 사용합니다.

필터 실행 방법

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

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

필터 정의 방법

필터는 로 특성 filterable이 지정된 필드의 텍스트 및 숫자(비벡터) 콘텐츠에 적용됩니다.

필터는 Azure AI 검색 지원하는 filter 구문 표현된 OData 식입니다.

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

필터 식의 제한 중 하나는 요청의 최대 크기 제한입니다. 필터를 포함한 전체 요청은 POST의 경우 최대 16MB, GET의 경우 8KB일 수 있습니다. 필터 식의 절 수에도 제한이 있습니다. 일반적인 경험칙으로, 조항이 수백 개에 이르면 한계에 도달할 위험이 있습니다. 바인딩되지 않은 크기의 필터를 생성하지 않는 방식으로 애플리케이션을 디자인하는 것이 좋습니다.

다음 예제는 여러 API의 프로토타입 필터 정의를 나타냅니다.

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2026-04-01
{
    "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"로 구분된 복합 쿼리는 각각 자체 필터 조건을 사용합니다(예: '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을 and 필터와 결합하여 사용할 수도 있지만, 이는 검색 요청에서 or 및 search 매개 변수를 사용하는 것과 기능적으로 동일합니다. 예를 들어 다음 두 쿼리는 동일한 결과를 생성합니다.

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

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

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

Azure SDK 필터링 가능은 기본적으로 off입니다. 해당 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 필드에 "맑은 날" $filter=f eq 'sunny' 이 포함되어 있다고 가정합니다. 일치하지는 않지만 $filter=f eq 'sunny day' 일치합니다.

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

텍스트 필터링 방법

숫자 필터 기본 사항

숫자 필드는 전체 텍스트 검색의 컨텍스트에 있지 않습니다 searchable . 문자열만 전체 텍스트 검색이 적용됩니다. 예를 들어 검색어로 99.99를 입력하면 가격이 $99.99인 항목을 다시 받지 못합니다. 대신 문서의 문자열 필드에 숫자 99가 있는 항목이 표시됩니다. 따라서 숫자 데이터가 있는 경우 범위, 패싯, 그룹 등을 비롯한 필터에 사용할 것이라고 가정합니다.

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

다음 단계

먼저 Azure Portal에서 Search explorer를 시도하여 $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 필터 식 구문 > 예제를 참조하세요.

다음 항목 참고하기

• Azure AI 검색
• 문서 검색 REST API
• 단순 쿼리 구문
• Lucene 쿼리 구문
• 지원되는 데이터 형식