집계 스테이지 (Aggregation Stages)

집계 스테이지 (Aggregation Stages)

집계 파이프라인의 각 단계(stage)는 문서를 가져와서 어떤 작업을 한 뒤, 그 결과를 다음 단계로 넘겨요. db.collection.aggregate()와 db.aggregate() 메서드에서는 파이프라인 단계들이 배열 안에 담겨요. 문서는 배열에 적힌 순서대로 단계를 지나가죠. Atlas UI에서는 집계 파이프라인 빌더로 단계를 나열할 수 있어요.

db.collection.aggregate([ { <stage> }, ... ])

db.collection.aggregate() 단계

$out, $merge, $geoNear, $changeStream, $changeStreamSplitLargeEvent를 제외한 모든 단계는 파이프라인 안에서 여러 번 등장할 수 있어요.

각 단계의 자세한 문법과 예시는 아래 표의 링크(명령 레퍼런스 페이지)를 따라가면 확인할 수 있어요.

단계 설명
$addFields 문서에 새 필드를 추가해요. $project처럼 스트림의 각 문서를 재구성하되, 기존 필드는 그대로 두고 새 필드만 더해요. $set은 $addFields의 별칭이에요.
$bucket 지정한 표현식과 버킷 경계를 기준으로 수신 문서를 버킷이라 부르는 그룹으로 분류해요.
$bucketAuto 지정한 표현식 기준으로 문서를 정해진 개수의 버킷으로 분류해요. 버킷 경계는 문서를 비슷한 개수로 고르게 나누도록 자동으로 정해져요.
$changeStream 컬렉션의 변경 스트림 커서를 반환해요. 이 단계는 파이프라인에서 한 번만, 그것도 반드시 첫 번째 단계로 사용해야 해요.
$changeStreamSplitLargeEvent 16MB를 넘는 큰 변경 스트림 이벤트를 작은 조각으로 나눠 변경 스트림 커서로 반환해요. $changeStreamSplitLargeEvent는 $changeStream 파이프라인에서만 쓸 수 있고, 반드시 파이프라인의 마지막 단계여야 해요.
$collStats 컬렉션이나 뷰에 관한 통계를 반환해요.
$count 이 시점까지 지나온 문서의 개수를 반환해요. $count 축적자와는 다르다는 점 주의하세요.
$densify 특정 필드 값이 빠져 있는 구간에 새 문서를 만들어 채워 넣어요.
$documents 입력 표현식에서 리터럴 문서를 반환해요.
$facet 같은 입력 문서 세트에 대해 여러 집계 파이프라인을 한 단계 안에서 처리해요. 여러 차원(패싯)으로 데이터를 살펴보는 다면적 집계를 하나의 단계로 만들 수 있어요.
$fill 문서 안의 null 값과 누락된 필드 값을 채워요.
$geoNear 지리 공간 점과의 근접성 순서로 정렬된 문서 스트림을 반환해요. $match, $sort, $limit의 기능을 지리 공간 데이터에 합쳐 놓은 거예요. 출력 문서에는 거리 필드가, 상황에 따라 위치 식별자 필드가 추가돼요.
$graphLookup 컬렉션에서 재귀 검색을 수행해요. 각 출력 문서에 그 문서의 재귀 검색 결과를 담은 새 배열 필드를 추가해요.
$group 지정한 식별자 표현식으로 입력 문서를 묶고, 지정했다면 각 그룹에 축적자 표현식을 적용해요. 모든 입력 문서를 소비한 뒤 고유한 그룹마다 문서 하나를 내보내요. 출력 문서에는 식별자 필드와 축적된 필드(지정한 경우)만 들어 있어요.
$indexStats 컬렉션의 각 인덱스 사용 통계를 반환해요.
$limit 처음 n개 문서만 수정 없이 파이프라인으로 통과시켜요. 각 입력 문서에 대해 처음 n개는 문서 하나, 그 이후는 문서 0개를 출력해요.
$listClusterCatalog 클러스터의 컬렉션 정보(이름, 생성 옵션 등)를 검색해요.
$listSampledQueries 모든 컬렉션 또는 특정 컬렉션의 샘플링된 쿼리를 나열해요.
$listSearchIndexes 지정한 컬렉션이나 뷰의 기존 MongoDB Search 인덱스 정보를 반환해요.
$listSessions system.sessions 컬렉션까지 전파될 만큼 오래 활성화된 모든 세션을 나열해요.
$lookup 같은 데이터베이스 안의 다른 컬렉션이나 뷰에 왼쪽 외부 조인(left outer join)을 수행해 조회된 문서를 처리에 포함시켜요.
$match 일치하는 문서만 수정 없이 다음 단계로 통과시키도록 문서 스트림을 필터링해요. $match는 표준 MongoDB 쿼리를 그대로 써요. 각 입력 문서에 대해 일치하면 문서 하나, 아니면 문서 0개를 출력해요.
$merge 집계 파이프라인의 결과 문서를 컬렉션에 써요. 새 문서 삽입, 병합, 교체, 기존 문서 유지, 작업 실패, 사용자 정의 업데이트 파이프라인 처리 등으로 결과를 출력 컬렉션에 반영할 수 있어요. $merge를 쓰려면 반드시 파이프라인의 마지막 단계여야 해요.
$out 집계 파이프라인의 결과 문서를 컬렉션에 써요. $out를 쓰려면 반드시 파이프라인의 마지막 단계여야 해요.
$planCacheStats 컬렉션의 플랜 캐시 정보를 반환해요.
$project 새 필드를 추가하거나 기존 필드를 제거하는 식으로 스트림의 각 문서 모양을 바꿔요. 각 입력 문서에 대해 문서 하나를 출력해요. 기존 필드 제거는 $unset도 함께 보세요.
$querySettings setQuerySettings로 이전에 추가한 쿼리 설정을 반환해요. 버전 8.0에 추가됐어요.
$queryStats 기록된 쿼리의 런타임 통계를 반환해요. 경고: $queryStats 집계 단계는 지원되지 않고, 향후 릴리스에서 안정성을 보장할 수 없어요. 출력 형식이 바뀔 수 있으니 이 단계의 특정 출력 형식에 의존하는 기능을 만들지 마세요.
$rankFusion 문서 순위를 매기는 입력 파이프라인 결과들을 결합해요. $rankFusion은 입력 파이프라인 결과의 중복을 제거하고 Reciprocal Rank Fusion 알고리즘으로 최종 문서 순위를 만들어요.
$redact 문서 자체에 저장된 정보를 바탕으로 각 문서의 내용을 제한해 스트림의 문서를 재구성해요. $project와 $match의 기능을 합친 것으로, 필드 수준 편집(redaction)을 구현할 때 쓸 수 있어요. 각 입력 문서에 대해 문서 하나 또는 0개를 출력해요.
$replaceRoot 문서를 지정한 임베디드 문서로 통째로 바꿔요. _id 필드를 포함해 입력 문서의 모든 기존 필드를 대체하죠. 입력 문서에 내장된 문서를 명시해 그 문서를 최상위 수준으로 끌어올리는 식이에요. $replaceWith는 $replaceRoot 단계의 별칭이에요.
$replaceWith 문서를 지정한 임베디드 문서로 바꿔요. _id 필드를 포함해 기존 필드를 모두 대체하고, 내장 문서를 최상위로 승격해요. $replaceWith는 $replaceRoot 단계의 별칭이에요.
$sample 입력에서 지정한 개수만큼 문서를 임의로 선택해요.
$search 컬렉션의 한 필드 또는 여러 필드에 대해 전체 텍스트 검색을 수행해요. 자세한 내용은 MongoDB Search 집계 파이프라인 단계를 참고하세요.
$searchMeta Atlas 컬렉션에 대해 수행한 MongoDB Search 쿼리의 다양한 메타데이터 결과 문서를 반환해요. 자세한 내용은 MongoDB Search 집계 파이프라인 단계를 참고하세요.
$set 문서에 새 필드를 추가해요. $project처럼 각 문서를 재구성하되 기존 필드는 유지하고 새 필드만 더해요. $set은 $addFields 단계의 별칭이에요.
$setWindowFields 문서를 창(window)으로 묶고 각 창의 문서에 연산자 하나 이상을 적용해요. 버전 5.0에 추가됐어요.
$skip 처음 n개 문서를 건너뛰고 나머지를 수정 없이 파이프라인으로 통과시켜요. 각 입력 문서에 대해 처음 n개는 문서 0개, 그 이후는 문서 하나를 출력해요.
$sort 지정한 정렬 키로 문서 스트림의 순서를 다시 정렬해요. 순서만 바뀌고 문서 내용은 그대로예요. 각 입력 문서에 대해 문서 하나를 출력해요.
$sortByCount 들어오는 문서를 지정한 표현식의 값으로 그룹화한 뒤, 고유한 그룹마다 문서 개수를 세서 반환해요.
$unionWith 두 컬렉션의 결합을 수행해요. 즉, 두 컬렉션 또는 뷰의 파이프라인 결과를 하나의 결과 세트로 합쳐요.
$unset 문서에서 필드를 제거/제외해요. $unset는 필드를 제거하는 $project 단계의 별칭이에요.
$unwind 입력 문서의 배열 필드를 분해해 요소 각각에 대한 문서를 출력해요. 각 출력 문서는 배열을 요소 값 하나로 대체한 형태예요. 각 입력 문서에 대해 배열 요소 개수만큼(빈 배열이면 0개) 문서를 출력해요.
$vectorSearch Atlas 컬렉션의 지정 필드에 있는 벡터에 대해 ANN 또는 ENN 검색을 수행해요. $vectorSearch는 MongoDB v6.0.11 이상의 MongoDB Atlas 클러스터에서만 사용할 수 있고, 자체 관리 배포에서는 쓸 수 없어요. 버전 7.0.2에 추가됐어요.

파이프라인 단계에서 쓸 수 있는 표현식에 대해서는 Expressions 문서를 참고하세요.

db.aggregate() 단계

MongoDB는 db.aggregate() 메서드도 제공해요.

db.aggregate([ { <stage> }, ... ])

아래 단계들은 db.collection.aggregate()가 아니라 db.aggregate() 메서드에서 사용해요.

단계 설명
$changeStream 컬렉션의 변경 스트림 커서를 반환해요. 이 단계는 파이프라인에서 한 번만, 반드시 첫 번째 단계로 사용해야 해요.
$currentOp MongoDB 배포에서 활성 및/또는 대기 중인 작업에 대한 정보를 반환해요.
$documents 입력 값에서 리터럴 문서를 반환해요.
$listLocalSessions 현재 연결된 mongos 또는 mongod 인스턴스에서 최근에 사용된 모든 활성 세션을 나열해요. 이 세션들은 아직 system.sessions 컬렉션으로 전파되지 않았을 수 있어요.

업데이트에서 사용 가능한 단계

업데이트에서도 집계 파이프라인을 사용할 수 있어요. 업데이트 파이프라인은 아래 단계들을 지원해요.

명령 mongosh 메서드
findAndModify db.collection.findOneAndUpdate(), db.collection.findAndModify()
update db.collection.updateOne(), db.collection.updateMany(), Bulk.find.update(), Bulk.find.updateOne(), Bulk.find.upsert()