In this document we'll explore what finder methods can do:

    findOrCreate - Search for a specific element or create it if not available

    The method can be used to check if a certain element already exists in the database. If that is the case the method will result in a respective instance. If the element does not yet exist, it will be created.

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

    where option will be appended to defaults for create case.

    1. User
    2.   .findOrCreate({where: {username: 'sdepold'}, defaults: {job: 'Technical Lead JavaScript'}})
    3.   .then(([user, created]) => {
    4.     console.log(user.get({
    5.       plain: true
    6.     }))
    7.     console.log(created)
    9.     /*
    10.      findOrCreate returns an array containing the object that was found or created and a boolean that
    11.      will be true if a new object was created and false if not, like so:
    13.     [ {
    14.         username: 'sdepold',
    15.         job: 'Technical Lead JavaScript',
    16.         id: 1,
    17.         createdAt: Fri Mar 22 2013 21: 28: 34 GMT + 0100(CET),
    18.         updatedAt: Fri Mar 22 2013 21: 28: 34 GMT + 0100(CET)
    19.       },
    20.       true ]
    22.  In the example above, the array spread on line 3 divides the array into its 2 parts and passes them
    23.   as arguments to the callback function defined beginning at line 39, which treats them as "user" and
    24.   "created" in this case. (So "user" will be the object from index 0 of the returned array and
    25.   "created" will equal "true".)
    26.     */
    27.   })

    The code created a new instance. So when we already have an instance …

    1. User.create({ username: 'fnord', job: 'omnomnom' })
    2.   .then(() => User.findOrCreate({where: {username: 'fnord'}, defaults: {job: 'something else'}}))
    3.   .then(([user, created]) => {
    4.     console.log(user.get({
    5.       plain: true
    6.     }))
    7.     console.log(created)
    9.     /*
    10.     In this example, findOrCreate returns an array like this:
    11.     [ {
    12.         username: 'fnord',
    13.         job: 'omnomnom',
    14.         id: 2,
    15.         createdAt: Fri Mar 22 2013 21: 28: 34 GMT + 0100(CET),
    16.         updatedAt: Fri Mar 22 2013 21: 28: 34 GMT + 0100(CET)
    17.       },
    18.       false
    19.     ]
    20.     The array returned by findOrCreate gets spread into its 2 parts by the array spread on line 3, and
    21.     the parts will be passed as 2 arguments to the callback function beginning on line 69, which will
    22.     then treat them as "user" and "created" in this case. (So "user" will be the object from index 0
    23.     of the returned array and "created" will equal "false".)
    24.     */
    25.   })

    … the existing entry will not be changed. See the job of the second user, and the fact that created was false.

    findAndCountAll - Search for multiple elements in the database, returns both data and total count

    This is a convenience method that combinesfindAll and count (see below) this is useful when dealing with queries related to pagination where you want to retrieve data with a limit and offset but also need to know the total number of records that match the query:

    The success handler will always receive an object with two properties:

    • count - an integer, total number records matching the where clause and other filters due to associations
    • rows - an array of objects, the records matching the where clause and other filters due to associations, within the limit and offset range
    1. Project
    2.      where: {
    3.         title: {
    4.           [Op.like]: 'foo%'
    5.         }
    6.      },
    8.      limit: 2
    9.   })
    10.   .then(result => {
    11.     console.log(result.count);
    12.     console.log(result.rows);
    13.   });

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

    1. User.findAndCountAll({
    2.   include: [
    3.      { model: Profile, required: true }
    4.   ],
    5.   limit: 3
    6. });

    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. Adding a where clause to the include automatically makes it required:

    1. User.findAndCountAll({
    2.   include: [
    3.      { model: Profile, where: { active: true }}
    4.   ],
    5.   limit: 3
    6. });

    The query above will only count users who have an active profile, because required is implicitly set to true when you add a where clause to the include.

    The options object that you pass to findAndCountAll is the same as for findAll (described below).

    Complex filtering / OR / NOT queries

    It's possible to do complex where queries with multiple levels of nested AND, OR and NOT conditions. In order to do that you can use or, and or not Operators:

    1. Project.findOne({
    2.   where: {
    3.     name: 'a project',
    4.     [Op.or]: [
    5.       { id: [1,2,3] },
    6.       { id: { [Op.gt]: 10 } }
    7.     ]
    8.   }
    9. })
    11. Project.findOne({
    12.   where: {
    13.     name: 'a project',
    14.     id: {
    15.       [Op.or]: [
    16.         [1,2,3],
    17.         { [Op.gt]: 10 }
    18.       ]
    19.     }
    20.   }
    21. })

    Both pieces of code will generate the following:

    1. SELECT *
    2. FROM `Projects`
    3. WHERE (
    4.   `Projects`.`name` = 'a project'
    5.    AND (`Projects`.`id` IN (1,2,3) OR `Projects`.`id` > 10)
    6. )
    7. LIMIT 1;

    not example:

    1. Project.findOne({
    2.   where: {
    3.     name: 'a project',
    4.     [Op.not]: [
    5.       { id: [1,2,3] },
    6.       { array: { [Op.contains]: [3,4,5] } }
    7.     ]
    8.   }
    9. });

    Will generate:

    1. SELECT *
    2. FROM `Projects`
    3. WHERE (
    5.    AND NOT (`Projects`.`id` IN (1,2,3) OR `Projects`.`array` @> ARRAY[3,4,5]::INTEGER[])
    6. LIMIT 1;

    Manipulating the dataset with limit, offset, order and group

    1. // limit the results of the query
    2. Project.findAll({ limit: 10 })
    4. // step over the first 10 elements
    5. Project.findAll({ offset: 10 })
    7. // step over the first 10 elements, and take 2
    8. Project.findAll({ offset: 10, limit: 2 })

    The syntax for grouping and ordering are equal, so below it is only explained with a single example for group, and the rest for order. Everything you see below can also be done for group

    Notice how in the two examples above, the string provided is inserted verbatim into the query, i.e. column names are not escaped. When you provide a string to order/group, this will always be the case. If you want to escape column names, you should provide an array of arguments, even though you only want to order/group by a single column

    1. something.findOne({
    2.   order: [
    3.     // will return `name`
    4.     ['name'],
    5.     // will return `username` DESC
    6.     ['username', 'DESC'],
    7.     // will return max(`age`)
    8.     sequelize.fn('max', sequelize.col('age')),
    9.     // will return max(`age`) DESC
    10.     [sequelize.fn('max', sequelize.col('age')), 'DESC'],
    11.     // will return otherfunction(`col1`, 12, 'lalala') DESC
    12.     [sequelize.fn('otherfunction', sequelize.col('col1'), 12, 'lalala'), 'DESC'],
    13.     // will return otherfunction(awesomefunction(`col`)) DESC, This nesting is potentially infinite!
    14.     [sequelize.fn('otherfunction', sequelize.fn('awesomefunction', sequelize.col('col'))), 'DESC']
    15.   ]
    16. })

    To recap, the elements of the order/group array can be the following:

    • String - will be quoted
    • Array - first element will be quoted, second will be appended verbatim
    • Object -
      • Raw will be added verbatim without quoting
      • Everything else is ignored, and if raw is not set, the query will fail
    • Sequelize.fn and Sequelize.col returns functions and quoted column names

    Sometimes you might be expecting a massive dataset that you just want to display, without manipulation. For each row you select, Sequelize creates an instance with functions for update, delete, get associations etc. If you have thousands of rows, this might take some time. If you only need the raw data and don't want to update anything, you can do like this to get the raw data.

    1. // Are you expecting a massive dataset from the DB,
    2. // and don't want to spend the time building DAOs for each entry?
    3. // You can pass an extra query option to get the raw data instead:
    4. Project.findAll({ where: { ... }, raw: true })

    count - Count the occurrences of elements in the database

    There is also a method for counting database objects:

    1. Project.count().then(c => {
    2.   console.log("There are " + c + " projects!")
    3. })
    5. Project.count({ where: {'id': {[Op.gt]: 25}} }).then(c => {
    6.   console.log("There are " + c + " projects with an id greater than 25.")
    7. })

    max - Get the greatest value of a specific attribute within a specific table

    And here is a method for getting the max value of an attribute

    1. /*
    2.   Let's assume 3 person objects with an attribute age.
    3.   The first one is 10 years old,
    4.   the second one is 5 years old,
    5.   the third one is 40 years old.
    6. */
    7. Project.max('age').then(max => {
    8.   // this will return 40
    9. })
    11. Project.max('age', { where: { age: { [Op.lt]: 20 } } }).then(max => {
    12.   // will be 10
    13. })

    And here is a method for getting the min value of an attribute:

    1. /*
    2.   Let's assume 3 person objects with an attribute age.
    3.   The first one is 10 years old,
    4.   the second one is 5 years old,
    5.   the third one is 40 years old.
    6. */
    7. Project.min('age').then(min => {
    8.   // this will return 5
    9. })
    11. Project.min('age', { where: { age: { [Op.gt]: 5 } } }).then(min => {
    12. })

    sum - Sum the value of specific attributes

    In order to calculate the sum over a specific column of a table, you canuse the sum method.