Asociaciones

Tiene uno

Puede usar la macro has_one para declarar que los documentos representados por una clase también contienen un documento representado por una clase secundaria independiente. El siguiente ejemplo crea una clase Band con una relación has_one con una clase Studio:

class Band
  include Mongoid::Document
  has_one :studio
end

Al declarar una asociación has_one, la clase hija también debe usar la asociación belongs_to que hace referencia a la clase padre. El siguiente ejemplo muestra la clase Studio referenciada en la clase Band anterior:

class Studio
  include Mongoid::Document
  belongs_to :band
end

Para obtener más información sobre la macro belongs_to, consulte la Pertenece a la sección.

Puede utilizar validaciones para garantizar que la clase secundaria esté presente en su clase principal, como se muestra en el siguiente ejemplo:

class Band
  include Mongoid::Document
  has_one :studio
  validates_presence_of :studio
end

Para obtener más información sobre las validaciones en Mongoid, consulte la Guía de validaciones.

Tiene muchos

Puede usar la macro has_many para declarar que los documentos representados por una clase contienen varios documentos secundarios representados por otra clase. El siguiente ejemplo crea una clase Band con una relación has_many con una clase Members:

class Band
  include Mongoid::Document
  has_many :members
end

Al declarar una asociación has_many, la clase hija también debe usar la asociación belongs_to que hace referencia a la clase padre. El siguiente ejemplo muestra la clase Member referenciada en la clase Band anterior:

class Member
  include Mongoid::Document
  belongs_to :band
end

Para obtener más información sobre la belongs_to macro, consulte la sección Pertenece a.

Puede utilizar validaciones para garantizar que la clase secundaria esté presente en su clase principal, como se muestra en el siguiente ejemplo:

class Band
  include Mongoid::Document
  has_many :members
  validates_presence_of :members
end

Para obtener más información sobre las validaciones en Mongoid, consulte la guía de Validaciones.

band = Band.first
band.members.any?

band = Band.first
band.members.any? { |member| member.instrument == 'piano' }

class Drummer < Member
end
band = Band.first
band.members.any?(Drummer)

band = Band.create!
# Member is not persisted.
band.members.build
band.members.exists?
# Outputs: false
# Persist the member
band.members.map(&:save!)
band.members.exists?
# Outputs: true

Pertenece a

Utilice la macro belongs_to para declarar que un documento representado por una clase es hijo de un documento representado por otra clase. De forma predeterminada, el campo _id de la clase padre se almacena en la clase hija. El siguiente ejemplo crea una clase Members con una asociación belongs_to a una clase Band:

class Members
  include Mongoid::Document
  belongs_to :band
end

Puede permitir que Mongoid persista documentos en la base de datos sin almacenar el _id de la clase padre asociada configurando la opción optional en true, como se muestra en el siguiente ejemplo:

class Members
  include Mongoid::Document
  belongs_to :band, optional: true
end

Puede especificar una asociación belongs_to en una clase secundaria sin especificar una asociación has_one o has_many coincidente en la clase principal. Al hacerlo, no podrá acceder a los campos del documento secundario desde la clase principal, pero sí podrá acceder a los campos principales almacenados en la clase secundaria, como el campo _id de la clase principal. En el siguiente ejemplo, la clase Band no puede acceder a la clase Members, pero la clase Members sí puede acceder a la clase Band:

class Band
  include Mongoid::Document
end
class Members
  include Mongoid::Document
  belongs_to :band
end

Para mayor claridad, de manera opcional, puedes establecer la opción inverse_of en nil para indicar que la clase padre no contiene una asociación has_one o has_many con la clase hija, como se muestra en el siguiente ejemplo:

class Band
  include Mongoid::Document
end
class Members
  include Mongoid::Document
  belongs_to :band, inverse_of: nil
end

Tiene y pertenece a muchos

Utilice la macro has_and_belongs_to_many para declarar que un modelo de clase contiene una relación de varios a varios con otra clase. En una relación de varios a varios, cada documento de una clase puede asociarse con varios documentos de otra clase. El siguiente ejemplo crea una clase Band con una relación has_and_belongs_to_many con una clase Members. Un documento Band puede hacer referencia a varios documentos Members, y un documento Members puede hacer referencia a varios documentos Band.

class Band
  include Mongoid::Document
  has_and_belongs_to_many :members
end
class Members
  include Mongoid::Document
  has_and_belongs_to_many :bands
end

Al declarar una asociación has_and_belongs_to_many, ambas instancias del modelo almacenan una lista de los valores _id del documento asociado. Puede configurar la opción inverse_of como nil para almacenar los valores _id del documento asociado solo en una de las instancias del modelo. El siguiente ejemplo solicita a Mongoid que almacene los valores _id del documento asociado solo en la clase Band:

class Band
  include Mongoid::Document
  has_and_belongs_to_many :tags, inverse_of: nil
end
class Tag
  include Mongoid::Document
end

Asociaciones referenciadas por consulta

Puede usar una canalización de agregación para consultar documentos en asociaciones referenciadas. Esta canalización le permite crear consultas en múltiples colecciones y manipular datos en un formato específico. Para obtener más información sobre el uso de la canalización de agregación, consulte la guía de agregación.

Para consultas sencillas, puede consultar la asociación directamente. Al consultar directamente una colección, solo puede consultar los campos y valores que se encuentran en ella. No puede consultar directamente las colecciones asociadas a la que está consultando.

Por ejemplo, consideremos las siguientes clases Band y Tour:

class Band
  include Mongoid::Document
  has_many :tours
  field :name, type: String
end
class Tour
  include Mongoid::Document
  belongs_to :band
  field :year, type: Integer
end

El siguiente ejemplo consulta la clase Tour para encontrar documentos con un valor year igual o superior a 2000 y guarda el band_id de esos documentos. A continuación, consulta la clase Band para encontrar documentos con esos valores band_id.

band_ids = Tour.where(year: {'$gte' => 2000}).pluck(:band_id)
bands = Band.find(band_ids)

Incorpora uno

Para especificar que un modelo de clase contiene un documento incrustado de un tipo de clase diferente, utilice la macro embeds_one en la clase principal y la macro embedded_in en la clase incrustada. El siguiente ejemplo crea una clase Band con una clase Label incrustada:

class Band
  include Mongoid::Document
  
  embeds_one :label
end
class Label
  include Mongoid::Document
  field :name, type: String
  
  embedded_in :band
end

Mongoid almacena los documentos incrustados con la macro embeds_one en el documento principal como un campo con el mismo nombre que la clase incrustada. Los documentos Label anteriores se almacenan en el documento Band, como se muestra en el siguiente ejemplo:

# Band document
{
  "_id" : ObjectId("..."),
  "label" : {
    "_id" : ObjectId("..."),
    "name" : "Periphery",
  }
}

Puede almacenar el documento incrustado con un nombre diferente utilizando la opción store_as, como se muestra en el siguiente ejemplo:

class Band
  include Mongoid::Document
  
  embeds_one :label, store_as: "record_label"
end

Incrusta muchos

Para especificar que un modelo de clase contiene varios documentos incrustados de un tipo de clase diferente, utilice la macro embeds_many en la clase principal y la macro embedded_in en la clase incrustada. El siguiente ejemplo crea una clase Band con varios documentos incrustados de tipo Album:

class Band
  include Mongoid::Document
  
  embeds_many :albums
end
class Album
  include Mongoid::Document
  field :name, type: String
  embedded_in :band
end

Mongoid almacena los documentos incrustados con la macro embeds_many en el documento principal como un campo de matriz con el mismo nombre que la clase incrustada. Los documentos Album anteriores se almacenan en el documento Band, como se muestra en el siguiente ejemplo:

{
  "_id" : ObjectId("..."),
  "albums" : [
    {
      "_id" : ObjectId("..."),
      "name" : "Omega",
    }
  ]
}

Puede almacenar el documento incrustado con un nombre diferente utilizando la opción store_as, como se muestra en el siguiente ejemplo:

class Band
  include Mongoid::Document
  
  embeds_many :albums, store_as: "records"
end

Incrustación recursiva

Puede incrustar uno o más documentos del mismo tipo en una clase principal mediante las macros recursively_embeds_one y recursively_embeds_many. Ambas macros proporcionan accesores para los documentos principal y secundario mediante un método parent_* y un método child_*, donde * representa el nombre de la clase. El siguiente ejemplo crea una clase Band que incrusta recursivamente varios documentos Band para representar varios nombres de banda:

class Band
  include Mongoid::Document
  field :name, type: String
  recursively_embeds_many
end

Puede acceder a los documentos padre e hijo a través de los métodos parent_band y child_band, como se muestra en el siguiente ejemplo:

root = Band.new(name: "Linkin Park")
# Add child bands
child_one = root.child_band.build(name: "Lincoln Park")
child_two = root.child_band.build(name: "Xero")
# Access parent band
child_one.parent_band
# Outputs: root

Consultar asociaciones integradas

Puede acceder a documentos incrustados al consultar la colección de la clase principal mediante la notación de puntos.

El siguiente ejemplo utiliza la notación de puntos para consultar documentos de tipo Tour incrustados en una clase Band. La consulta devuelve documentos con un valor tours.year igual o superior a 2000:

Band.where('tours.year' => {'$gte' => 2000})

Puede utilizar el método de proyección pluck para recuperar documentos incrustados sin recuperar sus documentos principales asociados, como se muestra en el siguiente ejemplo:

# Get awards for bands that have toured since 2000
Band.where('tours.year' => {'$gte' => 2000}).pluck(:awards)

Puede usar los métodos de consulta de Mongoid para realizar coincidencias integradas, lo que le permite consultar asociaciones integradas de documentos ya cargados en la aplicación. Mongoid implementa la coincidencia integrada sin enviar consultas al servidor.

Los siguientes operadores de consulta son compatibles con coincidencia integrada:

• Operadores de comparación

• Operadores lógicos

• Operadores de consulta de matriz

• $exists

• $mod

• $type

• $regex

• Operadores bit a bit

El siguiente ejemplo consulta el campo tours incrustado de un documento Band cargado utilizando el operador de comparación $gte:

band = Band.where(name: 'Astral Projection').first
tours = band.tours.where(year: {'$gte' => 2000})

La coincidencia integrada en documentos cargados tiene las siguientes limitaciones conocidas:

• La coincidencia integrada no está implementada para las siguientes funciones:

  • Consulta de texto

  • Query geoespacial

  • Operadores que ejecutan código JavaScript, como $where

  • Operadores que se implementan a través de otras funcionalidades del servidor, como $expr y $jsonSchema

• Mongoid expande los argumentos Range a hashes con condiciones $gte y $lte. Esto puede generar consultas no válidas en algunos casos y generar una excepción InvalidQuery.

• Con el operador $regex, no se puede especificar un objeto de expresión regular como patrón y, al mismo tiempo, proporcionar opciones al campo $options. Solo se pueden proporcionar opciones si el patrón de expresión regular es una cadena.

Omitir campos _id

Por defecto, Mongoid añade un campo _id a los documentos incrustados. Se puede omitir este campo de los documentos incrustados mediante la especificación explícita del campo _id en el modelo y la omisión del valor por defecto. El siguiente ejemplo ordena a Mongoid no agregar un campo _id a la clase Albums:

class Album
  include Mongoid::Document
  field :name, type: String
  field :_id, type: Object
  embedded_in :band
end

En la clase Albums anterior, el campo _id no se agrega automáticamente. Sin un valor predeterminado, Mongoid no almacena el valor en la base de datos a menos que se proporcione uno en el modelo.

Borrar asociaciones incrustadas

Puede eliminar documentos secundarios de las asociaciones embeds_many mediante uno de los siguientes métodos:

• clear

• delete_all

• destroy_all

El clear método utiliza el operador $unset para eliminar una asociación incrustada completa del documento principal. El clear método no ejecuta ninguna destroy devolución de llamada. El siguiente ejemplo utiliza el clear método para eliminar todas las asociaciones incrustadas de la Band clase:

band = Band.find(...)
band.tours.clear

El delete_all método utiliza el operador $pullAll para eliminar documentos de una asociación incrustada. delete_all carga la asociación si aún no se ha cargado y, a continuación, elimina únicamente los documentos existentes en la aplicación. El delete_all método no ejecuta ninguna destroy devolución de llamada. El siguiente ejemplo utiliza el delete_all método para eliminar todos los Album documentos incrustados de la Band clase:

band = Band.find(...)
band.tours.delete_all

El destroy_all método también utiliza el operador $pullAll para eliminar documentos de una asociación incrustada. Además, ejecuta cualquier destroy devolución de llamada definida en los documentos asociados. El siguiente ejemplo utiliza el destroy_all método para eliminar todos los Album documentos incrustados de la Band clase:

band = Band.find(...)
band.tours.destroy_all

Extensiones

Las extensiones permiten añadir funcionalidades personalizadas a una asociación. Se puede definir una extensión en una asociación especificando un bloque en la definición de la asociación, como se muestra en el siguiente ejemplo:

class Band
  include Mongoid::Document
  embeds_many :albums do
    def find_by_name(name)
      where(name: name).first
    end
  end
end
band.albums.find_by_name("Omega") # returns album "Omega"

Nombres de asociaciones personalizadas

Puede usar la macro class_name para especificar un nombre de clase personalizado para una asociación. Esto resulta útil si desea asignar a la asociación un nombre distinto del de la clase. El siguiente ejemplo usa la macro class_name para especificar que una asociación incrustada llamada records representa la clase Album:

class Band
  include Mongoid::Document
  embeds_many :records, class_name: "Album"
end

Llaves personalizadas

De forma predeterminada, Mongoid utiliza el campo _id de la clase padre al buscar asociaciones. Puede especificar diferentes campos mediante las macros primary_key y foreign_key. El siguiente ejemplo especifica una nueva clave principal y una clave externa para la asociación albums en una clase Band:

class Band
  include Mongoid::Document
  field :band_id, type: String
  has_many :albums, primary_key: 'band_id', foreign_key: 'band_id_ref'
end
class Album
  include Mongoid::Document
  field :band_id_ref, type: String
  belongs_to :band, primary_key: 'band_id', foreign_key: 'band_id_ref'
end

Si especifica una asociación has_and_belongs_to_many, también puede usar las macros inverse_primary_key y inverse_foreign_key. La macro inverse_primary_key especifica el campo del modelo local que el modelo remoto utiliza para buscar los documentos. La macro inverse_foreign_key especifica el campo del modelo remoto que almacena los valores encontrados en inverse_primary_key.

El siguiente ejemplo especifica una nueva clave principal y externa para las clases Band y Members en una asociación has_and_belongs_to_many:

class Band
  include Mongoid::Document
  field :band_id, type: String
  field :member_ids, type: Array
  has_many :members, 
    primary_key: 'member_id', foreign_key: 'member_ids',
    inverse_primary_key: 'band_id', inverse_foreign_key: 'band_ids'
end
class Member
  include Mongoid::Document
  field :member_id, type: String
  field :band_ids, type: Array
  has_many :bands,
    primary_key: 'band_id', foreign_key: 'band_ids',
    inverse_primary_key: 'member_id', inverse_foreign_key: 'member_ids'
end

Ámbitos personalizados

Puede especificar el alcance de una asociación usando el parámetro scope. El parámetro scope determina los documentos que Mongoid considera parte de una asociación. Una asociación con alcance devuelve solo los documentos que cumplen las condiciones de alcance cuando se consultan. Puede establecer el scope en un Proc con una aridad de cero o en un Symbol que haga referencia a un alcance nombrado en el modelo asociado. El siguiente ejemplo establece ámbitos personalizados en las asociaciones de una clase Band:

class Band
  include Mongoid::Document
  has_many :albums, scope: -> { where(published: true) }
  
  # Uses a scope called "upcoming" on the Tour model
  has_many :tours, scope: :upcoming
end

Validaciones

Cuando Mongoid carga una asociación en memoria, utiliza la macro validates_associated de forma predeterminada para validar la presencia de sus hijos. Mongoid valida los hijos para los siguientes tipos de asociación:

• embeds_many

• embeds_one

• has_many

• has_one

• has_and_belongs_to_many

Puede desactivar este comportamiento de validación configurando la macro validate en false al definir la asociación, como se muestra en el siguiente ejemplo:

class Band
  include Mongoid::Document
  embeds_many :albums, validate: false
end

Polimorfismo

Mongoid admite polimorfismo en las clases hijas de asociaciones uno a uno y uno a muchos. Las asociaciones polimórficas permiten que una sola asociación contenga objetos de diferentes tipos de clase. Se puede definir una asociación polimórfica estableciendo la opción polymorphic en true en una asociación hija y añadiendo la opción as a la asociación padre. El siguiente ejemplo crea una asociación polimórfica en una clase Band:

class Tour
  include Mongoid::Document
  has_one :band, as: :featured
end
class Label
  include Mongoid::Document
  has_one :band, as: :featured
end
class Band
  include Mongoid::Document
  belongs_to :featured, polymorphic: true
end

En el ejemplo anterior, la asociación :featured en la clase Band puede contener un documento Label o Album.

has_and_belongs_to_many Las asociaciones no admiten polimorfismo.

class Band
  include Mongoid::Document
  identify_as 'artist'
  has_many :albums, as: :record
end

class Band
  include Mongoid::Document
  identify_as 'artist', 'group', 'troupe'
  has_many :albums, as: :record
end

Mongoid::ModelResolver.register_resolver Mongoid::ModelResolver.new, :mus
Mongoid::ModelResolver.register_resolver Mongoid::ModelResolver.new, :tool
module Music
  class Band
    include Mongoid::Document
    identify_as 'bnd', resolver: :mus
  end
end
module Tools
  class Band
    include Mongoid::Document
    identify_as 'bnd', resolver: :tool
  end
end

Comportamiento dependiente

Puede proporcionar opciones dependent a las asociaciones referenciadas para especificar cómo Mongoid gestiona los documentos asociados al eliminar un documento. Puede especificar las siguientes opciones:

• delete_all:Elimina todos los documentos secundarios sin ejecutar ninguna devolución de llamada de modelo.

• destroy:Elimina los documentos secundarios y ejecuta todas las devoluciones de llamadas del modelo.

• nullify: Establece la clave externa de los documentos secundarios en nil. El documento secundario podría quedar huérfano si solo el documento principal hace referencia a él.

• restrict_with_exception: Genera una excepción si el documento secundario no está vacío.

• restrict_with_error:Cancela la operación y devuelve false si el documento secundario no está vacío.

Si no especifica ninguna opción dependent, Mongoid deja el documento secundario sin cambios al eliminar el documento principal. El documento secundario sigue haciendo referencia al documento principal eliminado, y si solo se hace referencia a través del principal, queda huérfano.

El siguiente ejemplo especifica dependent opciones en la clase Band:

class Band
  include Mongoid::Document
  has_many :albums, dependent: :delete_all
  belongs_to :label, dependent: :nullify
end

Guardar automáticamente asociaciones referenciadas

De forma predeterminada, Mongoid no guarda automáticamente los documentos asociados de asociaciones no incrustadas al guardar el documento principal. Esto puede generar referencias colgantes a documentos inexistentes.

Puede usar la opción autosave en una asociación referenciada para guardar automáticamente los documentos asociados al guardar el documento principal. El siguiente ejemplo crea una clase Band con una clase Album asociada y especifica la opción autosave:

class Band
  include Mongoid::Document
  
  has_many :albums
end
class Album
  include Mongoid::Document
  
  belongs_to :band, autosave: true
end
band = Band.new
album = Album.create!(band: band)
# The band is persisted at this point.

No se necesita especificar la opción autosave para asociaciones incrustadas porque Mongoid guarda los documentos incrustados en el documento principal.

Autoconstrucción

Puede agregar la opción autobuild a asociaciones uno a uno, como has_one y embeds_one, para instanciar automáticamente un nuevo documento al acceder a una asociación nil. El siguiente ejemplo agrega la opción autobuild a una asociación en la clase Band:

class Band
  include Mongoid::Document
  embeds_one :label, autobuild: true
  has_one :producer, autobuild: true
end

Contacto

Cuando Mongoid accede a un documento, actualiza su updated_at campo con la fecha y hora actuales. Puede añadir la touch opción a cualquier belongs_to asociación para garantizar que Mongoid acceda al documento principal siempre que se actualice el documento secundario. El siguiente ejemplo añade la touch opción a una asociación en la Band clase:

class Band
  include Mongoid::Document
  field :name
  belongs_to :label, touch: true
end

También puede usar la opción touch para especificar otro campo en la asociación principal, como una cadena o un símbolo. Al acceder a la asociación principal, Mongoid establece tanto el campo updated_at como el campo especificado con la fecha y hora actuales.

El siguiente ejemplo le indica a Mongoid que toque el campo bands_updated_at:

class Band
  include Mongoid::Document
  belongs_to :label, touch: :bands_updated_at
end

Caché de contador

Puede usar la opción counter_cache para almacenar el número de objetos que pertenecen a un campo asociado. Al especificar esta opción, Mongoid almacena un atributo adicional en los modelos asociados para almacenar el recuento. Por ello, debe especificar el módulo Mongoid::Attributes::Dynamic en las clases asociadas.

El siguiente ejemplo agrega la opción counter_cache a una clase Band y especifica Mongoid::Attributes::Dynamic en una clase Label:

class Band
  include Mongoid::Document
  belongs_to :label, counter_cache: true
end
class Label
  include Mongoid::Document
  include Mongoid::Attributes::Dynamic
  has_many :bands
end

Atributos

Todas las asociaciones contienen atributos que almacenan información sobre el documento asociado. Las asociaciones contienen los siguientes atributos:

• _target:El documento o documentos proxy

• _base:El documento en el que se define la asociación

• _association:Información sobre la asociación

El siguiente ejemplo accede a cada uno de los atributos anteriores:

class Band
  include Mongoid::Document
  embeds_many :songs
end
Band.songs = [ song ]
Band.songs._target # returns [ song ]
Band.songs._base # returns band
Band.songs._association # returns the association metadata

La siguiente tabla muestra la información almacenada en el atributo _association: