Nodes

These are the classes that represent nodes in the AST for a SQL statement. Application code should very rarely have to deal with these classes directly; Instead, the APIs exposed by the various query manager classes are intended to cover the majority of use-cases.

However, in the spirit of “making hard things possible”, all of AST nodes are exported from this module so you can constructed and assemble them manually if you need to.

class Node

(Empty) base Node class

class ValueNode extends Node

A ValueNode is a literal string that should be printed unescaped.

class IntegerNode extends ValueNode

A ValueNode that validates it’s input is an integer.

class Identifier extends ValueNode

An identifier is a column or relation name that may need to be quoted.

class NodeSet extends Node

A set of nodes joined together by @glue

method NodeSet.constructor(nodes, glue)
Parameters:
  • @nodes – A list of child nodes.
  • glue – A string that will be used to join the nodes when compileing
method NodeSet.addNode(node)

Add a new Node to the end of this set

class ParenthesizedNodeSet extends NodeSet

A NodeSet wrapped in parenthesis.

class SqlFunction extends Node

Includes ComparableMixin

class Parameter extends ValueNode

Like a ValueNode, but will render as a bound parameter place-holder (e.g. $1) and it’s value will be collected by the dialect when compiling.

class Relation extends Identifier

A relation node represents a table name or alias in a statement.

method Relation.ref()

Return the table name. Aliased tables return the alias name.

method Relation.project(field)

Return a new Column of field from this table.

class RelationAlias extends AbstractAlias

An aliased Relation

class Field extends Identifier

A column name

class Column extends FixedNodeSet

Includes ComparableMixin

method Column.as(alias)

Return an aliased version of this column.

class ColumnSet extends NodeSet

The list of projected columns in a query

class RelationSet extends NodeSet

Manages a set of relations and exposes methods to find them by alias.

class Select extends Statement

The root node of a SELECT query

class Update extends Statement

The root node of an UPDATE query

class Insert extends Statement

The root node of an INSERT query

method Insert.addRowObject(row)

Add a row from an object. This will set the column list of the query if it isn’t set yet. If it is set, then only keys matching the existing column list will be inserted.

class Delete extends Statement

The root node of a DELETE query

class ComparableMixin

A mixin that adds comparison methods to a class. Each of these comparison methods will yield a new AST node comparing the invocant to the argument.

method ComparableMixin.eq(other)

this = other

method ComparableMixin.ne(other)

this != other

method ComparableMixin.gt(other)

this > other

method ComparableMixin.lt(other)

this < other

method ComparableMixin.lte(other)

this <= other

method ComparableMixin.gte(other)

this >= other

method ComparableMixin.compare(op, other)

this op other DANGER op is NOT escaped!

function toParam(it)

Return a Node that can be used as a parameter.

  • SelectQuery instances will be treated as un-named sub queries,
  • Node instances will be returned unchanged.
  • Arrays will be turned into a Tuple instance.

All other types will be wrapped in a Parameter instance.

function toRelation(it)

Transform it into a Relation instance.

This accepts strings, ``Relation` and Alias instances, and objects with a single key-value pair, which will be turned into an Alias instance.

Examples:

toRelation('table1')     == new Relation('table1')
toRelation(t1: 'table1') == new Alias(new Relation('table1'), 't1')

Throws Errors if the input is not valid.

function toColumn(relation, field)

Create a new Column instance.

The first argument is optional and specifies a table (or alias) name. Alternatively, you can specify the relation name and field with a single dot-separated string:

toColumn('departments.name') == toColumn('departments', 'name')

Either argument can be an pre-constructed node object (of the correct type).

function sqlFunction(name, args)

Create a new SQL function call node. For example:

count = g.sqlFunction(‘count’, [g.text(‘*’)])

function func(name)

Create a factory for calling the given SQL function. Example:

count = g.func('count')
count(g.text('*'))

The returned factory accepts any number of parameters:

substringIndex = g.func('SUBSTRING_INDEX')
substringIndex(g.text('mycol'), '-', 1)  # SUBSTRING_INDEX(mycol, '-', 1)
function getAlias(o)

Check if o is an object literal representing an alias, and return the alias name if it is.

function text(rawSQL, bindVals)

Construct a node with a raw SQL string and (optionally) parameters. Useful for when you want to construct a query that is difficult or impossible with the normal APIs. [1]

To use bound parameters in the SQL string, use $ prefixed names, and pass a bindVals argument with corresponding property names. For example, SUDQuery.where doesn’t (currently) support the SQL BETWEEN operator, but if you needed it, you could use text:

function peopleInWeightRange (min, max, callback) {
  return select('people')
    .where(text("weight BETWEEN $min AND $max", {min: min, max: max}))
    .execute(callback)
}

Because javascript doesn’t distinguish between array indexing and property access, it can be more clear to use numbered parameters for such short snippets:

function peopleInWeightRange (min, max, callback) {
  return select('people')
    .where(text("weight BETWEEN $0 AND $1", [min, max]))
    .execute(callback)
}
[1]If you find yourself using this function often, please open an issue on Github with details on your use case so gesundheit can support it more elegantly.
function binaryOp(left, op, right)

Create a new Binary node:

binaryOp('hstore_column', '->', toParam(y))
# hstore_column -> ?

This is for special cases, normally you want to use the methods from ComparableMixin.

function exists(subquery)

Create an EXISTS (<subquery>) node for where

function notExists(subquery)

Create a NOT EXISTS (<subquery>) node for where

function tuple(input)

Create a new Tuple from an array of nodes. Any item in the array that is not an instanceof Node will be turned into a parameter with toParam.