intercalación

Colección

Solo se puede establecer una intercalación predeterminada para una colección durante su creación. Sin embargo, se puede especificar una intercalación en un nuevo índice de una colección existente. Todas las operaciones compatibles que analizan la colección aplican la intercalación predeterminada. Consulte la sección Índice de esta guía para obtener más información.

El siguiente ejemplo muestra cómo especificar la intercalación de localización "en_US" al crear una nueva colección llamada items:

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

Para comprobar si creó la intercalación correctamente, obtenga una lista de los índices en esa colección de la siguiente manera:

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

La salida del código anterior debe contener lo siguiente:

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

Index

Puede especificar una intercalación al crear un nuevo índice en una colección. El índice almacena documentos en el orden especificado, lo que elimina la necesidad de ordenación en memoria durante las query. Para usar el índice, la operación debe usar la misma intercalación que la especificada en el índice y estar cubierta por ese índice.

El siguiente ejemplo muestra cómo crear un índice en el campo "nombre" con la intercalación de localización "en_US" en orden ascendente:

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

Para comprobar si creó la intercalación correctamente, obtenga una lista de los índices en esa colección de la siguiente manera:

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

La salida del código anterior debe contener lo siguiente:

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

El siguiente ejemplo muestra una operación que especifica la misma intercalación y está cubierta por el índice creado en el ejemplo 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();

Operación

Puedes anular la intercalación predeterminada pasando una nueva intercalación a una operación compatible. Sin embargo, sin un índice, la consulta realiza una ordenación en memoria, lo que resulta más lento que usar una intercalación indexada. Para obtener más información sobre las desventajas de las operaciones de ordenación no cubiertas por un índice,consulta «Usar índices para ordenar los resultados de las consultas» en el manual de MongoDB Server.

El siguiente ejemplo muestra una operación de query con las siguientes características:

• La colección a la que se hace referencia tiene un "en_US" índice de intercalación predeterminado, similar al especificado en la sección Colección.

• La query especifica la intercalación islandesa ("is"). Debido a que esto difiere de la intercalación del índice, la query no utiliza el índice y, en su lugar, realiza una clasificación en memoria.

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 no admiten intercalaciones

La mayoría de los tipos de índice de MongoDB admiten la intercalación. Sin embargo, los siguientes tipos solo admiten la comparación binaria y no admiten la intercalación:

• text

• 2d

find() and sort() Example

El siguiente ejemplo muestra cómo aplicar una intercalación al recuperar resultados ordenados de una colección. Para realizar esta operación, llama a find() en la colección de ejemplos y encadena los métodos collation() y sort() para especificar el orden en el que deseas recibir los 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();

Cuando realizas esta operación en la colección de ejemplo, la salida se asemeja a la siguiente:

{"_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 obtener más información sobre los métodos y clases mencionados en esta sección, consulta la siguiente documentación de la API:

• find()

• sort()

• Ordena

Ejemplo de findOneAndUpdate()

El siguiente ejemplo especifica una intercalación en una operación findOneAndUpdate() instanciando un objeto FindOneAndUpdateOptions y pasándolo como parámetro. El ejemplo realiza las siguientes operaciones:

• Recupera el primer documento de la colección de ejemplos que precede a "Gunter" en orden ascendente.

• Configura opciones para la operación, incluyendo la intercalación "de@collation=phonebook".

• Añade un nuevo campo "verificado" con el valor "verdadero".

• Recupera e imprime el documento actualizado.

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

Dado que "Günter" aparece léxicamente antes de "Gunter" al utilizar la intercalación de@collation=phonebook en orden ascendente, la operación anterior devuelve el siguiente documento:

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

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulta la siguiente documentación de la API:

• findOneAndUpdate()

• FindOneAndUpdateOptions

• filtro

• Updates

• Ordena

Ejemplo de findOneAndDelete()

El siguiente ejemplo especifica una intercalación de ordenación numérica en una operación findOneAndDelete() al instanciar un objeto FindOneAndDeleteOptions y pasarlo como parámetro. La colección contiene los siguientes documentos:

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

La intercalación establece la opción locale en "en" y la opción numericOrdering en "true" para ordenar las cadenas en función de su 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());
}

Después de ejecutar la operación anterior, el resultado se asemeja a lo siguiente:

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

El valor numérico de la string "179" es mayor que 100, por lo que el documento anterior es el único que coincide. Sin ordenación numérica, la intercalación binaria ordena "100" antes que "16", "84" y "179", por lo que el filtro coincide con todos los documentos.

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulta la siguiente documentación de la API:

• findOneAndDelete()

• FindOneAndDeleteOptions

• filtro

• Ordena

Ejemplo de agregación

El siguiente ejemplo muestra cómo especificar una intercalación en una operación de agregación. Para realizar una agregación, llame al método aggregate() en un objeto MongoCollection.

Para especificar una intercalación para una operación de agregación, llame al método collation() en el AggregatePublisher devuelto por la operación de agregación. Especifique una etapa de agregación de ordenamiento en su pipeline para aplicar la intercalación.

El siguiente ejemplo construye una canalización de agregación en la colección de ejemplo y aplica una intercalación especificando lo siguiente:

• Una etapa de agregación de grupo que utiliza Aggregates.group() para identificar cada documento por el campo first_name y usar ese valor como el _id del resultado.

• Un acumulador en la etapa de grupo para sumar el número de instancias de valores coincidentes en el campo first_name.

• Una ordenación ascendente en el campo _id de los documentos de salida.

• Un objeto de intercalación que especifica la localización alemana y una fuerza de intercalación que ignora los acentos y las diéresis.

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

El código anterior genera los siguientes documentos:

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

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulta la siguiente documentación de la API:

• aggregate()

• AggregatePublisher

• CollationStrength

• Acumuladores

• Agregados

• Ordena