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
Visão geral
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
Agrupamentos do MongoDB
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.
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 "é".
Especificar um agrupamento
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) | 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 toCollationAlternate::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 |
Exemplo
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();
Definir um agrupamento em uma coleção
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()
.
Criar collection com um exemplo de collection
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?;
Demonstração de pedidos de agrupamento
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.
Definir um agrupamento em um índice
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()
.
Exemplo
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
Definir um agrupamento em uma operação
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.
Exemplo
Este exemplo executa as seguintes ações:
Define a opção de agrupamento
numeric_ordering
comotrue
, o que garante que os valores sejam classificados em ordem numérica em vez de ordem alfabéticaUsa o método
find()
para retornar documentos nos quais o valor do campolength
é maior que"1000"
Especifica um agrupamento encadeando o método
collation()
ao métodofind()
, 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
.
Informações adicionais
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:
Documentação da API
Para saber mais sobre qualquer um dos métodos ou tipos mencionados neste guia, consulte a seguinte documentação da API: