Creating new records

note

This guide assumes you understand how to create models. In the examples below, we will use the User class, which is a Model.

Inserting a single entity

The simplest way to create a new record is to use the create method of your model:

// Create a new user
const jane = await User.create({ firstName: 'Jane', lastName: 'Doe' });
// by this point, the user has been saved to the database!
console.log("Jane's auto-generated ID:", jane.id);

The Model.create() method is a shorthand for building an unsaved instance with Model.build() then saving the instance with instance.save(). You can do the individual steps yourself if you need more control:

const jane = User.build({ firstName: 'Jane', lastName: 'Doe' });

// "jane" has not been saved to the database yet!
// You can change any of its properties here, and call `save()` later to persist them all at once.

await jane.save();

// "jane" is now saved to the database!

Note, from the usage of await in the snippet above, that save is an asynchronous method. In fact, almost every Sequelize method is asynchronous; build is one of the very few exceptions.

findOrCreate

The method findOrCreate will create an entry in the table unless it can find one fulfilling the query options. In both cases, it will return an instance (either the found instance or the created instance) and a boolean indicating whether that instance was created or already existed.

The where option is considered for finding the entry, and the defaults option is used to define what must be created in case nothing was found. If the defaults do not contain values for every column, Sequelize will take the values given to where (if present).

Let's assume we have an empty database with a User model which has a username and a job.

const [user, created] = await User.findOrCreate({
  where: { username: 'sdepold' },
  defaults: {
    job: 'Technical Lead JavaScript',
  },
});

console.log(user.username); // 'sdepold'
console.log(user.job); // This may or may not be 'Technical Lead JavaScript'
console.log(created); // The boolean indicating whether this instance was just created
if (created) {
  console.log(user.job); // This will certainly be 'Technical Lead JavaScript'
}

caution

findOrCreate wraps its operations in a transaction (or a savepoint if a transaction is already in progress).
You may want to use findCreateFind instead if you want to avoid this.

findOrBuild is also available if you want to avoid saving the new instance.

Inserting in bulk

Sequelize provides the Model.bulkCreate method to allow creating multiple records at once, with only one query.

The usage of Model.bulkCreate is very similar to Model.create, by receiving an array of objects instead of a single object.

const captains = await Captain.bulkCreate([{ name: 'Jack Sparrow' }, { name: 'Davy Jones' }]);

console.log(captains.length); // 2
console.log(captains[0] instanceof Captain); // true
console.log(captains[0].name); // 'Jack Sparrow'
console.log(captains[0].id); // 1 (or another auto-generated value)

If you are accepting values directly from the user, it might be beneficial to limit the columns that you want to actually insert. To support this, bulkCreate() accepts a fields option, an array defining which fields must be considered (the rest will be ignored).

await User.bulkCreate(
  [
    { username: 'foo' },
    {
      username: 'bar',
      // This property will be ignored, because it is not listed in the "fields" option
      admin: true,
    },
  ],
  { fields: ['username'] },
);

Inserting Associated Records

note

This section assumes you understand how to associate models.

If two models are associated, you can create both instances in one go by using the include option, which is available on the create method.

In the following example, we want to immediately assign an Address to a User, as soon as a User is created.

await User.create(
  {
    name: 'Mary Read',
    address: {
      // you can specify the attributes of the associated model you want to create
      city: 'Nassau',
      country: 'Bahamas',
    },
  },
  {
    // you must specify which associated models must be created here
    include: ['address'],
  },
);

tip

If your association's type is HasMany or BelongsToMany, you can create multiple associated models at once:

await User.create(
  {
    name: 'Mary Read',
    addresses: [
      {
        city: 'Nassau',
        country: 'Bahamas',
      },
      {
        city: 'London',
        country: 'England',
      },
    ],
  },
  {
    include: ['addresses'],
  },
);

caution

The feature described above only works if you need to create the associated model, and not if you need to associate an existing model.

If you need to associate an existing model upon creation of the main model, you must specify its foreign key (when possible), or associate it after creation:

const address = await Address.create();

// This will not work
await User.create({
  name: 'Mary Read',
  address,
});

// This will work (assuming the foreign key is on User, and not Address)
await User.create({
  name: 'Mary Read',
  addressId: address.id,
});

// This also works (no matter where the foreign key is)
await User.create({
  name: 'Mary Read',
});

await user.setAddress(address);

We intend on improving this feature in a future version of Sequelize. Read more on this on issue #15233