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 configuración regional "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

Al crear un nuevo índice en una colección, puede especificar una intercalación. El índice almacena los documentos en el orden especificado, lo que elimina la necesidad de ordenarlos en memoria durante las consultas. Para usar el índice, la operación debe utilizar la misma intercalación que la especificada en el índice y estar cubierta por este.

El siguiente ejemplo muestra cómo crear un índice en el campo "nombre" con la intercalación de configuración regional "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 consulta 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 consulta especifica la intercalación islandesa ("is"). Dado que esta difiere de la intercalación del índice, la consulta no utiliza el índice y, en su lugar, realiza una ordenació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 índices de MongoDB admiten intercalación. Sin embargo, los siguientes tipos solo admiten comparación binaria y no admiten 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, llame al método find() en la colección de ejemplo y encadene los métodos collation() y sort() para especificar el orden en que desea 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.

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

• Agrega 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" está léxicamente antes que "Gunter" utilizando la intercalación de@collation=phonebook en orden ascendente, la operación precedente 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 orden numérico en una operación findOneAndDelete() mediante la creación de una instancia de un objeto FindOneAndDeleteOptions y su paso 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 "verdadero" para ordenar las cadenas según 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 cadena "179" es mayor que 100, por lo que el documento anterior es la única coincidencia. Sin orden numérico, 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 ordenación en su canalización 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 configuración regional alemana y una intensidad 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