intercalación

Datos de muestra para ejemplos

Los ejemplos de esta página utilizan una colección MongoDB con los siguientes documentos:

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

Estos documentos son representados por la siguiente clase de datos:

data class FirstName(
    @BsonId val id: Int, 
    val firstName: String, 
    val verified: Boolean = false
)

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(
    "names",
    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:

val collection = database.getCollection<FirstName>("names")
val indexInformation = collection.listIndexes().first()
println(indexInformation.toJson())

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

Index

Puedes especificar una intercalación cuando creas un índice nuevo en una colección. El índice almacena una representación ordenada de los documentos en la colección, por lo que tu operación no necesita realizar el ordenamiento en la memoria. Para utilizar 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 snippet muestra cómo se puede crear un índice en el campo "firstName" con la intercalación de localización "en_US" en orden ascendente:

val collection = database.getCollection<FirstName>("names")
val idxOptions = IndexOptions().collation(Collation.builder().locale("en_US").build())
collection.createIndex(Indexes.ascending(FirstName::firstName.name), idxOptions)

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

val collection = database.getCollection<FirstName>("names")
val indexInformation = collection.listIndexes().first()
println(indexInformation.toJson())

{
  // ...
  "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:

val resultsFlow = collection.find()
    .collation(Collation.builder().locale("en_US").build())
    .sort(Sorts.ascending(FirstName::firstName.name));

Operación

Puedes anular la intercalación por defecto en una colección pasando la nueva intercalación como un parámetro a una de las operaciones admitidas. Sin embargo, como la operación no utiliza un índice, la operación puede no funcionar tan bien como una cubierta por un índice. Para obtener más información sobre las desventajas de las operaciones de ordenación no cubiertas por un índice, consulta la página del manual del servidor sobre Utiliza los índices para ordenar los resultados de la query.

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.

val findFlow = collection.find()
    .collation(Collation.builder().locale("is").build())
    .sort(Sorts.ascending(FirstName::firstName.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

• geoHaystack

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.

Cuando realizamos esta operación en nuestra colección de ejemplo, la salida debería ser similar a la siguiente:

val resultsFlow = collection.find()
    .collation(Collation.builder().locale("de@collation=phonebook").build())
    .sort(Sorts.ascending(FirstName::firstName.name))
resultsFlow.collect { println(it) }

FirstName(id=3, firstName=Günter, verified=false)
FirstName(id=2, firstName=Gunter, verified=false)
FirstName(id=5, firstName=Hannah, verified=false)
FirstName(id=4, firstName=Jürgen, verified=false)
FirstName(id=1, firstName=Klara, verified=false)

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.

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

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

• Recupere e imprima el documento actualizado.

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

val result = collection.findOneAndUpdate(
    Filters.lt(FirstName::firstName.name, "Gunter"),
    Updates.set("verified", true),
    FindOneAndUpdateOptions()
        .collation(Collation.builder().locale("de@collation=phonebook").build())
        .sort(Sorts.ascending(FirstName::firstName.name))
        .returnDocument(ReturnDocument.AFTER)
)
println(result)

FirstName(id=3, firstName=Günter, verified=true)

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" }

Estos documentos son representados por la siguiente clase de datos:

data class CollationExample(@BsonId val id: Int, val a: String)

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.

val result = collection.findOneAndDelete(
    Filters.gt(CollationExample::a.name, "100"),
    FindOneAndDeleteOptions()
        .collation(Collation.builder().locale("en").numericOrdering(true).build())
        .sort(Sorts.ascending(CollationExample::a.name))
)
println(result)

CollationExample(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 AggregateFlow 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 firstName 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 firstName.

• 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.

data class Result(@BsonId val id: String, val nameCount: Int)
val groupStage = Aggregates.group(
    "\$${FirstName::firstName.name}",
    Accumulators.sum("nameCount", 1)
)
val sortStage = Aggregates.sort(Sorts.ascending("_id"))
val resultsFlow = collection.aggregate<Result>(listOf(groupStage, sortStage))
    .collation(
        Collation.builder().locale("de")
            .collationStrength(CollationStrength.PRIMARY)
            .build()
    )
resultsFlow.collect { println(it) }

Result(id=Gunter, nameCount=2)
Result(id=Hannah, nameCount=1)
Result(id=Jürgen, nameCount=1)
Result(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()

• AggregateFlow

• CollationStrength

• Acumuladores

• Agregados

• Ordena