intercalación

Colección

Puede establecer una intercalación predeterminada al crear una colección. Al crear una colección con una intercalación específica, todas las operaciones compatibles que la analicen aplicarán las reglas de la intercalación.

Solo se puede asignar una Intercalación predeterminada a una colección al crear esa colección. Sin embargo, puedes especificar una intercalación en un nuevo índice de una colección existente. Consulta la sección Índice de esta guía para obtener más información.

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

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

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

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

La salida de tu código debe contener lo siguiente:

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

Index

Puedes especificar una intercalación cuando creas un nuevo índice en una colección. El índice almacena una representación ordenada de los documentos en la colección, de modo que tu operación no realice la ordenación en memoria. Para usar el índice, tu operación debe cumplir los siguientes criterios:

• La operación utiliza la misma intercalación que la especificada en el índice.

• La operación está cubierta por el índice que contiene la intercalación.

El siguiente fragmento de código muestra cómo puede crear un índice en el campo "nombre" con la intercalación de configuración regional "en_US" en orden ascendente:

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 comprobar si creó la intercalación correctamente, obtenga una lista de los índices en esa colección de la siguiente manera:

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

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

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

El siguiente snippet muestra un ejemplo de operación que especifica la misma intercalación y está cubierto por el índice que creamos en el snippet anterior:

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

Operación

Puede anular la intercalación predeterminada de una colección pasando la nueva intercalación como parámetro a una de las operaciones compatibles. Sin embargo, dado que la operación no utiliza un índice, podría no funcionar tan bien como una operación que sí lo esté. Para obtener más información sobre las desventajas de las operaciones de ordenación que no están incluidas en un índice, consulte la página del manual del servidor sobre el uso de índices para ordenar los resultados de las consultas.

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

• La colección referenciada contiene la intercalación por defecto "en_US", similar a la especificada en la sección Colección.

• La query especifica la intercalación islandesa («is»), que no está cubierta por el índice de intercalación por defecto de la colección.

• Dado que la intercalación especificada no está cubierta por un índice, la operación de ordenación se realiza en la memoria.

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

Tipos de índice que no admiten intercalaciones

Aunque la mayoría de los tipos de índices de MongoDB admiten la intercalación, los siguientes tipos admiten únicamente la comparación binaria:

• text

• 2d

find() and sort() Example

El siguiente ejemplo demuestra cómo se puede 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.

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

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, consulte la siguiente documentación de la API:

• find()

• clasificar()

• Ordena

Ejemplo de findOneAndUpdate()

Esta sección muestra cómo se puede especificar una intercalación en una operación que actualiza la primera coincidencia de su query. Para especificar la intercalación de esta operación, instancie un objeto FindOneAndUpdateOptions, establezca una intercalación en él y páselo como parámetro en su llamada al método findOneAndUpdate().

En este ejemplo, demostramos lo siguiente:

• Recupere el primer documento de nuestra colección de ejemplo que precede a "Gunter" en orden ascendente.

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

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

• Recupere e imprima el documento actualizado.

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

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

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

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

• findOneAndUpdate

• findOneAndUpdateOptions

• Filtros

• Updates

• Ordena

Ejemplo de findOneAndDelete()

Esta sección demuestra cómo puedes especificar un orden numérico de cadenas en una intercalación en una operación que elimina la primera coincidencia de tu query. Para especificar la intercalación para esta operación, instancie un objeto FindOneAndDeleteOptions, establezca una ordenación numérica en él y páselo como parámetro a su llamada al método findOneAndDelete().

Este ejemplo llama a la operación findOneAndDelete() en una colección que contiene los siguientes documentos:

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

En la intercalación, establecemos la opción locale en "en" y la opción numericOrdering en "verdadero" para ordenar cadenas en función de su orden numérico.

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

Después de ejecutar la operación anterior, el resultado será similar al siguiente:

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

El valor numérico de la cadena "179" es mayor que el número 100, por lo que el documento anterior es la única coincidencia.

Si realizamos la misma operación sin la intercalación de orden numérico en la colección original de tres documentos, el filtro coincide con todos nuestros documentos ya que "100" viene antes que "16", "84" y "179" cuando se ordena por intercalación binaria.

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

• findOneAndDelete

• FindOneAndDeleteOptions

• Filtros

• Ordena

Ejemplo de agregación

Esta sección demuestra cómo se puede especificar una intercalación en una operación de agregación. En una operación de agrupación, puedes especificar una serie de etapas de agregación que colectivamente se denominan el pipeline de agregación. Para realizar una agregación, llama al método aggregate() en un objeto MongoCollection.

Para especificar una intercalación para una operación de agregación, llama al método collation() en el AggregateIterable devuelto por la operación de agregación. Asegúrate de especificar una etapa de agregación de ordenamiento sobre la cual aplicar la intercalación en tu pipeline de agregación.

El siguiente ejemplo muestra cómo podemos construir un pipeline de agregación en la colección de ejemplo y aplicar una intercalación especificando lo siguiente:

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

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

• Aplicar una ordenación ascendente al campo _id de los documentos de salida de la etapa de agregación anterior.

• Construya un objeto de intercalación, especificando la localización alemana y una fuerza de intercalación que ignore los acentos y las diéresis.

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

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, consulte la siguiente documentación de la API:

• aggregate()

• AggregateIterable

• CollationStrength

• Acumuladores

• Agregados

• Ordena