Skip to main content
Version: Next

Separating Concerns using Embeddables

Support for embeddables was added in version 4.0

Embeddables are classes which are not entities themselves, but are embedded in entities and can also be queried. You'll mostly want to use them to reduce duplication or separating concerns. Value objects such as date range or address are the primary use case for this feature.

Embeddables needs to be discovered just like regular entities, don't forget to add them to the list of entities when initializing the ORM.

Embeddables can contain properties with basic @Property() mapping, nested @Embedded() properties or arrays of @Embedded() properties. From version 5.0 you can also use @ManyToOne() properties.

For the purposes of this tutorial, let's assume that you have a User class in your application, and you would like to store an address in the User class. The Address class will be modeled as an embeddable instead of simply adding the respective columns to the User class.

import { defineEntity, p } from '@mikro-orm/core';

const UserSchema = defineEntity({
  name: 'User',
  properties: {
    id: p.integer().primary(),
    address: () => p.embedded(Address),
  },
});


const AddressSchema = defineEntity({
  name: 'Address',
  embeddable: true,
  properties: {
    street: p.string(),
    postalCode: p.string(),
    city: p.string(),
    country: p.string(),
  },
});

export class Address extends AddressSchema.class {}
AddressSchema.setClass(Address);

export class User extends UserSchema.class {}
UserSchema.setClass(User);

When using ReflectMetadataProvider, you might need to provide the class in decorator options: @Embedded(() => Address) or @Embedded({ entity: () => Address }).

In terms of your database schema, MikroORM will automatically inline all columns from the Address class into the table of the User class, just as if you had declared them directly there.

Initializing embeddables​

In case all fields in the embeddable are nullable, you might want to initialize the embeddable, to avoid getting a null value instead of the embedded object.

./entities/User.ts
const UserSchema = defineEntity({
  name: 'User',
  properties: {
    id: p.integer().primary(),
    address: () => p.embedded(Address)
      .onCreate(() => new Address()),
  },
});

export class User extends UserSchema.class {}
UserSchema.setClass(User);

Column Prefixing​

By default, MikroORM names your columns by prefixing them, using the value object name.

Following the example above, your columns would be named as address_street, address_postal_code...

You can change this behaviour to meet your needs by changing the prefix attribute in the @Embedded() notation.

The following example shows you how to set your prefix to myPrefix_:

./entities/User.ts
const UserSchema = defineEntity({
  name: 'User',
  properties: {
    id: p.integer().primary(),
    address: () => p.embedded(Address).prefix('myPrefix_')
  },
});

export class User extends UserSchema.class {}
UserSchema.setClass(User);

You can also decide more precisely how the column name is determined with an explicit prefix. With the example below:

  • relative mode (default) concatenates the prefix with its parent's prefix (if any), naming them contact_addr2_city, contact_addr2_street, ...
  • absolute mode sets the prefix at the beginning of the column, naming them addr_city, addr_street, ...
./entities/User.ts
const ContactSchema = defineEntity({
  name: 'Contact',
  embeddable: true,
  properties: {
    address: () => p.embedded(Address).prefix('addr_').prefixMode('absolute'),
    address2: () => p.embedded(Address).prefix('addr2_').prefixMode('relative'),
  },
});


const UserSchema = defineEntity({
  name: 'User',
  properties: {
    id: p.integer().primary(),
    contact: () => p.embedded(Contact),
  },
});

export class Contact extends ContactSchema.class {}
ContactSchema.setClass(Contact);

export class User extends UserSchema.class {}
UserSchema.setClass(User);

The default behavior can be overridden in the ORM configuration:

MikroORM.init({
  embeddables: {
    prefixMode: 'absolute', // defaults to `true`
  }, 
})

To have MikroORM drop the prefix and use the value object's property name directly, set prefix: false:

./entities/User.ts
const UserSchema = defineEntity({
  name: 'User',
  properties: {
    id: p.integer().primary(),
    address: () => p.embedded(Address).prefix(false),
  },
});

export class User extends UserSchema.class {}
UserSchema.setClass(User);

Storing embeddables as objects​

You can also store the embeddable as an object instead of inlining its properties to the owning entity.

./entities/User.ts
const UserSchema = defineEntity({
  name: 'User',
  properties: {
    id: p.integer().primary(),
    address: () => p.embedded(Address).object(),
  },
});

export class User extends UserSchema.class {}
UserSchema.setClass(User);

In SQL drivers, this will use a JSON column to store the value.

Only MySQL and PostgreSQL drivers support searching by JSON properties currently.

This part of documentation is highly inspired by doctrine tutorial as the behaviour here is pretty much the same.

Array of embeddables​

Embedded arrays are always stored as JSON. It is possible to use them inside nested embeddables.

./entities/User.ts
const UserSchema = defineEntity({
  name: 'User',
  properties: {
    id: p.integer().primary(),
    addresses: () => p.embedded(Address).array().onCreate(() => []),
  },
});

export class User extends UserSchema.class {}
UserSchema.setClass(User);

Querying array embeddables​

You can query properties of embedded array elements directly. MikroORM will automatically generate the appropriate SQL using platform-specific JSON array iteration (e.g. jsonb_array_elements for PostgreSQL, json_table for MySQL/MariaDB, json_each for SQLite).

When multiple property conditions are specified, they must all match the same array element (similar to MongoDB's $elemMatch):

// find users who have an address in London
const users = await em.find(User, {
  addresses: { city: 'London' },
});

// find users who have an address in London, UK (same element must match both)
const users = await em.find(User, {
  addresses: { city: 'London', country: 'UK' },
});

// operators work too
const users = await em.find(User, {
  addresses: { number: { $gt: 5 } },
});

// $or/$and within the array element scope
const users = await em.find(User, {
  addresses: { $or: [{ city: 'London' }, { city: 'Paris' }] },
});

// $not finds rows where NO element matches the condition (NOT EXISTS)
const users = await em.find(User, {
  addresses: { $not: { city: 'London' } },
});

// combine $not with positive conditions:
// at least one element in Paris AND no element in London
const users = await em.find(User, {
  addresses: { $not: { city: 'London' }, city: 'Paris' },
});

Note: Top-level $not uses NOT EXISTS semantics (no array element matches). Inside $or/$and, $not applies element-level negation instead (the current element does not match).

Array-level operators like $contains, $contained, and $overlap continue to work as before, operating on the array column as a whole.

Nested embeddables​

You can also nest embeddables, both in inline mode and object mode:

./entities/User.ts
const UserSchema = defineEntity({
  name: 'User',
  properties: {
    id: p.integer().primary(),
    name: p.string(),
    address: () => p.embedded(Address),
  },
});


const ProfileSchema = defineEntity({
  name: 'Profile',
  embeddable: true,
  properties: {
    username: p.string(),
    identity: () => p.embedded(Identity),
  },
});

export class Profile extends ProfileSchema.class {}
ProfileSchema.setClass(Profile);

const IdentitySchema = defineEntity({
  name: 'Identity',
  embeddable: true,
  properties: {
    email: p.string(),
  },
});

export class Identity extends IdentitySchema.class {}
IdentitySchema.setClass(Identity);

export class User extends UserSchema.class {}
UserSchema.setClass(User);

Polymorphic embeddables​

It is also possible to use polymorphic embeddables. This means you can define multiple classes for a single embedded property and the right one will be used based on the discriminator column, similar to how single table inheritance work.

import { defineEntity, p } from '@mikro-orm/core';

export enum AnimalType {
  CAT,
  DOG,
}

const AnimalSchema = defineEntity({
  name: 'Animal',
  embeddable: true,
  abstract: true,
  discriminatorColumn: 'type',
  properties: {
    type: p.enum(() => AnimalType),
    name: p.string(),
  },
});

export class Animal extends AnimalSchema.class {}
AnimalSchema.setClass(Animal);

const CatSchema = defineEntity({
  name: 'Cat',
  embeddable: true,
  extends: Animal,
  discriminatorValue: AnimalType.CAT,
  properties: {
    canMeow: p.boolean().nullable(),
  },
});

export class Cat extends CatSchema.class {}
CatSchema.setClass(Cat);

const DogSchema = defineEntity({
  name: 'Dog',
  embeddable: true,
  extends: Animal,
  discriminatorValue: AnimalType.DOG,
  properties: {
    canBark: p.boolean().nullable(),
  },
});

export class Dog extends DogSchema.class {}
DogSchema.setClass(Dog);

const OwnerSchema = defineEntity({
  name: 'Owner',
  properties: {
    id: p.integer().primary(),
    name: p.string(),
    pet: () => p.embedded([Cat, Dog]),
  },
});

export class Owner extends OwnerSchema.class {}
OwnerSchema.setClass(Owner);