Class Model

View code

A Model represents a table in the database. Sometimes you might also see it referred to as model, or simply as factory. This class should not be instantiated directly, it is created using sequelize.define, and already created models can be loaded using sequelize.import

Mixes:

• Hooks
• Associations

removeAttribute([attribute])

View code

Remove attribute from model definition

Params:

sync() -> Promise.<this>

View code

Sync this Model to the DB, that is create the table. Upon success, the callback will be called with the model instance (this)

See:

• Sequelize#sync

drop([options]) -> Promise

View code

Drop the table represented by this Model

Params:

schema(schema, [options]) -> this

View code

Apply a schema to this model. For postgres, this will actually place the schema in front of the table name - "schema"."tableName", while the schema will be prepended to the table name for mysql and sqlite - 'schema.tablename'.

Params:

getTableName([options]) -> String|Object

View code

Get the tablename of the model, taking schema into account. The method will return The name as a string if the model has no schema, or an object with tableName, schema and delimiter properties.

Params:

unscoped() -> Model

View code

addScope(name, scope, [options])

View code

Add a new scope to the model. This is especially useful for adding scopes with includes, when the model you want to include is not available at the time this model is defined.

By default this will throw an error if a scope with that name already exists. Pass override: true in the options object to silence this error.

Params:

scope(options*) -> Model

View code

Apply a scope created in define to the model. First let's look at how to create scopes:

var Model = sequelize.define('model', attributes, {
  defaultScope: {
    where: {
      username: 'dan'
    },
    limit: 12
  },
  scopes: {
    isALie: {
      where: {
        stuff: 'cake'
      }
    },
    complexFunction: function(email, accessLevel) {
      return {
        where: {
          email: {
            $like: email
          },
          accesss_level {
            $gte: accessLevel
          }
        }
      }
    }
  }
})

Now, since you defined a default scope, every time you do Model.find, the default scope is appended to your query. Here's a couple of examples:

Model.findAll() // WHERE username = 'dan'
Model.findAll({ where: { age: { gt: 12 } } }) // WHERE age > 12 AND username = 'dan'

To invoke scope functions you can do:

Model.scope({ method: ['complexFunction' '[email protected]', 42]}).findAll()
// WHERE email like '[email protected]%' AND access_level >= 42

Params:

Returns: A reference to the model, with the scope(s) applied. Calling scope again on the returned model will clear the previous scope.

findAll([options]) -> Promise.<Array.<Instance>>

View code

Search for multiple instances.

Simple search using AND and =

Model.findAll({
  where: {
    attr1: 42,
    attr2: 'cake'
  }
})

WHERE attr1 = 42 AND attr2 = 'cake'

Using greater than, less than etc.

Model.findAll({
  where: {
    attr1: {
      gt: 50
    },
    attr2: {
      lte: 45
    },
    attr3: {
      in: [1,2,3]
    },
    attr4: {
      ne: 5
    }
  }
})

WHERE attr1 > 50 AND attr2 <= 45 AND attr3 IN (1,2,3) AND attr4 != 5

Possible options are: $ne, $in, $not, $notIn, $gte, $gt, $lte, $lt, $like, $ilike/$iLike, $notLike, $notILike, '..'/$between, '!..'/$notBetween, '&&'/$overlap, '@>'/$contains, '<@'/$contained

Queries using OR

Model.findAll({
  where: {
    name: 'a project',
    $or: [
      {id: [1, 2, 3]},
      {
        $and: [
          {id: {gt: 10}},
          {id: {lt: 100}}
        ]
      }
    ]
  }
});

WHERE `Model`.`name` = 'a project' AND (`Model`.`id` IN (1, 2, 3) OR (`Model`.`id` > 10 AND `Model`.`id` < 100));

The success listener is called with an array of instances if the query succeeds.

See:

• Sequelize#query

Params:

Aliases: all

findById(id, [options]) -> Promise.<Instance>

View code

Search for a single instance by its primary key.

See:

• Model#findAll

Params:

Aliases: findByPrimary

findOne([options]) -> Promise.<Instance>

View code

Search for a single instance. This applies LIMIT 1, so the listener will always be called with a single instance.

See:

• Model#findAll

Params:

Aliases: find

aggregate(field, aggregateFunction, [options]) -> Promise.<options.dataType|object>

View code

Run an aggregation method on the specified field

Params:

Returns: Returns the aggregate result cast to options.dataType, unless options.plain is false, in which case the complete data result is returned.

count([options]) -> Promise.<Integer>

View code

Count the number of records matching the provided where clause.

If you provide an include option, the number of matching associations will be counted instead.

Params:

findAndCount([findOptions]) -> Promise.<Object>

View code

Find all the rows matching your query, within a specified offset / limit, and get the total number of rows matching your query. This is very useful for paging

Model.findAndCountAll({
  where: ...,
  limit: 12,
  offset: 12
}).then(function (result) {
  ...
})

In the above example, result.rows will contain rows 13 through 24, while result.count will return the total number of rows that matched your query.

When you add includes, only those which are required (either because they have a where clause, or because required is explicitly set to true on the include) will be added to the count part.

Suppose you want to find all users who have a profile attached:

User.findAndCountAll({
  include: [
     { model: Profile, required: true}
  ],
  limit 3
});

Because the include for Profile has required set it will result in an inner join, and only the users who have a profile will be counted. If we remove required from the include, both users with and without profiles will be counted

See:

• Model#findAll

Params:

Aliases: findAndCountAll

max(field, [options]) -> Promise.<Any>

View code

Find the maximum value of field

See:

• Model#aggregate

Params:

min(field, [options]) -> Promise.<Any>

View code

Find the minimum value of field

See:

• Model#aggregate

Params:

sum(field, [options]) -> Promise.<Number>

View code

Find the sum of field

See:

• Model#aggregate

Params:

build(values, [options]) -> Instance

View code

Builds a new model instance. Values is an object of key value pairs, must be defined but can be empty.

Params:

create(values, [options]) -> Promise.<Instance>

View code

Builds a new model instance and calls save on it.

See:

• Instance#build
• Instance#save

Params:

findOrInitialize -> Promise.<Instance, initialized>

View code

Find a row that matches the query, or build (but don't save) the row if none is found. The successful result of the promise will be (instance, initialized) - Make sure to use .spread()

Params:

Aliases: findOrBuild

findOrCreate(options) -> Promise.<Instance, created>

View code

Find a row that matches the query, or build and save the row if none is found The successful result of the promise will be (instance, created) - Make sure to use .spread()

If no transaction is passed in the options object, a new transaction will be created internally, to prevent the race condition where a matching row is created by another connection after the find but before the insert call. However, it is not always possible to handle this case in SQLite, specifically if one transaction inserts and another tries to select before the first one has committed. In this case, an instance of sequelize.TimeoutError will be thrown instead. If a transaction is created, a savepoint will be created instead, and any unique constraint violation will be handled internally.

See:

• Model#findAll

Params:

findCreateFind(options) -> Promise.<Instance, created>

View code

A more performant findOrCreate that will not work under a transaction (at least not in postgres) Will execute a find call, if empty then attempt to create, if unique constraint then attempt to find again

See:

• Model#findAll

Params:

upsert(values, [options]) -> Promise.<created>

View code

Insert or update a single row. An update will be executed if a row which matches the supplied values on either the primary key or a unique key is found. Note that the unique index must be defined in your sequelize model and not just in the table. Otherwise you may experience a unique constraint violation, because sequelize fails to identify the row that should be updated.

Implementation details:

• MySQL - Implemented as a single query INSERT values ON DUPLICATE KEY UPDATE values
• PostgreSQL - Implemented as a temporary function with exception handling: INSERT EXCEPTION WHEN unique_constraint UPDATE
• SQLite - Implemented as two queries INSERT; UPDATE. This means that the update is executed regardless of whether the row already existed or not

Note that SQLite returns undefined for created, no matter if the row was created or updated. This is because SQLite always runs INSERT OR IGNORE + UPDATE, in a single query, so there is no way to know whether the row was inserted or not.

Params:

Returns: Returns a boolean indicating whether the row was created or updated. Aliases: insertOrUpdate

bulkCreate(records, [options]) -> Promise.<Array.<Instance>>

View code

Create and insert multiple instances in bulk.

The success handler is passed an array of instances, but please notice that these may not completely represent the state of the rows in the DB. This is because MySQL and SQLite do not make it easy to obtain back automatically generated IDs and other default values in a way that can be mapped to multiple records. To obtain Instances for the newly created values, you will need to query for them again.

Params:

truncate([options]) -> Promise

View code

Truncate all instances of the model. This is a convenient method for Model.destroy({ truncate: true }).

See:

• Model#destroy

Params:

destroy(options) -> Promise.<Integer>

View code

Delete multiple instances, or set their deletedAt timestamp to the current time if paranoid is enabled.

Params:

Returns: The number of destroyed rows

restore(options) -> Promise.<undefined>

View code

Restore multiple instances if paranoid is enabled.

Params:

update(values, options) -> Promise.<Array.<affectedCount, affectedRows>>

View code

Update multiple instances that match the where options. The promise returns an array with one or two elements. The first element is always the number of affected rows, while the second element is the actual affected rows (only supported in postgres with options.returning true.)

Params:

describe() -> Promise

View code

Run a describe query on the table. The result will be return to the listener as a hash of attributes and their types.

This document is automatically generated based on source code comments. Please do not edit it directly, as your changes will be ignored. Please write on IRC, open an issue or a create a pull request if you feel something can be improved. For help on how to write source code documentation see JSDoc and dox