add raw-queries recipe to new docs

koskimas · koskimas · commit 0299b3e28a7b · 2018-09-16T20:18:13.000+03:00
diff --git a/newDoc/.vuepress/config.js b/newDoc/.vuepress/config.js
@@ -15,6 +15,11 @@ module.exports = {
       {
         text: 'API Reference',
         link: '/api/model',
+      },
+
+      {
+        text: 'Recipe Book',
+        link: '/recipes/raw-queries',
       }
     ],
 
@@ -45,6 +50,14 @@ module.exports = {
           'query-builder',
           'types'
         ]
+      }],
+
+      '/recipes/': [{
+        title: 'Recipes',
+        collapsable: false,
+        children: [
+          'raw-queries'
+        ]
       }]
     }
   },
diff --git a/newDoc/guide/contributing.md b/newDoc/guide/contributing.md
@@ -26,25 +26,17 @@ For a pull request to get merged it needs to have the following things:
 
 ## Development setup
 
-1. Fork objection in github
+1. **Fork objection in github**
 
-2. Clone objection
-
-3. Install MySQL and PostgreSQL or alternatively run `docker-compose up` in the repo root
-
-4. Create test users and databases
-
-5. Run `npm test` in objection's root to see if everything works.
-
-6. Run `npm run docs:dev` and goto http://localhost:8080 to see the generated documentation site when you change the markdown files in the `doc` folder.
-
-cloning:
+2. **Clone objection**
 
 ```shell
 git clone git@github.com:<your-account>/objection.js.git objection
 ```
 
-creating users and databases for the tests:
+3. **Install MySQL and PostgreSQL or alternatively run `docker-compose up` in the repo root**
+
+4. **Create test users and databases**
 
 ```shell
 psql -U postgres -c "CREATE USER objection SUPERUSER"
@@ -54,6 +46,10 @@ mysql -u root -e "GRANT ALL PRIVILEGES ON *.* TO objection"
 mysql -u root -e "CREATE DATABASE objection_test"
 ```
 
+5. **Run `npm test` in objection's root to see if everything works.**
+
+6. **Run `npm run docs:dev` and goto http://localhost:8080 to see the generated documentation site when you change the markdown files in the `doc` folder.**
+
 You can run the tests on a subset of databases by setting the `DATABASES` env variable
 
 ```shell
diff --git a/newDoc/recipes/README.md b/newDoc/recipes/README.md
diff --git a/newDoc/recipes/raw-queries.md b/newDoc/recipes/raw-queries.md
@@ -0,0 +1,43 @@
+# Raw queries
+
+To mix raw SQL with queries, use the [raw](/api/objection.html#raw) function from the main module or the [Model.raw()](/api/model.html#static-raw) method of any [Model](/api/model.html) subclass. The only difference between these two is that the [raw](/api/objection.html#raw) function from the main module doesn't depend on knex where as [Model.raw()](/api/model.html#static-raw) will throw if the model doesn't have a knex instance installed. Both of these functions work just like the [knex's raw method](http://knexjs.org/#Raw). And of course you can just use [knex.raw()](http://knexjs.org/#Raw).
+
+There are also some helper methods such as [whereRaw](/api/query-builder.html#whereraw) in the [QueryBuilder](/api/query-builder.html).
+
+## Examples
+
+```js
+const { raw } = require('objection');
+
+const childAgeSums = await Person
+  .query()
+  .select(raw('coalesce(sum(??), 0) as ??', ['age', 'childAgeSum']))
+  .where(raw(`?? || ' ' || ??`, 'firstName', 'lastName'), 'Arnold Schwarzenegger')
+  .orderBy(raw('random()'));
+
+console.log(childAgeSums[0].childAgeSum);
+```
+
+```js
+const childAgeSums = await Person
+  .query()
+  .select(raw('coalesce(sum(??), 0) as ??', ['age', 'childAgeSum']))
+  .groupBy('parentId');
+
+console.log(childAgeSums[0].childAgeSum);
+```
+
+Raw binding arguments can be other [raw](/api/objection.html#raw) instances, [QueryBuilders](/api/query-builder.html) or pretty much anything you can think of.
+
+```js
+const { raw, ref } = require('objection');
+
+const childAgeSums = await Person
+  .query()
+  .alias('p')
+  .select(raw('array(?) as childIds', [
+    Person.query()
+      .select('id')
+      .where('id', ref('p.parentId')).
+  ]);
+```
