db.collection.distinct() (método mongosh)

MongoDB com drivers

Esta página documenta um método mongosh. Para ver o método equivalente em um driver MongoDB , consulte a página correspondente para sua linguagem de programação:

C#Java Sync Node.js PyMongo C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

Definição

db.collection.distinct(field, query, options): Encontra os valores distintos para um campo especificado em uma única collection ou visualização e retorna os resultados exclusivos em uma array.

Compatibilidade

Esse método está disponível em implantações hospedadas nos seguintes ambientes:

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

Observação

Este comando é aceito em todos os clusters do MongoDB Atlas. Para obter informações sobre o suporte do Atlas a todos os comandos, consulte Comandos não suportados.

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 distinct() chamada.

Opções

{ collation: <document> }

Campo

Tipo

Descrição

collation

documento

Opcional.

Opcional. Especifica a agrupamento para utilizar 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.

Para coleções de séries temporais, o comando distinct não consegue fazer uso eficiente dos índices. Em vez disso, use uma agregação $group para agrupar documentos por valores distintos. Para obter detalhes, consulte Limitações de séries temporais.

Campos de array

Se o valor do field especificado for uma array, db.collection.distinct() considerará cada elemento dela 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 usar índices.

Os índices também podem abranger operações db.collection.distinct(). Consulte Executar queries cobertas 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 comando distinct, bem como o pipeline de agregação com o estágio $group.
Para coleções fragmentadas, você não pode utilizar o método db.collection.distinct() ou o comando distinct.

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

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 nó do conjunto de réplicas, as operações dedistinct exigem que o nó esteja no estado PRIMARY ou SECONDARY. Se o nó estiver em outro estado, como STARTUP2, haverá erros na operação.

Configurações de query

Novidades na versão 8.0.:

Você pode usar as configurações de query para definir dicas de índice, definir filtros de descarte de operação e outros campos. As configurações se aplicam à forma de query em todo o cluster. O cluster mantém as configurações após o fechamento.

O otimizador de query usa as configurações da query como uma entrada adicional durante o planejamento da query, o que afeta o plano selecionado para executar a query. Você também pode usar as configurações de query para bloquear uma forma de query.

Para adicionar configurações de query e explorar exemplos, consulte setQuerySettings.

Você pode adicionar configurações de consulta para os comandos find, distinct e aggregate.

As configurações de consulta têm mais funcionalidade e são preferidas em relação aos filtros de índice obsoletos.

Para remover as configurações de query, use removeQuerySettings. Para obter as configurações de consulta, use um estágio $querySettings em um pipeline de agregação .

Exemplos

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

db.inventory.insertMany( [
   { _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 seguinte retorna valores distintos para o campo dept :

db.inventory.distinct( "dept" )

A operação retorna:

[ "A", "B" ]

Valores Distintos de Retorno para um Campo Incorporado

O exemplo a seguir retorna valores distintos para o campo item.sku incorporado:

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

A operação retorna:

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

Dica

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 seguinte retorna valores distintos para o campo de array sizes:

db.inventory.distinct( "sizes" )

A operação retorna:

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

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

Especificar query com `distinct`

O exemplo a seguir retorna valores distintos para o campo item.sku incorporado em que dept é igual a "A":

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

A operação retorna:

[ "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:

db.myColl.insertMany( [
   { _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.

Voltar

db.collection.deleteOne

db.collection.drop

db.collection.distinct() (método mongosh)

Definição

Compatibilidade

Observação

Sintaxe

Observação

Opções

Comportamento

Campos de array

Uso do índice

Transações

Importante

Desconexão do cliente

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

Configurações de query

Exemplos

Valores Distintos de Devolução para um Campo

Valores Distintos de Retorno para um Campo Incorporado

Dica

Valores Distintos de Retorno para um Campo de Array

Especificar query com distinct

Especificar um agrupamento

Especificar query com `distinct`