Javascript API

The javascript API integrates seamlessly with knex. GQL converts both string and JSON filters into where clauses which are then applied to a knex connection.

The JSON API is valuable because it allows queries to be checked, sanitized or filtered before execution for safety reasons.

Basic Usage

var knex = require('knex'),
     gql = require('gql');

// Connect knex to our database
knex = knex({
    client: 'sqlite3',
    connection: {filename: ':memory:'}
});

// Execute a query
// This translates into `SELECT * FROM posts WHERE title='Hello World!'`

// String API
gql.parse('title:\'Hello World!\'').applyTo(knex('posts')).select();

// equivalent JSON API
gql.parse({title: 'Hello World!'}).applyTo(knex('posts')).select();

API

.parse(<string> or JSON)

Interprets a string or JSON object into an object that can be applied to a knex connection by calling .applyTo().

---

.applyTo(<knex>)

Applies the query logic interpreted from .parse() to a knex connection. Returns the knex object.

Example:

var theQuery = gql.parse('title:\'Hello World!\''});
var knexQuery = theQuery.applyTo(knex('posts'));

// Executes "SELECT * FROM posts WHERE title=\'Hello World!\'";
var resultsPromise = knexQuery.select();

The object returned from .applyTo() is the actual knex object passed into it. So you have full access to the entire knex api for joins, limit, orderBy, etc.

---

.relations()

Returns the names of all tables referenced in the string or JSON passed into .parse() as an array of strings. This is handy when working with queries and/or object models that necessitate table joins.

Example:

gql.parse('posts.title:\'Hello World!\'',comments.created_at:>\'2016-01-01\'}).relations(); // returns ['posts', 'comments'];