Escopo

Escopo avançado

Você pode definir Proc objetos e blocos em escopos nomeados para que eles aceitem parâmetros e estendam a funcionalidade.

Este exemplo define um modelo Band que inclui o escopo based_in, que corresponde a documentos nos quais o valor do campo country é o valor especificado passado como um parâmetro:

class Band
  include Mongoid::Document
  field :name, type: String
  field :country, type: String
  scope :based_in, ->(country){ where(country: country) }
end

Em seguida, faça uma query usando o escopo based_in, conforme mostrado no código a seguir:

Band.based_in("Spain")

O Mongoid permite definir um escopo que sombreia um método de classe existente, conforme mostrado no exemplo a seguir:

class Band
  include Mongoid::Document
  def self.on_tour
    true
  end
  scope :on_tour, ->{ where(on_tour: true) }
end

Você pode direcionar o Mongoid para gerar um erro quando um escopo substituir um método de classe existente definindo a opção de configuração scope_overwrite_exception como true.

Para saber mais sobre essa configuração, consulte o guia Configuração do aplicativo.

Inicialização do campo

A especificação de um escopo padrão inicializa os campos de novos modelos para os valores fornecidos no escopo padrão se esses valores forem literais, como valores booleanos ou inteiros.

class Band
  include Mongoid::Document
  field :name, type: String
  field :on_tour, type: Boolean, default: true
  default_scope ->{ where(on_tour: false) }
end
# Creates a new Band instance in which "on_tour" is "false"
Band.new

Não recomendamos usar notação de ponto para fazer referência a campos aninhados em escopos padrão. Isso pode direcionar o Mongoid a inicializar campos inesperados em novos modelos.

Por exemplo, se você definir um escopo padrão que referencia o campo tour.year , um novo modelo será inicializado com o campo tour.year em vez de um campo tour com um objeto aninhado que contém um campo year .

Ao consultar, o Mongoid interpreta a notação de ponto corretamente e corresponde a documentos nos quais um campo aninhado tem o valor especificado.

Associações

Se você definir um escopo padrão em um modelo que faz parte de uma associação, será necessário recarregar a associação para que o escopo seja reaplicado. Isso é necessário para quando você altera um valor de um documento na associação que afeta sua visibilidade quando o escopo é aplicado.

Este exemplo usa os seguintes modelos:

class Label
  include Mongoid::Document
  field :name, type: String
  embeds_many :bands
end
  
class Band
  include Mongoid::Document
  field :name, type: String
  field :active, default: true
  embedded_in :label
  default_scope ->{ where(active: true) }
end

Suponha que você crie um modelo Label que contenha uma associação com um Band no qual o valor de active é true. Quando você atualiza o campo active para false, o Mongoid ainda o carrega, apesar do escopo padrão. Para visualizar os documentos na associação com o escopo aplicado, você deve chamar o operador reload.

O seguinte código demonstra esta sequência:

label = Label.new(name: "Hello World Records")
band = Band.new(name: "Ghost Mountain")
label.bands.push(band)
label.bands # Displays the Band because "active" is "true"
band.update_attribute(:active, false) # Updates "active" to "false"
# Displays the "Ghost Mountain" band
label.bands # => {"_id":"...","name":"Ghost Mountain",...}
# Won't display "Ghost Mountain" band after reloading
label.reload.bands # => nil

ou e nem Comportamento da query

O Mongoid trata os critérios em um escopo padrão da mesma forma que quaisquer outras condições de query. Isso pode levar a um comportamento surpreendente ao usar os métodos or e nor.

Os exemplos a seguir demonstram como o Mongoid interpreta queries em modelos com um escopo padrão:

class Band
  include Mongoid::Document
  
  field :name
  field :touring
  field :member_count
  
  default_scope ->{ where(touring: true) }
end
# Combines the condition to the default scope with "and"
Band.where(name: 'Infected Mushroom')
# Interpreted query:
# {"touring"=>true, "name"=>"Infected Mushroom"}
# Combines the first condition to the default scope with "and"
Band.where(name: 'Infected Mushroom').or(member_count: 3)
# Interpreted query:
# {"$or"=>[{"touring"=>true, "name"=>"Infected Mushroom"}, {"member_count"=>3}]}
# Combines the condition to the default scope with "or"
Band.or(member_count: 3)
# Interpreted query:
# {"$or"=>[{"touring"=>true}, {"member_count"=>3}]}

Para saber mais sobre operações lógicas, consulte Operações lógicas no guia Especificar uma query.

Desabilitar escopo ao fazer query

Você pode instruir o Mongoid a não aplicar o escopo padrão usando o operador unscoped, conforme mostrado nos exemplos a seguir:

# Inline example
Band.unscoped.where(name: "Depeche Mode")
# Block example
Band.unscoped do
  Band.where(name: "Depeche Mode")
end