Merge pull request #3585 from sequelize/jsonb-docs

JSONB (and more) documentation

docs/docs-generator.js

@@ -23,6 +23,7 @@ if (program.file) {
     {file:'lib/sequelize.js', output: 'sequelize'},
     {file:'lib/sequelize.js', output: 'sequelize'},
     {file:'lib/instance.js', output: 'instance'},
     {file:'lib/instance.js', output: 'instance'},
     {file:'lib/model.js', output: 'model'},
     {file:'lib/model.js', output: 'model'},
+    {file:'lib/querying.js', output: 'querying'},
     {file:'lib/hooks.js', output: 'hooks'},
     {file:'lib/hooks.js', output: 'hooks'},
     {file:'lib/associations/mixin.js', output: 'associations'},
     {file:'lib/associations/mixin.js', output: 'associations'},
     {file:'lib/promise.js', output: 'promise'},
     {file:'lib/promise.js', output: 'promise'},

docs/docs/models.md

@@ -80,6 +80,9 @@ Sequelize.BOOLEAN                     // TINYINT(1)
 Sequelize.ENUM('value 1', 'value 2')  // An ENUM with allowed values 'value 1' and 'value 2'
 Sequelize.ENUM('value 1', 'value 2')  // An ENUM with allowed values 'value 1' and 'value 2'
 Sequelize.ARRAY(Sequelize.TEXT)       // Defines an array. PostgreSQL only.
 Sequelize.ARRAY(Sequelize.TEXT)       // Defines an array. PostgreSQL only.
 
 
+Sequelize.JSON                        // JSON column. PostgreSQL only.
+Sequelize.JSONB                       // JSONB column. PostgreSQL only.
+
 Sequelize.BLOB                        // BLOB (bytea for PostgreSQL)
 Sequelize.BLOB                        // BLOB (bytea for PostgreSQL)
 Sequelize.BLOB('tiny')                // TINYBLOB (bytea for PostgreSQL. Other options are medium and long)
 Sequelize.BLOB('tiny')                // TINYBLOB (bytea for PostgreSQL. Other options are medium and long)
 Sequelize.UUID                        // UUID datatype for PostgreSQL and SQLite, CHAR(36) BINARY for MySQL (use defaultValue: Sequelize.UUIDV1 or Sequelize.UUIDV4 to make sequelize generate the ids automatically)
 Sequelize.UUID                        // UUID datatype for PostgreSQL and SQLite, CHAR(36) BINARY for MySQL (use defaultValue: Sequelize.UUIDV1 or Sequelize.UUIDV4 to make sequelize generate the ids automatically)
@@ -841,6 +844,45 @@ To recap, the elements of the order / group array can be the following
   * Everything else is ignored, and if raw is not set, the query will fail
   * Everything else is ignored, and if raw is not set, the query will fail
 * Sequelize.fn and Sequelize.col returns functions and quoted cools
 * Sequelize.fn and Sequelize.col returns functions and quoted cools
 
 
+### Indexes
+Sequelize supports adding indexes to the model definition which will be created during `Model.sync()` or `sequelize.sync`.
+
+```js
+sequelize.define('User', {}, {
+  indexes: [
+    // Create a unique index on email
+    {
+      unique: true,
+      fields: ['email']
+    },
+
+    // Creates a gin index on data with the jsonb_path_ops operator
+    {
+      fields: ['data'],
+      using: 'gin',
+      operator: 'jsonb_path_ops'
+    },
+
+    // By default index name will be [table]_[fields]
+    // Creates a multi column partial index
+    {
+      name: 'public_by_author',
+      fields: ['author', 'status'],
+      where: {
+        status: 'public'
+      }
+    },
+
+    // A BTREE index with a ordered field
+    {
+      name: 'title_index',
+      method: 'BTREE',
+      fields: ['author', {attribute: 'title', collate: 'en_US', order: 'DESC', length: 5}]
+    }
+  ]
+})
+```
+
 ### Raw queries
 ### Raw queries
 
 
 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 updat, 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.
 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 updat, 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.

docs/docs/querying.md

+## Where
+
+Whether you are querying with findAll/find or doing bulk updates/destroys you can pass a `where` object to filter the query.
+
+`where` generally takes an object from attribute:value pairs, where value can be primitives for equality matches or keyed objects for other operators.
+
+It's also possible to generate complex AND/OR conditions by nesting sets of `$or` and `$and`.
+
+### Basics
+```
+Post.findAll({
+  where: {
+    authorId: 2
+  }
+});
+// SELECT * FROM post WHERE authorId = 2
+
+Post.findAll({
+  where: {
+    authorId: 12,
+    status: active
+  }
+});
+// SELECT * FROM post WHERE authorId = 12
+
+Post.destroy({
+  where: {
+    status: 'inactive'
+  }
+});
+// DELETE FROM post WHERE status = 'inactive';
+
+Post.update({
+  deletedAt: null,
+}, {
+  where: {
+    deletedAt: {
+      $ne: null
+    }
+  }
+});
+// UPDATE post SET updatedAt = null WHERE updatedAt NOT NULL;
+```
+
+### Operators
+
+```js
+$gt: 6,                // id > 6
+$gte: 6,               // id >= 6
+$lt: 10,               // id < 10
+$lte: 10,              // id
+$ne: 20,               // id != 20
+$between: [6, 10],     // BETWEEN 6 AND 10
+$notBetween: [11, 15], // NOT BETWEEN 11 AND 15
+$in: [1, 2],           // IN [1, 2]
+$like: '%hat',         // LIKE '%hat'
+$notLike: '%hat'       // NOT LIKE '%hat'
+$iLike: '%hat'         // ILIKE '%hat' (case insensitive)
+$notILike: '%hat'      // NOT ILIKE '%hat'
+$overlap: [1, 2]       // && [1, 2] (PG array overlap operator)
+$contains: [1, 2]      // @> [1, 2] (PG array contains operator)
+$contained: [1, 2]     // <@ [1, 2] (PG array contained by operator)
+$any: [2,3]            // ANY ARRAY[2, 3]::INTEGER
+```
+
+### Combinations
+```js
+{
+  rank: {
+    $or: {
+      $lt: 100,
+      $eq: null
+    }
+  }
+}
+// rank < 1000 OR rank IS NULL
+
+{
+  createdAt: {
+    $lt: new Date(),
+    $gt: new Date(new Date() - 24 * 60 * 60 * 1000)
+  }
+}
+// createdAt < [timestamp] AND createdAt > [timestamp]
+
+{
+  $or: [
+    {
+      title: {
+        $like: 'Boat%'
+      }
+    },
+    {
+      description: {
+        $like: '%boat%'
+      }
+    }
+  ]
+}
+// title LIKE 'Boat%' OR description LIKE '%boat%'
+```
+
+### JSONB
+
+JSONB can be queried in three different ways.
+
+#### Nested object
+```js
+{
+  meta: {
+    video: {
+      url: {
+        $ne: null
+      }
+    }
+  }
+}
+```
+
+#### Nested key
+```js
+{
+  "meta.audio.length": {
+    $gt: 20
+  }
+}
+```
+
+#### Containment
+```js
+{
+  "meta": {
+    $contains: {
+      site: {
+        url: 'http://google.com'
+      }
+    }
+  }
+}
+```
+
+## Pagination / Limiting
+```js
+// Fetch 10 instances/rows
+Project.findAll({ limit: 10 })
+
+// Skip 8 instances/rows
+Project.findAll({ offset: 8 })
+
+// Skip 5 instances and fetch the 5 after that
+Project.findAll({ offset: 5, limit: 5 })
+```
+
+## Ordering
+
+`order` takes an array of items to order the query by. Generally you will want to use a tuple/array of either attribute, direction or just direction to ensure proper escaping.
+
+```js
+something.find({
+  order: [
+    // Will escape username and validate DESC against a list of valid direction parameters
+    ['username', 'DESC'],
+
+    // Will order by max(age)
+    sequelize.fn('max', sequelize.col('age')),
+
+    // Will order by max(age) DESC
+    [sequelize.fn('max', sequelize.col('age')), 'DESC'],
+
+    // Will order by  otherfunction(`col1`, 12, 'lalala') DESC    
+    [sequelize.fn('otherfunction', sequelize.col('col1'), 12, 'lalala'), 'DESC'],
+
+    // Both the following statements will be treated literally so should be treated with care
+    'name',
+    'username DESC'
+  ]
+})
+```
\ No newline at end of file