Modificar Resultados da Query

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 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.

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)

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.

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)

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)

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

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)

Método inclui

O método includes carrega associações utilizando queries separadas para cada associação. O código a seguir carrega bandas e seus discos e etiquetas associados utilizando queries separadas:

Band.where(name: 'The Beatles').includes({ albums: :songs }, :labels).first

Quando você usa o método includes, o Mongoid executa uma query na classe base para obter todos os documentos de base e, em seguida, uma query separada para cada associação que ele carrega.

O exemplo anterior executa as seguintes queries:

• Uma query para encontrar os documentos Band

• Uma query para carregar os documentos Album associados

• Uma query para carregar os documentos Label associados

• Uma query para carregar os documentos Song associados

Método antas_load

O método eager_load utiliza o pipeline de agregação MongoDB com operadores $lookup para carregar todas as associações em uma única query. O código a seguir usa uma única query de pipeline de agregação para carregar as bandas e seus discos e rótulos associados, com $lookup estágios para cada associação:

Band.where(name: 'The Beatles').eager_load({ albums: :songs }, :labels).first

Considerações de desempenho

Os métodos includes e eager_load executam carregamento rápido, mas o fazem de maneiras diferentes. O método includes executa uma query para os documentos base e, em seguida, queries separadas para cada associação. O método eager_load utiliza um único pipeline de agregação com estágios $lookup para carregar as associações.

O método eager_load executa menos queries e utiliza menos memória do que includes. No entanto, a eficiência do método difere com base no tipo de associações em seus documentos:

• eager_load é mais rápido para has_many, has_and_belongs_to_many e carregando múltiplas associações na maioria dos conjuntos de dados

• includes é mais rápido para belongs_to, has_one e associações aninhadas na maioria dos conjuntos de dados

Escolha o método que melhor se adequa ao seu caso de uso e tipos de associação.