Class BelongsToMany<SourceModel, TargetModel, ThroughModel, SourceKey, TargetKey>

Many-to-many association with a join/through table. See Model.belongsToMany

When the join table has additional attributes, these can be passed in the options object:

UserProject = sequelize.define('user_project', {
  role: DataTypes.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().

Type Parameters

SourceModel extends Model = Model
TargetModel extends Model = Model
ThroughModel extends Model = Model
SourceKey extends AttributeNames<SourceModel> = any
TargetKey extends AttributeNames<TargetModel> = any

Hierarchy

MultiAssociation<SourceModel, TargetModel, string, TargetKey, NormalizedBelongsToManyOptions<SourceKey, TargetKey, ThroughModel>>
- BelongsToMany

Constructors

constructor

new BelongsToMany<SourceModel, TargetModel, ThroughModel, SourceKey, TargetKey>(secret, source, target, options, pair?, parent?): BelongsToMany<SourceModel, TargetModel, ThroughModel, SourceKey, TargetKey>
Type Parameters
- SourceModel extends Model<any, any> = Model<any, any>
- TargetModel extends Model<any, any> = Model<any, any>
- ThroughModel extends Model<any, any> = Model<any, any>
- SourceKey extends string = any
- TargetKey extends string = any
Parameters
- secret: symbol
- source: ModelStatic<SourceModel>
- target: ModelStatic<TargetModel>
- options: NormalizedBelongsToManyOptions<SourceKey, TargetKey, ThroughModel>
- Optional pair: BelongsToMany<TargetModel, SourceModel, ThroughModel, TargetKey, SourceKey>
- Optional parent: Association<any, Model<any, any>, string, NormalizedAssociationOptions<string>>
Returns BelongsToMany<SourceModel, TargetModel, ThroughModel, SourceKey, TargetKey>
Overrides MultiAssociation.constructor
- Defined in packages/core/src/associations/belongs-to-many.ts:220

Properties

`Readonly` accessors

accessors: MultiAssociationAccessors

`Readonly` fromSourceToThrough

fromSourceToThrough: HasMany<SourceModel, ThroughModel, SourceKey, any, any>

`Readonly` fromSourceToThroughOne

fromSourceToThroughOne: HasOne<SourceModel, ThroughModel, SourceKey, any, any>

isAliased

isAliased: boolean

isSelfAssociation

isSelfAssociation: boolean

`Readonly` options

options: NormalizedBelongsToManyOptions<SourceKey, TargetKey, ThroughModel>

pairedWith

pairedWith: BelongsToMany<TargetModel, SourceModel, ThroughModel, TargetKey, SourceKey>

The corresponding association this entity is paired with.

`Readonly` parentAssociation

parentAssociation: null | Association<Model<any, any>, Model<any, any>, string, NormalizedAssociationOptions<string>>

A reference to the association that created this one.

source

source: ModelStatic<SourceModel>

target

target: ModelStatic<TargetModel>

Accessors

as

get as(): string
The identifier of the relation on the source model.

Returns string
Inherited from MultiAssociation.as
- Defined in packages/core/src/associations/base.ts:176

associationType

get associationType(): string
The type of the association. One of HasMany, BelongsTo, HasOne, BelongsToMany

Returns string
Inherited from MultiAssociation.associationType
- Defined in packages/core/src/associations/base.ts:126

foreignIdentifierField

get foreignIdentifierField(): string
The corresponding column name of BelongsToMany#otherKey

Returns string
- Defined in packages/core/src/associations/belongs-to-many.ts:155

foreignKey

get foreignKey(): string
Returns string
Overrides MultiAssociation.foreignKey
- Defined in packages/core/src/associations/belongs-to-many.ts:125

fromTargetToThrough

get fromTargetToThrough(): HasMany<TargetModel, ThroughModel, TargetKey, any, any>
Returns HasMany<TargetModel, ThroughModel, TargetKey, any, any>
- Defined in packages/core/src/associations/belongs-to-many.ts:200

fromTargetToThroughOne

get fromTargetToThroughOne(): HasOne<TargetModel, ThroughModel, TargetKey, any, any>
Returns HasOne<TargetModel, ThroughModel, TargetKey, any, any>
- Defined in packages/core/src/associations/belongs-to-many.ts:204

fromThroughToSource

get fromThroughToSource(): BelongsTo<ThroughModel, SourceModel, any, SourceKey>
Returns BelongsTo<ThroughModel, SourceModel, any, SourceKey>
- Defined in packages/core/src/associations/belongs-to-many.ts:196

fromThroughToTarget

get fromThroughToTarget(): BelongsTo<ThroughModel, TargetModel, any, TargetKey>
Returns BelongsTo<ThroughModel, TargetModel, any, TargetKey>
- Defined in packages/core/src/associations/belongs-to-many.ts:208

identifier

get identifier(): string
Returns string

Deprecated
use BelongsToMany#foreignKey
- Defined in packages/core/src/associations/belongs-to-many.ts:141

identifierField

get identifierField(): string
The corresponding column name of BelongsToMany#foreignKey

Returns string
- Defined in packages/core/src/associations/belongs-to-many.ts:148

isMultiAssociation

get isMultiAssociation(): boolean
Returns boolean
Inherited from MultiAssociation.isMultiAssociation
- Defined in packages/core/src/associations/base.ts:130

isSingleAssociation

get isSingleAssociation(): boolean
Returns boolean

Deprecated
negate isMultiAssociation instead
Inherited from MultiAssociation.isSingleAssociation
- Defined in packages/core/src/associations/base.ts:137

name

get name(): {
plural: string;
singular: string;
}
Returns {
plural: string;
singular: string;
}
- plural: string
- singular: string
Inherited from MultiAssociation.name
- Defined in packages/core/src/associations/base.ts:180

otherKey

get otherKey(): string
The name of the Foreign Key attribute, located on the through table, that points to the Target model.

Not to be confused with

Returns string

Link
, which points to the Source model instead.
- Defined in packages/core/src/associations/belongs-to-many.ts:134

rootAssociation

get rootAssociation(): Association<Model<any, any>, Model<any, any>, string, NormalizedAssociationOptions<string>>
Creating an associations can automatically create other associations. This returns the initial association that caused the creation of the descendant associations.

Returns Association<Model<any, any>, Model<any, any>, string, NormalizedAssociationOptions<string>>
Inherited from MultiAssociation.rootAssociation
- Defined in packages/core/src/associations/base.ts:113

scope

get scope(): undefined | AssociationScope
Returns undefined | AssociationScope
Inherited from MultiAssociation.scope
- Defined in packages/core/src/associations/base.ts:184

sourceKey

get sourceKey(): SourceKey
The name of the Attribute that the foreignKey fk (located on the Through Model) will reference on the Source model.

Returns SourceKey
- Defined in packages/core/src/associations/belongs-to-many.ts:162

sourceKeyField

get sourceKeyField(): string
The name of the Column that the foreignKey fk (located on the Through Table) will reference on the Source model.

Returns string
- Defined in packages/core/src/associations/belongs-to-many.ts:169

targetKey

get targetKey(): TargetKey
The name of the Attribute that the otherKey fk (located on the Through Model) will reference on the Target model.

Returns TargetKey
- Defined in packages/core/src/associations/belongs-to-many.ts:176

targetKeyField

get targetKeyField(): string
The name of the Column that the otherKey fk (located on the Through Table) will reference on the Target model.

Returns string
- Defined in packages/core/src/associations/belongs-to-many.ts:183

through

get through(): NormalizedThroughOptions<ThroughModel>
Returns NormalizedThroughOptions<ThroughModel>
- Defined in packages/core/src/associations/belongs-to-many.ts:212

throughModel

get throughModel(): ModelStatic<ThroughModel>
Returns ModelStatic<ThroughModel>
- Defined in packages/core/src/associations/belongs-to-many.ts:216

`Static` isMultiAssociation

get isMultiAssociation(): boolean
Returns boolean
Inherited from MultiAssociation.isMultiAssociation
- Defined in packages/core/src/associations/base.ts:204

Methods

`Private` #makeFkPairUnique

#makeFkPairUnique(): void
Returns void
- Defined in packages/core/src/associations/belongs-to-many.ts:352

`Private` #mixin

#mixin(modelPrototype): void
Parameters
- modelPrototype: Model<any, any>
Returns void
- Defined in packages/core/src/associations/belongs-to-many.ts:438

`Private` #updateAssociations

#updateAssociations(sourceInstance, currentThroughRows, newTargets, options?): Promise<void>
Private
Adds new target instances that were not already present in the through table. Updates the through table row of the instances that already were present.
Parameters
- sourceInstance: SourceModel
- currentThroughRows: readonly ThroughModel[]
- newTargets: readonly TargetModel[]
- Optional options: {
  through?: JoinTableAttributes;
  } & BulkCreateOptions<Attributes<ThroughModel>> & Omit<UpdateOptions<Attributes<ThroughModel>>, "where">
Returns Promise<void>
- Defined in packages/core/src/associations/belongs-to-many.ts:701

add

add(sourceInstance, newInstancesOrPrimaryKeys, options?): Promise<void>
Associate one or several rows with source instance. It will not un-associate any already associated instance that may be missing from newInstances.
Parameters
- sourceInstance: SourceModel
  
  source instance to associate new instances with
- newInstancesOrPrimaryKeys: AllowIterable<TargetModel | Exclude<TargetModel[TargetKey], any[]>>
  
  A single instance or primary key, or a mixed array of persisted instances or primary keys
- Optional options: BelongsToManyAddAssociationsMixinOptions<TargetModel>
  
  Options passed to through.findAll, bulkCreate and update
Returns Promise<void>
- Defined in packages/core/src/associations/belongs-to-many.ts:660

count

count(instance, options?): Promise<number>
Count everything currently associated with this, using an optional where clause.
Parameters
- instance: SourceModel
  
  instance
- Optional options: BelongsToManyCountAssociationsMixinOptions<TargetModel>
  
  find options
Returns Promise<number>
- Defined in packages/core/src/associations/belongs-to-many.ts:520

create

create(sourceInstance, values?, options?): Promise<TargetModel>
Create a new instance of the associated model and associate it with this.
Parameters
- sourceInstance: SourceModel
  
  source instance
- values: CreationAttributes<TargetModel> = {}
  
  values for target model
- options: undefined | BelongsToManyCreateAssociationMixinOptions<TargetModel> | (keyof Attributes<TargetModel>)[] = {}
  
  Options passed to create and add
Returns Promise<TargetModel>
- Defined in packages/core/src/associations/belongs-to-many.ts:818

get

get(instance, options?): Promise<TargetModel[]>
Get everything currently associated with this, using an optional where clause.

See Model for a full explanation of options
Parameters
- instance: SourceModel
  
  instance
- Optional options: BelongsToManyGetAssociationsMixinOptions<TargetModel>
  
  find options
Returns Promise<TargetModel[]>
- Defined in packages/core/src/associations/belongs-to-many.ts:461

has

has(sourceInstance, targetInstancesOrPks, options?): Promise<boolean>
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
Parameters
- sourceInstance: SourceModel
  
  source instance to check for an association with
- targetInstancesOrPks: AllowIterable<TargetModel | Exclude<TargetModel[TargetKey], any[]>>
  
  Can be an array of instances or their primary keys
- Optional options: BelongsToManyHasAssociationMixinOptions<TargetModel>
  
  Options passed to getAssociations
Returns Promise<boolean>
- Defined in packages/core/src/associations/belongs-to-many.ts:544

remove

remove(sourceInstance, targetInstanceOrPks, options?): Promise<void>
Un-associate one or more instance(s).
Parameters
- sourceInstance: SourceModel
  
  instance to un associate instances with
- targetInstanceOrPks: AllowIterable<TargetModel | Exclude<TargetModel[TargetKey], any[]>>
  
  Can be an Instance or its primary key, or a mixed array of instances and primary keys
- Optional options: BelongsToManyRemoveAssociationMixinOptions
  
  Options passed to through.destroy
Returns Promise<void>
- Defined in packages/core/src/associations/belongs-to-many.ts:792

set

set(sourceInstance, newInstancesOrPrimaryKeys, options?): Promise<void>
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.
Parameters
- sourceInstance: SourceModel
  
  source instance to associate new instances with
- newInstancesOrPrimaryKeys: AllowIterable<TargetModel | Exclude<TargetModel[TargetKey], any[]>>
  
  A single instance or primary key, or a mixed array of persisted instances or primary keys
- options: BelongsToManySetAssociationsMixinOptions<TargetModel> = {}
  
  Options passed to through.findAll, bulkCreate, update and destroy
Returns Promise<void>
- Defined in packages/core/src/associations/belongs-to-many.ts:594

`Private` toInstanceArray

toInstanceArray(input): TargetModel[]
Private
Normalize input
Parameters
- input: null | AllowIterable<TargetModel | Exclude<TargetModel[TargetKey], any[]>>
  
  it may be array or single obj, instance or primary key
Returns TargetModel[]
built objects
Inherited from MultiAssociation.toInstanceArray
- Defined in packages/core/src/associations/base.ts:231

`Protected` toInstanceOrPkArray

toInstanceOrPkArray(input): (TargetModel | Exclude<TargetModel[TargetKey], any[]>)[]
Parameters
- input: Nullish<AllowIterable<TargetModel | Exclude<TargetModel[TargetKey], any[]>>>
Returns (TargetModel | Exclude<TargetModel[TargetKey], any[]>)[]
Inherited from MultiAssociation.toInstanceOrPkArray
- Defined in packages/core/src/associations/base.ts:208

`Static` associate

associate<S, T, ThroughModel, SourceKey, TargetKey>(secret, source, target, options, pair?, parent?): BelongsToMany<S, T, ThroughModel, SourceKey, TargetKey>
Type Parameters
- S extends Model<any, any>
- T extends Model<any, any>
- ThroughModel extends Model<any, any>
- SourceKey extends string
- TargetKey extends string
Parameters
- secret: symbol
- source: ModelStatic<S>
- target: ModelStatic<T>
- options: BelongsToManyOptions<SourceKey, TargetKey, ThroughModel>
- Optional pair: BelongsToMany<T, S, ThroughModel, TargetKey, SourceKey>
- Optional parent: Association<any, Model<any, any>, string, NormalizedAssociationOptions<string>>
Returns BelongsToMany<S, T, ThroughModel, SourceKey, TargetKey>
- Defined in packages/core/src/associations/belongs-to-many.ts:403

Class BelongsToMany<SourceModel, TargetModel, ThroughModel, SourceKey, TargetKey>

Type Parameters

SourceModel extends Model = Model

TargetModel extends Model = Model

ThroughModel extends Model = Model

SourceKey extends AttributeNames<SourceModel> = any

TargetKey extends AttributeNames<TargetModel> = any

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

SourceModel extends Model<any, any> = Model<any, any>

TargetModel extends Model<any, any> = Model<any, any>

ThroughModel extends Model<any, any> = Model<any, any>

SourceKey extends string = any

TargetKey extends string = any

Parameters

secret: symbol

source: ModelStatic<SourceModel>

target: ModelStatic<TargetModel>

options: NormalizedBelongsToManyOptions<SourceKey, TargetKey, ThroughModel>

Optional pair: BelongsToMany<TargetModel, SourceModel, ThroughModel, TargetKey, SourceKey>

Optional parent: Association<any, Model<any, any>, string, NormalizedAssociationOptions<string>>

Returns BelongsToMany<SourceModel, TargetModel, ThroughModel, SourceKey, TargetKey>

Properties

Readonly accessors

Readonly fromSourceToThrough

Readonly fromSourceToThroughOne

isAliased

isSelfAssociation

Readonly options

pairedWith

Readonly parentAssociation

source

target

Accessors

as

Returns string

associationType

Returns string

foreignIdentifierField

Returns string

foreignKey

Returns string

fromTargetToThrough

Returns HasMany<TargetModel, ThroughModel, TargetKey, any, any>

fromTargetToThroughOne

Returns HasOne<TargetModel, ThroughModel, TargetKey, any, any>

fromThroughToSource

Returns BelongsTo<ThroughModel, SourceModel, any, SourceKey>

fromThroughToTarget

Returns BelongsTo<ThroughModel, TargetModel, any, TargetKey>

identifier

Returns string

Deprecated

identifierField

Returns string

isMultiAssociation

Returns boolean

isSingleAssociation

Returns boolean

Deprecated

name

Returns { plural: string; singular: string; }

plural: string

singular: string

otherKey

Returns string

Link

rootAssociation

Returns Association<Model<any, any>, Model<any, any>, string, NormalizedAssociationOptions<string>>

scope

Returns undefined | AssociationScope

sourceKey

Returns SourceKey

`Optional` pair: BelongsToMany<TargetModel, SourceModel, ThroughModel, TargetKey, SourceKey>

`Optional` parent: Association<any, Model<any, any>, string, NormalizedAssociationOptions<string>>

`Readonly` accessors

`Readonly` fromSourceToThrough

`Readonly` fromSourceToThroughOne

`Readonly` options

`Readonly` parentAssociation

Returns {
plural: string;
singular: string;
}

`Static` isMultiAssociation

`Private` #makeFkPairUnique

`Private` #mixin

`Private` #updateAssociations

`Optional` options: {
through?: JoinTableAttributes;
} & BulkCreateOptions<Attributes<ThroughModel>> & Omit<UpdateOptions<Attributes<ThroughModel>>, "where">

`Optional` options: BelongsToManyAddAssociationsMixinOptions<TargetModel>

`Optional` options: BelongsToManyCountAssociationsMixinOptions<TargetModel>

`Optional` options: BelongsToManyGetAssociationsMixinOptions<TargetModel>

`Optional` options: BelongsToManyHasAssociationMixinOptions<TargetModel>

`Optional` options: BelongsToManyRemoveAssociationMixinOptions

`Private` toInstanceArray