집계 빌더

개요

이 가이드에서는 애그리게이션 을 사용하는 방법을 배울 수 있습니다. MongoDB Java 드라이버에서 집계 파이프라인 단계 를 빌드하는 정적 팩토리 메서드를 제공하는 클래스입니다.

애그리게이션에 대해 자세히 알아보려면 애그리게이션 가이드 를 참조하세요. 검색 가능하고 안전한 형식의 Java 메서드를 사용하여 애그리게이션에서 사용할 표현식 작업을 생성하는 방법을 알아보려면 애그리게이션 표현식 작업을 참조하세요.

import static com.mongodb.client.model.Aggregates.*;
import static com.mongodb.client.model.Filters.*;
import static com.mongodb.client.model.Projections.*;
import static com.mongodb.client.model.Sorts.*;
import static com.mongodb.client.model.Accumulators.*;
import static com.mongodb.client.model.search.SearchPath.fieldPath;
import static com.mongodb.client.model.search.VectorSearchOptions.vectorSearchOptions;
import static java.util.Arrays.asList;

다음 메서드를 사용하여 파이프라인 단계를 구성하고 이를 애그리게이션에 목록으로 지정합니다.

Bson matchStage = match(eq("some_field", "some_criteria"));
Bson sortByCountStage = sortByCount("some_field");
collection.aggregate(asList(matchStage, sortByCountStage)).forEach(doc -> System.out.println(doc));

match

match() 메서드를 사용하여 수신 문서를 지정된 쿼리 필터와 일치시켜 일치하지 않는 문서를 필터링하는 $match 파이프라인 단계를 만듭니다.

다음 예에서는 title 필드가 'The Shawshank Redemption'과 동일한 모든 문서와 일치하는 파이프라인 단계를 만듭니다.

match(eq("title", "The Shawshank Redemption"));

프로젝트

project() 메서드를 사용하여 지정된 문서 필드를 프로젝션하는 $project 파이프라인 단계를 만듭니다. 애그리게이션에서의 필드 프로젝션은 쿼리에서의 필드 프로젝션과 동일한 규칙을 따릅니다.

다음 예에서는 _id 필드를 제외하고 title 및 plot 필드를 포함하는 파이프라인 단계를 만듭니다.

project(fields(include("title", "plot"), excludeId()));

project(fields(computed("rating", "$rated"), excludeId()));

문서

documents() 메서드를 사용하여 입력 값에서 리터럴 문서를 반환하는 $documents 파이프라인 단계를 만듭니다.

다음 예에서는 title 필드가 있는 샘플 문서를 생성하는 파이프라인 단계를 만듭니다.

documents(asList(
        new Document("title", "The Shawshank Redemption"),
        new Document("title", "Back to the Future"),
        new Document("title", "Jurassic Park")));

Sample

sample() 메서드를 사용하여 입력에서 문서를 무작위로 선택하는 $sample 파이프라인 단계를 만듭니다.

다음 예에서는 무작위로 5개 문서를 선택하는 파이프라인 단계를 만듭니다.

sample(5);

정렬

sort() 메서드를 사용하여 지정된 기준에 따라 정렬하는 $sort 파이프라인 단계를 만듭니다.

다음 예에서는 year 필드 값에 따라 내림차순으로 정렬한 다음 title 필드 값에 따라 오름차순으로 정렬하는 파이프라인 단계를 만듭니다.

sort(orderBy(descending("year"), ascending("title")));

Skip

skip() 메서드를 사용하여 문서를 다음 단계로 전달하기 전에 지정된 수의 문서를 건너뛰는 $skip 파이프라인 단계를 만듭니다.

다음 예에서는 처음 5개 문서를 건너뛰는 파이프라인 단계를 만듭니다.

skip(5);

Limit

$limit 파이프라인 단계를 사용하여 다음 단계로 전달되는 문서 수를 제한합니다.

다음 예에서는 문서 수를 10개로 제한하는 파이프라인 단계를 만듭니다.

limit(10);

Lookup

lookup() 메서드를 사용하여 두 컬렉션 간에 조인 및 상관관계가 없는 하위 쿼리를 수행하는 $lookup 파이프라인 단계를 만듭니다.

lookup("comments", "_id", "movie_id", "joined_comments");

List<Variable<String>> variables = asList(new Variable<>("order_item", "$item"),
        new Variable<>("order_qty", "$ordered"));
List<Bson> pipeline = asList(
        match(expr(new Document("$and",
                asList(new Document("$eq", asList("$$order_item", "$stock_item")),
                        new Document("$gte", asList("$instock", "$$order_qty")))))),
        project(fields(exclude("stock_item"), excludeId())));
Bson innerJoinLookup = lookup("warehouses", variables, pipeline, "stockdata");

Group

group() 메서드를 사용하여 지정된 표현식으로 문서를 그룹화하고 각 개별 그룹화에 대해 문서를 출력하는 $group 파이프라인 단계를 만듭니다.

다음 예에서는 customerId 필드 값을 기준으로 문서를 그룹화하는 파이프라인 단계를 만듭니다. 각 그룹은 quantity 필드 값의 합계와 평균을 totalQuantity 및 averageQuantity 필드에 축적합니다.

group("$customerId", sum("totalQuantity", "$quantity"), avg("averageQuantity", "$quantity"));

축적자 연산자에 대한 자세한 내용은 MongoDB Server 매뉴얼의 축적자 섹션을 참조하세요.

Pick-N 축적자

pick-n 축적자는 특정 순서가 지정된 경우 상위 및 하위 요소를 반환하는 애그리게이션 축적 연산자입니다. 애그리게이션 축적 연산자를 만들려면 다음 빌더 중 하나를 사용합니다.

• minN()

• maxN()

• firstN()

• lastN()

• top()

• topN()

• bottom()

• bottomN()

축적자에 대한 MongoDB Server 매뉴얼 섹션에서 축적자 연산자를 사용할 수 있는 집계 파이프라인 단계를 알아보세요 .

group(
        "$year",
        minN(
                "lowest_three_ratings",
                new BsonString("$imdb.rating"),
                3
                ));

group(
        "$year",
        maxN(
                "highest_two_ratings",
                new BsonString("$imdb.rating"),
                2
                ));

group(
        "$year",
        firstN(
                "first_four_movies",
                new BsonString("$title"),
                4
                ));

group(
        "$year",
        lastN(
                "last_three_movies",
                new BsonString("$title"),
                3
                ));

group(
        "$year", 
        top(
                "top_rated_movie",
                descending("imdb.rating"),
                asList(new BsonString("$title"), new BsonString("$imdb.rating"))
                ));

group(
        "$year", 
        topN(
                "longest_three_movies",
                descending("runtime"),
                asList(new BsonString("$title"), new BsonString("$runtime")),
                3
                ));

group(
        "$year", 
        bottom(
                "shortest_movies",
                descending("runtime"),
                asList(new BsonString("$title"), new BsonString("$runtime"))
                ));

group(
        "$year", 
        bottomN(
                "lowest_rated_two_movies",
                descending("imdb.rating"),
                asList(new BsonString("$title"), new BsonString("$imdb.rating")),
                2
                ));

풀다

unwind() 메서드를 사용하여 입력 문서에서 배열 필드를 분해하고 각 배열 요소에 대한 출력 문서를 생성하는 $unwind 파이프라인 단계를 만듭니다.

다음 예에서는 sizes 배열의 각 요소에 대한 문서를 만듭니다.

unwind("$sizes");

배열 필드에 값이 누락되어 있거나, null 값이 있거나, 배열이 비어 있는 문서를 보존하려면 다음을 수행합니다.

unwind("$sizes", new UnwindOptions().preserveNullAndEmptyArrays(true));

이 예에서는 배열 인덱스를 포함하기 위해 "position"이라는 필드에 다음을 수행합니다.

unwind("$sizes", new UnwindOptions().includeArrayIndex("position"));

Out

out() 메서드를 사용하여 동일한 데이터베이스의 지정된 컬렉션에 모든 문서를 쓰는 $out 파이프라인 단계를 만듭니다.

다음 예에서는 파이프라인의 결과를 authors 컬렉션에 씁니다.

out("authors");

Merge

merge() 메서드를 사용하여 모든 문서를 지정된 컬렉션에 병합하는 $merge 파이프라인 단계를 만듭니다.

다음 예에서는 기본 옵션을 사용하여 파이프라인을 authors 컬렉션에 병합합니다.

merge("authors");

다음 예에서는 date 및 customerId 둘 다 일치하는 경우 문서를 대체하고 그렇지 않으면 문서를 삽입하도록 지정하는 몇 가지 옵션을 사용하여 파이프라인을 reporting 데이터베이스의 customers 컬렉션에 병합합니다.

merge(new MongoNamespace("reporting", "customers"),
        new MergeOptions().uniqueIdentifier(asList("date", "customerId"))
                .whenMatched(MergeOptions.WhenMatched.REPLACE)
                .whenNotMatched(MergeOptions.WhenNotMatched.INSERT));

GraphLookup

graphLookup() 메서드를 사용하여 지정된 컬렉션에서 재귀 검색을 수행하여 한 문서의 지정된 필드를 다른 문서의 지정된 필드와 일치시키는 $graphLookup 파이프라인 단계를 만듭니다.

다음 예에서는 friends 필드의 값을 name 필드에 반복적으로 일치시켜 contacts 컬렉션의 사용자에 대한 소셜 네트워크 그래프를 계산합니다.

graphLookup("contacts", "$friends", "friends", "name", "socialNetwork");

원하는 경우 GraphLookupOptions를 사용하여 반복 사용할 깊이와 깊이 필드의 이름을 지정할 수 있습니다. 이 예에서 $graphLookup은 최대 두 번 반복되고 모든 문서에 대한 재귀 깊이 정보가 포함된 degrees 필드를 만듭니다.

graphLookup("contacts", "$friends", "friends", "name", "socialNetwork",
        new GraphLookupOptions().maxDepth(2).depthField("degrees"));

GraphLookupOptions를 사용하면 MongoDB에서 검색에 문서가 포함되도록 문서를 일치시키는 필터를 지정할 수 있습니다. 이 예에서는 hobbies 필드에 '골프'가 포함된 링크만 포함됩니다.

graphLookup("contacts", "$friends", "friends", "name", "socialNetwork",
        new GraphLookupOptions().maxDepth(1).restrictSearchWithMatch(eq("hobbies", "golf")));

SortByCount

sortByCount() 메서드를 사용하여 지정된 표현식을 기준으로 문서를 그룹화한 다음 이러한 그룹을 내림차순으로 카운트별로 정렬하는 $sortByCount 파이프라인 단계를 만듭니다.

[
    { "$group": { "_id": <expression to group on>, "count": { "$sum": 1 } } },
    { "$sort": { "count": -1 } }
]

다음 예에서는 x 필드의 잘린 값을 기준으로 문서를 그룹화하고 각 고유 값의 개수를 계산합니다.

sortByCount(new Document("$floor", "$x"));

ReplaceRoot

replaceRoot() 메서드를 사용하여 각 입력 문서를 지정된 문서로 대체하는 $replaceRoot 파이프라인 단계를 만듭니다.

다음 예에서는 각 입력 문서를 spanish_translation 필드의 중첩 문서로 바꿉니다.

replaceRoot("$spanish_translation");

AddFields

addFields() 메서드를 사용하여 문서에 새 필드를 추가하는 $addFields 파이프라인 단계를 만듭니다.

다음 예에서는 입력 문서에 a 및 b라는 두 개의 새 필드를 추가합니다.

addFields(new Field("a", 1), new Field("b", 2));

Count

count() 메서드를 사용하여 단계에 들어가는 문서 수를 계산하고 해당 값을 지정된 필드 이름에 할당하는 $count 파이프라인 단계를 만듭니다. 필드를 지정하지 않으면 count() 는 기본적으로 필드 이름을 "count"로 설정합니다.

{ "$group":{ "_id": 0, "count": { "$sum" : 1 } } }

다음 예에서는 'total' 필드의 수신 문서 수를 출력하는 파이프라인 단계를 만듭니다.

count("total");

Bucket

bucket() 메서드를 사용하여 미리 정의된 경계 값을 중심으로 데이터 버킷을 자동화하는 $bucket 파이프라인 단계를 만듭니다.

다음 예에서는 screenSize 필드의 값을 기준으로 수신 문서를 그룹화하는 파이프라인 단계를 만듭니다. 여기에서 하한 경계 값과 상한 경계 값은 제외됩니다.

bucket("$screenSize", asList(0, 24, 32, 50, 70, 200));

BucketOptions 클래스를 사용하여 지정된 경계를 벗어난 값에 대한 기본 버킷을 지정하고 추가적인 축적자를 지정할 수 있습니다.

다음 예에서는 screenSize 필드 값을 기준으로 수신 문서를 그룹화하고, 각 버킷에 속하는 문서 수를 계산하여, screenSize 값을 matches라는 필드에 넣고, 화면 크기가 '70' 보다 큰 경우 'monster'라는 버킷에 캡처하여 엄청나게 큰 화면 크기로 저장하는 파이프라인 단계를 만듭니다.

bucket("$screenSize", asList(0, 24, 32, 50, 70),
        new BucketOptions().defaultBucket("monster").output(sum("count", 1), push("matches", "$screenSize")));

BucketAuto

bucketAuto() 메서드를 사용하여 지정된 수의 버킷에 문서를 균등하게 배포하려고 시도할 때 각 버킷의 경계를 자동으로 결정하는 $bucketAuto 파이프라인 단계를 만듭니다.

다음 예에서는 price 필드 값을 사용하여 문서를 생성하고 10개의 버킷에 균등하게 배포하려고 시도하는 파이프라인 단계를 만듭니다.

bucketAuto("$price", 10);

BucketAutoOptions 클래스를 사용하여 기본 숫자 기반의 체계를 지정하여 경계 값을 설정하고 추가적인 축적자를 지정합니다.

다음 예에서는 price 필드 값을 사용하여 문서를 10개 버킷에 생성하고 균등하게 배포하는 파이프라인 단계를 만들고, 버킷 경계를 2의 거듭제곱(2, 4, 8, 16, ...)으로 설정합니다. 또한 각 버킷의 문서 수를 계산하고 avgPrice라는 새 필드에서 평균 price를 계산합니다.

bucketAuto("$price", 10, new BucketAutoOptions().granularity(BucketGranularity.POWERSOF2)
        .output(sum("count", 1), avg("avgPrice", "$price")));

패싯

facet() 메서드를 사용하여 병렬 파이프라인을 정의할 수 있는 $facet 파이프라인 단계를 만듭니다.

다음 예에서는 두 개의 병렬 애그리게이션을 실행하는 파이프라인 단계를 만듭니다.

• 첫 번째 애그리게이션은 수신 문서를 attributes.screen_size 필드에 따라 5개 그룹으로 배포합니다.

• 두 번째 애그리게이션은 모든 manufacturers를 계산하고 상위 5개로 제한되는 개수를 반환합니다.

facet(new Facet("Screen Sizes",
        bucketAuto("$attributes.screen_size", 5, new BucketAutoOptions().output(sum("count", 1)))),
        new Facet("Manufacturer", sortByCount("$attributes.manufacturer"), limit(5)));

SetWindowFields

setWindowFields() 메서드를 사용하여 기간 연산자를 통해 컬렉션의 지정된 기간 범위의 문서에서 작업을 수행할 수 있는 $setWindowFields 파이프라인 단계를 만듭니다.

다음 예에서는 rainfall 및 temperature 필드에 표시된 보다 세분화된 측정값을 바탕으로 각 지역의 지난 달 누적 강우량과 평균 기온을 계산하는 파이프라인 단계를 만듭니다.

Window pastMonth = Windows.timeRange(-1, MongoTimeUnit.MONTH, Windows.Bound.CURRENT);
setWindowFields("$localityId", Sorts.ascending("measurementDateTime"),
        WindowOutputFields.sum("monthlyRainfall", "$rainfall", pastMonth),
        WindowOutputFields.avg("monthlyAvgTemp", "$temperature", pastMonth));

Densify

densify() 메서드를 사용하여 지정된 간격에 걸쳐 일련의 문서 시퀀스를 생성하는 $densify 파이프라인 단계를 만듭니다.

1시간 간격으로 유사한 position 필드에 대한 측정값이 포함된 Atlas 샘플 날씨 데이터 세트 에서 검색한 다음 문서를 가정해 보겠습니다.

Document{{ _id=5553a..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:00:00 EST 1984, ... }}
Document{{ _id=5553b..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 09:00:00 EST 1984, ... }}

이러한 문서에서 아래의 조치를 수행하는 파이프라인 단계를 생성해야 한다고 가정해 보겠습니다.

• ts 값이 아직 존재하지 않는 경우 15분 간격으로 문서를 추가합니다.

• position 필드를 기준으로 문서를 그룹화합니다.

이러한 조치를 수행하는 densify() 애그리게이션 단계 빌더에 대한 호출은 다음과 유사합니다.

densify(
        "ts", 
        DensifyRange.partitionRangeWithStep(15, MongoTimeUnit.MINUTE),
        DensifyOptions.densifyOptions().partitionByFields("position.coordinates"));

다음 출력에는 기존 문서 간에 15분마다 ts 값을 포함하는 애그리게이션 단계에서 생성된 문서가 강조되어 있습니다.

Document{{ _id=5553a..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:00:00 EST 1984, ... }}
Document{{ position=Document{{coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:15:00 EST 1984 }}
Document{{ position=Document{{coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:30:00 EST 1984 }}
Document{{ position=Document{{coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:45:00 EST 1984 }}
Document{{ _id=5553b..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 09:00:00 EST 1984, ... }}

자세한 내용은 densify 패키지 API 설명서를 참조하세요.

가득 따르다

fill() 메서드를 사용하여 null 및 누락된 필드 값을 채우는 $fill 파이프라인 단계를 만듭니다.

시간별 온도 및 기압 측정 값이 포함된 다음 문서를 고려합니다.

Document{{_id=6308a..., hour=1, temperature=23C, air_pressure=29.74}}
Document{{_id=6308b..., hour=2, temperature=23.5C}}
Document{{_id=6308c..., hour=3, temperature=null, air_pressure=29.76}}

다음과 같이 문서에서 누락된 온도 및 기압 데이터 포인트를 채워야 한다고 가정해 보겠습니다.

• 선형 보간법을 사용하여 '2' 시간에 대한 air_pressure 필드를 채워 값을 계산합니다.

• 누락된 temperature 값을 '3' 시간에 대해 '23.6C'로 설정합니다.

이러한 조치를 수행하는 fill() 애그리게이션 단계 빌더에 대한 호출은 다음과 유사합니다.

fill(
        FillOptions.fillOptions().sortBy(ascending("hour")),
        FillOutputField.value("temperature", "23.6C"),
        FillOutputField.linear("air_pressure")
        );

다음 출력에는 애그리게이션 단계에서 채워진 필드가 포함된 문서가 강조되어 있습니다.

Document{{_id=6308a..., hour=1, temperature=23C, air_pressure=29.74}}
Document{{_id=6308b..., hour=2, temperature=23.5C, air_pressure=29.75}}
Document{{_id=6308c..., hour=3, temperature=23.6C, air_pressure=29.76}}

자세한 내용은 fill 패키지 API 설명서를 참조하세요.

Atlas 전체 텍스트 검색

search() 메서드를 사용하여 하나 이상의 필드에 대한 전체 텍스트 검색을 지정하는 $search 파이프라인 단계를 만듭니다.

다음 예에서는 title 필드에서 'Future'라는 단어가 포함된 텍스트를 검색하는 파이프라인 단계를 만듭니다.

Bson textSearch = Aggregates.search(
        SearchOperator.text(
                SearchPath.fieldPath("title"), "Future"));

Atlas Search API 패키지 문서에서 빌더에 대해 자세히 알아보세요.

Atlas Search 메타데이터

searchMeta() 메서드를 사용하여 Atlas 전체 텍스트 검색 쿼리에서 결과의 메타데이터 부분만 반환하는 $searchMeta 파이프라인 단계를 만듭니다.

다음 예에서는 Atlas Search 애그리게이션 단계의 count 메타데이터를 보여 줍니다.

Aggregates.searchMeta(
        SearchOperator.near(2010, 1, SearchPath.fieldPath("year")));

searchMeta() API 문서에서이 헬퍼에 대해 자세히 알아보세요.

Atlas Vector Search

vectorSearch() 메서드를 사용하여 시맨틱 Atlas Search 를 지정하는 $vectorSearch 파이프라인 단계를 만듭니다. 시맨틱 Atlas Search는 의미가 유사한 정보를 찾는 Atlas Search의 한 유형입니다.

이 기능을 사용하려면 벡터 Atlas Search 인덱스를 설정하고 벡터 임베딩을 인덱스해야 합니다. MongoDB Atlas 에서 이를 설정하는 방법을 알아보려면 Vector Atlas Search를 위한 벡터 임베딩을 인덱스하는 방법을 참조하세요.

다음 예에서는 vectorSearch() 및 project() 메서드를 사용하여 벡터 검색 점수를 계산하는 애그리게이션 파이프라인을 구축하는 방법을 보여줍니다.

List<Double> queryVector = (asList(-0.0072121937, -0.030757688, -0.012945653));
String indexName = "mflix_movies_embedding_index";
FieldSearchPath fieldSearchPath = fieldPath("plot_embedding");
int numCandidates = 2;
int limit = 1;
VectorSearchOptions options = vectorSearchOptions().filter(gte("year", 2016));
List<Bson> pipeline = asList(
        vectorSearch(
                fieldSearchPath,
                queryVector,
                indexName,
                numCandidates,
                limit,
                options),
        project(
                metaVectorSearchScore("vectorSearchScore")));

다음 예에서는 앞에 설명한 애그리게이션 파이프라인의 결과에서 점수를 출력하는 방법을 보여줍니다.

Document found = collection.aggregate(pipeline).first();
double score = found.getDouble("vectorSearchScore").doubleValue();
System.out.println("vectorSearch score: " + score);

이 헬퍼에 대한 자세한 내용은 vectorSearch() API 설명서를 참조하세요.