Class BelongsToManyAssociation<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> = AttributeNames<SourceModel>
TargetKey extends AttributeNames<TargetModel> = AttributeNames<TargetModel>

Constructors

constructor

new BelongsToManyAssociation<
    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 = AttributeNames<SourceModel>,
    TargetKey extends string = AttributeNames<TargetModel>,
>(
    secret: symbol,
    source: ModelStatic<SourceModel>,
    target: ModelStatic<TargetModel>,
    options: NormalizedBelongsToManyOptions<SourceKey, TargetKey, ThroughModel>,
    pair?: BelongsToManyAssociation<
        TargetModel,
        SourceModel,
        ThroughModel,
        TargetKey,
        SourceKey,
    >,
    parent?: Association<
        any,
        Model<any, any>,
        string,
        NormalizedAssociationOptions<string>,
    >,
): BelongsToManyAssociation<
    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 = AttributeNames<SourceModel>
- TargetKey extends string = AttributeNames<TargetModel>
Parameters
- secret: symbol
- source: ModelStatic<SourceModel>
- target: ModelStatic<TargetModel>
- options: NormalizedBelongsToManyOptions<SourceKey, TargetKey, ThroughModel>
- Optionalpair: BelongsToManyAssociation<
      TargetModel,
      SourceModel,
      ThroughModel,
      TargetKey,
      SourceKey,
  >
- Optionalparent: Association<any, Model<any, any>, string, NormalizedAssociationOptions<string>>
Returns BelongsToManyAssociation<
    SourceModel,
    TargetModel,
    ThroughModel,
    SourceKey,
    TargetKey,
>
Overrides MultiAssociation< SourceModel, TargetModel, /* ForeignKey */ string, TargetKey, NormalizedBelongsToManyOptions<SourceKey, TargetKey, ThroughModel> >.constructor
- Defined in core/src/associations/belongs-to-many.ts:228

Properties

`Readonly`accessors

accessors: MultiAssociationAccessors

`Readonly`fromSourceToThrough

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

`Readonly`fromSourceToThroughOne

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

isAliased

isAliased: boolean

isSelfAssociation

isSelfAssociation: boolean

`Readonly`options

options: NormalizedBelongsToManyOptions

pairedWith

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

The corresponding association this entity is paired with.

`Readonly`parentAssociation

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

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 core/src/associations/base.ts:184

associationType

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

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

foreignIdentifierField

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

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

foreignKey

get foreignKey(): string
The name of the foreign key attribute used by this association.

Returns string
Overrides <internal>.foreignKey
- Defined in core/src/associations/belongs-to-many.ts:127

identifierField

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

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

isMultiAssociation

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

isSingleAssociation

get isSingleAssociation(): boolean
Returns boolean

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

name

get name(): { plural: string; singular: string }
Returns { plural: string; singular: string }
Inherited from <internal>.name
- Defined in core/src/associations/base.ts:188

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 BelongsToManyAssociation#foreignKey, which points to the Source model instead.

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

rootAssociation

get rootAssociation(): Association
Creating an associations can automatically create other associations. This returns the initial association that caused the creation of the descendant associations.

Returns Association
Inherited from <internal>.rootAssociation
- Defined in core/src/associations/base.ts:119

scope

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

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 core/src/associations/belongs-to-many.ts:164

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 core/src/associations/belongs-to-many.ts:171

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 core/src/associations/belongs-to-many.ts:178

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 core/src/associations/belongs-to-many.ts:185

through

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

throughModel

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

`Static`isMultiAssociation

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

Methods

add

add(
    sourceInstance: SourceModel,
    newInstancesOrPrimaryKeys: AllowIterable<
        TargetModel
        | Exclude<TargetModel[TargetKey], any[]>,
    >,
    options?: BelongsToManyAddAssociationsMixinOptions<TargetModel>,
): 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
- Optionaloptions: BelongsToManyAddAssociationsMixinOptions<TargetModel>
  Options passed to through.findAll, bulkCreate and update
Returns Promise<void>
- Defined in core/src/associations/belongs-to-many.ts:723

count

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

create

create(
    sourceInstance: SourceModel,
    values?: CreationAttributes<TargetModel>,
    options?:
        | (keyof Attributes<TargetModel>)[]
        | BelongsToManyCreateAssociationMixinOptions<TargetModel>
        | undefined,
): 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:
      | (keyof Attributes<TargetModel>)[]
      | BelongsToManyCreateAssociationMixinOptions<TargetModel>
      | undefined = {}
  Options passed to create and add
Returns Promise<TargetModel>
- Defined in core/src/associations/belongs-to-many.ts:883

get

get(
instance: SourceModel,
options?: BelongsToManyGetAssociationsMixinOptions<TargetModel>,
): 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
- Optionaloptions: BelongsToManyGetAssociationsMixinOptions<TargetModel>
  find options
Returns Promise<TargetModel[]>
- Defined in core/src/associations/belongs-to-many.ts:513

has

has(
    sourceInstance: SourceModel,
    targetInstancesOrPks: AllowIterable<
        TargetModel
        | Exclude<TargetModel[TargetKey], any[]>,
    >,
    options?: BelongsToManyHasAssociationMixinOptions<TargetModel>,
): 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
- Optionaloptions: BelongsToManyHasAssociationMixinOptions<TargetModel>
  Options passed to getAssociations
Returns Promise<boolean>
- Defined in core/src/associations/belongs-to-many.ts:604

remove

remove(
    sourceInstance: SourceModel,
    targetInstanceOrPks: AllowIterable<
        TargetModel
        | Exclude<TargetModel[TargetKey], any[]>,
    >,
    options?: BelongsToManyRemoveAssociationMixinOptions,
): 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
- Optionaloptions: BelongsToManyRemoveAssociationMixinOptions
  Options passed to through.destroy
Returns Promise<void>
- Defined in core/src/associations/belongs-to-many.ts:857

set

set(
    sourceInstance: SourceModel,
    newInstancesOrPrimaryKeys: AllowIterable<
        TargetModel
        | Exclude<TargetModel[TargetKey], any[]>,
    >,
    options?: BelongsToManySetAssociationsMixinOptions<TargetModel>,
): 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 core/src/associations/belongs-to-many.ts:651

`Protected`toInstanceOrPkArray

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

`Static`associate

associate<
    S extends Model<any, any>,
    T extends Model<any, any>,
    ThroughModel extends Model<any, any>,
    SourceKey extends string,
    TargetKey extends string,
>(
    secret: symbol,
    source: ModelStatic<S>,
    target: ModelStatic<T>,
    options: BelongsToManyOptions<SourceKey, TargetKey, ThroughModel>,
    pair?: BelongsToManyAssociation<T, S, ThroughModel, TargetKey, SourceKey>,
    parent?: Association<
        any,
        Model<any, any>,
        string,
        NormalizedAssociationOptions<string>,
    >,
): BelongsToManyAssociation<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>
- Optionalpair: BelongsToManyAssociation<T, S, ThroughModel, TargetKey, SourceKey>
- Optionalparent: Association<any, Model<any, any>, string, NormalizedAssociationOptions<string>>
Returns BelongsToManyAssociation<S, T, ThroughModel, SourceKey, TargetKey>
- Defined in core/src/associations/belongs-to-many.ts:438

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

Type Parameters

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

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

Properties

Readonlyaccessors

ReadonlyfromSourceToThrough

ReadonlyfromSourceToThroughOne

isAliased

isSelfAssociation

Readonlyoptions

pairedWith

ReadonlyparentAssociation

source

target

Accessors

as

Returns string

associationType

Returns string

foreignIdentifierField

Returns string

foreignKey

Returns string

fromTargetToThrough

Returns HasManyAssociation<TargetModel, ThroughModel, TargetKey, any>

fromTargetToThroughOne

Returns HasOneAssociation<TargetModel, ThroughModel, TargetKey, any>

fromThroughToSource

Returns BelongsToAssociation<ThroughModel, SourceModel, any, SourceKey>

fromThroughToTarget

Returns BelongsToAssociation<ThroughModel, TargetModel, any, TargetKey>

identifier

Returns string

Deprecated

identifierField

Returns string

isMultiAssociation

Returns boolean

isSingleAssociation

Returns boolean

Deprecated

name

Returns { plural: string; singular: string }

otherKey

Returns string

rootAssociation

Returns Association

scope

Returns AssociationScope | undefined

sourceKey

Returns SourceKey

sourceKeyField

Returns string

targetKey

Returns TargetKey

targetKeyField

Returns string

through

Returns NormalizedThroughOptions<ThroughModel>

throughModel

Returns ModelStatic<ThroughModel>

StaticisMultiAssociation

Returns boolean

Methods

add

Parameters

Returns Promise<void>

count

Parameters

Returns Promise<number>

create

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

`Readonly`accessors

`Readonly`fromSourceToThrough

`Readonly`fromSourceToThroughOne

`Readonly`options

`Readonly`parentAssociation

`Static`isMultiAssociation

`Protected`toInstanceOrPkArray

`Static`associate