static/v5/class/lib/associations/belongs-to-many.js~BelongsToMany.html
publicclass| source
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().
| 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.
| |
| From class Association | | public |
The type of the association.
| | | public |
| | | public |
| |
Associate one or several rows with source instance. It will not un-associate any already associated instance that may be missing from newInstances.
| Name | Type | Attribute | Description | | sourceInstance | Model | |
source instance to associate new instances with
| | newInstances | Model | Model[] | string[] | string | number[] | number |
|
A single instance or primary key, or a mixed array of persisted instances or primary keys
| | options | Object |
|
Options passed to through.findAll, bulkCreate and update
| | options.validate | Object |
|
Run validation for the join model.
| | options.through | Object |
|
Additional attributes for the join table.
|
| Promise |
Count everything currently associated with this, using an optional where clause.
| Name | Type | Attribute | Description | | instance | Model | |
instance
| | options | Object |
|
find options
| | options.where | Object |
|
An optional where clause to limit the associated models
| | options.scope | string | boolean |
|
Apply a scope on the related model, or remove its default scope by passing false
|
Create a new instance of the associated model and associate it with this.
| Name | Type | Attribute | Description | | sourceInstance | Model | |
source instance
| | values | Object |
|
values for target model
| | options | Object |
|
Options passed to create and add
| | options.through | Object |
|
Additional attributes for the join table
|
| Promise |
Get everything currently associated with this, using an optional where clause.
| Name | Type | Attribute | Description | | instance | Model | |
instance
| | options | Object |
|
find options
| | options.where | Object |
|
An optional where clause to limit the associated models
| | options.scope | string | boolean |
|
Apply a scope on the related model, or remove its default scope by passing false
| | options.schema | string |
|
Apply a schema on the related model
|
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
| Name | Type | Attribute | Description | | sourceInstance | Model | |
source instance to check for an association with
| | instances | Model | Model[] | string[] | string | number[] | number |
|
Can be an array of instances or their primary keys
| | options | Object |
|
Options passed to getAssociations
|
Un-associate one or more instance(s).
| Name | Type | Attribute | Description | | sourceInstance | Model | |
instance to un associate instances with
| | oldAssociatedObjects | Model | Model[] | string | string[] | number | number[] |
|
Can be an Instance or its primary key, or a mixed array of instances and primary keys
| | options | Object |
|
Options passed to through.destroy
|
| Promise |
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.
| Name | Type | Attribute | Description | | sourceInstance | Model | |
source instance to associate new instances with
| | newAssociatedObjects | Model | Model[] | string[] | string | number[] | number |
|
A single instance or primary key, or a mixed array of persisted instances or primary keys
| | options | Object |
|
Options passed to through.findAll, bulkCreate, update and destroy
| | options.validate | Object |
|
Run validation for the join model
| | options.through | Object |
|
Additional attributes for the join table.
|
| Promise |