Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB
distinto
Definição
distinct
Encontra os valores distintos para um campo especificado em uma única collection.
distinct
retorna um documento que contém uma array de valores distintos. O documento de retorno também contém um documento incorporado com estatísticas de query e o plano de query.Dica
Em
mongosh
, esse comando também pode ser executado por meio do método auxiliardb.collection.distinct()
..Os métodos auxiliares são convenientes para os usuários
mongosh
, mas podem não retornar o mesmo nível de informações que os comandos do banco de dados. Nos casos em que a conveniência não for necessária ou os campos de retorno adicionais forem necessários, use o comando de banco de dados.
Compatibilidade
Este comando está disponível em sistemas hospedados nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem
Observação
Este comando tem suporte limitado em clusters M0, M2 e M5 . Para obter mais informações, consulte Comandos não suportados.
MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão código-disponível, de uso gratuito e autogerenciada do MongoDB
Sintaxe
O comando tem a seguinte sintaxe:
db.runCommand( { distinct: "<collection>", key: "<field>", query: <query>, readConcern: <read concern document>, collation: <collation document>, comment: <any>, hint: <string or document> } )
Campos de comando
O comando utiliza os seguintes campos:
Campo | Tipo | Descrição | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
distinct | string | O nome da collection para consultar valores distintos. | ||||||||||
key | string | O campo para o qual retornar valores distintos. | ||||||||||
query | documento | Opcional. Uma query que especifica os documentos a partir dos quais recuperar os valores distintos. | ||||||||||
readConcern | documento | Opcional. Especifica a read concern. A partir do MongoDB 3.6, a opção readConcern tem a seguinte sintaxe: Os possíveis níveis de read concern são:
Para obter mais informações sobre os read concern, consulte Níveis de read concern. | ||||||||||
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:
Ao especificar agrupamento, o campo Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão (consulte Se nenhum agrupamento for especificado para a collection 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. | ||||||||||
comment | qualquer | Opcional. Um comentário fornecido pelo usuário para anexar a este comando. Depois de definido, esse comentário aparece junto com os registros desse comando nos seguintes locais:
Um comentário pode ser qualquer tipo BSON válido (string, inteiro, objeto, array etc). | ||||||||||
hint | string ou documento | Opcional. Especifique o nome do índice, como uma string ou um documento. Se especificado, o planejador de query considera apenas os planos usando o índice sugerido. Para mais detalhes, consulte Especificar um índice. Novidade na versão 7.1. |
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 MongoDB também fornece o método shell wrapper db.collection.distinct()
para o comando distinct
. Além disso, muitos drivers MongoDB fornecem um método wrapper. Consulte a documentação específica do driver.
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, distinct
considera cada elemento da array como um valor separado.
Por exemplo, se um campo tiver como seu valor [ 1, [1], 1 ]
, então distinct
considera 1
, [1]
e 1
como valores separados.
A partir do MongoDB 6.0, o comando distinct
retorna os mesmos resultados para collections e visualizações ao usar arrays.
Para exemplos, consulte:
Uso do índice
Quando possível, as operações do distinct
podem utilizar índices.
Os índices também podem abranger operações 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:
Para coleções não fragmentadas, você pode usar o método
db.collection.distinct()
/o commanddistinct
, bem como o pipeline de agregação com o stage$group
.Para coleções fragmentadas, você não pode utilizar o método
db.collection.distinct()
ou o comandodistinct
.Para encontrar os valores distintos de uma pipeline de agregação fragmentada, use o pipeline de agregação com o estágio
$group
. Consulte Operação Distinta para detalhes.
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 distinct
se desconectar antes da conclusão da operação, o MongoDB marcará 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éplicas, 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.
Filtros e Agrupamentos de Índice
Iniciando no MongoDB 6.0, um filtro de índice utiliza a coleção definida anteriormente utilizando o comando planCacheSetFilter
.
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.runCommand ( { distinct: "inventory", key: "dept" } )
O comando retorna um documento com um campo denominado values
que contém os valores distintos do dept
:
{ "values" : [ "A", "B" ], "ok" : 1 }
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.runCommand ( { distinct: "inventory", key: "item.sku" } )
O comando retorna um documento com um campo denominado values
que contém os valores distintos do sku
:
{ "values" : [ "111", "222", "333" ], "ok" : 1 }
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.runCommand ( { distinct: "inventory", key: "sizes" } )
O comando retorna um documento com um campo denominado values
que contém os valores distintos do sizes
:
{ "values" : [ "M", "S", "L" ], "ok" : 1 }
Para informações sobre distinct
e campos de array, consulte a seção Comportamento .
Arrays em collections e visualizações
A partir do MongoDB 6.0, o comando distinct
retorna os mesmos resultados para collections e visualizações ao usar arrays.
O exemplo a seguir cria uma collection chamada sensor
com uma array de valores de temperatura para cada documento:
db.sensor.insertMany( [ { _id: 0, temperatures: [ { value: 1 }, { value: 4 } ] }, { _id: 1, temperatures: [ { value: 2 }, { value: 8 } ] }, { _id: 2, temperatures: [ { value: 3 }, { value: 12 } ] }, { _id: 3, temperatures: [ { value: 1 }, { value: 4 } ] } ] )
O exemplo seguinte cria uma visualização denominada sensorView
a partir da collection sensor
:
db.createView( "sensorView", "sensor", [] )
O exemplo a seguir usa distinct
para retornar os valores exclusivos da array temperatures
na collection sensor
:
db.sensor.distinct( "temperatures.1.value" )
O 1
em temperatures.1.value
especifica o índice da array temperatures
.
Saída de exemplo:
[ 4, 8, 12 ]
Exemplo para sensorView
:
db.sensorView.distinct( "temperatures.1.value" )
Saída de exemplo:
[ 4, 8, 12 ]
começando no MongoDB 6.0 (idêntico ao resultado retornado da collectionsensor
).[]
em versões MongoDB anteriores a 6.0.
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.runCommand ( { distinct: "inventory", key: "item.sku", query: { dept: "A"} } )
O comando retorna um documento com um campo denominado values
que contém os valores distintos do sku
:
{ "values" : [ "111", "333" ], "ok" : 1 }
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.runCommand( { distinct: "myColl", key: "category", collation: { locale: "fr", strength: 1 } } )
Para obter descrições sobre os campos de agrupamento, consulte Documento de agrupamento.
Substituir o Padrão Atenção com a Leitura
Para substituir o nível de preocupação de leitura padrão do "local"
, utilize a opção readConcern
.
A operação a seguir em um conjunto de réplicas especifica uma read concern de "majority"
para ler a cópia mais recente dos dados confirmados como gravados na maioria dos nós.
Observação
Independentemente do nível de read concern, os dados mais recentes em um nó podem não refletir a versão mais recente dos dados no sistema.
db.runCommand( { distinct: "restaurants", key: "rating", query: { cuisine: "italian" }, readConcern: { level: "majority" } } )
Para garantir que um único thread possa ler suas próprias gravações, use "majority"
read concern e "majority"
write concern em relação ao primário do conjunto de réplicas.
Especificar um índice
Você pode especificar um nome ou padrão de índice usando a opção dica.
Para especificar uma dica com base em um nome de índice:
db.runCommand ( { distinct: "inventory", key: "dept", hint: "sizes" } )
Para especificar uma dica com base em um padrão de índice:
db.runCommand ( { distinct: "inventory", key: "dept", hint: { sizes: 1 } } )