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:

Project.create({ id: 11 }).then(function (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(function (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(newAssociation(s): Model[] \| Model \| string[] \| string \| number[] \| Number, options: Object): Promise Associate one ore several rows with `this`.
public	count(options: Object): Promise<Integer> Count everything currently associated with this, using an optional where clause.
public	create(values: Object, options: Object): Promise Create a new instance of the associated model and associate it with this.
public	get(options: Object): Promise<Array<Model>> Get everything currently associated with this, using an optional where clause.
public	has(instance(s): Model[] \| Model \| string[] \| String \| number[] \| Number, options: Object): Promise<boolean> Check if one or more instance(s) are associated with this.
public	remove(oldAssociated: Model \| String \| Number, options: Object): Promise Un-associate one or more instance(s).
public	set(newAssociations: Array<Model\|String\|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(newAssociation(s): Model[] | Model | string[] | string | number[] | Number, options: Object): Promise source

Associate one ore several rows with this.

Params:

Name	Type	Attribute	Description
newAssociation(s)	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(options: Object): Promise<Integer> source

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

Params:

Name	Type	Attribute	Description
options	Object	optional
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<Integer>

public create(values: Object, options: Object): Promise source

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

Params:

Name	Type	Attribute	Description
values	Object	optional
options	Object	optional	Options passed to create and add
options.through	Object	optional	Additional attributes for the join table

Return:

Promise

public get(options: Object): Promise<Array<Model>> source

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

Params:

Name	Type	Attribute	Description
options	Object	optional
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.findAll for a full explanation of options

public has(instance(s): 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
instance(s)	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(oldAssociated: Model | String | Number, options: Object): Promise source

Un-associate one or more instance(s).

Params:

Name	Type	Attribute	Description
oldAssociated	Model \| String \| 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(newAssociations: Array<Model|String|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
newAssociations	Array<Model\|String\|Number>	optional	An array of persisted instances or primary key of instances to associate with this. Pass `null` or `undefined` to remove all associations.
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