Agrupamentos

collection

Você só pode definir um agrupamento padrão para uma coleção durante a criação. No entanto, você pode especificar um agrupamento em um novo índice em uma coleção existente. Todas as operações compatíveis que verificam a coleção então aplicam o agrupamento padrão. Consulte a seção Índice deste guia para obter mais informações.

O exemplo a seguir mostra como especificar o agrupamento de localidade "en_US" ao criar uma nova coleção chamada items:

Mono.from(database.createCollection(
                "items",
                new CreateCollectionOptions().collation(
                        Collation.builder().locale("en_US").build())))
        .block();

Para verificar se você criou o agrupamento com sucesso, recupere uma lista dos índices nessa coleção da seguinte maneira:

List<Document> indexes = Flux.from(itemsCollection.listIndexes())
        .collectList().block();
if (indexes != null) {
    indexes.forEach(idx -> System.out.println(idx.toJson()));
}

A saída do código anterior deve conter o seguinte:

{ ...
  "collation": { "locale": "en_US", ... }
  ...
}

Index

Você pode especificar um agrupamento ao criar um novo índice em uma coleção. O índice armazena documentos na ordem especificada, eliminando a necessidade de classificação na memória durante as query. Para usar o índice, a operação deve usar o mesmo agrupamento especificado no índice e ser coberta por esse índice.

O exemplo a seguir mostra como criar um índice no campo "nome" com o agrupamento de localidade "en_US" em ordem crescente:

IndexOptions idxOptions = new IndexOptions();
idxOptions.collation(Collation.builder().locale("en_US").build());
Mono.from(itemsCollection.createIndex(
        Indexes.ascending("name"), idxOptions)).block();

Para verificar se você criou o agrupamento com sucesso, recupere uma lista dos índices nessa coleção da seguinte maneira:

List<Document> indexes = Flux.from(itemsCollection.listIndexes())
        .collectList().block();
if (indexes != null) {
    indexes.forEach(idx -> System.out.println(idx.toJson()));
}

A saída do código anterior deve conter o seguinte:

{ ...
  "collation": { "locale": "en_US", ... }
  ...
}

O exemplo a seguir mostra uma operação que especifica o mesmo agrupamento e é coberta pelo índice criado no exemplo anterior:

FindPublisher<Document> indexPublisher = itemsCollection.find()
        .collation(Collation.builder().locale("en_US").build())
        .sort(Sorts.ascending("name"));
Flux.from(indexPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

(operação)

Você pode substituir o agrupamento padrão passando um novo agrupamento para uma operação suportada. No entanto, sem um índice, sua query executa a classificação na memória, o que é mais lento do que usar um agrupamento indexado. Para obter mais informações sobre as desvantagens das operações de classificação não cobertas por um índice, consulte Usar índices para classificar resultados de query no manual do MongoDB Server.

O exemplo a seguir mostra uma operação de query com as seguintes características:

• A coleção referenciada tem um índice de agrupamentos "en_US" padrão, semelhante ao especificado na seção Coleção.

• A query especifica o agrupamento islandês ("is"). Como isso difere do agrupamento de índice, a query não usa o índice e, em vez disso, executa uma classificação na memória.

FindPublisher<Document> customPublisher = itemsCollection.find()
        .collation(Collation.builder().locale("is").build())
        .sort(Sorts.ascending("name"));
Flux.from(customPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

Tipos de índice que não suportam agrupamentos

A maioria dos tipos de índice do MongoDB oferece suporte a agrupamentos. No entanto, os seguintes tipos oferecem suporte apenas à comparação binária e não oferecem suporte a agrupamentos:

• text

• 2d

Exemplo de find() e sort()

O exemplo a seguir mostra como aplicar um agrupamento ao recuperar resultados classificados de uma coleção. Para executar esta operação, chame find() na coleção de exemplo e encadeie os métodos collation() e sort() para especificar a ordem na qual você deseja receber os resultados.

FindPublisher<Document> findPublisher = phonebookCollection.find()
        .collation(Collation.builder()
                .locale("de@collation=phonebook").build())
        .sort(Sorts.ascending("first_name"));
Flux.from(findPublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

Quando você executa esta operação na coleção de exemplo, a saída se assemelha ao seguinte:

{"_id": 3, "first_name": "Günter"}
{"_id": 2, "first_name": "Gunter"}
{"_id": 5, "first_name": "Hannah"}
{"_id": 4, "first_name": "Jürgen"}
{"_id": 1, "first_name": "Klara"}

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• find()

• sort()

• Tipos

Exemplo de findOneAndUpdate ()

O exemplo a seguir especifica um agrupamento em uma operação findOneAndUpdate() instanciando um objeto FindOneAndUpdateOptions e passando-o como um parâmetro. O exemplo executa as seguintes operações:

• Recupera o primeiro documento na coleção de exemplo que precede "Gunter" em ordem crescente.

• Define as opções para a operação, incluindo o agrupamento "de@collation=phonebook".

• Adiciona um novo campo "verified" com o valor "true".

• Recupera e imprime o documento atualizado.

Document updatedDoc = Mono.from(
                phonebookCollection.findOneAndUpdate(
                        Filters.lt("first_name", "Gunter"),
                        Updates.set("verified", true),
                        new FindOneAndUpdateOptions()
                                .collation(Collation.builder()
                                        .locale("de@collation=phonebook")
                                        .build())
                                .sort(Sorts.ascending("first_name"))
                                .returnDocument(ReturnDocument.AFTER)))
        .block();
if (updatedDoc != null) {
    System.out.println("Updated document: " + updatedDoc.toJson());
}

Como "Günter" vem lexicalmente antes de "Gunter" usando o agrupamento de@collation=phonebook em ordem crescente, a operação anterior retorna o seguinte documento:

Updated document: {"_id": 3, "first_name": "Günter", "verified": true}

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• findOneAndUpdate()

• FindOneAndUpdateOptions

• Filtros

• Updates

• Tipos

Exemplo de findOneAndDelete()

O exemplo a seguir especifica um agrupamento de ordenação numérica em uma operação findOneAndDelete() instanciando um objeto FindOneAndDeleteOptions e passando-o como parâmetro. A coleção contém os seguintes documentos:

{ "_id" : 1, "a" : "16 apples" }
{ "_id" : 2, "a" : "84 oranges" }
{ "_id" : 3, "a" : "179 bananas" }

O agrupamento define a opção locale como "en" e a opção numericOrdering como "true" para classificar as strings com base em seu valor numérico.

Document deletedDoc = Mono.from(
                numericalCollection.findOneAndDelete(
                        Filters.gt("a", "100"),
                        new FindOneAndDeleteOptions()
                                .collation(Collation.builder()
                                        .locale("en")
                                        .numericOrdering(true)
                                        .build())
                                .sort(Sorts.ascending("a"))))
        .block();
if (deletedDoc != null) {
    System.out.println("Deleted document: " + deletedDoc.toJson());
}

Depois de executar a operação anterior, seu resultado será semelhante ao seguinte:

Deleted document: {"_id": 3, "a": "179 bananas"}

O valor numérico da string "179" é maior que 100, portanto, o documento anterior é a única correspondência. Sem ordem numérica, a agrupamentos binária classifica "100" antes de "16", "84" e "179", portanto, o filtro corresponde a todos os documentos.

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• findOneAndDelete()

• FindOneAndDeleteOptions

• Filtros

• Tipos

Exemplo de agregação

O exemplo a seguir mostra como especificar um agrupamento em uma operação de agregação. Para executar uma agregação, chame o método aggregate() em um objeto MongoCollection.

Para especificar um agrupamento para uma operação de agregação, chame o método collation() no AggregatePublisher retornado pela operação de agregação. Especifique um estágio de agregação de classificação em seu pipeline para aplicar o agrupamento.

O exemplo a seguir constrói um pipeline de agregação na coleção de exemplo e aplica um agrupamento especificando o seguinte:

• Um estágio de agregação de grupo usando Aggregates.group() para identificar cada documento pelo campo first_name e usar esse valor como _id do resultado.

• Um acumulador no estágio de grupo para somar o número de instâncias de valores correspondentes no campo first_name .

• Uma classificação ascendente no campo _id dos documentos de saída.

• Um objeto de agrupamento especificando a locale alemã e uma força de agrupamento que ignora acentos e umlauts.

Bson groupStage = Aggregates.group(
        "$first_name", Accumulators.sum("nameCount", 1));
Bson sortStage = Aggregates.sort(Sorts.ascending("_id"));
AggregatePublisher<Document> aggregatePublisher =
        phonebookCollection
                .aggregate(Arrays.asList(groupStage, sortStage))
                .collation(Collation.builder()
                        .locale("de")
                        .collationStrength(CollationStrength.PRIMARY)
                        .build());
Flux.from(aggregatePublisher)
        .doOnNext(doc -> System.out.println(doc.toJson()))
        .blockLast();

O código anterior gera os seguintes documentos:

{"_id": "Gunter", "nameCount": 2}
{"_id": "Hannah", "nameCount": 1}
{"_id": "Jürgen", "nameCount": 1}
{"_id": "Klara", "nameCount": 1}

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• Aggregate()

• Aggregatepublisher

• Força do agrupamento

• Accumulators

• Agregados

• Tipos