Menu Docs
Página inicial do Docs
/ / /
Driver Rust
/

Agrupamentos

Nesta página

  • Visão geral
  • Agrupamentos do MongoDB
  • Especificar um agrupamento
  • Exemplo
  • Definir um agrupamento em uma coleção
  • Criar collection com um exemplo de collection
  • Demonstração de pedidos de agrupamento
  • Definir um agrupamento em um índice
  • Exemplo
  • Definir um agrupamento em uma operação
  • Exemplo
  • Informações adicionais
  • Documentação da API

Neste guia, você pode aprender como usar agrupamentos para ordenar seus resultados de operação de busca ou agregação por valores de string. Um agrupamento é um conjunto de convenções de ordenação de caracteres que correspondem a um idioma e localidade específicos.

Este guia inclui as seguintes seções:

  • Agrupamentos do MongoDB descreve como o MongoDB classifica os valores de string de acordo com o agrupamento padrão e agrupamentos personalizados

  • Especificar um agrupamento descreve como criar uma instância de estrutura Collation

  • Definir um agrupamento em uma coleção descreve como definir o agrupamento para uma nova coleção

  • Definir um agrupamento em um índice descreve como definir o agrupamento para um índice

  • Definir um agrupamento em uma operação descreve como aplicar um agrupamento a determinadas operações CRUD

  • Informações adicionais fornecem links para recursos e documentação da API para os tipos e métodos mencionados neste guia

O MongoDB classifica strings utilizando agrupamento binário por padrão. Esse método de agrupamento usa os valores de caracteres padrão ASCII para comparar e ordenar strings. Alguns idiomas e localidade têm convenções específicas de ordenação de caracteres que diferem do padrão ASCII.

Dica

Por exemplo, no francês canadense, o caractere mais acentuado à direita determina a ordem das strings quando os outros caracteres são os mesmos. Considere as seguintes palavras do francês canadense:

  • cote

  • coté

  • côte

  • côté

Ao usar o agrupamento binário padrão, o MongoDB classifica as palavras na seguinte ordem:

cote
coté
côte
côté

Nessa ordem de classificação, "coté" é colocado antes de "côte" porque o padrão ASCII posiciona o caractere "o" antes do caractere "o".

Ao usar o agrupamento francês canadense, o MongoDB classifica as palavras na seguinte ordem:

cote
côte
coté
côté

Nessa ordem de classificação, "coté" é colocado depois de "côte" porque as regras de agrupamento francesas canadenses posicionam o caractere "e" antes do caractere "é".

Você pode definir um agrupamento especificando uma localidade de agrupamento e outras opções em uma instância de estrutura do Collation . Para começar a construir uma instância do Collation , chame o método Collation::builder() .

Observação

Instanciação de estruturas

O driver Rust implementa o padrão de design Builder para a criação de alguns tipos de estruturas, incluindo Collation. Você pode usar o método builder() para construir uma instância de cada tipo encadeando métodos de construtor de opção.

A tabela seguinte descreve os métodos de construtor que você pode utilizar para configurar campos de uma instância do Collation . Você deve usar o método locale() para construir uma estrutura Collation válida, mas todos os outros métodos de construtor são opcionais:

Método
Valores possíveis
Descrição
locale() (Required)
For a full list of supported locales, see
in the Server manual.
Specifies the ICU locale
strength()
CollationStrength::Primary, CollationStrength::Secondary, CollationStrength::Tertiary, CollationStrength::Quaternary, CollationStrength::Identical
Especifica o nível de comparação a ser executado
case_level()
true, false
Specifies whether the driver performs case comparison
case_first()
CollationCaseFirst::Upper, CollationCaseFirst::Lower , CollationCaseFirst::Off
Especifica a ordem de classificação das diferenças de caso durante comparações de nível terciário
numeric_ordering()
true, false
Specifies whether the driver compares numeric strings as numbers
alternate()
CollationAlternate::NonIgnorable, CollationAlternate::Shifted
Especifica se o driver considera espaços em branco e pontuação como caracteres básicos durante a comparação de strings
max_variable()
CollationMaxVariable::Punct,
CollationMaxVariable::Space
Specifies which characters the driver ignores when alternate is set to
CollationAlternate::Shifted
normalization()
true, false
Especifica se o driver executa normalização de texto para valores de string
backwards()
true, false
Specifies whether the driver sorts strings containing diacritics in reverse character order

O exemplo a seguir especifica uma instância Collation e define a localidade de agrupamento como "en_US":

let collation = Collation::builder()
.locale("en_US")
.build();

Ao criar uma nova collection, você pode definir o agrupamento para operações futuras chamadas nessa collection. Defina o agrupamento encadeando a função collation() ao método create_collection() , passando sua instância Collation como parâmetro para collation().

Este exemplo especifica um agrupamento de acordo com as convenções de localidade "fr" , ou francesas, e aplica o agrupamento a uma nova collection chamada books . O campo strength é configurado para CollationStrength::Primary para ignorar diferenças em diacríticos.

let collation = Collation::builder()
.locale("fr")
.strength(CollationStrength::Primary)
.build();
let result = my_db.create_collection("books")
.collation(collation)
.await?;

Se você executar uma operação que ofereça suporte a agrupamentos na books coleção, a operação usará o agrupamento especificado no anterior Criar coleção com um exemplo de agrupamento.

Suponha que a coleção books contenha os seguintes documentos:

{ "name" : "Emma", "length" : "474" }
{ "name" : "Les Misérables", "length": "1462" }
{ "name" : "Infinite Jest", "length" : "1104" }
{ "name" : "Cryptonomicon", "length" : "918" }
{ "name" : "Ça", "length" : "1138" }

Dica

Para saber como inserir documentos em uma coleção, consulte o guia Inserir documentos .

O exemplo a seguir usa o método find() para retornar todos os documentos nos quais o valor do campo name precede alfabeticamente "Infinite Jest":

let query = doc! { "name": doc! { "$lt": "Infinite Jest" } };
let mut cursor = my_coll.find(query).await?;
while let Some(doc) = cursor.try_next().await? {
println!("{}", doc);
}
{ "name": "Emma", "length": 474 }
{ "name": "Cryptonomicon", "length": 918 }
{ "name" : "Ça", "length" : "1138" }

Se você não especificar um agrupamento para a collection books , o método find() seguirá as regras de agrupamento binárias padrão para determinar os valores name que precedem "Infinite Jest" . Essas regras colocam as palavras que começam com "ç" após aquelas que começam com "I". Portanto, quando a operação de localização anterior segue regras de agrupamento binárias, o documento no qual o valor name é "Ça" não corresponde aos critérios do filtro.

Ao criar um novo índice em uma collection, você pode definir o agrupamento para operações que são cobertas pelo índice. Para executar uma operação que usa o índice e seu agrupamento, sua operação e o índice devem especificar o mesmo agrupamento.

Dica

Para saber mais sobre índices e consultas cobertas, consulte o guia de índices .

Defina o agrupamento do índice usando a função collation() para construir uma instância IndexOptions . Em seguida, passe seu IndexOptions como um argumento para uma função do construtor IndexModel e passe seu IndexModel como um argumento para o método create_index() .

O exemplo a seguir usa o método create_index() para criar um índice ascendente no campo name e especifica um novo agrupamento correspondente à localidade "en_US" :

let collation = Collation::builder()
.locale("en_US")
.build();
let index_opts = IndexOptions::builder()
.collation(collation)
.build();
let index = IndexModel::builder()
.keys(doc! { "name": 1 })
.options(index_opts)
.build();
let result = my_coll.create_index(index).await?;
println!("Created index: {}", result.index_name);
Created index: name_1

As operações que leem, atualizam e excluem documentos de uma coleção podem usar agrupamentos. A aplicação de um agrupamento a uma operação substitui qualquer agrupamento definido anteriormente para uma coleção ou índice.

Se você aplicar um agrupamento a uma operação que difere do agrupamento de um índice, não poderá usar esse índice. Como resultado, a operação pode não ser executada de forma tão eficiente quanto uma coberta por um índice. Para obter mais informações sobre as desvantagens de classificar operações não cobertas por um índice, consulte Usando índices para classificar resultados de query no manual do servidor.

Este exemplo executa as seguintes ações:

  • Define a opção de agrupamento numeric_ordering como true, o que garante que os valores sejam classificados em ordem numérica em vez de ordem alfabética

  • Usa o método find() para retornar documentos nos quais o valor do campo length é maior que "1000"

  • Especifica um agrupamento encadeando o método collation() ao método find() , que substitui o agrupamento da coleção

let collation = Collation::builder()
.locale("en_US")
.numeric_ordering(true)
.build();
let filter = doc! { "length": doc! { "$gt": "1000" } };
let mut cursor = my_coll.find(filter)
.collation(collation)
.await?;
while let Some(result) = cursor.try_next().await? {
println!("{}", result);
};
{ "name" : "Les Misérables", "length": "1462" }
{ "name" : "Infinite Jest", "length" : "1104" }
{ "name" : "Ça", "length" : "1138" }

Se você executar a operação find mencionada sem definir a opção numeric_ordering como true, o driver compara os valores de length como strings e ordena o valor "1000" da string anteriormente aos valores "474" e "918". Neste caso, a operação find anterior retorna todos os documentos na coleção books.

Para saber mais sobre o método find() , consulte o guia Recuperar dados .

Para saber mais sobre agrupamentos, consulte as seguintes páginas de manual do servidor:

Para saber mais sobre qualquer um dos métodos ou tipos mencionados neste guia, consulte a seguinte documentação da API:

Voltar

Monitoramento de conexão