Menu Docs

Especificar uma query de documento

Neste guia, você pode aprender como especificar uma query usando Mongoid.

Você pode refinar o conjunto de documentos que uma query retorna criando um filtro de query. Um filtro de query é uma expressão que especifica os critérios de pesquisa que o MongoDB usa para corresponder a documentos em uma operação de leitura ou gravação. Ao criar um filtro de consulta, você pode solicitar ao driver que pesquise documentos com uma correspondência exata à sua consulta ou pode compor filtros de consulta para expressar critérios de correspondência mais complexos.

O Mongoid fornece uma query de linguagem específica de domínio (DSL) semelhante à usada no Active Record.

Os exemplos deste guia usam o modelo Band, que representa uma banda ou grupo social. A definição do modelo Band pode ser diferente para cada seção para demonstrar diferentes funcionalidades de consulta. Algumas seções podem usar outros modelos para demonstrar a funcionalidade da query.

Os métodos de query do Mongoid retornam objetos Mongoid::Criteria, que são encadeáveis e são invólucros avaliados de forma preguiçosa para a MongoDB Query API. As queries são executadas quando você itera pelos resultados. O exemplo a seguir demonstra o tipo de retorno para uma query simples:

# Creates a simple query
Band.where(name: "Deftones")
# Returns a Criteria object
# => #<Mongoid::Criteria
# selector: {"name"=>"Deftones"}
# options: {}
# class: Band
# embedded: false>
# Evaluate the query by converting to JSON
Band.where(name: "Deftones").to_json
# Returns matching documents
# => [{"_id":"...","name":"Deftones"}]

Você pode usar métodos como first e last para retornar documentos individuais. Você também pode iterar um objeto Criteria usando métodos como each ou map para recuperar documentos do servidor. Você pode usar to_json para converter um objeto Criteria em JSON.

Dica

Métodos de encadeamento

Se você encadear outros métodos de query em um objeto Criteria existente, o Mongoid mesclará os critérios de filtro.

Esta seção descreve os padrões de sintaxe que você pode utilizar para criar critérios de filtro. Você pode especificar queries no Mongoid usando qualquer um dos seguintes padrões de sintaxe :

  • Sintaxe de campo

  • sintaxe da API de query

  • Sintaxe do operador de símbolos

Observação

Comportamentos de sintaxe

Essas sintaxes suportam a query de documentos incorporados usando a notação de ponto. As sintaxes também respeitam osaliases de campo e os tipos de campo , se o campo que está sendo consultado estiver definido na classe do modelo.

Os exemplos nesta seção usam a seguinte definição de modelo:

class Band
include Mongoid::Document
field :name, type: String
field :founded, type: Integer
field :m, as: :member_count, type: Integer
embeds_one :manager
end
class Manager
include Mongoid::Document
embedded_in :band
field :name, type: String
end

A sintaxe de consulta do campo utiliza os hash Ruby básicos. As chaves podem ser símbolos ou strings e correspondem a nomes de campo em documentos MongoDB .

O código a seguir mostra duas queries equivalentes que usam a sintaxe de query de campo para recuperar documentos nos quais o valor de campo name é 'Depeche Mode':

Band.where(name: 'Depeche Mode')
Band.where('name' => 'Depeche Mode')

Você pode especificar um operador de API de query em qualquer campo usando a sintaxe de hash , conforme mostrado pelas seguintes consultas equivalentes:

Band.where(founded: {'$gt' => 1980})
Band.where('founded' => {'$gt' => 1980})

Você pode especificar operadores de API de query como métodos em símbolos para o respectivo nome de campo , conforme mostrado no código a seguir:

Band.where(:founded.gt => 1980)

Esta seção descreve como realizar queries em campos com diferentes tipos de valores.

Para fazer query de um campo, o campo não precisa estar na definição da classe de modelo . No entanto, se um campo for definido na classe do modelo, o Mongoid forçará os valores da query para corresponder aos tipos de campo definidos ao construir a query.

O seguinte código especifica um valor de string ao executar query do campo founded. Como o campo founded é definido na classe do modelo para ter Integer valores, o Mongoid força a string '2020' para 2020 ao executar a query:

Band.where(founded: '2020')

Para saber mais sobre como definir campos no Mongoid, consulte o guia Tipos de campo.

Para ignorar o comportamento de coerção do tipo de query do Mongoid e consultar diretamente o valor digitado bruto no banco de dados, envolva o valor da query na classe Mongoid::RawValue, conforme mostrado no código a seguir:

Band.where(founded: Mongoid::RawValue('2020'))

As queries seguem os nomes de campo de armazenamento e os aliases de campo que você pode ter definido na definição da classe de modelo.

Os campos id e _id são aliases, então você pode utilizar qualquer nome de campo em queries:

Band.where(id: '5ebdeddfe1b83265a376a760')
Band.where(_id: '5ebdeddfe1b83265a376a760')

Para consultar valores de campos de documentos incorporados, você pode usar a notação de ponto. O código a seguir recupera documentos no qual o campo name do documento Manager incorporado é 'Smith':

Band.where('manager.name' => 'Smith')

O seguinte código demonstra como usar um operador de símbolo ao executar uma query de um campo incorporado:

Band.where(:'manager.name'.ne => 'Smith')

Observação

As queries sempre retornam instâncias de modelo de nível superior, mesmo que todas as condições façam referência a campos de documento incorporado .

O Mongoid suporta as seguintes operações lógicas em objetos Criteria :

  • and

  • or

  • nor

  • not

Esses métodos tomam um ou mais hashes de condições ou outro objeto Criteria como seus argumentos. A operação not tem uma versão sem argumentos.

O seguinte código demonstra como usar as operações lógicas em queries:

# Uses "and" to combine criteria
Band.where(label: 'Trust in Trance').and(name: 'Astral Projection')
# Uses "or" to specify criteria
Band.where(label: 'Trust in Trance').or(Band.where(name: 'Astral Projection'))
# Uses "not" to specify criteria
Band.not(label: 'Trust in Trance', name: 'Astral Projection')
# Uses "not" without arguments
Band.not.where(label: 'Trust in Trance', name: 'Astral Projection')

Observação

Parâmetros da matriz

Para garantir a compatibilidade com versões anteriores do Mongoid, os métodos de operação lógica aceitam arrays de parâmetros, que são achatadas para obter os critérios.

Passar arrays para operações lógicas é obsoleto e pode ser removido em uma versão futura.

As seguintes queries produzem as mesmas condições:

# Conditions passed to separate "and" calls
Band.and(name: 'Sun Kil Moon').and(member_count: 2)
# Multiple conditions in the same "and" call
Band.and({name: 'Sun Kil Moon'}, {member_count: 2})
# Multiple conditions in an array - Deprecated
Band.and([{name: 'Sun Kil Moon'}, {member_count: 2}])
# Condition in "where" and a scope
Band.where(name: 'Sun Kil Moon').and(Band.where(member_count: 2))
# Condition in "and" and a scope
Band.and({name: 'Sun Kil Moon'}, Band.where(member_count: 2))
# Scope as an array element, nested arrays - Deprecated
Band.and([Band.where(name: 'Sun Kil Moon'), [{member_count: 2}]])

Os operadores lógicos têm a mesma semântica que os do Active Record.

Quando as condições são especificadas no mesmo campo várias vezes, todas as condições são adicionadas aos critérios, conforme mostrado pelas queries no código a seguir:

# Combines as "and"
Band.where(name: 'Swans').where(name: 'Feist')
# Combines as "or"
Band.where(name: 'Swans').or(name: 'Feist')

As operações any_of, none_of, nor e not comportam-se da mesma forma.

Quando você usa operadores lógicos and, or e nor, eles operam de acordo com os critérios criados até aquele ponto:

# "or" applies to the first condition, and the second is combined
# as "and"
Band.or(name: 'Sun').where(label: 'Trust')
# Same as previous example - "where" and "and" are aliases
Band.or(name: 'Sun').and(label: 'Trust')
# Same operator can be stacked any number of times
Band.or(name: 'Sun').or(label: 'Trust')
# The last label condition is added to the top level as "and"
Band.where(name: 'Sun').or(label: 'Trust').where(label: 'Feist')
# Interpreted query:
# {"$or"=>[{"name"=>"Sun"}, {"label"=>"Trust"}], "label"=>"Feist"}

Você pode usar o método not sem argumentos e, nesse caso, ele nega a próxima condição especificada. O método not pode ser chamado com uma ou mais condições de hash ou objetos Criteria, que são todos negados e adicionados aos critérios.

Os seguintes exemplos demonstram o comportamento de not:

# "not" negates "where"
Band.not.where(name: 'Best')
# The second "where" is added as "$and"
Band.not.where(name: 'Best').where(label: /Records/)
# "not" negates its argument
Band.not(name: 'Best')

Observação

Você não pode usar o operador $not no MongoDB com um argumento de string. O Mongoid usa o operador $ne para obter a negação:

# String negation - uses "$ne"
Band.not.where(name: 'Best')
# Regex negation - uses "$not"
Band.not.where(name: /Best/)

Da mesma forma que and, a operação not nega condições individuais para critérios de campo simples. Para condições complexas e quando um campo já tem uma condição definida nele, o Mongoid emula $not usando uma construção {'$and' => [{'$nor' => ...}]}, porque o MongoDB suporta o operador $not apenas em uma base por campo em vez de globalmente:

# Simple condition
Band.not(name: /Best/)
# Complex conditions
Band.where(name: /Best/).not(name: 'Astral Projection')
# Symbol operator syntax
Band.not(:name.ne => 'Astral Projection')

Se você estiver utilizando not o com arrays ou expressões regulares, consulte as limitações do $not no manual do Servidor.

Por padrão, quando você adiciona condições a uma query, o Mongoid considera cada condição completa e independente de quaisquer outras condições presentes na query. Por exemplo, chamar in duas vezes adiciona duas condições $in separadas:

Band.in(name: ['a']).in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["a"]}, "$and"=>[{"name"=>{"$in"=>["b"]}}]}

Alguns métodos de operador permitem criar a condição de forma incremental. Quando você adiciona uma condição que usa um dos operadores suportados, o Mongoid vê se já existe uma condição no mesmo campo usando o mesmo operador. Em caso afirmativo, as expressões do operador são combinadas de acordo com a estratégia de mesclagem especificada. A seção a seguir descreve as estratégias de mesclagem disponíveis.

O Mongoid fornece as seguintes estratégias de mesclagem:

  • Substituir: a nova instância do operador substitui quaisquer condições existentes no mesmo campo usando o mesmo operador.

  • Interseção: se já houver uma condição usando o mesmo operador no mesmo campo, os valores da condição existente serão cruzados com os valores da nova condição e o resultado será armazenado como o valor do operador.

  • Unidade: se já houver uma condição usando o mesmo operador no mesmo campo, os valores da nova condição serão adicionados aos valores da condição existente e o resultado será armazenado como o valor do operador.

O código a seguir demonstra como as estratégias de mesclagem produzem critérios usando in como operador de exemplo :

Band.in(name: ['a']).override.in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["b"]}}
Band.in(name: ['a', 'b']).intersect.in(name: ['b', 'c'])
# Interpreted query:
# {"name"=>{"$in"=>["b"]}}
Band.in(name: ['a']).union.in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["a", "b"]}}

A estratégia é solicitada ligando para override, intersect ou union em uma instância do Criteria. A estratégia solicitada se aplica ao próximo método de condição chamado na query. Se o próximo método de condição chamado não for compatível com estratégias de mesclagem, a estratégia será redefinida, conforme mostrado no exemplo a seguir:

Band.in(name: ['a']).union.ne(name: 'c').in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["a"], "$ne"=>"c"}, "$and"=>[{"name"=>{"$in"=>["b"]}}]}

Como o ne não suporta estratégias de mesclagem, a estratégia union é ignorada e redefinida. Então, quando in é invocado pela segunda vez, não há nenhuma estratégia ativa.

Aviso

As estratégias de mesclagem pressupõem que as condições anteriores tenham sido adicionadas ao nível superior da query. No entanto, esse nem sempre é o caso, pois as condições podem estar aninhadas em uma cláusula $and. Usar estratégias de mesclagem com critérios complexos pode gerar queries incorretas.

Os métodos de operador a seguir oferecem suporte a estratégias de mesclagem:

  • all

  • in

  • nin

O conjunto de métodos pode ser expandido em futuras versões do Mongoid. Para garantir compatibilidade futura, invoque um método estratégico somente quando a próxima chamada de método for um operador que ofereça suporte a estratégias de mesclagem.

As estratégias de mesclagem são aplicadas somente quando as condições são adicionadas por meio dos métodos designados. No exemplo a seguir, a estratégia de mesclagem não é aplicada porque a segunda condição é adicionada como where, não usando in:

Band.in(name: ['a']).union.where(name: {'$in' => 'b'})
# Interpreted query:
# {"foo"=>{"$in"=>["a"]}, "$and"=>[{"foo"=>{"$in"=>"b"}}]}

Os métodos de operador que suportam estratégias de mesclagem usam Array como seu tipo de valor. O Mongoid expande os tipos compatíveis com Array, como um Range, quando são utilizados com estes métodos de operador.

O exemplo a seguir demonstra como você pode passar um objeto Range como valor de query ao usar o método in:

Band.in(year: 1950..1960)
# Interpreted query:
# {"year"=>{"$in"=>[1950, 1951, 1952, 1953, 1954, 1955, 1956, 1957, 1958, 1959, 1960]}}

O Mongoid envolve valores nãoArray em arrays, como mostrado no exemplo a seguir:

Band.in(year: 1950)
# Interpreted query: {"year"=>{"$in"=>[1950]}}

Você pode utilizar o método elem_match para combinar documentos que contêm um campo de array com pelo menos um elemento que corresponda a todos os critérios de query especificados.

O exemplo a seguir cria um documento de amostra que contém um campo de array . Em seguida, ele usa o método elem_match para combinar documentos em que o campo de array tour contém uma entrada em que o valor city é 'London':

aerosmith = Band.create!(name: 'Aerosmith', tours: [
{city: 'London', year: 1995},
{city: 'New York', year: 1999},
])
swans = Band.create!(name: 'Swans', tours: [
{city: 'Milan', year: 2014},
{city: 'Montreal', year: 2015},
])
# Returns only "Aerosmith"
Band.elem_match(tours: {city: 'London'})

Você pode usar o método elem_match para corresponder a associações incorporadas.

Este exemplo utiliza os seguintes modelos que definem uma associação embutida entre Band e Tour:

class Band
include Mongoid::Document
field :name, type: String
embeds_many :tours
end
class Tour
include Mongoid::Document
field :city, type: String
field :year, type: Integer
embedded_in :band
end

O código a seguir cria um objeto Band e incorpora objetos Tour e, em seguida, usa o método elem_match para fazer uma query no campo city :

aerosmith = Band.create!(name: 'Aerosmith')
Tour.create!(band: aerosmith, city: 'London', year: 1995)
Tour.create!(band: aerosmith, city: 'New York', year: 1999)
# Returns the "Aerosmith" document
Band.elem_match(tours: {city: 'London'})

Observação

Não é possível usar elem_match em associações não incorporadas porque o MongoDB não executa uma operação de junção nas collections. Se você executar esta query, as condições serão adicionadas à collection que é a origem da associação não incorporada em vez da collection da associação.

Você pode utilizar o elem_match para consultar associações recursivamente incorporadas, como mostrado no seguinte exemplo:

class Tag
include Mongoid::Document
field name:, type: String
recursively_embeds_many
end
# Creates the root Tag
root = Tag.create!(name: 'root')
# Adds embedded Tags
sub1 = Tag.new(name: 'sub_tag_1', child_tags: [Tag.new(name: 'sub_sub_tag_1')])
root.child_tags << sub1
root.child_tags << Tag.new(name: 'sub_tag_2')
root.save!
# Searches for Tag in which one child Tag tame is "sub_tag_1"
Tag.elem_match(child_tags: {name: 'sub_tag_1'})
# Searches for a child Tag in which one child Tag tame is "sub_sub_tag_1"
root.child_tags.elem_match(child_tags: {name: 'sub_sub_tag_1'})

Para saber mais sobre associações, consulte o guia Associações.

O Mongoid fornece o método find, que permite fazer query de documentos por seus valores _id.

O exemplo seguinte utiliza o método find para corresponder um documento com o valor de campo _id especificado:

Band.find('6725342d4cb3e161059f91d7')

Observação

conversão de tipo

Quando você passa um valor de ID para o método find, o método o converte para o tipo de dados declarado para o campo _id no modelo. Por padrão, o campo _id é definido como um tipo BSON::ObjectId.

O exemplo anterior é equivalente ao seguinte código, que passa uma instância BSON::ObjectId como argumento para find:

Band.find(BSON::ObjectId.from_string('5f0e41d92c97a64a26aabd10'))

Se você usar o driver Ruby para fazer a query do campo _id, find não executará internamente a conversão de tipo.

O método find aceita vários argumentos ou uma array de argumentos. O Mongoid interpreta cada argumento ou elemento de array como um valor _id e retorna documentos com todos os valores _id especificados em uma array, conforme mostrado no exemplo a seguir:

# Equivalent ways to match multiple documents
Band.find('5f0e41d92c97a64a26aabd10', '5f0e41b02c97a64a26aabd0e')
Band.find(['5f0e41d92c97a64a26aabd10', '5f0e41b02c97a64a26aabd0e'])

O método find exibe o seguinte comportamento:

  • Se você fornecer o mesmo valor de _id mais de uma vez, o Mongoid retornará apenas um documento, se houver.

  • O Mongoid não retorna documentos de forma ordenada. Os documentos podem ser retornados em ordem diferente da ordem dos valores _id fornecidos.

  • Se qualquer um dos valores _id não for encontrado no banco de dados, o resultado dependerá do valor da opção de configuração raise_not_found_error.

    Se você definir a opção raise_not_found_error como true, find gerará um erro Mongoid::Errors::DocumentNotFound se qualquer um dos valores _id não for encontrado.

    Se você definir a opção raise_not_found_error como false e consultar um único valor _id, find retornará nil se o Mongoid não corresponder a um documento. Se você passar vários valores de _id e alguns ou todos não forem correspondentes, o valor de retorno será uma array de documentos correspondentes ou uma array vazia se nenhum documento corresponder.

Esta seção descreve métodos semelhantes ao método find descrito na seção anterior.

Você pode usar o método find_by para recuperar documentos com base nos critérios fornecidos. Se nenhum documento for encontrado, ele gerará um erro ou retornará nil dependendo de como você definir a opção de configuração raise_not_found_error.

O seguinte código demonstra como utilizar o método find_by:

# Simple equality query
Band.find_by(name: "Photek")
# Performs an action on each returned result
Band.find_by(name: "Tool") do |band|
band.fans += 1
end

Você pode usar o método find_or_create_by para recuperar documentos com base nos critérios fornecidos. Se nenhum documento for encontrado, ele criará e retornará uma instância que será salva no MongoDB.

O seguinte código demonstra como utilizar o método find_or_create_by:

# If no matches, creates a Band with just the "name" field
Band.find_or_create_by(name: "Photek")
# If no matches, creates a Band with just the "name" field because the
# query condition is not a literal
Band.where(:likes.gt => 10).find_or_create_by(name: "Photek")
# Creates a Band in which the name is Aerosmith because there is no
# document in which "name" is Photek and Aerosmith at the same time
Band.where(name: "Photek").find_or_create_by(name: "Aerosmith")

Você pode usar o método find_or_initialize_by para recuperar documentos com base nos critérios fornecidos. Se nenhum documento for encontrado, ele retornará um novo, sem persisti-lo no MongoDB. Use a mesma sintaxe para find_or_initialize_by que você faz para o método find_or_create_by.

O Mongoid permite fazer query de documentos usando expressões regulares em seus critérios de filtro.

O seguinte código cria um modelo Band de amostra:

Band.create!(name: 'Tame Impala', description: "Tame\nImpala is an American band")

Você pode realizar queries usando expressões regulares Ruby, conforme mostrado no código a seguir:

# Matches documents in which the "name" field includes the string "impala"
Band.where(name: /impala/i)
# => Returns sample document

Você também pode executar queries usando a sintaxe Perl Compatible Regular Expression (PCRE) e os objetos BSON::Regexp::Raw:

# Matches "description" values that start exactly with "Impala"
Band.where(description: /\AImpala/)
# => nil
# Matches "description" values that start exactly with "Impala"
Band.where(description: BSON::Regexp::Raw.new('^Impala'))
# => nil
# Matches "description" values that start exactly with "Impala" with
# the multiline option
Band.where(description: BSON::Regexp::Raw.new('^Impala', 'm'))
# => Returns sample document

Quando você especifica uma query em um campo definido em um modelo, se o campo tiver um tipos de dados especificado, o Mongoid converte o valor da query com base em como o campo é definido.

Considere a seguinte definição de modelo Album que contém um campo com valor Date , um campo com valor Timee um campo implícito com valor Object. O modelo também intencionalmente não define um campo last_reviewed chamado:

class Album
include Mongoid::Document
field :release_date, type: Date
field :last_commented, type: Time
field :last_purchased
end

Você pode executar queries nos campos release_date e last_commented utilizando valores Date e Time, como mostrado no seguinte código:

Album.where(release_date: Date.today)
# Interpreted query:
# {"release_date"=>2024-11-05 00:00:00 UTC}
Album.where(last_commented: Time.now)
# Interpreted query:
# {"last_commented"=>2024-11-04 17:20:47.329472 UTC}

No entanto, se você fizer query usando apenas Date valores em campos definidos como outros tipos, as queries geradas exibirão o comportamento de conversão padrão, conforme mostrado no exemplo a seguir:

Album.where(last_commented: Date.today)
# Interpreted query:
# {"last_commented"=>Mon, 04 Nov 2024 00:00:00.000000000 EST -05:00}
Album.where(last_purchased: Date.today)
# Interpreted query:
# {"last_purchased"=>"2024-11-04"}
Album.where(last_reviewed: Date.today)
# Interpreted query:
# {"last_reviewed"=>2024-11-04 00:00:00 UTC}

No exemplo anterior, as seguintes conversões se aplicam:

  • Ao usar um Date valor para fazer uma query Time last_commented do campo com valor, o Mongoid interpreta a data como sendo na hora local e aplica o zona horário configurado.

  • Ao executar query no campo last_purchased , que não tem tipo explícito, a data é utilizada sem modificações na query construída.

  • Ao executar query do campo last_reviewed indefinido, o Mongoid interpreta o Date como UTC e converte para uma hora, correspondendo ao comportamento de executar query de um campo com valor Date, como release_date.

Esta seção descreve mais métodos de query que você pode usar no Mongoid.

Você pode usar os métodos count e estimated_count para contar o número de documentos em uma coleção.

Você pode contar o número de documentos que correspondem aos critérios de filtro usando o método count:

# Counts all documents in collection
Band.count
# Counts documents that match criteria
Band.where(country: 'England').count

Dica

Métodos de comprimento e tamanho

Você também pode usar o método length ou size para contar documentos. Esses métodos armazenam em cache chamadas subsequentes para o banco de dados, o que pode produzir melhorias de desempenho.

Você pode obter um número aproximado de documentos na coleção a partir dos metadados da coleção usando o método estimated_count:

Band.estimated_count

O estimated_count método não aceita condições de query, incluindo condições definidas por um escopo no modelo. Se você estiver chamando esse método em um modelo que tenha um escopo padrão, deverá primeiro chamar o método unscoped para desativar o escopo.

Os métodos descritos na lista a seguir permitem selecionar um resultado específico da lista de documentos devolvidos com base em sua posição.

  • first: retorna o primeiro documento correspondente . Você pode obter os primeiros n documentos passando um parâmetro de valor inteiro. Este método usa automaticamente uma classificação no campo _id. Consulte as linhas 1- no código a seguir para obter exemplos.8

  • last: retorna o último documento correspondente . Você pode obter os últimos n documentos passando um parâmetro de valor inteiro. Este método usa automaticamente uma classificação no campo _id. Consulte a linha no código a seguir para obter um exemplo.11

  • first_or_create: retorna o primeiro documento correspondente . Se nenhum documento corresponder, cria e retorna um novo salvo.

  • first_or_initialize: retorna o primeiro documento correspondente . Se nenhum documento corresponder, retorna um novo.

  • second: retorna o segundo documento correspondente . Utiliza automaticamente uma classificação no campo _id.

  • third: Retorna o terceiro documento correspondente . Utiliza automaticamente uma classificação no campo _id.

  • fourth: retorna o quarto documento correspondente . Utiliza automaticamente uma classificação no campo _id.

  • fifth: Retorna o quinto documento correspondente . Utiliza automaticamente uma classificação no campo _id.

  • second_to_last: retorna o penúltimo documento correspondente. Utiliza automaticamente uma classificação no campo _id. Consulte a linha no código a seguir para obter um exemplo.14

  • third_to_last: retorna o antepenúltimo documento correspondente. Utiliza automaticamente uma classificação no campo _id.

O seguinte código demonstra como usar alguns métodos descritos na lista anterior:

1# Returns the first document in the collection
2Band.first
3
4# Returns the first matching document
5Band.where(founded: {'$gt' => 1980}).first
6
7# Returns the first two matching documents
8Band.first(2)
9
10# Returns the last matching document
11Band.where(founded: {'$gt' => 1980}).last
12
13# Returns the second to last document
14Band.second_to_last

Dica

Geração de erro

Cada método descrito nesta seção tem uma variação com o sufixo ! que retorna um erro se o Mongoid não corresponder a nenhum documento. Por exemplo, para implementar o tratamento de erros em seu aplicação quando sua query não retornar resultados, use o método first! em vez de first.

Para inspecionar os valores de campos especificados de documentos em uma coleção, você pode usar os seguintes métodos:

  • distinct: Obtém uma lista de valores distintos para um único campo. Consulte as linhas 1- no código a seguir para obter exemplos.7

  • pick: obtém os valores de um documento para os campos fornecidos. Retorna nil para campos não definidos e para campos inexistentes. Consulte a linha no código a seguir para obter um exemplo.10

  • pluck: Obtém todos os valores para o campo fornecido . Retorna nil para campos não definidos e para campos inexistentes. Consulte a linha no código a seguir para obter um exemplo.13

  • tally: Obtém um mapeamento de valores para contagens para o campo especificado . Consulte a linha no código a seguir para obter um exemplo.16

Os métodos anteriores aceitam nomes de campo referenciados usando notação de ponto, o que permite fazer referência a campos em associações incorporadas. Eles também respeitam os aliases de campo, incluindo aqueles definidos em documentos incorporados.

O seguinte código demonstra como usar estes métodos:

1Band.distinct(:name)
2# Example output: "Ghost Mountain" "Hello Goodbye" "She Said"
3
4Band.where(:members.gt => 2).distinct(:name)
5# Example output: "Arctic Monkeys" "The Smiths"
6
7Band.distinct('tours.city')
8# Example output: "London" "Sydney" "Amsterdam"
9
10Band.all.pick(:name)
11# Example output: "The Smiths"
12
13Band.all.pluck(:country)
14# Example output: "England" "Spain" "England" "Japan"
15
16Band.all.tally(:country)
17# Example output: ["England",2] ["Italy",3]

A lista a seguir descreve os métodos Mongoid que não se encaixam em outra categoria:

  • each: itera sobre todos os documentos correspondentes.

# Print each matching document "name" to console
Band.where(:members.gt => 1).each do |band|
p band.name
end
  • exists?: Determina se existe algum documento correspondente, retornando true se pelo menos um documento correspondente for encontrado.

# Checks existence of any document
Band.exists?
# Checks existence based on query
Band.where(name: "Le Tigre").exists?
Band.exists?(name: "Le Tigre")
# Checks existence based on "_id" value
Band.exists?('6320d96a3282a48cfce9e72c')
# Always returns false
Band.exists?(false)
Band.exists?(nil)

Para saber como modificar a maneira como o Mongoid retorna resultados para você, consulte Modificar resultados da consulta.

Para saber mais sobre como definir escopos em seus modelos, consulte Escopo.

Para saber mais sobre os métodos que você pode conectar às suas queries para persistir dados, consulte Persistir dados de queries.

Para saber mais sobre o recurso de cache de query, consulte Cache de query.

Para saber mais sobre como realizar queries assíncronas, consulte Queries assíncronas.