Modificar Resultados da Query
Nesta página
Visão geral
Neste guia, você pode aprender a personalizar a maneira como o Mongoid retorna resultados de queries. O MongoDB permite que você execute as seguintes ações para modificar a forma como os resultados aparecem:
Dados de amostra
Os exemplos neste 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 também usam o modelo Manager
, que representa uma pessoa que gerencia uma determinada banda, ou o modelo Tour
, que representa atuações ao vivo de uma determinada banda.
Retornar campos especificados
No MongoDB, projeção é o processo de especificar campos a serem incluídos ou excluídos dos resultados. O Mongoid fornece os seguintes operadores para projeto campos:
only
: especifica os campos a serem incluídoswithout
: especifica os campos a serem excluídos
Incluir campos
O método only
recupera somente os campos especificados do banco de dados.
O código a seguir retorna apenas o campo name
de documentos nos quais o valor do campo members
é 4
:
Band.where(members: 4).only(:name)
Observação
Campo _id
No MongoDB, o campo _id
é incluído nos resultados mesmo que você não o inclua explicitamente.
Se você tentar referenciar atributos que não foram carregados, o Mongoid gerará um erro Mongoid::Errors::AttributeNotLoaded
.
Você também pode usar o método only
para incluir campos de documentos incorporados.
Considere que o modelo Band
incorpora vários objetos Tour
. Você pode projeto campos do modelo Tour
como year
, conforme mostrado no código a seguir:
bands = Band.only(:name, 'tours.year')
Em seguida, você pode acessar os campos incorporados a partir dos documentos retornados:
# Returns the first Tour object from # the first Band in the results bands.first.tours.first
Você pode passar campos de associações referenciadas para o método only
, mas a projeção é ignorada ao carregar os objetos embarcados. O Mongoid carrega todos os campos das associações referenciadas. Por exemplo, quando você acessa o objeto Tour
incorporado, conforme mostrado no código anterior, o Mongoid retorna o objeto completo, não apenas o campo year
.
Observação
Se você estiver conectado a uma implantação executando o MongoDB 4.4 ou posterior, não poderá especificar uma associação e seus campos em uma projeção na mesma query.
Se um documento contiver associações has_one
ou has_and_belongs_to_many
e você quiser que o Mongoid carregue essas associações quando chamar o método only
, será necessário incluir os campos com chaves estrangeiras na lista de atributos.
No exemplo seguinte, os modelos Band
e Manager
têm uma associação has_and_belongs_to_many
:
class Band include Mongoid::Document field :name, type: String has_and_belongs_to_many :managers end class Manager include Mongoid::Document has_and_belongs_to_many :bands end
O código a seguir demonstra como o Mongoid pode carregar os objetos Manager
associados se você incluir o campo manager_ids
:
# Returns null Band.where(name: 'Astral Projection').only(:name).first.managers # Returns the first Manager object Band.where(name: 'Astral Projection').only(:name, :manager_ids).first.managers
Exclua campos
Você pode excluir campos explicitamente dos resultados usando o método without
.
O seguinte código exclui o campo year
dos objetos Band
retornados:
Band.where(members: 4).without(:year)
Importante
Campo _id
O Mongoid requer o _id
campo para várias operações, portanto você não pode excluir o _id
campo ou o id
nome alternativo dos resultados. Se você passar _id
ou id
para o método without
, o Mongoid o ignorará.
Classificar resultados
Você pode especificar a ordem em que o Mongoid retorna documentos usando os métodos order
e order_by
.
Esses métodos aceitam um hash que indica por quais campos os documentos devem ser ordenados e se uma ordem crescente ou decrescente para cada campo deve ser usada.
Você pode especificar a direção de classificação usando números inteiros, símbolos ou strings. Recomendamos usar a mesma sintaxe de classificação em todo o aplicação para obter consistência. A lista a seguir fornece cada sintaxe e mostra como classificar nos campos name
e year
:
Inteiros
1
(ascendente) e-1
(descendente)Exemplo:
Band.order(name: 1, year: -1)
Símbolos
:asc
e:desc
Exemplo:
Band.order(name: :asc, year: :desc)
Strings
"asc"
e"desc"
Exemplo:
Band.order_by(name: "asc", year: "desc")
O método order
também aceita as seguintes especificações de classificação:
Array de arrays de dois elementos:
Strings
Exemplo:
Band.order([['name', 'asc'], ['year', 'desc']])
Símbolos
Exemplo:
Band.order([[:name, :asc], [:year, :desc]])
Métodos
asc
edesc
em símbolosExemplo:
Band.order(:name.asc, :year.desc)
sintaxe SQL
Exemplo:
Band.order('name asc', 'year desc')
Dica
Em vez de utilizar order
ou order_by
, você também pode utilizar os métodos asc
e desc
para especificar ordens de classificação:
Band.asc('name').desc('year')
Quando você encadeia especificações de classificação, a primeira chamada define a primeira ordem de classificação e a chamada mais recente define a última ordem de classificação depois que as classificações anteriores têm sido aplicadas.
Observação
Classificação em escopos
Se você definir um escopo padrão em seu modelo que inclua uma especificação de classificação, a classificação do escopo terá precedência sobre a classificação especificada em uma query, pois o escopo padrão será avaliado primeiro.
Paginar resultados
O Mongoid fornece os métodos de paginação limit
, skip
e batch_size
que você pode usar em objetos Criteria
. As seções a seguir descrevem como usar esses operadores.
Limitar número de resultados
Você pode usar o método limit
para limitar o número de resultados que o Mongoid retorna.
O seguinte código recupera um máximo de 5
documentos:
Band.limit(5)
Observação
Alternativamente, você pode usar o método take
para recuperar um número específico de documentos do banco de dados:
Band.take(5)
Ignorar resultados
Você pode ignorar um número específico de resultados usando o método skip
ou seu alias offset
.
Se você encadear uma chamada limit
para skip
, o limite será aplicado depois que os documentos forem ignorados, conforme demonstrado no exemplo a seguir:
Band.skip(2).limit(5) # Skips the first two results and returns # the following five results
Dica
Ao realizar a paginação, use skip
em resultados classificados para garantir resultados consistentes.
O seguinte código ignora os primeiros 3
documentos ao retornar resultados:
Band.skip(3) # Equivalent Band.offset(3)
Gerar lotes de resultados
Ao executar query grandes e ao iterar sobre os resultados da query usando um método enumerador Criteria#each
como, o Mongoid usa automaticamente o comando getMore do MongoDB para carregar os resultados em lotes. O tamanho do lote padrão é 1000
, mas você pode definir um valor diferente usando o método batch_size
.
O seguinte código define o tamanho do lote para 500
:
Band.batch_size(500)
Informações adicionais
To learn more about constructing queries, see the Especificar uma query de documento guide.
Para saber mais sobre a modelagem de dados Mongoid, consulte os guias Modele seus dados.