- Schema Configuration >
- Inheritance
Inheritance¶
On this page
Mongoid supports inheritance in both top level and embedded documents. When a child document inherits from a parent document, the parent document’s fields, associations, validations and scopes are copied to the child document.
In the above example, Canvas
, Browser
and Firefox
will all save in the canvases
collection. An additional attribute _type
is stored in order to make sure when loaded
from the database the correct document is returned. This also holds true for the embedded
documents Circle
, Rectangle
, and Shape
.
Note
When searching for a Circle
, the query will only return documents in the shape collection
where the _type
(or whatever the discriminator key was set to) field has the value Circle
(or
whatever the discriminator value was set to), all other discriminator values will be considered an object
of the Shape class.
Similarly, when querying by parent classes (Canvas
in this example), any documents in the collection
that do not have a discriminator value, or whose discriminator value does not map to either the parent
or any of its descendants, will be returned as instances of the parent class.
Changing the Discriminator Key¶
Mongoid supports changing the discriminator key from the default _type
. There are a few
cases where one might want to do this:
- For optimization: The user might want to use a shorter key like
_t
. - When trying to work with an existing system: It’s possible the user is working with an existing system or dataset that has predefined keys.
There are two ways to change the discriminator key, on the class level and on the global level.
To change the discriminator key on the class level the user can set it directly on the parent class using
the discriminator_key=
method.
Take the above example:
Here a call to the discriminator_key=
setter was added to the parent class. Now, on
creation of a Rectangle or Circle, a shape_type
field will be added.
Note that the discriminator key can only be modified in the parent class, and an error will be raised if trying to set it on the child class.
If the discriminator key is changed after the child class is created, a new field is added with the new discriminator key value, and the old field will remain unchanged. For example:
In this case, on creation of a Rectangle or Circle, there will be both a shape_type
and a _type
field that both default to Rectangle
or Circle
respectively.
The discriminator key can also be set on the global level. Meaning, all classes will
use the globally set discriminator key instead of _type
. Take the above example:
After setting the global discriminator key, all classes will use _the_type
as
the discriminator key and will not contain a _type
field.
Note that when defining the discriminator key on the global level, it must be set before the
child class is defined for the child class to use that global value.
On the global level, however, if the user does not set the discriminator key before defining a child
class, the discriminator field will use the default _type
and not the new global setting in
that child class.
Changing the Discriminator Value¶
Mongoid also supports changing the discriminator value from the default value, which is the class name.
One can change the discriminator value by using the discriminator_value=
method on that specific class.
Take the above example:
Here, a call to the discriminator_value=
setter was added to Circle
.
Now, on creation of a Circle
, the document will contain a field with the key _type
(or whatever the discriminator_key
was changed to)
and the value “round thing.”
Note
Because the discriminator value overrides are declared in child classes,
the child classes potentially found by a query must be loaded prior to
sending that query. In the above example, the Circle
class definition
must be loaded when querying on Shape
if the returned documents could
potentially be instances of Circle
(since autoloading wouldn’t resolve
"round thing"
to Circle
).
Querying Subclasses¶
Querying for subclasses is handled in the normal manner, and although the documents are all in the same collection, queries will only return documents of the correct type, similar to Single Table Inheritance in ActiveRecord.
Associations¶
You can add any type of subclass to a has one or has many association, through either normal setting or through the build and create methods on the association: