API Reference Source
public class | source

BelongsToMany

Extends:

Association → BelongsToMany

Many-to-many association with a join table.

When the join table has additional attributes, these can be passed in the options object:

UserProject = sequelize.define('user_project', {
  role: Sequelize.STRING
});
User.belongsToMany(Project, { through: UserProject });
Project.belongsToMany(User, { through: UserProject });
// through is required!

user.addProject(project, { through: { role: 'manager' }});

All methods allow you to pass either a persisted instance, its primary key, or a mixture:

const project = await Project.create({ id: 11 });
await user.addProjects([project, 12]);

If you want to set several target instances, but with different attributes you have to set the attributes on the instance, using a property with the name of the through model:

p1.UserProjects = {
  started: true
}
user.setProjects([p1, p2], { through: { started: false }}) // The default value is false, but p1 overrides that.

Similarly, when fetching through a join table with custom attributes, these attributes will be available as an object with the name of the through model.

const projects = await user.getProjects();
const p1 = projects[0];
p1.UserProjects.started // Is this project started yet?
})

In the API reference below, add the name of the association to the method, e.g. for User.belongsToMany(Project) the getter will be user.getProjects().

See:

Method Summary

Public Methods
public

async add(sourceInstance: Model, newInstances: Model | Model[] | string[] | string | number[] | number, options: object): Promise

Associate one or several rows with source instance.

public

async count(instance: Model, options: object): Promise<number>

Count everything currently associated with this, using an optional where clause.

public

async create(sourceInstance: Model, values: object, options: object): Promise

Create a new instance of the associated model and associate it with this.

public

async get(instance: Model, options: object): Promise<Array<Model>>

Get everything currently associated with this, using an optional where clause.

public

async has(sourceInstance: Model, instances: Model | Model[] | string[] | string | number[] | number, options: object): Promise<boolean>

Check if one or more instance(s) are associated with this.

public

remove(sourceInstance: Model, oldAssociatedObjects: Model | Model[] | string | string[] | number | number[], options: object): Promise

Un-associate one or more instance(s).

public

async set(sourceInstance: Model, newAssociatedObjects: Model | Model[] | string[] | string | number[] | number, options: object): Promise

Set the associated models by passing an array of instances or their primary keys.

Inherited Summary

From class Association
public

The type of the association.

public
public

Public Methods

public async add(sourceInstance: Model, newInstances: Model | Model[] | string[] | string | number[] | number, options: object): Promise source

Associate one or several rows with source instance. It will not un-associate any already associated instance that may be missing from newInstances.

Params:

NameTypeAttributeDescription
sourceInstance Model

source instance to associate new instances with

newInstances Model | Model[] | string[] | string | number[] | number
  • optional

A single instance or primary key, or a mixed array of persisted instances or primary keys

options object
  • optional

Options passed to through.findAll, bulkCreate and update

options.validate object
  • optional

Run validation for the join model.

options.through object
  • optional

Additional attributes for the join table.

Return:

Promise

public async count(instance: Model, options: object): Promise<number> source

Count everything currently associated with this, using an optional where clause.

Params:

NameTypeAttributeDescription
instance Model

instance

options object
  • optional

find options

options.where object
  • optional

An optional where clause to limit the associated models

options.scope string | boolean
  • optional

Apply a scope on the related model, or remove its default scope by passing false

Return:

Promise<number>

public async create(sourceInstance: Model, values: object, options: object): Promise source

Create a new instance of the associated model and associate it with this.

Params:

NameTypeAttributeDescription
sourceInstance Model

source instance

values object
  • optional

values for target model

options object
  • optional

Options passed to create and add

options.through object
  • optional

Additional attributes for the join table

Return:

Promise

public async get(instance: Model, options: object): Promise<Array<Model>> source

Get everything currently associated with this, using an optional where clause.

Params:

NameTypeAttributeDescription
instance Model

instance

options object
  • optional

find options

options.where object
  • optional

An optional where clause to limit the associated models

options.scope string | boolean
  • optional

Apply a scope on the related model, or remove its default scope by passing false

options.schema string
  • optional

Apply a schema on the related model

options.through.where object
  • optional

An optional where clause applied to through model (join table)

options.through.paranoid boolean
  • optional
  • default: true

If true, only non-deleted records will be returned from the join table. If false, both deleted and non-deleted records will be returned. Only applies if through model is paranoid

Return:

Promise<Array<Model>>

See:

  • Model for a full explanation of options

public async has(sourceInstance: Model, instances: Model | Model[] | string[] | string | number[] | number, options: object): Promise<boolean> source

Check if one or more instance(s) are associated with this. If a list of instances is passed, the function returns true if all instances are associated

Params:

NameTypeAttributeDescription
sourceInstance Model

source instance to check for an association with

instances Model | Model[] | string[] | string | number[] | number
  • optional

Can be an array of instances or their primary keys

options object
  • optional

Options passed to getAssociations

Return:

Promise<boolean>

public remove(sourceInstance: Model, oldAssociatedObjects: Model | Model[] | string | string[] | number | number[], options: object): Promise source

Un-associate one or more instance(s).

Params:

NameTypeAttributeDescription
sourceInstance Model

instance to un associate instances with

oldAssociatedObjects Model | Model[] | string | string[] | number | number[]
  • optional

Can be an Instance or its primary key, or a mixed array of instances and primary keys

options object
  • optional

Options passed to through.destroy

Return:

Promise

public async set(sourceInstance: Model, newAssociatedObjects: Model | Model[] | string[] | string | number[] | number, options: object): Promise source

Set the associated models by passing an array of instances or their primary keys. Everything that it not in the passed array will be un-associated.

Params:

NameTypeAttributeDescription
sourceInstance Model

source instance to associate new instances with

newAssociatedObjects Model | Model[] | string[] | string | number[] | number
  • optional

A single instance or primary key, or a mixed array of persisted instances or primary keys

options object
  • optional

Options passed to through.findAll, bulkCreate, update and destroy

options.validate object
  • optional

Run validation for the join model

options.through object
  • optional

Additional attributes for the join table.

Return:

Promise