Intercalaciones

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 fragmento muestra cómo especificar la intercalación de configuració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 ha creado la intercalación correctamente, recupere una lista de los índices de 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 fragmento de código muestra cómo crear un índice en el campo "firstName" con la intercalación de configuración regional "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 ha creado la intercalación correctamente, recupere una lista de los índices de 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 fragmento de código muestra una operación de ejemplo que especifica la misma intercalación y está cubierta por el índice que creamos en el fragmento de código anterior:

val resultsFlow = collection.find()
    .collation(Collation.builder().locale("en_US").build())
    .sort(Sorts.ascending(FirstName::firstName.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 tener el mismo rendimiento que 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 predeterminada "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 clasificación se realiza en la memoria.

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

Tipos de índices que no admiten intercalaciones

Si bien la mayoría de los tipos de índice de MongoDB admiten la intercalación, los siguientes tipos solo admiten la comparación binaria:

• text

• 2 d

• geoHaystack

Ejemplo de find() y sort()

El siguiente ejemplo muestra cómo aplicar una intercalación al recuperar resultados ordenados de una colección. Para ello, llame a 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.

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 API:

• find()

• clasificar()

• Ordena

Ejemplo de findOneAndUpdate()

Esta sección muestra cómo especificar una intercalación en una operación que actualiza la primera coincidencia de la consulta. Para especificar la intercalación, cree una instancia de un objeto FindOneAndUpdateOptions, defínalo y páselo como parámetro al llamar 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.

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

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 API:

• findOneAndUpdate

• findOneAndUpdateOptions

• Filtros

• Updates

• Ordena

Ejemplo de findOneAndDelete()

Esta sección muestra cómo especificar el orden numérico de las cadenas en una intercalación durante una operación que elimina la primera coincidencia de la consulta. Para especificar la intercalación, cree una instancia de un objeto FindOneAndDeleteOptions, defínale una intercalación de orden numérico y pásela como parámetro al llamar 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 "true" para ordenar las cadenas según 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 de "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 API:

• findOneAndDelete

• Opciones de búsqueda y eliminación

• Filtros

• Ordena

Ejemplo de agregación

Esta sección muestra cómo especificar una intercalación en una operación de agregación. En una operación de agregación, se puede especificar una serie de etapas de agregación, denominadas conjuntamente canalización de agregación. Para realizar una agregación, se llama 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 valor AggregateFlow devuelto por la operación de agregación. Asegúrese de especificar una etapa de agregación de ordenación donde aplicar la intercalación en su canalización de agregación.

El siguiente ejemplo muestra cómo podemos construir una canalización 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 ayudante Aggregates.group() para identificar cada documento mediante el campo firstName y utilizar ese valor como el _id del resultado.

• Un acumulador en la etapa de agregación de grupo para sumar la cantidad 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 configuración regional alemana y un nivel de intercalación que ignore acentos y 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 API:

• agregar()

• Flujo agregado

• Fuerza de intercalación

• Acumuladores

• Agregados

• Ordena