Interface IncludeOptions

A single eager-loaded association: which one, what to select from it, whether it filters the parent (required), and any nesting beneath it.

interface IncludeOptions {
    model: ModelStatic<any>;
    as?: string;
    where?: WhereOptions<any>;
    attributes?: string[] | { include?: string[]; exclude?: string[] };
    schema?: string;
    required?: boolean;
    through?: {
        model?: ModelStatic<any>;
        as?: string;
        attributes?: string[] | { include?: string[]; exclude?: string[] };
        where?: WhereOptions<any>;
        required?: boolean;
    };
    on?: WhereOptions<any>;
    order?: Order;
    limit?: number;
    offset?: number;
    paranoid?: boolean;
    nested?: boolean;
    all?: string | boolean;
    includeIgnoreAttributes?: boolean;
    foreignKey?:
        | string
        | string[]
        | { name?: string
        | string[]; allowNull?: boolean };
    include?: IncludeOptions[] | Includeable[];
    duplicating?: boolean;
    duplicate?: boolean;
    targetKey?: string | string[];
    joinType?: "FULL" | "INNER" | "LEFT" | "RIGHT" | "CROSS";
    lateral?: boolean;
    antiJoin?: boolean;
    exclude?: boolean;
    antiJoinType?: "notIn" | "notExists" | "leftJoinIsNull";
    apply?: "CROSS" | "OUTER";
    lateralSubquery?: {
        model: ModelStatic<any>;
        where?: WhereOptions<any>;
        attributes?: string[] | { include?: string[]; exclude?: string[] };
    };
}

Hierarchy (View Summary)

Includeable
- IncludeOptions

Properties

model

model: ModelStatic<any>

The model to include

`Optional`as

as?: string

Alias for the included model. Used as:

The key in result objects (e.g., user.myPosts instead of user.Posts)
The base name for association methods (e.g., user.getMyPosts(), user.setMyPosts())
The table alias in SQL JOINs

Example

// With 'as' alias
User.findAll({
  include: [{ model: Post, as: 'myPosts' }]
})
// Result: { id: 1, name: 'John', myPosts: [...] }

// Without 'as' - defaults to model name
User.findAll({
  include: [{ model: Post }]
})
// Result: { id: 1, name: 'John', Posts: [...] }

`Optional`where

where?: WhereOptions<any>

`Optional`attributes

attributes?: string[] | { include?: string[]; exclude?: string[] }

`Optional`schema

schema?: string

Schema to use for the included model

`Optional`required

required?: boolean

`Optional`through

through?: {
    model?: ModelStatic<any>;
    as?: string;
    attributes?: string[] | { include?: string[]; exclude?: string[] };
    where?: WhereOptions<any>;
    required?: boolean;
}

For many-to-many (belongsToMany) relationships, specify the junction table model. This is required when including models through a join table.

Type Declaration

Optionalmodel?: ModelStatic<any>

The junction/through model
Optionalas?: string

Alias for the through model in SQL
Optionalattributes?: string[] | { include?: string[]; exclude?: string[] }

Attributes to include from the through model
Optionalwhere?: WhereOptions<any>

Where conditions on the through model
Optionalrequired?: boolean

Whether to require the join (INNER JOIN vs LEFT JOIN)

`Optional`on

on?: WhereOptions<any>

`Optional`order

order?: Order

`Optional`limit

limit?: number

`Optional`offset

offset?: number

`Optional`paranoid

paranoid?: boolean

`Optional`nested

nested?: boolean

When true, includes nested associations recursively

`Optional`all

all?: string | boolean

Include all associations, or a string to filter by association name

`Optional`includeIgnoreAttributes

includeIgnoreAttributes?: boolean

Ignore attributes from included models (default: true)

`Optional`foreignKey

foreignKey?:
    | string
    | string[]
    | { name?: string
    | string[]; allowNull?: boolean }

Custom foreign key for the join. Can be a single string for simple foreign keys, or an array for composite foreign keys.

Example

foreignKey: 'userId'  // Simple FK
foreignKey: ['orderId', 'customerId']  // Composite FK

`Optional`include

include?: IncludeOptions[] | Includeable[]

Nested includes

`Optional`duplicating

duplicating?: boolean

Whether to duplicate parent rows for each child (for hasMany)

`Optional`duplicate

duplicate?: boolean

Allow duplicate column names in the result. When true, uses table aliases to distinguish columns

`Optional`targetKey

targetKey?: string | string[]

Target key for the association (defaults to primary key). Can be a single string for simple keys, or an array for composite keys.

Example

targetKey: 'id'  // Simple key
targetKey: ['id', 'customerId']  // Composite key

`Optional`joinType

joinType?: "FULL" | "INNER" | "LEFT" | "RIGHT" | "CROSS"

Type of JOIN to use.

'INNER': INNER JOIN
'LEFT': LEFT JOIN (outer)
'RIGHT': RIGHT JOIN (outer)
'FULL': FULL OUTER JOIN
'CROSS': CROSS JOIN

Example

joinType: 'FULL'  // Full outer join

`Optional`lateral

lateral?: boolean

Whether to use LATERAL JOIN (PostgreSQL only). LATERAL allows subqueries to reference columns from preceding tables.

Example

lateral: true  // LATERAL JOIN

`Optional`antiJoin

antiJoin?: boolean

Whether to use anti-join pattern (NOT EXISTS or LEFT JOIN WHERE NULL). This finds records that do not have related records in the included model.

Example

// Find users with no orders
User.findAll({
  include: [{ model: Order, antiJoin: true }]
})
// SQL: SELECT users.* FROM users LEFT JOIN orders ON users.id = orders.user_id WHERE orders.id IS NULL

`Optional`exclude

exclude?: boolean

Alias for antiJoin - when true, uses anti-join pattern.

Example

// Find users that are NOT in the banned_users table
User.findAll({
  include: [{ model: BannedUser, exclude: true }]
})

`Optional`antiJoinType

antiJoinType?: "notIn" | "notExists" | "leftJoinIsNull"

Type of anti-join to use.

'notExists': Uses NOT EXISTS subquery pattern
'notIn': Uses NOT IN subquery pattern
'leftJoinIsNull': Uses LEFT JOIN WHERE NULL pattern (default)

Example

// Find users with no orders using NOT EXISTS
User.findAll({
  include: [{ model: Order, antiJoin: true, antiJoinType: 'notExists' }]
})

`Optional`apply

apply?: "CROSS" | "OUTER"

Whether to use CROSS APPLY or OUTER APPLY (SQL Server only).

'CROSS': CROSS APPLY - returns only matching rows
'OUTER': OUTER APPLY - returns all rows from left table (like LEFT JOIN)

Example

// SQL Server CROSS APPLY with a subquery
User.findAll({
  include: [{
    model: Order,
    apply: 'CROSS',
    where: { status: 'active' }
  }]
})

`Optional`lateralSubquery

lateralSubquery?: {
    model: ModelStatic<any>;
    where?: WhereOptions<any>;
    attributes?: string[] | { include?: string[]; exclude?: string[] };
}

Inline lateral subquery for advanced use cases. Allows defining an inline subquery that can reference columns from preceding tables.

Type Declaration

model: ModelStatic<any>

The model for the lateral subquery
Optionalwhere?: WhereOptions<any>

WHERE conditions on the subquery
Optionalattributes?: string[] | { include?: string[]; exclude?: string[] }

Attributes to select from the subquery

Example

// PostgreSQL LATERAL subquery
User.findAll({
  include: [{
    lateralSubquery: {
      model: Order,
      where: { status: 'active' },
      attributes: ['id', 'total']
    }
  }]
})

Interface IncludeOptions

Hierarchy (View Summary)

Index

Properties

Properties

model

Optionalas

Example

Optionalwhere

Optionalattributes

Optionalschema

Optionalrequired

Optionalthrough

Type Declaration

Optionalmodel?: ModelStatic<any>

Optionalas?: string

Optionalattributes?: string[] | { include?: string[]; exclude?: string[] }

Optionalwhere?: WhereOptions<any>

Optionalrequired?: boolean

Optionalon

Optionalorder

Optionallimit

Optionaloffset

Optionalparanoid

Optionalnested

Optionalall

OptionalincludeIgnoreAttributes

OptionalforeignKey

Example

Optionalinclude

Optionalduplicating

Optionalduplicate

OptionaltargetKey

Example

OptionaljoinType

Example

Optionallateral

Example

OptionalantiJoin

Example

Optionalexclude

Example

OptionalantiJoinType

Example

Optionalapply

Example

OptionallateralSubquery

Type Declaration

model: ModelStatic<any>

Optionalwhere?: WhereOptions<any>

Optionalattributes?: string[] | { include?: string[]; exclude?: string[] }

Example

Settings

On This Page

`Optional`as

`Optional`where

`Optional`attributes

`Optional`schema

`Optional`required

`Optional`through

`Optional`model?: ModelStatic<any>

`Optional`as?: string

`Optional`attributes?: string[] | { include?: string[]; exclude?: string[] }

`Optional`where?: WhereOptions<any>

`Optional`required?: boolean

`Optional`on

`Optional`order

`Optional`limit

`Optional`offset

`Optional`paranoid

`Optional`nested

`Optional`all

`Optional`includeIgnoreAttributes

`Optional`foreignKey

`Optional`include

`Optional`duplicating

`Optional`duplicate

`Optional`targetKey

`Optional`joinType

`Optional`lateral

`Optional`antiJoin

`Optional`exclude

`Optional`antiJoinType

`Optional`apply

`Optional`lateralSubquery

`Optional`where?: WhereOptions<any>

`Optional`attributes?: string[] | { include?: string[]; exclude?: string[] }