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:

Project.create({ id: 11 }).then(project => {
  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.

user.getProjects().then(projects => {
  let 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	add(sourceInstance: Model, newInstances: Model \| Model[] \| string[] \| string \| number[] \| number, options: Object): Promise Associate one or several rows with source instance.
public	count(instance: Model, options: Object): Promise<number> Count everything currently associated with this, using an optional where clause.
public	create(sourceInstance: Model, values: Object, options: Object): Promise Create a new instance of the associated model and associate it with this.
public	get(instance: Model, options: Object): Promise<Array<Model>> Get everything currently associated with this, using an optional where clause.
public	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	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 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 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 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 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

Return:

Promise<Array<Model>>

See:

Model for a full explanation of options

public 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 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