Especificar uma query de documento
Nesta página
- Visão geral
- Dados de amostra
- Queries no Mongoid
- Criar um filtro de query
- Sintaxe de campo
- Sintaxe da API de consulta
- Sintaxe do operador de símbolos
- Query em diferentes tipos de campo
- Campos definidos
- Valores brutos
- Aliases de campo
- Documentos incorporados
- Operações lógicas
- Combinações do operador
- não Comportamento
- Construção de queries incrementais
- Estratégias de fusão
- Métodos de operador suportados
- Expansão de valor do operador
- Correspondência de elemento
- Associações
- Query por _id Value
- encontrar variações
- Expressões regulares
- Conversões de query do tipo de campo
- Métodos de queries adicionais
- Contagem de documentos
- Métodos ordinais
- Valores do campo de pesquisa
- Diversos
- Informações adicionais
Visão geral
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.
Dados de amostra
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.
Queries no Mongoid
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.
Criar um filtro de query
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
Sintaxe de campo
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')
Sintaxe da API de consulta
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})
Sintaxe do operador de símbolos
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)
Query em diferentes tipos de campo
Esta seção descreve como realizar queries em campos com diferentes tipos de valores.
Campos definidos
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.
Valores brutos
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'))
Aliases de campo
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')
Documentos incorporados
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 .
Operações lógicas
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}]])
Combinações do operador
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"}
não Comportamento
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.
Construção de queries incrementais
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.
Estratégias de fusão
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.
Métodos de operador suportados
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"}}]}
Expansão de valor do operador
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]}}
Correspondência de elemento
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'})
Associações
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.
Query por _id Value
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çãoraise_not_found_error
.Se você definir a opção
raise_not_found_error
comotrue
,find
gerará um erroMongoid::Errors::DocumentNotFound
se qualquer um dos valores_id
não for encontrado.Se você definir a opção
raise_not_found_error
comofalse
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.
encontrar variações
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
.
Expressões regulares
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
Conversões de query do tipo de campo
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 Time
e 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 queryTime
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 oDate
como UTC e converte para uma hora, correspondendo ao comportamento de executar query de um campo com valorDate
, comorelease_date
.
Métodos de queries adicionais
Esta seção descreve mais métodos de query que você pode usar no Mongoid.
Contagem de documentos
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.
Métodos ordinais
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 primeirosn
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.8last
: retorna o último documento correspondente . Você pode obter os últimosn
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.11first_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.14third_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 2 Band.first 3 4 # Returns the first matching document 5 Band.where(founded: {'$gt' => 1980}).first 6 7 # Returns the first two matching documents 8 Band.first(2) 9 10 # Returns the last matching document 11 Band.where(founded: {'$gt' => 1980}).last 12 13 # Returns the second to last document 14 Band.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
.
Valores do campo de pesquisa
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.7pick
: obtém os valores de um documento para os campos fornecidos. Retornanil
para campos não definidos e para campos inexistentes. Consulte a linha no código a seguir para obter um exemplo.10pluck
: Obtém todos os valores para o campo fornecido . Retornanil
para campos não definidos e para campos inexistentes. Consulte a linha no código a seguir para obter um exemplo.13tally
: 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:
1 Band.distinct(:name) 2 # Example output: "Ghost Mountain" "Hello Goodbye" "She Said" 3 4 Band.where(:members.gt => 2).distinct(:name) 5 # Example output: "Arctic Monkeys" "The Smiths" 6 7 Band.distinct('tours.city') 8 # Example output: "London" "Sydney" "Amsterdam" 9 10 Band.all.pick(:name) 11 # Example output: "The Smiths" 12 13 Band.all.pluck(:country) 14 # Example output: "England" "Spain" "England" "Japan" 15 16 Band.all.tally(:country) 17 # Example output: ["England",2] ["Italy",3]
Diversos
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, retornandotrue
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)
Informações adicionais
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.