distance_feature 쿼리

distance_feature 쿼리

distance_feature 쿼리를 사용해 특정 날짜나 지리적 지점에 더 가까운 문서의 관련성을 높일 수 있어요. 이는 검색 결과에서 더 최근이거나 가까운 콘텐츠를 우선시하는 데 도움이 됩니다. 예를 들어 더 최근에 제조된 제품에 더 많은 가중치를 부여하거나, 사용자가 지정한 위치에 가장 가까운 항목을 높일 수 있어요.

이 쿼리는 날짜나 위치 데이터를 포함하는 필드에 적용할 수 있어요. 결과를 필터링하지 않으면서 관련성 점수를 개선하기 위해 주로 bool 쿼리의 should 절 안에서 사용됩니다.

출처: 문서

본문

인덱스 구성하기 (Configuring the index)

distance_feature 쿼리를 사용하기 전에 인덱스에 다음 필드 유형 중 하나 이상이 있는지 확인하세요.

  • date
  • date_nanos
  • geo_point

이 예제에서는 distance feature 쿼리를 실행하는 데 사용할 opening_date와 coordinates 필드를 구성해 보겠어요.

PUT /stores
{
  "mappings": {
    "properties": {
      "opening_date": {
        "type": "date"
      },
      "coordinates": {
        "type": "geo_point"
      }
    }
  }
}

인덱스에 샘플 문서를 추가해요.

PUT /stores/_doc/1
{
  "store_name": "Green Market",
  "opening_date": "2025-03-10",
  "coordinates": [74.00, 40.70]
}

PUT /stores/_doc/2
{
  "store_name": "Fresh Foods",
  "opening_date": "2025-04-01",
  "coordinates": [73.98, 40.75]
}

PUT /stores/_doc/3
{
  "store_name": "City Organics",
  "opening_date": "2021-04-20",
  "coordinates": [74.02, 40.68]
}

예제: 최신성 기준으로 점수 높이기

다음 쿼리는 store_name이 market과 일치하는 문서를 검색하고 최근에 열린 매장을 높여요.

GET /stores/_search
{
  "query": {
    "bool": {
      "must": {
        "match": {
          "store_name": "market"
        }
      },
      "should": {
        "distance_feature": {
          "field": "opening_date",
          "origin": "2025-04-07",
          "pivot": "10d"
        }
      }
    }
  }
}

응답에는 일치하는 문서가 포함돼요.

{
  "took": 4,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.2372394,
    "hits": [
      {
        "_index": "stores",
        "_id": "1",
        "_score": 1.2372394,
        "_source": {
          "store_name": "Green Market",
          "opening_date": "2025-03-10",
          "coordinates": [
            74,
            40.7
          ]
        }
      }
    ]
  }
}

예제: 지리적 근접성 기준으로 점수 높이기

다음 쿼리는 store_name이 market과 일치하는 문서를 검색하고 주어진 origin 지점에 더 가까운 결과를 높여요.

GET /stores/_search
{
  "query": {
    "bool": {
      "must": {
        "match": {
          "store_name": "market"
        }
      },
      "should": {
        "distance_feature": {
          "field": "coordinates",
          "origin": [74.00, 40.71],
          "pivot": "500m"
        }
      }
    }
  }
}

응답에는 일치하는 문서가 포함돼요.

{
  "took": 3,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.2910118,
    "hits": [
      {
        "_index": "stores",
        "_id": "1",
        "_score": 1.2910118,
        "_source": {
          "store_name": "Green Market",
          "opening_date": "2025-03-10",
          "coordinates": [
            74,
            40.7
          ]
        }
      }
    ]
  }
}

파라미터 (Parameters)

다음 표는 distance_feature 쿼리가 지원하는 모든 최상위 파라미터를 나열해요.

  • field (필수): 거리 계산에 사용되는 필드의 이름이에요. index: true(기본값)와 doc_values: true(기본값)인 date, date_nanos 또는 geo_point 필드여야 해요.
  • origin (필수): 거리 계산에 사용되는 원점입니다. date 필드에는 날짜나 날짜 수학 표현(예: now-1h)을, geo_point 필드에는 지오포인트를 사용해요.
  • pivot (필수): 점수가 boost 값의 절반을 받는 origin으로부터의 거리예요. date 필드에는 시간 단위(예: 10d)를, 지리 필드에는 거리 단위(예: 1km)를 사용해요. 자세한 내용은 Units를 참고하세요.
  • boost (선택): 일치하는 문서의 관련성 점수에 대한 배율이에요. 음이 아닌 부동소수점이어야 해요. 기본값은 1.0이에요.

점수 계산 방법 (How scores are calculated)

distance_feature 쿼리는 다음 공식을 사용해 문서의 관련성 점수를 계산해요.

score = boost · pivot / (pivot + distance) | 여기서 distance는 origin과 필드 값의 절대 차이예요.

비경쟁 히트 건너뛰기 (Skipping non-competitive hits)

function_score 쿼리 같은 다른 점수 수정 쿼리와 달리 distance_feature 쿼리는 전체 히트 추적(track_total_hits)이 비활성화되어 있을 때 비경쟁 히트를 효율적으로 건너뛰도록 최적화되어 있어요.

더 알아보기 (Learn more)