$nearSphere

※ MongoDB 공식 매뉴얼에 나와있는 $nearSphere 부분을 번역해 보도록 하겠습니다. 번역을 안하는게 나을 것 같은 용어들은 한번만 번역하거나 그대로 두었습니다.

 

Definition (정의)

$nearSphere

 

geospatial query 가 가장 가까운 곳에서 먼 곳 까지의 documents 를 반환하는 point 를 지정합니다. MongoDB 는 구형 geometry 를 사용해서 $nearSphere 쿼리의 거리를 계산합니다.

 

$nearSphere 은 geospatial index 를 필요로 합니다.

 

• 2dsphere index : GeoJSON point 로 정의된 위치 데이터용
• 2d index : 레거시 좌표 쌍으로 정의된 위치 데이터용. GeoJSON point 에서 2d index 를 사용하려면, GeoJSON object 의 좌표 필드에 인덱스를 만들어야 합니다.

$nearSphere 연산자는 GeoJSON point 또는 레거시 좌표 point 를 지정할 수 있습니다.

GeoJSON point 를 지정하려면, 다음의 문법을 사용하세요 :

 

{
  $nearSphere: {
     $geometry: {
        type : "Point",
        coordinates : [ <longitude>, <latitude> ]
     },
     $minDistance: <distance in meters>,
     $maxDistance: <distance in meters>
  }
}

 

• 옵션으로 $minDistance 를 사용하면 중심점으로부터 적어도 지정한 거리만큼은 떨어진 documents 를 반환하도록 제한합니다.
• $maxDistance 옵션은 어떤 인덱스에서나 사용할 수 있습니다.

 

레거시 좌표 point 를 지정하기 위해선, 다음의 문법을 사용하세요 :

 

{
  $nearSphere: [ <x>, <y> ],
  $minDistance: <distance in radians>,
  $maxDistance: <distance in radians>
}

 

• $minDistance 옵션은 쿼리가 2dsphere index 를 사용할 때만 가능하며, 중심점으로부터 적어도 지정한 거리만큼은 떨어진 documents 를 반환하도록 제한합니다.
• $maxDistance 옵션은 어떤 인덱스에서나 사용할 수 있습니다.

만약 레거시 좌표에 경도와 위도를 사용한다면, 경도를 먼저 지정한 후에 위도를 지정하세요.

 

관련 문서 : 2d Indexes and Geospatial Near Queries

 

Behavior (동작)

Special Indexes Restriction (특수 인덱스 제한)

 

특수 geospatial index 를 필요로 하는 $nearSphere 연산자는 또 다른 특수 인덱스를 요구하는 쿼리 연산자나 명령어와 결합할 수 없습니다. 예를 들어 $nearSphere 과 $text 쿼리는 결합할 수 없습니다.

 

Sharded Collections (샤드된 콜렉션)

 

MongoDB 4.0 부터 $nearSphere 쿼리는 샤드된 콜렉션에 지원됩니다.

그 전 버전에서 $nearSphere 쿼리는 샤드된 콜렉션에 지원되지 않았습니다. 대신 샤드된 클러스터에서, 반드시 $geoNear aggregation stage 혹은 geoNear 명령어를 사용해야 했습니다. (MongoDB 4.0 및 그 이전 버전에서 사용 가능)

 

Sort Operation (정렬 연산)

 

$nearSphere 은 documents 를 거리에 의해 정렬합니다. 쿼리에 sort() 를 포함하고 있다면, sort() 는 이미 $nearSphere 에 의해 수행된 정렬 연산을 효과적으로 재정의해 매칭된 documents 를 재정렬 합니다. sort() 를 geospatial queries 와 함께 사용할 땐 $nearSphere 대신 documents 를 정렬하지않는 $geoWithin 연산자 사용을 고려해 보십시오.

 

Examples (예시)

Specify Center Point Using GeoJSON (GeoJSON 을 사용한 중심점 지정)

 

places 콜렉션의 documents 가 location 필드 및 2dsphere index 를 가지고 있다고 가정합니다.

다음 예시는 지정한 point 로부터 location 이 1000m 에서 5000m 사이에 있는 데이터들을 가까운 것부터 먼 순서로 정렬해 반환합니다 :

 

db.places.find(
   {
     location: {
        $nearSphere: {
           $geometry: {
              type : "Point",
              coordinates : [ -73.9667, 40.78 ]
           },
           $minDistance: 1000,
           $maxDistance: 5000
        }
     }
   }
)

 

Specify Center Point Using Legacy Coordinates (레거시 좌표를 사용한 중심점 지정)

 

2d Index

 

legacyPlaces 콜렉션의 documents 가 레거시 좌표쌍의 location 필드 및 2d index 를 가지고 있다고 가정합니다.

다음의 예시는 location 이 지정한 점으로부터 최대 0.10 라디안만큼 떨어진 documents 를 가까운 것부터 먼 순서로 정렬해 반환합니다 :

 

db.legacyPlaces.find(
   { location : { $nearSphere : [ -73.9667, 40.78 ], $maxDistance: 0.10 } }
)

 

2dsphere Index

 

만약 콜렉션이 2dsphere index 를 갖고 있다면, $minDistance 옵션 또한 지정할 수 있습니다. 다음의 예시는 지정한 점으로부터 location 이 적어도 0.0004 라디안만큼 떨어진 documents 를 가까운 것부터 먼 순서로 정렬해 반환합니다 :

 

db.legacyPlaces.find(
   { location : { $nearSphere : [ -73.9667, 40.78 ], $minDistance: 0.0004 } }
)

 

 

출처 : https://docs.mongodb.com/manual/reference/operator/query/nearSphere/

$nearSphere — MongoDB Manual