/ /

연산자

집계 파이프라인 단계

Docs Home

데이터베이스 매뉴얼

참조

연산자

집계 파이프라인 단계

$geoNear (표현식 연산자)

이 버전의 문서는 보관되어 더 이상 지원되지 않습니다. 6.0 배포서버 업그레이드 하려면 MongoDB 7.0 업그레이드 절차를 참조하세요.

정의

$geoNear

지정된 점을 기준으로 가장 가까운 것부터 가장 먼 것 순으로 문서를 출력합니다.

참고

MongoDB 단계에 대한 limit 및 num $geoNear 옵션과 기본값 제한인 100 문서를 제거합니다. 의 $geoNear 결과를 $geoNear 제한하려면 단계를 $limit 단계와 함께 사용합니다.

$geoNear 단계의 프로토타입 형식은 다음과 같습니다.

{ $geoNear: { <geoNear options> } }

$geoNear 연산자는 다음 $geoNear 옵션이 포함된 문서를 허용합니다. 처리된 문서의 좌표계와 동일한 단위로 모든 거리를 지정합니다.

필드	유형	설명
`distanceField`	문자열	계산된 거리가 포함된 출력 필드입니다. 내장된 문서 내에서 필드를 지정하려면 점 표기법을 사용합니다.
`distanceMultiplier`	숫자	선택 사항. 쿼리에서 반환된 모든 거리를 곱하는 요소입니다. 예를 들어 구형 쿼리에서 반환된 라디안을 지구 반지름으로 곱하여 킬로미터로 변환하려면 `distanceMultiplier`를 사용합니다.
`includeLocs`	문자열	선택 사항. 거리를 계산하는 데 사용되는 위치를 식별하는 출력 필드를 지정합니다. 이 옵션은 위치 필드에 여러 위치가 포함된 경우 유용합니다. 내장된 문서 내에서 필드를 지정하려면 점 표기법을 사용합니다.
`key`		선택 사항입니다. 거리를 계산할 때 사용할 지리 공간적 인덱스 필드를 지정합니다. 컬렉션 여러 개의 `2d` 및 여러 개의 `2dsphere` 인덱스가 있는 경우 `key` 옵션을 사용하여 사용할 인덱싱된 필드 경로 지정해야 합니다. 사용할 지리 공간적 인덱스 지정하기에서 전체 예시 제공합니다. `2d` 인덱스가 두 개 이상이거나 `2dsphere` 인덱스가 두 개 이상이고 `key`를 지정하지 않은 경우 MongoDB는 오류를 반환합니다. `key`를 지정하지 않고 최대 하나의 `2d` 인덱스 및 하나의 `2dsphere` 인덱스만 있는 경우 MongoDB는 먼저 사용할 `2d` 인덱스를 찾습니다. `2d` 인덱스가 없으면 MongoDB는 사용할 `2dsphere` 인덱스를 찾습니다.
`maxDistance`	숫자	선택 사항입니다. 문서가 위치할 수 있는 중심점으로부터의 최대 거리입니다. MongoDB는 중심점에서 지정된 거리 내에 있는 문서로 결과를 제한합니다. 지정된 지점이 GeoJSON인 경우 거리를 미터 단위로 지정하고, 지정된 지점이 레거시 좌표 쌍인 경우 라디안 단위로 지정합니다.
`minDistance`	숫자	선택 사항입니다. 문서가 위치할 수 있는 중심점으로부터의 최소 거리입니다. MongoDB는 중심점에서 지정된 거리를 벗어나는 문서로 결과를 제한합니다. GeoJSON 데이터의 경우 미터 단위로, 레거시 좌표 쌍의 경우 라디안 단위로 거리를 지정합니다.
`near`	GeoJSON 포인트 또는 레거시 좌표 쌍	가장 가까운 문서를 찾을 수 있는 점입니다. 2D스피어 인덱스를 사용하는 경우, 포인트를 GeoJSON 포인트 또는 레거시 좌표 쌍으로 지정할 수 있습니다. 2D 인덱스를 사용하는 경우, 점을 레거시 좌표 쌍으로 지정합니다.
`query`	문서	선택 사항입니다. 결과를 쿼리와 일치하는 문서로 제한합니다. 쿼리 구문은 일반적인 MongoDB 읽기 작업 쿼리 구문입니다. 단계의 `$near` 필드 에는 술어를 지정할 수 `query` `$geoNear` 없습니다.
`spherical`	부울	선택 사항. MongoDB가 두 포인트 사이의 거리를 계산하는 방법을 결정합니다: `true`인 경우 MongoDB는 `$nearSphere` 시맨틱을 사용하고 구형 기하학을 사용하여 거리를 계산합니다. `false`일 경우, MongoDB는 2dsphere 인덱스에는 구면 기하학, 2d 인덱스에는 평면 기하학을 적용하는 `$near` 시맨틱을 사용합니다. 기본값: false.

행동

거리 계산

$geoNear 입력 문서 둘레의 가장 가까운 점 기준으로 거리를 계산합니다.

예시 들어, 입력 문서 도형인 경우 는 도형의 둘레에서 지정된 점 에 가장 가까운 점 식별하고 지정된 점 과 도형의 가장 가까운 점 사이의 거리를$geoNear 출력합니다.

고려 사항

$geoNear를 사용할 때는 다음 사항을 고려하세요.

$geoNear는 파이프라인의 첫 번째 단계로만 사용할 수 있습니다.
반드시 distanceField 옵션을 포함해야 합니다. distanceField 옵션은 계산된 거리를 포함할 필드를 지정합니다.
$geoNear는 지리 공간적 인덱스가 필요합니다.
컬렉션에 두 개 이상의 지리 공간적 인덱스가 있는 경우 keys 매개변수를 사용하여 계산에 사용할 필드를 지정합니다. 지리 공간적 인덱스가 하나만 있는 경우 $geoNear는 암시적으로 계산에 인덱싱된 필드를 사용합니다.

$geoNear 단계의 query 필드에는 $near 술어를 지정할 수 없습니다.
$geoNear 더 이상 기본 문서 수가 100개로 제한되지 않습니다.
MongoDB 5.1부터 near 매개변수는 let 옵션과 바인딩된 let 옵션을 지원합니다.
MongoDB 5.3부터 time series 컬렉션의 모든 필드에서 $geoNear 연산자를 사용할 수 있습니다.
MongoDB 6.0부터는 time series 컬렉션의 모든 필드에 partial 및 2dsphere 인덱스를 만들 수 있습니다.

예시

다음 문서를 사용하여 컬렉션 places를 생성합니다.

db.places.insertMany( [
   {
      name: "Central Park",
      location: { type: "Point", coordinates: [ -73.97, 40.77 ] },
      category: "Parks"
   },
   {
      name: "Sara D. Roosevelt Park",
      location: { type: "Point", coordinates: [ -73.9928, 40.7193 ] },
      category: "Parks"
   },
   {
      name: "Polo Grounds",
      location: { type: "Point", coordinates: [ -73.9375, 40.8303 ] },
      category: "Stadiums"
   }
] )

다음 작업은 location 필드에 2dsphere 인덱스를 생성합니다:

db.places.createIndex( { location: "2dsphere" } )

최대 거리

참고

MongoDB는 $geoNear 단계에 대한 limit 및 num 옵션과 문서 100개 기본 제한을 제거합니다. $geoNear 결과를 제한하려면 $geoNear 단계와 $limit 단계를 함께 사용합니다.

위의 places 컬렉션에는 2dsphere 인덱스가 있습니다. 다음 집계는 $geoNear를 사용하여 중심 [ -73.99279 , 40.719296 ]에서 최대 2m 떨어져 있고 Parks와 같은 category가 있는 문서를 찾습니다.

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        distanceField: "dist.calculated",
        maxDistance: 2,
        query: { category: "Parks" },
        includeLocs: "dist.location",
        spherical: true
     }
   }
])

집계는 다음을 반환합니다.

{
   "_id" : 8,
   "name" : "Sara D. Roosevelt Park",
   "category" : "Parks",
   "location" : {
      "type" : "Point",
      "coordinates" : [ -73.9928, 40.7193 ]
   },
   "dist" : {
      "calculated" : 0.9539931676365992,
      "location" : {
         "type" : "Point",
         "coordinates" : [ -73.9928, 40.7193 ]
      }
   }
}

일치하는 문서에는 다음과 같이 두 개의 새로운 필드가 포함되어 있습니다.

dist.calculated 계산된 거리가 포함된 필드
dist.location 필드는 계산에 사용된 위치를 포함합니다.

최소 거리

참고

다음 예시에서는 minDistance 옵션을 사용하여 문서가 위치할 수 있는 중심점으로부터의 최소 거리를 지정합니다. 다음 집계에서는 위치가 중심 [ -73.99279 , 40.719296 ]에서 2미터 이상 떨어져 있고, category가 Parks인 모든 문서를 찾습니다.

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        distanceField: "dist.calculated",
        minDistance: 2,
        query: { category: "Parks" },
        includeLocs: "dist.location",
        spherical: true
     }
   }
])

옵션이 포함된 $geoNear `let`

이 예시에서는

let 옵션은 [-73.99279,40.719296] 배열 값을 $pt 변수에 설정하는 데 사용됩니다.
$pt $geoNear 단계에서 near 매개변수에 대한 let 옵션으로 지정됩니다.

db.places.aggregate(
[
   {
      "$geoNear":
      {
         "near":"$$pt",
         "distanceField":"distance",
         "maxDistance":2,
         "query":{"category":"Parks"},
         "includeLocs":"dist.location",
         "spherical":true
      }
   }
],
{
   "let":{ "pt": [ -73.99279, 40.719296 ] }
}
)

집계는 다음을 포함하는 모든 문서를 반환합니다.

let 변수에 정의된 점에서 최대 2미터 떨어진 위치입니다
Parks와 동일한 category.

{
   _id: ObjectId("61715cf9b0c1d171bb498fd7"),
   name: 'Sara D. Roosevelt Park',
   location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
   category: 'Parks',
   distance: 1.4957325341976439e-7,
   dist: { location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] } }
},
{
   _id: ObjectId("61715cf9b0c1d171bb498fd6"),
   name: 'Central Park',
   location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },
   category: 'Parks',
   distance: 0.0009348548688841822,
   dist: { location: { type: 'Point', coordinates: [ -73.97, 40.77 ] } }
}

바운드 옵션이 있는 $geoNear `let`

let 옵션은 $geoNear 쿼리에 사용할 수 있는 변수를 바인딩할 수 있습니다.

이 예시에서 $lookup은(는) 다음을 사용합니다.

let : $pt를 정의하기 위해
pipeline의 $geoNear입니다.
$pt $geoNear 파이프라인 단계에서 near를 정의합니다.

db.places.aggregate( [
   {
      $lookup: {
         from: "places",
         let: { pt: "$location" },
         pipeline: [
            {
               $geoNear: {
                  near: "$$pt",
                  distanceField: "distance"
               }
            }
         ],
         as: "joinedField"
      }
   },
   {
      $match: { name: "Sara D. Roosevelt Park" }
   }
] );

집계는 다음을 포함하는 문서를 반환합니다.

'사라 D. 루즈벨트 공원(Sara D. Roosevelt Park)' 문서를 주요 문서로 사용합니다.
$pt 변수로 거리를 계산해 컬렉션 내 모든 문서를 subDocuments로 반환합니다.

{
   _id: ObjectId("61715cf9b0c1d171bb498fd7"),
      name: 'Sara D. Roosevelt Park',
      location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
      category: 'Parks',
      joinedField: [
         {
         _id: ObjectId("61715cf9b0c1d171bb498fd7"),
         name: 'Sara D. Roosevelt Park',
         location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
         category: 'Parks',
         distance: 0
         },
         {
         _id: ObjectId("61715cf9b0c1d171bb498fd6"),
         name: 'Central Park',
         location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },
         category: 'Parks',
         distance: 5962.448255234964
         },
         {
         _id: ObjectId("61715cfab0c1d171bb498fd8"),
         name: 'Polo Grounds',
         location: { type: 'Point', coordinates: [ -73.9375, 40.8303 ] },
         category: 'Stadiums',
         distance: 13206.535424939102
         }
      ]
}

사용할 지리 공간적 인덱스 지정

places 컬렉션에서 location 필드에 2dsphereplaces 인덱스 및 legacy 필드에 2d 인덱스가 있다고 가정해 보겠습니다.

places 컬렉션의 문서는 다음과 유사합니다.

{
   "_id" : 3,
   "name" : "Polo Grounds",
   "location": {
      "type" : "Point",
      "coordinates" : [ -73.9375, 40.8303 ]
   },
   "legacy" : [ -73.9375, 40.8303 ],
   "category" : "Stadiums"
}

다음 예시에서는 key 옵션을 사용해 $geoNear 작업에 집계가 legacy 필드 값이 아닌 location 필드 값을 사용하도록 지정합니다. 또한 파이프라인은 $limit를 사용하여 문서를 최대 5개 반환합니다.

참고

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.98142 , 40.71782 ] },
        key: "location",
        distanceField: "dist.calculated",
        query: { "category": "Parks" }
     }
   },
   { $limit: 5 }
])

집계는 다음을 반환합니다.

{
   "_id" : 8,
   "name" : "Sara D. Roosevelt Park",
   "location" : {
      "type" : "Point",
      "coordinates" : [
         -73.9928,
         40.7193
      ]
   },
   "category" : "Parks",
   "dist" : {
      "calculated" : 974.175764916902
   }
}
{
   "_id" : 1,
   "name" : "Central Park",
   "location" : {
      "type" : "Point",
      "coordinates" : [
         -73.97,
         40.77
      ]
   },
   "legacy" : [
      -73.97,
      40.77
   ],
   "category" : "Parks",
   "dist" : {
      "calculated" : 5887.92792958097
   }
}

이 페이지의 C# 예제에서는 Atlas 샘플 데이터 세트의 sample_mflix.theaters 컬렉션 사용합니다. 무료 MongoDB Atlas cluster 생성하고 샘플 데이터 세트를 로드하는 방법을 학습하려면 MongoDB .NET/ C# 드라이버 문서에서 시작하기 를 참조하세요.

다음 Theater, Location 및 Address 클래스는 sample_mflix.theaters 컬렉션의 문서를 모델링합니다.

public class Theater
{
  public ObjectId Id { get; set; }
  [BsonElement("theaterId")]
  public int TheaterId { get; set; }
  [BsonElement("location")]
  public Location Location { get; set; }
  [BsonElement("distance")]
  public double? Distance { get; set; }
}
public class Location
{
  [BsonElement("address")]
  public Address Address { get; set; }
  [BsonElement("geo")]
  public GeoJsonPoint<GeoJson2DGeographicCoordinates> Geo { get; set; }
}
[BsonIgnoreExtraElements]
public class Address
{
  [BsonElement("city")]
  public string City { get; set; }
  [BsonElement("state")]
  public string State { get; set; }
}

MongoDB .NET/C# 드라이버를 사용하여 단계를 MongoDB $geoNear 집계 파이프라인에 추가하려면 GeoNear() 메서드를 PipelineDefinition 객체에서 호출하세요.

이 메서드는 MongoDB .NET/ C# 운전자 v3.4 이상에서만 사용할 수 있습니다.

최대 거리

다음 예시에서는 지정된 점의 반경 8000미터 내에 있는 문서를 거리 오름차순으로 반환하는 파이프라인 단계를 만듭니다. 코드에는 location.address.state 필드의 값이 "NJ"인 문서에만 일치하는 Query 매개변수가 포함되어 있습니다. 코드는 계산된 거리를 출력 문서의 distance 필드에 저장합니다.

var pipeline = new EmptyPipelineDefinition<Theater>()
    .GeoNear(
        GeoJson.Point(GeoJson.Geographic(-74.1, 40.95)),
        new GeoNearOptions<Theater, Theater>
        {
          DistanceField = "distance",
          MaxDistance = 8000,
          Key = "location.geo",
          Query = Builders<Theater>.Filter.Eq(t => t.Location.Address.State, "NJ"),
        });

최소 거리

다음 예시 지정된 점 의 8000 미터 반경을 벗어난 첫 번째 4 일치하는 문서를 거리 오름차순으로 반환합니다. 이 코드에는 location.address.state 필드 값이 "NJ"인 문서와만 일치하는 Query 매개 변수가 포함되어 있습니다. 이 코드는 또한 출력 문서의 distance 필드 에 계산된 거리를 저장합니다.

var pipeline = new EmptyPipelineDefinition<Theater>()
    .GeoNear(
        GeoJson.Point(GeoJson.Geographic(-74.1, 40.95)),
        new GeoNearOptions<Theater, Theater>
        {
          DistanceField = "distance",
          MinDistance = 8000,
          Key = "location.geo",
          Query = Builders<Theater>.Filter.Eq(t => t.Location.Address.State, "NJ"),
        })
    .Limit(4);

이 페이지의 Node.js 예제에서는 Atlas 샘플 데이터 세트의 sample_mflix 데이터베이스 사용합니다. 무료 MongoDB Atlas cluster 생성하고 샘플 데이터 세트를 로드하는 방법을 학습하려면 MongoDB Node.js 운전자 설명서에서 시작하기 를 참조하세요.

MongoDB Node.js 운전자 사용하여 집계 파이프라인 에 $geoNear 단계를 추가하려면 파이프라인 객체 에서 $geoNear 연산자 사용합니다.

최대 거리

다음 예시 지정된 점 의 8000 미터 반경에 있는 문서를 거리 오름차순으로 반환하는 파이프라인 단계를 만듭니다. 이 코드에는 location.address.state 필드 값이 "NJ"인 문서와만 일치하는 query 필드 포함되어 있습니다. 이 코드는 또한 출력 문서의 distance 필드 에 계산된 거리를 저장합니다. 그런 다음 이 예시 에서는 집계 파이프라인 실행합니다.

const pipeline = [
  {
    $geoNear: {
      near: {
        type: "Point",
        coordinates: [-74.1, 40.95]
      },
      distanceField: "distance",
      maxDistance: 8000,
      query: { "location.address.state": "NJ" },
      spherical: true
    }
  }
];
const cursor = collection.aggregate(pipeline);
return cursor;

최소 거리

다음 예시 지정된 점 의 8000 미터 반경을 벗어난 첫 번째 4 일치하는 문서를 거리 오름차순으로 반환합니다. 이 코드에는 location.address.state 필드 값이 "NJ"인 문서와만 일치하는 query 필드 포함되어 있습니다. 이 코드는 또한 출력 문서의 distance 필드 에 계산된 거리를 저장합니다.

const pipeline = [
  {
    $geoNear: {
      near: {
        type: "Point",
        coordinates: [-74.1, 40.95]
      },
      distanceField: "distance",
      minDistance: 8000,
      query: { "location.address.state": "NJ" },
      spherical: true
    },
  },
  { $limit: 4 }
];
const cursor = collection.aggregate(pipeline);
return cursor;

자세히 알아보기

관련 파이프라인 단계에 대해 자세히 학습 $limit 가이드 참조하세요.

돌아가기

$fill

$graphLookup

정의

참고

행동

거리 계산

고려 사항

예시

최대 거리

참고

최소 거리

참고

옵션이 포함된 $geoNear let

바운드 옵션이 있는 $geoNear let

사용할 지리 공간적 인덱스 지정

참고

최대 거리

최소 거리

최대 거리

최소 거리

자세히 알아보기

옵션이 포함된 $geoNear `let`

바운드 옵션이 있는 $geoNear `let`