Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Referência
/
Métodos de mongosh
/
Métodos de collection

db.collection.distinct()

Nesta página

  • Definição
  • Compatibilidade
  • Sintaxe
  • Opções
  • Comportamento
  • Exemplos

Definição

db.collection.distinct(field, query, options)

Importante

Método mongosh

Esta página documenta um método mongosh . Esta não é a documentação para comandos de banco de dados ou drivers específicos de idioma, como Node.js.

Para o comando do banco de dados, consulte o comando distinct.

Para drivers de API do MongoDB, consulte a documentação do driver MongoDB específica do idioma.

Para a documentação de shell legada do mongo, consulte a documentação para a versão correspondente do MongoDB Server:

mongo shell v4.4

Encontra os valores distintos de um campo especificado em uma única coleção ou visualização e retorna os resultados em uma array.

Compatibilidade

Você pode utilizar o db.collection.distinct() para implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem

  • MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

  • MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

Este método utiliza os seguintes parâmetros:

Parâmetro
Tipo
Descrição
field
string
O campo para o qual retornar valores distintos.
query
documento
Uma query que especifica os documentos a partir dos quais recuperar os valores distintos.
options
documento
Opcional. Um documento que especifica as opções. Consulte Opções.

Observação

Os resultados não devem ser maiores do que o tamanho máximo do BSON. Se seus resultados excederem o tamanho máximo de BSON, use o pipeline de agregação para recuperar valores distintos usando o operador $group, conforme descrito em Recuperar valores distintos com o pipeline de agregação.

O diagrama a seguir mostra um exemplo db.collection.distinct() chamada.

Diagrama da operação distinta anotada.

Opções

{ collation: <document> }
Campo
Tipo
Descrição
collation
documento

Opcional.

Especifica o agrupamento a ser usado para a operação.

A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.

A opção de agrupamento tem a seguinte sintaxe:

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

Ao especificar agrupamento, o campo locale é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento.

Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão (consulte db.createCollection()), a operação usará o agrupamento especificado para a coleção.

Se nenhum agrupamento for especificado para a coleção ou para as operações, o MongoDB usa a comparação binária simples usada nas versões anteriores para comparações de strings.

Você não pode especificar vários agrupamentos para uma operação. Por exemplo, você não pode especificar agrupamentos diferentes por campo ou, se estiver realizando uma busca com uma classificação, não poderá usar um agrupamento para a busca e outro para a classificação.

Comportamento

Em um cluster fragmentado, o comando distinct pode retornar documentos órfãos.

Campos de array

Se o valor do field especificado for uma array, db.collection.distinct() considera cada elemento da array como um valor separado.

Por exemplo, se um campo tiver como seu valor [ 1, [1], 1 ], então db.collection.distinct() considera 1, [1] e 1 como valores separados.

Para obter um exemplo, consulte Retornar valores distintos para um campo de array.

Uso do índice

Quando possível, as operações do db.collection.distinct() podem utilizar índices.

Os índices também podem abranger operações db.collection.distinct() . Consulte query coberta para obter mais informações sobre queries cobertas por índices.

Transações

Para realizar uma operação distinta dentro de uma transação:

Importante

Na maioria dos casos, uma transação distribuída incorre em um custo de desempenho maior do que as gravações de um único documento, e a disponibilidade de transações distribuídas não deve substituir o design eficaz do esquema. Em muitos cenários, o modelo de dados desnormalizado (documentos e arrays incorporados) continuará a ser ideal para seus dados e casos de uso. Ou seja, para muitos cenários, modelar seus dados adequadamente minimizará a necessidade de transações distribuídas.

Para considerações adicionais sobre o uso de transações (como limite de tempo de execução e limite de tamanho do oplog), consulte também Considerações de produção.

Desconexão do cliente

A partir do MongoDB 4.2, se o cliente que emitiu db.collection.distinct() se desconectar antes da conclusão da operação, o MongoDB marcará db.collection.distinct() para encerramento usando killOp.

Restrição de estado do membro do conjunto de réplica

Para executar em um membro do conjunto de réplica, as operações do distinct exigem que o membro esteja no estado PRIMARY ou SECONDARY . Se o membro estiver em outro estado, como STARTUP2, os erros de operação.

Exemplos

Os exemplos utilizam a coleção inventory que contém os seguintes documentos:

{ "_id": 1, "dept": "A", "item": { "sku": "111", "color": "red" }, "sizes": [ "S", "M" ] }
{ "_id": 2, "dept": "A", "item": { "sku": "111", "color": "blue" }, "sizes": [ "M", "L" ] }
{ "_id": 3, "dept": "B", "item": { "sku": "222", "color": "blue" }, "sizes": "S" }
{ "_id": 4, "dept": "A", "item": { "sku": "333", "color": "black" }, "sizes": [ "S" ] }

Valores Distintos de Devolução para um Campo

O exemplo a seguir retorna os valores distintos para o campo dept de todos os documentos na coleção inventory:

db.inventory.distinct( "dept" )

O método retorna a seguinte array de valores dept distintos:

[ "A", "B" ]

Valores Distintos de Retorno para um Campo Incorporado

O exemplo seguinte retorna os valores distintos para o campo sku, embutido no campo item, de todos os documentos na coleção inventory:

db.inventory.distinct( "item.sku" )

O método retorna a seguinte array de valores sku distintos:

[ "111", "222", "333" ]

Dica

Veja também:

Notação de pontos para obter informações sobre como acessar campos em documentos incorporados

Valores Distintos de Retorno para um Campo de Array

O exemplo a seguir retorna os valores distintos para o campo sizes de todos os documentos na coleção inventory:

db.inventory.distinct( "sizes" )

O método retorna a seguinte array de valores sizes distintos:

[ "M", "S", "L" ]

Para informações sobre distinct() e campos de array, consulte a seção Comportamento .

Especificar query com distinct

O exemplo seguinte retorna os valores distintos para o campo sku, embutido no campo item, a partir dos documentos cujo dept é igual a "A":

db.inventory.distinct( "item.sku", { dept: "A" } )

O método retorna a seguinte array de valores sku distintos:

[ "111", "333" ]

Especificar um agrupamento

A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.

Uma coleção myColl possui os seguintes documentos:

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

A seguinte operação de aggregation inclui a opção Agrupamento:

db.myColl.distinct( "category", {}, { collation: { locale: "fr", strength: 1 } } )

Para obter descrições sobre os campos de agrupamento, consulte Documento de agrupamento.

← db.collection.deleteMany()
db.collection.drop() →

Nesta página