Skip to content

Latest commit

 

History

History
105 lines (69 loc) · 4.04 KB

overview.md

File metadata and controls

105 lines (69 loc) · 4.04 KB

Overview

Links

Glossary

Datastores
Term Definition
record The basic unit of data in Waterline; a dictionary with multiple keys. Always contains a primary key field (e.g. id: 7). Equivalent to a SQL row or a Mongo document.
primary key A record's unique identifier. Always either an integer or a string.
field A key/value pair stored as part of a record (e.g. title:'Robinson Crusoe'). The key (left-hand side) is a column name and the value (right-hand side) is any value compatible with the database.
primary key field The key/value pair stored as part of a record (e.g. id:7) which uniquely identifies it in the table.
column name The name of a key which is present in all records in a particular table. Equivalent to a SQL column name.
table A set of (at least partially) homogeneous records. Equivalent to a SQL table or Mongo collection.
datastore A set of tables. Equivalent to a SQL or Mongo "database".
Statements
Term Definition
statement e.g. { select: ['title', 'author'], from: 'books', where: {title: 'robinson crusoe'} }
clause e.g. from: 'books' or select: ['title', 'author'].
predicate e.g. title = 'robinson crusoe'
expression e.g. 'robinson crusoe'

Extensions to the Specification

Adapters are free to implement extensions to RQL syntax, provided those extensions are in the form of additional properties within prescribed namespaces.

Example: Postgresql schemas

PostgreSQL "schemas" are custom to Postgres. Neither MySQL nor MongoDB supports anything like them. And yet they are more than a namespace or table prefix. To add to the complexity, "schema" is an extremely overloaded term.

Let's use "schemas" as a test case for passing adapter-specific metadata through RQL:

{
  select: '*',
  from: 'books',
  opts: {
    schema: 'public'
  }
}

Outputs:

-- PostgreSQL
select * from "public"."books"
// MongoDB    
db.books.find({}, {})

Notice that the generated Mongo operation ignores the "schema". If Mongo had its own concept of a schema, it might handle it completely differently.

What about an operation not supported by RQL at all?

Some operations have a sole purpose which is not a feature not provided by RQL out of the box (i.e. perhaps it is database-specific, or just a rare query). These types of operations are achievable using the standard native query machine or get-connection machine.

In addition, mp-postgresql might also choose to a non-standard machine for the use case. This is totally fine... as long as the non-standard machine follow conventions of the rest of the standardized machines in the pack; e.g.:

var Postgresql = require('machinepack-postgresql');

Postgresql.getConnection({ connectionString: '...' }).exec({
  error: function(err) { /* ... */ },
  success: function (connection){
    Postgresql.createSchema({ connection: connection, name: 'dogpark' }).exec({
      error: function(err) { /* ... */ },
      success: function () {
        Postgresql.releaseConnection({ connection: connection }).exec({
          error: function (err) { /* ... */ },
          success: function () { /* ... */ }
        });
      }
    })
  }
});