Realizar operações de dados

criar!

Utilize o método create! na sua classe de modelo para inserir um ou mais documentos em uma collection. Se ocorrer algum erro de servidor ou validação, create! criará uma exceção.

Para chamar create!, passe um hash de atributos que definem o documento que você deseja inserir. Se você deseja criar e inserir vários documentos, passe uma array de hashes.

Este exemplo mostra várias maneiras de chamar create!. O primeiro exemplo cria um documento Person e o segundo exemplo cria dois documentos Person. O terceiro exemplo passa um bloco do..end para create!. O Mongoid invoca este bloco com os documentos passados para create! como argumentos. O método create! tenta salvar o documento no final do bloco:

Person.create!(
  first_name: "Heinrich",
  last_name: "Heine"
)
Person.create!([
  { first_name: "Heinrich", last_name: "Heine" },
  { first_name: "Willy", last_name: "Brandt" }
])
Person.create!(first_name: "Heinrich") do |doc|
  doc.last_name = "Heine"
end

criar

Use o método create para inserir um novo documento ou vários novos documentos em um banco de dados. create não gera uma exceção em erros de validação, ao contrário da versão !com sufixo. create gera exceções em erros do servidor , como se você inserir um documento com um campo _id duplicado.

Se create encontrar algum erro de validação, o documento não será inserido, mas retornado com outros documentos que foram inseridos. Você pode usar os métodos persisted?, new_record? ou errors para verificar os documentos inseridos no banco de dados.

Este exemplo mostra como usar o create para inserir novos documentos no MongoDB. O primeiro exemplo mostra como inserir um documento Person . O segundo exemplo tenta inserir dois documentos Post, mas o segundo documento falha na validação porque contém um título duplicado. Em seguida, o exemplo usa o método persisted? para confirmar quais documentos foram inseridos com sucesso na coleção:

Person.create(
  first_name: "Heinrich",
  last_name: "Heine"
)
class Post
  include Mongoid::Document
  validates_uniqueness_of :title
end
posts = Post.create([{title: "test"}, {title: "test"}])
posts.map { |post| post.persisted? } # => [true, false]

Para saber mais sobre os persisted? new_record? métodos e, consulte a seção Atributos de persistência deste guia.

save!

Use o método save! para salvar atomicamente atributos alterados na coleção ou inserir um novo documento. save! gera uma exceção se houver algum erro de servidor ou validação. Você pode usar o método new para criar uma nova instância de documento . Em seguida, use save! para inserir o documento no banco de dados.

O exemplo a seguir mostra como usar save! para inserir um novo documento Person e atualizar o campo first_name do documento existente:

person = Person.new(
  first_name: "Esmeralda",
  last_name: "Qemal"
)
person.save!
person.first_name = "Malik"
person.save!

Salvar

O método save não gera uma exceção se houver algum erro de validação. save ainda gera uma exceção se houver algum erro no servidor . O método retorna true se todos os atributos alterados forem salvos e false se ocorrer algum erro de validação.

Você pode passar as seguintes opções para save:

• validate: false: Para ignorar validações ao salvar o novo documento ou atributos atualizados.

• touch: false: Para não atualizar o campo updated_at ao atualizar os atributos especificados. Esta opção não tem efeito ao inserir um novo documento.

O código a seguir usa save para inserir um novo documento. Em seguida, ele atualiza esse documento e aplica a opção validate: false.

person = Person.new(
  first_name: "Tamara",
  last_name: "Graham"
)
person.save
person.first_name = "Aubrey"
person.save(validate: false)

attributes

Você pode utilizar o método attributes para recuperar os atributos de uma instância de modelo como um hash. Esse hash também contém os atributos de todos os documentos incorporados.

O seguinte exemplo mostra como utilizar o attributes:

person = Person.new(first_name: "James", last_name: "Nan")
person.save
puts person.attributes

{ "_id" => BSON::ObjectId('...'),
  "first_name" => "James",
  "last_name" => "Nan"
}

recarregar

Você pode usar o método reload para acessar a versão mais recente de um documento do MongoDB. Quando você recarrega um documento, o Mongoid também recarrega quaisquer associações incorporadas na mesma query. No entanto, o Mongoid não recarrega associações referenciadas. Em vez disso, ele limpa esses valores para que sejam carregados do banco de dados durante o próximo acesso.

Quando você chama reload em um documento, todas as alterações não salvas no documento são perdidas. O código a seguir mostra como chamar reload em um documento:

band = Band.create!(name: 'Sun 1')
# => #<Band _id: ..., name: "Sun 1">
band.name = 'Moon 2'
# => #<Band _id: ..., name: "Moon 2">
band.reload
# => #<Band _id: ..., name: "Sun 1">

O exemplo anterior atualiza o campo name no documento band, mas não salva o novo valor. Como o Mongoid não persistiu a alteração no valor name, name contém o valor original salvo no banco de dados.

existing = Band.create!(name: 'Photek')
band = Band.new(id: existing.id)
band.reload
puts band.name

Photek

update_attributes!

Você pode utilizar o método update_attributes! para atualizar os atributos de uma instância do modelo existente. Este método gera uma exceção se encontrar algum erro de validação ou servidor .

O exemplo a seguir mostra como usar update_attributes! para atualizar os atributos first_name e last_name de um documento existente:

person.update_attributes!(
  first_name: "Maximilian",
  last_name: "Hjalmar"
)

update_attributes

O método update_attributes não gera uma exceção em erros de validação. O método retorna true se passar na validação e o documento for atualizado e false caso contrário.

O seguinte exemplo mostra como utilizar o update_attributes:

person.update_attributes(
  first_name: "Hasan",
  last_name: "Emine"
)

update_attribute

Você pode utilizar o update_attribute método para ignorar validações e atualizar um único atributo de uma instância do modelo.

O exemplo a seguir mostra como usar update_attribute para atualizar o valor do atributo first_name de um documento:

person.update_attribute(:first_name, "Jean")

upsert

Você pode usar o método upsert para atualizar, inserir ou substituir um documento.

upsert aceita uma opção replace. Se você definir essa opção como true e o documento que chama upsert já existir no banco de dados, o novo documento substituirá o documento no banco de dados. Todos os campos no banco de dados que o novo documento não substitui são removidos.

Se você definir a opção replace como false e o documento existir no banco de dados, ele será atualizado. O Mongoid não altera nenhum campo além dos especificados no documento de atualização . Se o documento não existir no banco de dados, ele será inserido com os campos e valores especificados no documento de atualização. A opção replace é definida como false por padrão.

O exemplo a seguir mostra como usar upsert para primeiro inserir um novo documento e, em seguida, substituí-lo definindo replace: true:

person = Person.new(
  first_name: "Balu",
  last_name: "Rama"
)
person.upsert
person.first_name = "Ananda"
person.upsert(replace: true)

toque

Você pode usar o método touch para atualizar o carimbo de data/hora updated_at de um documento para a hora atual. touch propaga a atualização para qualquer uma das associações belongs_to do documento. Você também pode passar outro campo com valor de tempo como uma opção para também atualizar esse campo.

O exemplo a seguir usa touch para atualizar os registros de data e hora updated_at e audited_at:

person.touch(:audited_at)

excluir

Você pode usar o método delete para excluir um documento do banco de dados. Quando você usa delete, o Mongoid não executa nenhum retorno de chamada. Se o documento não for salvo no banco de dados, delete tentará excluir qualquer documento com o mesmo valor de _id.

O exemplo a seguir mostra como usar o método delete e demonstra o que acontece quando você exclui um documento que não é salvo no banco de dados:

person = Person.create!(name: 'Edna Park')
unsaved_person = Person.new(id: person.id)
unsaved_person.delete
person.reload

No exemplo anterior, o Mongoid gera um erro Mongoid::Errors::DocumentNotFound quando você chama reload porque unsaved_person.delete exclui o documento person porque os dois documentos têm o mesmo valor para _id.

destruir

O método destroy opera de forma semelhante a delete, exceto pelo Mongoid que executa chamadas de resposta quando você chama destroy. Se o documento não for encontrado no banco de dados, destroy tentará excluir qualquer documento com o mesmo _id.

O seguinte exemplo mostra como utilizar o destroy:

person.destroy

delete_all

O método delete_all exclui todos os documentos da collection que são modelados por sua classe de modelo Mongoid. delete_all não executa retornos de chamada.

O exemplo a seguir mostra como usar o delete_all para excluir todos os documentos do Person:

Person.delete_all

Destruir_all

O método destroy_all exclui todos os documentos da collection que são modelados por sua classe de modelo Mongoid. Esta pode ser uma operação cara porque o Mongoid carrega todos os documentos na memória.

O exemplo a seguir mostra como usar o destroy_all para excluir todos os documentos do Person:

Person.destroy_all

new_record?

O new_record? atributo retorna true se a instância do modelo ainda não tiver sido salva no banco de dados e false caso contrário. Ele verifica a condição oposta como o persisted? atributo.

O seguinte exemplo mostra como utilizar o new_record?:

person = Person.new(
  first_name: "Tunde",
  last_name: "Adebayo"
)
puts person.new_record?
person.save!
puts person.new_record?

true
false

persistiu?

O atributo persisted? retorna true se Mongoid persistir a instância do modelo e false caso contrário. Ele verifica a condição oposta como o atributo new_record?.

O seguinte exemplo mostra como utilizar o persisted?:

person = Person.new(
  first_name: "Kiana",
  last_name: "Kahananui"
)
puts person.persisted?
person.save!
puts person.persisted?

false
true

Obter e definir valores de campo

Existem várias maneiras de obter e definir valores de campo em um documento. Se você declarar explicitamente um campo, poderá obter e definir o valor desse campo diretamente no documento . O exemplo seguinte mostra como configurar e obter o campo first_name para uma instância do Person:

class Person
  include Mongoid::Document
  field :first_name
end
  
person = Person.new
  
person.first_name = "Artem"
person.first_name # => "Artem"

O exemplo anterior primeiro usa o atributo first_name para definir um valor e, em seguida, o chama novamente para recuperar o valor.

Você também pode usar os métodos [] e [] = em uma instância de modelo do Mongoid para acessar atributos usando a sintaxe de hash. O método [] é um alias para o método read_attribute e o método [] = é um alias para o método write_attribute. O exemplo a seguir mostra como obter e definir o campo first_name com nome alternativo usando os métodos [] e []=:

class Person
  include Mongoid::Document
  
  field :first_name, as: :fn
end
  
person = Person.new(first_name: "Artem")
  
person["fn"]
# => "Artem"
person[:first_name] = "Vanya"
# => "Artem"
person
# => #<Person _id: ..., first_name(fn): "Vanya">

Para saber mais sobre esses métodos, consulte a seguinte seção read_attribute e write_attribute deste guia.

read_attribute e write_attribute

Você pode utilizar os métodos read_attribute e write_attribute para especificar o comportamento personalizado ao ler ou gravar campos. Você pode usar esses métodos ao definir um modelo ou chamando-os em instâncias de modelo.

Para utilizar o read_attribute para obter um campo, passe o nome do campo para o método. Para usar write_attribute para definir um campo, passe o nome do campo e o valor a ser atribuído.

O exemplo seguinte utiliza read_attribute e write_attribute em uma definição de modelo para definir first_name e first_name= como métodos que são utilizados para ler e escrever no atributo fn:

class Person
  include Mongoid::Document
  def first_name
    read_attribute(:fn)
  end
  def first_name=(value)
    write_attribute(:fn, value)
  end
end
  
person = Person.new
person.first_name = "Artem"
person.first_name
# => "Artem"

Você também pode chamar read_attribute e write_attribute diretamente em uma instância de modelo para obter e definir atributos. O exemplo seguinte utiliza estes métodos em uma instância de modelo para obter o atributo first_name e defini-lo para o valor "Pushkin".

class Person
  include Mongoid::Document
  field :first_name, as: :fn
end
  
person = Person.new(first_name: "Artem")
# => #<Person _id: ..., first_name(fn): "Artem">
person.read_attribute(:first_name)
# => "Artem"
person.read_attribute(:fn)
# => "Artem"
person.write_attribute(:first_name, "Pushkin")
person
# => #<Person _id: ..., first_name(fn): "Pushkin">

Atributos de gravação em massa

Você pode escrever em vários campos ao mesmo tempo usando os métodos attributes= ou write_attributes em uma instância do modelo.

Para utilizar o método attributes=, chame o método em uma instância de modelo e passe um objeto de hash que contenha os campos e valores que você deseja definir. O exemplo a seguir mostra como usar o método attributes= para definir os campos first_name e middle_name em um documento person :

person.attributes = { first_name: "Jean-Baptiste", middle_name: "Emmanuel" }

Para utilizar o método write_attributes, chame o método em uma instância do modelo e passe os campos e valores que você deseja definir. O exemplo a seguir mostra como usar o método write_attributes para definir os campos first_name e middle_name em um documento person :

person.write_attributes(
  first_name: "Jean-Baptiste",
  middle_name: "Emmanuel",
)

Operações atômicas do grupo

Para agrupar operações atômicas, você pode usar o método atomically em uma instância de modelo. O Mongoid envia todas as operações que você passa para um bloco atomically em um único comando atômico.

O exemplo a seguir mostra como usar o atomically para atualizar atomicamente vários campos em um documento:

person.atomically do
  person.inc(age: 1)
  person.set(name: 'Jake')
end

Você pode aninhar #atomically blocos ao atualizar um único documento. Por padrão, o Mongoid realiza gravações atômicas definidas por cada bloco quando o bloco termina. O exemplo a seguir mostra como aninhar atomically blocos:

person.atomically do
  person.atomically do
      person.inc(age: 1)
      person.set(name: 'Jake')
  end
  raise 'An exception'
  # Name and age changes are persisted
end

No exemplo anterior, as operações $inc e $set são executadas no final do bloco atomically interno.

person.atomically do
  person.atomically(join_context: true) do
      person.inc(age: 1)
      person.set(name: 'Jake')
  end
  raise 'An exception'
  # Name and age changes are not persisted
end

Ver alterações

O Mongoid registra as alterações desde o momento em que um modelo é instanciado, seja como um novo documento ou recuperando um do banco de dados, até o momento em que ele é salvo. Qualquer operação de persistência limpa as alterações.

A Mongoid cria métodos específicos do modelo que permitem explorar as alterações em uma instância do modelo. O código a seguir demonstra maneiras de visualizar as alterações na instância do modelo:

# Retrieves a person instance
person = Person.first
# Sets a new `name` value
person.name = "Sarah Frank"
# Checks to see if the document is changed
person.changed? # true
# Gets an array of changed fields.
person.changed # [ :name ]
# Gets a hash of the old and changed values for each field
person.changes # { "name" => [ "Sarah Frink", "Sarah Frank" ] }
# Checks if a specific field is changed
person.name_changed? # true
# Gets the changes for a specific field
person.name_change # [ "Sarah Frink", "Sarah Frank" ]
# Gets the previous value for a field
person.name_was # "Sarah Frink"

Redefinir alterações

Você pode redefinir um campo alterado para seu valor anterior ligando para o método reset, como mostrado no seguinte código:

person = Person.first
person.name = "Sarah Frank"
# Reset the changed `name` field
person.reset_name!
person.name # "Sarah Frink"

Persistência

O Mongoid usa o rastreamento sujo como base de todas as operações de persistência. Ele avalia as alterações em um documento e atualiza atomicamente apenas o que foi alterado, em comparação com outras estruturas que gravam o documento inteiro em cada salvamento. Se você não fizer nenhuma alteração, o Mongoid não acessará o banco de dados quando você chamar Model#save.

Ver alterações anteriores

Depois de persistir um modelo no MongoDB, o Mongoid limpa as alterações atuais. No entanto, você ainda pode ver quais alterações foram feitas anteriormente chamando o método previous_changes, como mostrado no seguinte código:

person = Person.first
person.name = "Sarah Frank"
person.save # Clears out current changes
# Lists the previous changes
person.previous_changes
# { "name" => [ "Sarah Frink", "Sarah Frank" ] }