Package Exports

rbql

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (rbql) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

RBQL is both a library and a command line tool which provides SQL-like language with JavaScript expressions

RBQL as browser library
RBQL as Node library
RBQL as command line tool
RBQL language description

Using RBQL as browser library

Installation:

In order to make RBQL work in browser as a library for your App you need just one single file: web_rbql.js To get it you can either use npm:

$ npm install rbql

Or just copy it directly from the repository:

$ wget https://raw.githubusercontent.com/mechatroner/rbql-js/master/web_rbql.js

Now you can just source web_rbql.js and it will work:

<script src="web_rbql.js"></script>

API description

The following two functions are avilable in the browser version:

rbql.table_run(...)
rbql.generic_run(...)

rbql.table_run(...)

Run user query against input array of records and put the result set in the output array:

function table_run(user_query, input_table, output_table, success_handler, error_handler, join_table=null)

Parameters:

user_query: string
query that user of your app manually enters in some kind of input field.
input_table: array
an array with input records
output_table: array
an array where to output records would be pushed
success_handler: function(warnings) a callback which gets called on query success. warnings is an array of warning messages, which can be empty
error_handler: function(error_type, error_msg)
a callback which gets called on query failure. error_type and error_msg are strings.
join_table: array
an array with join table records so that user can use join table B in input queries

rbql.generic_run(...)

Allows to run queries against any kind of structured data.
You will have to implement special wrapper classes for your custom data structures and pass them to the rbql.generic_run(...) function.

function generic_run(user_query, input_iterator, output_writer, success_handler, error_handler, join_tables_registry=null)

Parameters:

user_query: string
query that user of your app manually enters in some kind of input field.
input_iterator: RBQLInputIterator
special object which iterates over input records. E.g. over a remote table
output_writer: RBQLOutputWriter
special object which stores output records somewhere. E.g. to an array
success_handler: function(warnings) a callback which gets called on query success. warnings is an array of warning messages, which can be empty
error_handler: function(error_type, error_msg) a callback which gets called on query failure. error_type and error_msg are strings.
join_tables_registry: RBQLJoinTablesRegistry
special object which provides RBQLInputIterator iterators for join tables (e.g. table "B") which user can refer to in queries.

Examples of RBQLInputIterator, RBQLOutputWriter and RBQLJoinTablesRegistry implementations can be found in RBQL source code

Usage:

"Hello world" web test in RBQL

Very simple test to make sure that RBQL library works:

<!DOCTYPE html>
<html><head>

<script src="web_rbql.js"></script>
<script>
    let output_table = [];
    let error_handler = function(error_type, error_msg) {
        console.log('Error: ' + error_type + ': ' + error_msg);
    }
    let success_handler = function(warnings) {
        console.log('warnings: ' + JSON.stringify(warnings));
        console.log('output table: ' + JSON.stringify(output_table));
    }
    rbql.table_run('select a2 + " test", a1 limit 2', [[1, 'foo'], [2, 'bar'], [3, 'hello']], output_table, success_handler, error_handler);
</script>

<title>RBQL Generic Test</title>
</head>
<body><div><span>Open browser console</span></div></body>
</html>

Save the code above as rbql_test.html; put web_rbql.js in the same folder; open rbql_test.html in your browser and make sure that console output contains the expected result.

"JSFiddle" demo test

A little more advanced, but still very simple demo test with JSFiddle It uses the same web_rbql.js script file.

Using RBQL as Node library

Installation:

$ npm install rbql

API description

The following 3 functions are avilable in Node version:

rbql.csv_run(...)
rbql.table_run(...) - identical to browser version
rbql.generic_run(...) - identical to browser version

rbql.csv_run(...)

Run user query against input_path CSV file and save it as output_path CSV file.

function rbql.csv_run(user_query, input_path, input_delim, input_policy, output_path, output_delim, output_policy, csv_encoding, success_handler, error_handler)

Parameters:

user_query: string
query that user of your application manually enters in some kind of input field.
input_path: string
path of the input csv table
input_delim: string
field separator character in input table
input_policy: string
allowed values: 'simple', 'quoted'
along with input_delim defines CSV dialect of input table. "quoted" means that separator can be escaped inside double quoted fields
output_path: string
path of the output csv table
output_delim: string
same as input_delim but for output table
output_policy: string
same as input_policy but for output table
csv_encoding: string
allowed values: 'binary', 'utf-8'
encoding of input, output and join tables (join table can be defined inside the user query)
success_handler: function(warnings) a callback which gets called on query success. warnings is an array of warning messages, which can be empty
error_handler: function(error_type, error_msg) a callback which gets called on query failure. error_type and error_msg are strings.

Usage:

Example of table_run() usage:

const rbql = require('rbql')

let input_table = [
    ['Roosevelt',1858,'USA'],
    ['Napoleon',1769,'France'],
    ['Dmitri Mendeleev',1834,'Russia'],
    ['Jane Austen',1775,'England'],
    ['Hayao Miyazaki',1941,'Japan'],
];
let user_query = 'SELECT a1, a2 % 1000 WHERE a3 != "USA" LIMIT 3';
let output_table = [];
let error_handler = function(error_type, error_msg) {
    console.log('Error: ' + error_type + ': ' + error_msg);
}
let success_handler = function(warnings) {
    console.log('warnings: ' + JSON.stringify(warnings));
    console.log('output table: ' + JSON.stringify(output_table));
}
rbql.table_run(user_query, input_table, output_table, success_handler, error_handler);

Example of csv_run() usage:

const rbql = require('rbql');

let user_query = 'SELECT a1, parseInt(a2) % 1000 WHERE a3 != "USA" LIMIT 5';
let error_handler = function(error_type, error_msg) {
    console.log('Error: ' + error_type + ': ' + error_msg);
}
let success_handler = function(warnings) {
    if (warnings.length)
        console.log('warnings: ' + JSON.stringify(warnings));
    console.log('output table: output.csv');
}
rbql.csv_run(user_query, 'input.csv', ',', 'quoted', 'output.csv', ',', 'quoted', 'utf-8', success_handler, error_handler);

You can also check rbql-js cli app code as a usage example: rbql-js cli source code

Using RBQL as command line tool

Installation:

To use RBQL as CLI app you need to install it in global (-g) mode:

$ npm install -g rbql

Usage:

$ rbql-js --query "select a1, a2 order by a1" < input.tsv

Usage (interactive mode):

In interactive mode rbql-js will show input table preview so it is easier to type SQL-like query.

$ rbql-js --input input.csv --output result.csv

Language description

Main Features

Use JavaScript expressions inside SELECT, UPDATE, WHERE and ORDER BY statements
Result set of any query immediately becomes a first-class table on it's own
Supports input tables with inconsistent number of fields per record
Output records appear in the same order as in input unless ORDER BY is provided
Each record has a unique NR (line number) identifier
Supports all main SQL keywords
Provides some new useful query modes which traditional SQL engines do not have
Supports both TOP and LIMIT keywords
Supports user-defined functions (UDF)
Works out of the box, no external dependencies

Limitations:

RBQL doesn't support nested queries, but they can be emulated with consecutive queries
Number of tables in all JOIN queries is always 2 (input table and join table), use consecutive queries to join 3 or more tables

Supported SQL Keywords (Keywords are case insensitive)

SELECT
UPDATE
WHERE
ORDER BY ... [ DESC | ASC ]
[ LEFT | INNER ] JOIN
DISTINCT
GROUP BY
TOP N
LIMIT N

All keywords have the same meaning as in SQL queries. You can check them online

Special variables

Variable Name	Variable Type	Variable Description
a1, a2,..., a{N}	string	Value of i-th column
b1, b2,..., b{N}	string	Value of i-th column in join table B
NR	integer	Line number (1-based)
NF	integer	Number of fields in line

UPDATE statement

UPDATE query produces a new table where original values are replaced according to the UPDATE expression, so it can also be considered a special type of SELECT query. This prevents accidental data loss from poorly written queries.
UPDATE SET is synonym to UPDATE, because in RBQL there is no need to specify the source table.

Aggregate functions and queries

RBQL supports the following aggregate functions, which can also be used with GROUP BY keyword:
COUNT(), MIN(), MAX(), SUM(), AVG(), VARIANCE(), MEDIAN(), FOLD()

Additionally RBQL supports DISTINCT COUNT keyword which is like DISTINCT, but adds a new column to the "distinct" result set: number of occurrences of the entry, similar to uniq -c unix command.
SELECT DISTINCT COUNT a1 is equivalent to SELECT a1, COUNT(a1) GROUP BY a1

Limitations

Aggregate function are CASE SENSITIVE and must be CAPITALIZED.
Aggregate functions inside JS expressions are not supported. Although you can use expressions inside aggregate functions. E.g. MAX(a1 / 1000) - valid; MAX(a1) / 1000 - invalid

JOIN statements

Join table B can be referenced either by it's file path or by it's name - an arbitary string which user should provide before executing the JOIN query.
RBQL supports STRICT LEFT JOIN which is like LEFT JOIN, but generates an error if any key in left table "A" doesn't have exactly one matching key in the right table "B".

Limitations

JOIN statements must have the following form: <JOIN_KEYWORD> (/path/to/table.tsv | table_name ) ON ai == bj

SELECT EXCEPT statement

SELECT EXCEPT can be used to select everything except specific columns. E.g. to select everything but columns 2 and 4, run: SELECT * EXCEPT a2, a4
Traditional SQL engines do not support this query mode.

FOLD() and UNFOLD()

FOLD()

FOLD is an aggregate function which accumulates all values into a list.
By default it would return the list joined by pipe | character, but you can provide a callback function to change this behavior.
FOLD is very similar to "GROUP_CONCAT" function in MySQL and "array_agg" in PostgreSQL
Example: select a2, FOLD(a1, v => v.sort().join(';')) group by a2

UNFOLD()

UNFOLD() is a function-like query mode which will do the opposite to FOLD().
UNFOLD() accepts a list as an argument and will repeat the output record multiple times - one time for each value from the list argument.
Equivalent in PostgreSQL: "unnest"
Example: SELECT a1, UNFOLD(a2.split(';'))

User Defined Functions (UDF)

RBQL supports User Defined Functions
You can define custom functions and/or import libraries in the special file:

~/.rbql_init_source.js - for JavaScript

Examples of RBQL queries

select top 100 a1, a2 * 10, a4.length where a1 == "Buy" order by parseInt(a2)
select * order by Math.random() - random sort, this is an equivalent of bash command sort -R
select top 20 a1.length / 10, a2 where ["car", "plane", "boat"].indexOf(a2) > -1
select a1.length / 10, a2 where ["car", "plane", "boat"].indexOf(a2) > -1 limit 20
update set a3 = 'US' where a3.indexOf('of America') != -1
select * where NR <= 10 - this is an equivalent of bash command "head -n 10", NR is 1-based')
select a1, a4 - this is an equivalent of bash command "cut -f 1,4"
select * order by parseInt(a2) desc - this is an equivalent of bash command "sort -k2,2 -r -n"
select NR, * - enumerate lines, NR is 1-based
select a1, b1, b2 inner join ./countries.txt on a2 == b1 order by a1, a3 - an example of join query
select distinct count a1.length where a2 != 'US'
select MAX(a1), MIN(a1) where a2 != 'US' group by a2, a3

References

RBQL: Official Site RBQL is integrated with Rainbow CSV extensions in Vim, VSCode, Sublime Text editors.
RBQL in PyPI: $ pip install rbql
Rainbow CSV extension with integrated RBQL in Visual Studio Code
Rainbow CSV extension with integrated RBQL in Vim
Rainbow CSV extension with integrated RBQL in Sublime Text 3

bigbash - SQL queries as bash one-liners
q - uses sqlite3
TextQL - uses sqlite3

rbql

Package Exports

Readme

Table of Contents

Using RBQL as browser library

Installation:

API description

rbql.table_run(...)

Parameters:

rbql.generic_run(...)

Parameters:

Usage:

"Hello world" web test in RBQL

"JSFiddle" demo test

Using RBQL as Node library

Installation:

API description

rbql.csv_run(...)

Parameters:

Usage:

Example of table_run() usage:

Example of csv_run() usage:

Using RBQL as command line tool

Installation:

Usage:

Usage (interactive mode):

Language description

Main Features

Limitations:

Supported SQL Keywords (Keywords are case insensitive)

Special variables

UPDATE statement

Aggregate functions and queries

Limitations

JOIN statements

Limitations

SELECT EXCEPT statement

FOLD() and UNFOLD()

FOLD()

UNFOLD()

User Defined Functions (UDF)

Examples of RBQL queries

References

Related projects