/ /

$geoNear (집계 단계)

정의

$geoNear

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

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

{ $geoNear: { <geoNear options> } }

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

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

행동

거리 계산

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

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

고려 사항

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

$geoNear 는 파이프라인 의 첫 번째 단계로만 사용할 수 있습니다.
$geoNear 에는 지리 공간적 인덱스 필요합니다.

컬렉션 에 지리 지리 공간적 인덱스 두 개 이상 있는 경우 keys 매개변수를 사용하여 계산에 사용할 필드 지정합니다. 지리 공간적 인덱스 하나만 있는 경우 $geoNear 는 암시적으로 계산에 인덱싱된 필드 사용합니다.

$geoNear 단계의 query 필드에는 $near 술어를 지정할 수 없습니다.
$geoNear 더 이상 기본 문서 수가 100개로 제한되지 않습니다.
near 매개변수는 let 옵션과 바인딩된 let 옵션을 지원합니다.
time series 컬렉션의 모든 필드에서 $geoNear 파이프라인 연산자를 사용할 수 있습니다. 그러나 time series 컬렉션 에서는 $geoNear 에 query 필드 사용할 수 없습니다.
time series 컬렉션 의 모든 필드에 부분 및 2dsphere 인덱스를만들 수 있습니다.
MongoDB 8.0, $near, $nearSphere 및 $geoNear부터 지정된 GeoJSON 포인트의 유형이 Point인지 검증합니다. 다른 입력 유형은 오류를 반환합니다.

예시

다음 문서를 사용하여 컬렉션 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" } )

최대 거리

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

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
     }
   }
])

`let` 옵션이 포함된 $geoNear

이 예시에서는

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 ] } }
}

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

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

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

let : $pt를 정의하기 위해
$geoNear pipeline에 있습니다.
$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 데이터베이스 사용합니다. 무료 MongoDB Atlas cluster 생성하고 샘플 데이터 세트를 로드하는 방법을 학습하려면 MongoDB .NET/ C# 드라이버 문서에서 시작하기 를 참조하세요.

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

[BsonIgnoreExtraElements]
public class Theater
{
    [BsonId]
    public ObjectId Id { get; set; }
    [BsonElement("theaterId")]
    public int TheaterId { get; set; }
    [BsonElement("location")]
    public TheaterLocation Location { get; set; } = null!;
    [BsonElement("distance")]
    public double? Distance { get; set; }
}
[BsonIgnoreExtraElements]
public class TheaterLocation
{
    [BsonElement("address")]
    public TheaterAddress Address { get; set; } = null!;
}
[BsonIgnoreExtraElements]
public class TheaterAddress
{
    [BsonElement("city")]
    public string? City { get; set; }
    [BsonElement("state")]
    public string? State { get; set; }
}

MongoDB .NET/ C# 운전자 사용하여 집계 파이프라인 에 $geoNear 단계를 추가하려면 PipelineDefinition 객체 에서 UnionWith() 메서드를 호출합니다.

이 메서드는 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"),
        });

{ "_id" : "...", "theaterId" : 344, "location" : { "address" : { "city" : "Paramus", "state" : "NJ" } }, "distance" : "..." }
{ "_id" : "...", "theaterId" : 2978, "location" : { "address" : { "city" : "Paramus", "state" : "NJ" } }, "distance" : "..." }
{ "_id" : "...", "theaterId" : 1936, "location" : { "address" : { "city" : "Paramus", "state" : "NJ" } }, "distance" : "..." }
{ "_id" : "...", "theaterId" : 887, "location" : { "address" : { "city" : "Paramus", "state" : "NJ" } }, "distance" : "..." }

최소 거리

다음 예시 지정된 점 의 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);

{ "_id" : "...", "theaterId" : 468, "location" : { "address" : { "city" : "Woodland Park", "state" : "NJ" } }, "distance" : "..." }
{ "_id" : "...", "theaterId" : 8539, "location" : { "address" : { "city" : "Bloomfield", "state" : "NJ" } }, "distance" : "..." }
{ "_id" : "...", "theaterId" : 2703, "location" : { "address" : { "city" : "Wayne", "state" : "NJ" } }, "distance" : "..." }
{ "_id" : "...", "theaterId" : 2509, "location" : { "address" : { "city" : "Riverdale", "state" : "NJ" } }, "distance" : "..." }

이 페이지의 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` 옵션이 있는 $geoNear