Agrupamentos

collection

Você pode definir um agrupamento padrão ao criar uma collection. Quando você cria uma collection com um agrupamento especificado, todas as operações suportadas que verificam essa collection aplicam as regras do agrupamento.

Você só pode atribuir um agrupamento padrão a uma collection ao criá-la. No entanto, você pode especificar um agrupamento em um novo índice em uma coleta existente. Consulte a seção Índice deste guia para obter mais informações.

O trecho a seguir mostra como especificar o agrupamento de localidade "en_US" ao criar uma nova collection chamada items:

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

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

MongoCollection<Document> collection = database.getCollection("items");
List<Document> indexes = new ArrayList<>();
collection.listIndexes().into(indexes);
// Prints the collection's indexes and any default collations
indexes.forEach(idx -> System.out.println(idx.toJson()));

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

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

Índice

Você pode especificar um agrupamento ao criar um novo índice em uma collection. O índice armazena uma representação ordenada dos documentos na collection para que sua operação não execute a ordenação na memória. Para usar o índice, sua operação deve atender aos seguintes critérios:

• A operação usa o mesmo agrupamento especificado no índice.

• A operação é coberta pelo índice que contém o agrupamento.

O seguinte trecho de código mostra como você pode criar um índice no campo "nome" com o agrupamento de localidade "en_US" em ordem crescente:

MongoCollection<Document> collection = database.getCollection("items");
IndexOptions idxOptions = new IndexOptions();
// Defines options that set a collation locale
idxOptions.collation(Collation.builder().locale("en_US").build());
// Creates an index on the "name" field with the collation and ascending sort order
collection.createIndex(Indexes.ascending("name"), idxOptions);

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

MongoCollection<Document> collection = database.getCollection("items");
List<Document> indexes = new ArrayList<>();
collection.listIndexes().into(indexes);
// Prints the collection's indexes and any default collations
indexes.forEach(idx -> System.out.println(idx.toJson()));

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

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

O seguinte trecho de código mostra uma operação de exemplo que especifica o mesmo agrupamento e é coberta pelo índice que criamos no trecho de código anterior:

FindIterable<Document> cursor = collection.find()
        .collation(Collation.builder().locale("en_US").build())
        .sort(Sorts.ascending("name"));

(operação)

Você pode substituir o agrupamento padrão em uma collection passando o novo agrupamento como parâmetro para uma das operações aceitas. No entanto, como a operação não usa um índice, a operação pode não funcionar tão bem quanto uma coberta por um índice. Para obter mais informações sobre as desvantagens das operações de classificação não cobertas por um índice, consulte a página do manual do servidor sobre Usar índices para classificar resultados de queries.

O seguinte trecho de código mostra um exemplo de operação de query com as seguintes características:

• A coleção referenciada contém o agrupamento padrão "en_US" semelhante ao especificado na seção Coleções.

• A query especifica o agrupamento Islandês ("é"), que não é coberto pelo índice de agrupamento padrão da collection.

• Como o agrupamento especificado não é coberto por um índice, a operação de classificação é executada na memória.

FindIterable<Document> cursor = collection.find()
        .collation(Collation.builder().locale("is").build())
        .sort(Sorts.ascending("name"));

Tipos de índice que não suportam agrupamentos

Embora a maioria dos tipos de índice MongoDB ofereça suporte ao agrupamento, os seguintes tipos oferecem suporte somente à comparação binária:

• texto

• 2d

Exemplo de find() e sort()

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

List<Document> results = new ArrayList<>();
// Retrieves all documents and applies a "de@collation-phonebook" collation and ascending sort to the results
collection.find()
        .collation(Collation.builder().locale("de@collation=phonebook").build())
        .sort(Sorts.ascending("first_name")).into(results);
// Prints the JSON representation of the results          
if (results != null) {
    results.forEach(doc -> System.out.println(doc.toJson()));
}

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 ()

Esta seção mostra como especificar um agrupamento em uma operação que atualiza o primeiro resultado correspondente à sua consulta. Para especificar o agrupamento para essa operação, instancie um objeto FindOneAndUpdateOptions, defina um agrupamento nele e use-o como parâmetro ao chamar o método findOneAndUpdate() .

Neste exemplo, demonstramos o seguinte:

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

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

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

• Recupere e imprima o documento atualizado.

Document result = collection.findOneAndUpdate(
        Filters.gt("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));
// Prints the JSON representation of the updated document if an update occurred           
if (result != null) {
    System.out.println("Updated document: " + result.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 de atualização:

{
  lastErrorObject: { updatedExisting: true, n: 1 },
  value: { _id: 3, first_name: 'Günter' },
  ok: 1
}

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

• Atualizações

• Tipos

Exemplo de findOneAndDelete()

Esta seção demonstra como você pode especificar uma ordenação numérica de strings em um agrupamento em uma operação que exclui a primeira correspondência da sua query. Para especificar o agrupamento para esta operação, instancie um objeto FindOneAndDeleteOptions , defina um agrupamento de ordem numérica nele e passe-o como um parâmetro para sua chamada ao método findOneAndDelete() .

Este exemplo chama a operação findOneAndDelete() em uma collection que contém os seguintes documento:

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

No agrupamento, definimos a opção locale como "en" e a opção numericOrdering como "true" para classificar as strings com base em sua ordem numérica.

Document result = collection.findOneAndDelete(
        Filters.gt("a", "100"),
        new FindOneAndDeleteOptions()
                .collation(
                        Collation.builder()
                                .locale("en")
                                .numericOrdering(true)
                                .build())
                .sort(Sorts.ascending("a")));
// Prints the JSON representation of the deleted document  
if (result != null) {
    System.out.println("Deleted document: " + result.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 o número 100, portanto, o documento anterior é a única correspondência.

Se executarmos a mesma operação sem o agrupamento de ordenação numérica na coleção original de três documentos, o filtro corresponderá a todos os nossos documentos, já que "100" vem antes de "16", "84" e "179" quando ordenados por agrupamento binário.

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

• encontrarOneAndDelete

• FindOneAndDeleteOptions

• Filtros

• Tipos

Exemplo de agregação

Esta seção demonstra como você pode especificar um agrupamento em uma operação de agregação. Em uma operação de agregação, você pode especificar uma série de estágios de agregação que são chamados coletivamente de pipeline 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 AggregateIterable retornado pela operação de agregação. Certifique-se de especificar um estágio de agregação de classificação no qual aplicar o agrupamento em seu pipeline de agregação.

O exemplo a seguir mostra como podemos construir um pipeline de agregação na coleção de exemplo e aplicar um agrupamento especificando o seguinte:

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

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

• Aplique uma classificação ascendente ao campo _id dos documentos de saída do estágio de agregação anterior.

• Construa um objeto de agrupamento, especificando a localidade 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"));
AggregateIterable<Document> results = collection
        // Runs the aggregation pipeline that includes tallying "first_name" frequencies
        .aggregate(Arrays.asList(groupStage, sortStage))
        // Applies a collation to sort documents alphabetically by using the German locale, ignoring accents
        .collation(Collation.builder().locale("de").collationStrength(CollationStrength.PRIMARY).build());
// Prints the JSON representation of the results
if (results != null) {
    results.forEach(doc -> System.out.println(doc.toJson()));
}

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()

• AggregateIterable

• Força do agrupamento

• Accumulators

• Agregados

• Tipos