Relationships

Relationships

What is a relationship?

A relationship is a connection between two collections.

Relationships are visible and actionable in Forest Admin:

• hasMany (1)

• belongsTo or hasOne(2)

If you installed Forest Admin within a Rails app, then all the relationships defined in your ActiveRecord models are supported out of the box. Check the official Rails documentation to create new ones.

If you installed Forest Admin directly on a database, then most relationships should have been automatically generated. However, depending on your database nature and structure, you may have to add some manually.

Adding relationships (databases only)

Depending on your database type, your models will have been generated in Sequelize (for SQL databases) or Mongoose (for Mongo databases).

Below are some simple snippets showing you how to add relationships. However, should you want to dig deeper, please refer to the appropriate framework's documentations:

• Sequelize's documentation on adding relationships in your models (SQL)

• Mongoose's documentation on adding relationships in your models (Mongodb)

Adding a hasMany relationship

In our Live demo, a customer can have multiple orders. In that case, we have to use a hasMany relationship.

SQL

Mongodb

/models/customers.js

Copy

module.exports = (sequelize, DataTypes) => {
  const Customer = sequelize.define('customers',
    ...
  );

  Customer.associate = (models) => {
    Customer.hasMany(models.orders);
  };

  return Customer;
};

/models/customers.js

Copy

module.exports = (mongoose, Mongoose) => {
  const schema = Mongoose.Schema({
    ...
    'orders': [{ type: Mongoose.Schema.Types.ObjectId, ref: 'orders' }],
    ...
  }, {
    timestamps: true,
  });

  return mongoose.model('customers', schema, 'customers');
};

Note that for orders to be displayed within the related data section of your customer, they have to be populated in your database. For instance:

Adding a hasOne relationship

In case of a one-to-one relationship between 2 collections, the opposite of a belongsTo relationship is a hasOne relationship. Taking the same example as before, the opposite of "an address belongsTo a customer" is simply "a customerhasOne address".

module.exports = (sequelize, DataTypes) => {
  const Customer = sequelize.define('customers',
    ...
  );

  Customer.associate = (models) => {
    Customer.hasOne(models.addresses);
  };

  return Customer;
};

module.exports = (mongoose, Mongoose) => {
  const schema = Mongoose.Schema({
    ...
    'address': { type: Mongoose.Schema.Types.ObjectId, ref: 'addresses' },
    ...
  }, {
    timestamps: true,
  });

  return mongoose.model('customers', schema, 'customers');
};

Adding a belongsTo relationship

On our Live Demo example, the Address model has a foreignKey customer_id that points to the Customer. In other words, an addressbelongsTo a customer.

module.exports = (sequelize, DataTypes) => {
  const Address = sequelize.define('addresses',
    ...
  );

  Address.associate = (models) => {
    Address.belongsTo(models.customers);
  };

  return Address;
};

module.exports = (mongoose, Mongoose) => {
  const schema = Mongoose.Schema({
    ...
    'customer_id': { type: Mongoose.Schema.Types.ObjectId, ref: 'customers' },
    ...
  }, {
    timestamps: true,
  });

  return mongoose.model('addresses', schema, 'addresses');
};

Declaring a foreign key (SQL only)

It's possible that your tables are linked in an unusual way (using names instead of ids for instance). In that case, adding the above code will not suffice to add the belongsTo relationship. Even though we recommend you modify your database structure to stay within foreign key conventions (pointing to an id), there is a way to specify how your tables are linked.

If the field fk_customername of a table Address points to the field name of a table Customer, add the following:

...
Address.associate = (models) => {
  Address.belongsTo(models.customers, {
    foreignKey: 'fk_companyname'
    targetKey: 'name'
  });
};
...

Adding a belongsToMany relationship (SQL only)

belongsToMany association is often used to set up a many-to-many relationship with another model. For this example, we will consider the models Projects and Users. A user can be part of many projects, and one project has many users. The junction table that will keep track of the associations will be called userProjects, which will contain the foreign keys projectId and userId.

...
UserProjects.associate = (models) => {
  UserProjects.belongsTo(models.projects, {
    foreignKey: {
      name: 'projectIdKey',
      field: 'projectId',
    },
    as: 'project',
  });
  UserProjects.belongsTo(models.users, {
    foreignKey: {
      name: 'userIdKey',
      field: 'userId',
    },
    as: 'user',
  });
};
...

...
Users.associate = (models) => {
  Users.belongsToMany(models.projects, {
    through: 'userProjects',
    foreignKey: 'userId',
    otherKey: 'projectId',
  });
};
...

...
Projects.associate = (models) => {
  Projects.belongsToMany(models.users, {
    through: 'userProjects',
    foreignKey: 'projectId',
    otherKey: 'userId',
  });
};
...

Relationship generation rules

Forest Admin automatically generates most relationships, according to the below rules: