Home Reference Source RepositoryJoin us on Slack
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:

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
public

Public Methods

public add(newAssociation(s): Model[] | Model | string[] | string | number[] | Number, options: Object): Promise source

Associate one ore several rows with this.

Params:

NameTypeAttributeDescription
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:

NameTypeAttributeDescription
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:

NameTypeAttributeDescription
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:

NameTypeAttributeDescription
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:

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:

NameTypeAttributeDescription
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:

NameTypeAttributeDescription
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:

NameTypeAttributeDescription
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