Overview

Note:

This relation best works with databases that support foreign keyconstraints (SQL).Using this relation with NoSQL databases will result in unexpected behavior,such as the ability to create a relation with a model that does not exist. We are working on a solution to better handle this. It is fine to use this relation with NoSQL databases for purposes such as navigatingrelated models, where the referential integrity is not critical.

A belongsTo relation denotes a many-to-one connection of a model to anothermodel through referential integrity. The referential integrity is enforced by aforeign key constraint on the source model which usually references a primarykey on the target model. This relation indicates that each instance of thedeclaring or source model belongs to exactly one instance of the target model.For example, in an application with customers and orders, an order alwaysbelongs to exactly one customer as illustrated in the diagram below.

The diagram shows the declaring (source) model Order has propertycustomerId as the foreign key to reference the target model Customer’sprimary key id.

To add a belongsTo relation to your LoopBack application and expose itsrelated routes, you need to perform the following steps:

• Add a property to your source model to define the foreign key.
• Modify the source model repository class to provide an accessor function forobtaining the target model instance.
• Call the accessor function in your controller methods.

Defining a belongsTo Relation

This section describes how to define a belongsTo relation at the model levelusing the @belongsTo decorator to define the constraining foreign key.

/src/models/order.model.ts

import {belongsTo, Entity, model, property} from '@loopback/repository';
import {Customer} from './customer.model';
@model()
export class Order extends Entity {
  @property({
    type: 'number',
    id: true,
  })
  id: number;
  @belongsTo(() => Customer)
  customerId: number;
  @property({type: 'number'})
  quantity: number;
  constructor(data: Partial<Order>) {
    super(data);
  }
}
export interface OrderRelations {
  // describe navigational properties here
}
export type OrderWithRelations = Order & OrderRelations;

The definition of the belongsTo relation is inferred by using the @belongsTodecorator. The decorator takes in a function resolving the target model classconstructor and designates the relation type. It also calls property() toensure that the decorated property is correctly defined.

A usage of the decorator with a custom primary key of the target model for theabove example is as follows:

class Order extends Entity {
  // constructor, properties, etc.
  @belongsTo(() => Customer, {keyTo: 'pk'})
  customerId: number;
}
export interface OrderRelations {
  customer?: CustomerWithRelations;
}

Configuring a belongsTo relation

The configuration and resolution of a belongsTo relation takes place at therepository level. Once belongsTo relation is defined on the source model, thenthere are a couple of steps involved to configure it and use it. On the sourcerepository, the following are required:

• In the constructor of your source repository class, useDependency Injection to receive a getter functionfor obtaining an instance of the target repository. Note: We need a getterfunction, accepting a string repository name instead of a repositoryconstructor, or a repository instance, in order to break a cyclic dependencybetween a repository with a belongsTo relation and a repository with thematching hasMany relation.
• Declare a property with the factory function typeBelongsToAccessor<targetModel, typeof sourceModel.prototype.id> on thesource repository class.
• call the createBelongsToAccessorFor function in the constructor of thesource repository class with the relation name (decorated relation property onthe source model) and target repository instance and assign it the propertymentioned above.The following code snippet shows how it would look like:

/src/repositories/order.repository.ts

import {Getter, inject} from '@loopback/context';
import {
  BelongsToAccessor,
  DefaultCrudRepository,
  juggler,
  repository,
} from '@loopback/repository';
import {Customer, Order, OrderRelations} from '../models';
import {CustomerRepository} from '../repositories';
export class OrderRepository extends DefaultCrudRepository<
  Order,
  typeof Order.prototype.id,
  OrderRelations
> {
  public readonly customer: BelongsToAccessor<
    Customer,
    typeof Order.prototype.id
  >;
  constructor(
    @inject('datasources.db') protected db: juggler.DataSource,
    @repository.getter('CustomerRepository')
    customerRepositoryGetter: Getter<CustomerRepository>,
  ) {
    super(Order, db);
    this.customer = this.createBelongsToAccessorFor(
      'customer',
      customerRepositoryGetter,
    );
  }
}

BelongsToAccessor is a function accepting the primary key (id) of a sourcemodel instance (e.g. order.id) and returning back the related target modelinstance (e.g. a Customer the order belongs to). See alsoAPI Docs

Using BelongsToAccessor in a controller

The same pattern used for ordinary repositories to expose their CRUD APIs viacontroller methods is employed for belongsTo relation too. Once the belongsTorelation has been defined and configured, a new controller method can expose theaccessor API as a new endpoint.

src/controllers/order.controller.ts

import {repository} from '@loopback/repository';
import {get} from '@loopback/rest';
import {Customer, Order} from '../models/';
import {OrderRepository} from '../repositories/';
export class OrderController {
  constructor(
    @repository(OrderRepository) protected orderRepository: OrderRepository,
  ) {}
  // (skipping regular CRUD methods for Order)
  @get('/orders/{id}/customer')
  async getCustomer(
    @param.path.number('id') orderId: typeof Order.prototype.id,
  ): Promise<Customer> {
    return this.orderRepository.customer(orderId);
  }
}

In LoopBack 3, the REST APIs for relations were exposed using static methodswith the name following the pattern {methodName}{relationName} (e.g.Order.get__customer). While we recommend to create a new controller for eachhasMany relation in LoopBack 4, we also think it’s best to use the main CRUDcontroller as the place where to explose belongsTo API.

Handling recursive relations

Given an e-commerce system has many Category, each Category may have severalsub-categories, and may belong to 1 parent-category.

export class Category extends Entity {
  @property({
    type: 'number',
    id: true,
    generated: true,
  })
  id?: number;
  @hasMany(() => Category, {keyTo: 'parentId'})
  categories?: Category[];
  @belongsTo(() => Category)
  parentId?: number;
  constructor(data?: Partial<Category>) {
    super(data);
  }
}
export interface CategoryRelations {
  categories?: CategoryWithRelations[];
  parent?: CategoryWithRelations;
}
export type CategoryWithRelations = Category & CategoryRelations;

The CategoryRepository must be declared like below

export class CategoryRepository extends DefaultCrudRepository<
  Category,
  typeof Category.prototype.id,
  CategoryRelations
> {
  public readonly parent: BelongsToAccessor<
    Category,
    typeof Category.prototype.id
  >;
  public readonly categories: HasManyRepositoryFactory<
    Category,
    typeof Category.prototype.id
  >;
  constructor(@inject('datasources.db') dataSource: DbDataSource) {
    super(Category, dataSource);
    this.categories = this.createHasManyRepositoryFactoryFor(
      'categories',
      Getter.fromValue(this),
    );
    this.parent = this.createBelongsToAccessorFor(
      'parent',
      Getter.fromValue(this),
    ); // for recursive relationship
  }
}

DO NOT declare@repository.getter(CategoryRepository) protected categoryRepositoryGetter: Getter<CategoryRepository>on constructor to avoid “Circular dependency” error (seeissue #2118)