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:

Model.belongsToMany

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	associationType: string The type of the association.
public	source: Model
public	target: Model

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:

Name	Type	Attribute	Description
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:

Name	Type	Attribute	Description
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:

Name	Type	Attribute	Description
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:

Name	Type	Attribute	Description
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:

Name	Type	Attribute	Description
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:

Name	Type	Attribute	Description
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:

Name	Type	Attribute	Description
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