Class Index | File Index

## Classes

- _Association
- _global_
- Dataset
- ManyToMany
- ManyToOne
- MayToOne
- Migrations
- Model
- moose
- moose.adapters
- moose.adapters.client.Client
- moose.adapters.client.ConnectionPool
- moose.adapters.client.mysql.ConnectionPool
- moose.adapters.client.mysql.Query
- moose.adapters.client.mysql.TransactionQuery
- moose.adapters.mysql
- moose.adapters.mysql.types
- moose.plugins
- moose.plugins.AssociationPlugin
- moose.plugins.CachePlugin
- moose.plugins.QueryPlugin
- moose.plugins.TimeStampPlugin
- moose.Table
- OneToMany
- SQL
- Type

# Class moose.plugins.QueryPlugin

Adds query support to a model. The QueryPlugin exposes methods to save, update, create, and delete. The plugin also exposes static functions to query Models. The functions exposed on class are.

- filter
- findById
- count
- join
- where
- select
- all
- forEach
- first
- one
- last

All queries require an action to be called on them before the results are fetched. The action methods are :

- all
- forEach
- first
- one
- last

The action items accept a callback that will be called with the results. They also return a promise that will be called with the results.

Assume we have an Employee model.

first Get the record in a dataset, this query does not require an action method

             Employee.first() => select * from employee limit 1

filter Sets the where clause on a query. See Dataset

             //Equality Checks
             Employee.filter({eid : 1})
                     => select * from employee where eid = 1
             Employee.filter({eid : {gt : 1}})
                     => select * from employee where eid > 1
             Employee.filter({eid : {gte : 1}})
                     => select * from employee where eid >= 1
             Employee.filter({eid : {lt : 1}})
                     => select * from employee where eid < 1
             Employee.filter({eid : {lte : 1}})
                     => select * from employee where eid <= 1
             //Nested query in filter
             Employee.filter({eid : {gt : 1}, lastname : "bob"})
                     => select * from employee where eid > 1 and lastname = 'bob';
             Employee.filter({eid : [1,2,3], lastname : "bob"})
                     => select * from employee where eid in (1,2,3) and lastname = 'bob'

findById Find a record in a dataset by id, this query does not require an action method

             Employee.findById(1) => select * from employee where eid = 1

count Find the number of records in a dataset, this query does not require an action method

             Employee.count() => select count(*) as count from employee
             Employee.filter({eid : {gte : 1}}).count()
                     => select count(*) as count from employee  where eid > 1

join Get Join two models together, this will not create model instances for the result.

             Employee.join("words", {eid : "eid"}).where({"employee.eid" : 1})
                     => select * from employee inner join works on employee.id=works.id where employee.eid = 1

Where Sets the where clause on a query. See Dataset

             //Equality Checks
             Employee.where({eid : 1})
                     => select * from employee where eid = 1
             Employee.where({eid : {gt : 1}})
                     => select * from employee where eid > 1
             Employee.where({eid : {gte : 1}})
                     => select * from employee where eid >= 1
             Employee.where({eid : {lt : 1}})
                     => select * from employee where eid < 1
             Employee.where({eid : {lte : 1}})
                     => select * from employee where eid <= 1
             //Nested query in filter
             Employee.where({eid : {gt : 1}, lastname : "bob"})
                     => select * from employee where eid > 1 and lastname = 'bob';
             Employee.where({eid : [1,2,3], lastname : "bob"})
                     => select * from employee where eid in (1,2,3) and lastname = 'bob'

select Selects only certain columns to return, this will not create model instances for the result.

             Employee.select(eid).where({firstname : { gt : "bob"}})
                     => select eid from employee where firstname > "bob"

all, foreach, first, one, last These methods all act as action methods and fetch the results immediately. Each method accepts a query, callback, and errback. The methods return a promise that can be used to listen for results also.

             Employee.all()
                     => select * from employee
             Employee.forEach(function(){})
                     => select * from employee
             Employee.forEach({eid : [1,2,3]}, function(){}))
                     => select * from employee where eid in (1,2,3)
             Employee.one()
                     => select * from employee limit 1

Defined in: query.js.

Class Summary
Constructor Attributes | Constructor Name and Description
--- | ---
| moose.plugins.QueryPlugin()

Method Summary
Method Attributes | Method Name and Description
--- | ---
<static> | moose.plugins.QueryPlugin.all(callback, errback) Retrieve all rows from the query.
<static> | moose.plugins.QueryPlugin.count(callback, errback) Retrieve the number of records in the database.
<static> | moose.plugins.QueryPlugin.filter(options, hydrate) Filter a model to return a subset of results.
<static> | moose.plugins.QueryPlugin.findById(id) Retrieves a record by the primarykey of a table.
<static> | moose.plugins.QueryPlugin.first(callback, errback) Retrieve the first result from an ordered query.
<static> | moose.plugins.QueryPlugin.forEach(callback, errback, scope) Provide Array style looping a query results.
<static> | moose.plugins.QueryPlugin.join(table, options) This is an alias for an inner join.
<static> | moose.plugins.QueryPlugin.last(callback, errback) Retrieve the last result from an ordered query.
<static> | moose.plugins.QueryPlugin.one(callback, errback) Retrieve one row result from the query.
| reload() Force the reload of the data for a particular model instance.
<static> | moose.plugins.QueryPlugin.remove(q, errback) Remove rows from the Model.
| remove(errback) Remove this model.
<static> | moose.plugins.QueryPlugin.save(record, errback) Save either a new model or list of models to the database.
| save(options, errback) Save a model with new values.
<static> | moose.plugins.QueryPlugin.select(columns, options) Use to return particular columns from a query, i.e.
| toSql() Serializes all values in this model to the sql equivalent.
| update(options, errback) Update a model with new values.
<static> | moose.plugins.QueryPlugin.update(vals, options, callback, errback) Update multiple rows with a set of values.
<static> | moose.plugins.QueryPlugin.where(options) Set the where clause of the query.

Class Detail
moose.plugins.QueryPlugin()
Method Detail
<static> {comb.Promise} moose.plugins.QueryPlugin.all(callback, errback)
Retrieve all rows from the query.
Defined in: dataset.js.

    dataset.all(function(r){
        Do something....
    }, function(err){
        Do something...
    });

    //OR

    dataset.all().then(function(r){
        Do something....
    }, function(err){
        Do something...
    });

Parameters:
{Function} callback Optional
  executed with the results.
{Function} errback Optional
  executed if an error occurs.

Returns:
  {comb.Promise} called back with results or the error if one occurs.

<static> {comb.Promise} moose.plugins.QueryPlugin.count(callback, errback)
Retrieve the number of records in the database.

Parameters:
{Function} callback Optional
  function to execute with the result
{Function} errback Optional
  funciton to execute if the operation fails

Returns:
  {comb.Promise} called back with the result, or errors if the operation fails.

<static> {Dataset} moose.plugins.QueryPlugin.filter(options, hydrate)
Filter a model to return a subset of results. SQL#find

This function requires all, forEach, one, last, or count to be called inorder for the results to be fetched

Parameters:
{Object} options Optional
  query to filter the dataset by.
{Boolean} hydrate Optional, Default: true
  if true model instances will be the result of the query, otherwise just the results will be returned.

Returns:
  {Dataset} A dataset to query, and or fetch results.

<static> {comb.Promise} moose.plugins.QueryPlugin.findById(id)
Retrieves a record by the primarykey of a table.

Parameters:
{*} id
  the primary key record to find.

Returns:
  {comb.Promise} called back with the record or null if one is not found.

<static> {comb.Promise} moose.plugins.QueryPlugin.first(callback, errback)
Retrieve the first result from an ordered query.
Defined in: dataset.js.

    dataset.first(function(r){
        Do something....
    }, function(err){
        Do something...
    });

    //OR

    dataset.first().then(function(r){
        Do something....
    }, function(err){
        Do something...
    });

Parameters:
{Function} callback Optional
  executed with the row
{Function} errback Optional
  executed if an error occurs.

Returns:
  {comb.Promise} called back with result or the error if one occurs.

<static> {comb.Promise} moose.plugins.QueryPlugin.forEach(callback, errback, scope)
Provide Array style looping a query results.
Defined in: dataset.js.

    dataset.forEach(function(r, i){
        console.log("Row %d", i);
    });

Parameters:
{Function} callback Optional
  executed for each row returned.
{Function} errback Optional
  executed if an error occurs.
{Object} scope Optional
  scope to execute the callback and errback in.

Returns:
  {comb.Promise} called back with results or the error if one occurs.

<static> {SQL} moose.plugins.QueryPlugin.join(table, options)
This is an alias for an inner join.
Defined in: sql.js.

    //select * from test inner join test2 on test.id=test2.id
     sql.join("test2", {id : "id"});
    //select * from test inner join test2 using (id, name)
     sql.join("test2", ["id", "name"]);
     //select * from test inner join test2 on test.id=test2.id left join test3 using (name)
    sql.join("test2", {id : "id"}).leftJoin("test3", ["name"]);
    //select * from test inner join test2 using (id, name) natural join test3
    sql.join("test2", ["id", "name"]).naturalJoin("test3
    //select * from test inner join test2 on test.id=test2.id left join test3 using (name) where x = 2 or x = 3
    sql.join("test2", {id : "id"}).leftJoin("test3", ["name"]).eq({x : 2}).or({x : 3});

Parameters:
{String|SQL} table
  the table or SQL clause that specifies the joining table.
{Array|Object} options
  When an array is passed in the a using clause is used to specify the columns to join on, of an object is passed in then it is the same as using an on clause;

Returns:
  {SQL} this to allow chaining of query elements.

<static> {comb.Promise} moose.plugins.QueryPlugin.last(callback, errback)
Retrieve the last result from an ordered query. If the query is not ordered then the result is ambiguous.
Defined in: dataset.js.

    dataset.last(function(r){
        Do something....
    }, function(err){
        Do something...
    });

    //OR

    dataset.last().then(function(r){
        Do something....
    }, function(err){
        Do something...
    });

Parameters:
{Function} callback Optional
  executed with the row
{Function} errback Optional
  executed if an error occurs.

Returns:
  {comb.Promise} called back with result or the error if one occurs.

<static> {comb.Promise} moose.plugins.QueryPlugin.one(callback, errback)
Retrieve one row result from the query.
Defined in: dataset.js.

    dataset.one(function(r){
        Do something....
    }, function(err){
        Do something...
    });

    //OR

    dataset.one().then(function(r){
        Do something....
    }, function(err){
        Do something...
    });

Parameters:
{Function} callback Optional
  executed with the row
{Function} errback Optional
  executed if an error occurs.

Returns:
  {comb.Promise} called back with result or the error if one occurs.

{comb.Promise} reload()
Force the reload of the data for a particular model instance.

    myModel.reload().then(function(myModel){
       //work with this instance
    });

Returns:
  {comb.Promise} called back with the reloaded model instance.

<static> {comb.Promise} moose.plugins.QueryPlugin.remove(q, errback)
Remove rows from the Model.

Parameters:
{Object} q Optional
  query to filter the rows to remove
{Function} errback Optional
  function to call if the removal fails.

Returns:
  {comb.Promise} called back when the removal completes.

{comb.Promise} remove(errback)
Remove this model.

Parameters:
{Function} errback
  called in the deletion fails.

Returns:
  {comb.Promise} called back after the deletion is successful

<static> {comb.Promise} moose.plugins.QueryPlugin.save(record, errback)
Save either a new model or list of models to the database.

    //Save a group of records
    MyModel.save([m1,m2, m3]);

    Save a single record
    MyModel.save(m1);

Parameters:
{Array|Object} record
  the record/s to save to the database
{Function} errback Optional
  function to execute if the save fails

Returns:
  {comb.Promise} called back with the saved record/s.

{comb.Promise} save(options, errback)
Save a model with new values.

    someModel.save({
         myVal1 : "newValue1",
         myVal2 : "newValue2",
         myVal3 : "newValue3"
         }).then(..do something);

    //or

    someModel.myVal1 = "newValue1";
    someModel.myVal2 = "newValue2";
    someModel.myVal3 = "newValue3";

    someModel.save().then(..so something);

Parameters:
{Object} options Optional
  values to save this model with
{Function} errback Optional
  function to call if the save fails, the promise will errback also if it fails.

Returns:
  {comb.Promise} called on completion or error of save.

<static> {SQL} moose.plugins.QueryPlugin.select(columns, options)
Use to return particular columns from a query, i.e. select clause in sql.
Defined in: sql.js.

    var sql = new SQL("test", db);

    //select a, b, c from testTable;
    sql.select(["a", "b", "c"]);
    //select a from testTable;
    sql.select("a");
    //select a from test where x = 1 and y >=1 and y <= 10
    sql.select("a", {x : 1, y : {between : [1,10]}});

Parameters:
{String|Array} columns
  the columns to select
{Object} options
  query SQL#find

Returns:
  {SQL} this to allow chaining of query elements.

toSql()
Serializes all values in this model to the sql equivalent.

{comb.Promise} update(options, errback)
Update a model with new values.

    someModel.update({
         myVal1 : "newValue1",
         myVal2 : "newValue2",
         myVal3 : "newValue3"
         }).then(..do something);

    //or

    someModel.myVal1 = "newValue1";
    someModel.myVal2 = "newValue2";
    someModel.myVal3 = "newValue3";

    someModel.update().then(..so something);

Parameters:
{Object} options Optional
  values to update this model with
{Function} errback Optional
  function to call if the update fails, the promise will errback also if it fails.

Returns:
  {comb.Promise} called on completion or error of update.

<static> {comb.Promise|Dataset} moose.plugins.QueryPlugin.update(vals, options, callback, errback)
Update multiple rows with a set of values.

Parameters:
{Object} vals
  the values to set on each row.
{Object} options Optional
  query to limit the rows that are updated
{Function} callback Optional
  function to call after the update is complete.
{Function} errback Optional
  function to call if the update errors.

Returns:
  {comb.Promise|Dataset} if just values were passed in then a dataset is returned and exec has to be called in order to complete the update. If options, callback, or errback are provided then the update is executed and a promise is returned that will be called back when the update completes.

<static> {SQL} moose.plugins.QueryPlugin.where(options)
Set the where clause of the query. This is different fron find in that it can be used with updates, and deletions.
Defined in: sql.js.

    QUERYING

    var sql = new SQL("test", db);

    //select * from test where id = 1
    sql.where({id : 1});
    //select * from test where id in (1,2,3,4,5)
    sql.where({id : [1,2,3,4,5]});
    //select * from test where x != 0
    sql.where({x : {neq : 0}});
    //select distinct * from test where id = 1
    sql.where({id : 1}).distinct();
    //select * from test where a >= 'b' limit 1
    sql.where({a : {gte : "b"}}).limit(1);
    //select * from test where flag is unknown
    sql.where({flag : {is : "unknown"}});
    //select * from test where flag is not unknown
    sql.where({flag : {isNot : "unknown"}});
    //select * from test where flag is false and flag is not unknown and anotherFlag is null and yetAnotherFlag is not null
    sql.where({flag : {is : false}, flag2 : {isNot : "unknown"}, anotherFlag : {isNull : true}, yetAnotherFlag : {isNotNull : true}});
    //select * from test where firstName like 'bob' and lastName not like 'henry'
    sql.where({firstName : {like : 'bob'}, lastName : {notLike : "henry"}});
    //select * from test where firstName like 'bob' and lastName not like 'henry'
    sql.where({firstName : {like : 'bob'}, lastName : {notLike : "henry"}});

    UPDATES

    //update test set x=1 where x >= 1 and x <= 5
    sql.update({x : 1}).where({x : {between : [1,5]}});

    DELETIONS

    //delete from test where x >= 1 and x <= 5
    sql.remove().where({x : {between : [1,5]}});

Parameters:
{Object} options
  See SQL#find

Returns:
  {SQL} this to allow chaining of query elements.

Documentation generated by JsDoc Toolkit 2.4.0 on Sat Jun 11 2011 03:16:40 GMT-0500 (CDT)