Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including rbql with all npm packages installed. Try it out:

var rbql = require("rbql")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

rbql v0.10.0

Rainbow Query Language

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

Table of Contents

  1. RBQL as browser library
  2. RBQL as Node library
  3. RBQL as command line tool
  4. 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

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:

  1. rbql.table_run(...)
  2. rbql.generic_run(...)

rbql.table_run(...)

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

async function table_run(user_query, input_table, output_table, 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
  • join_table: array
    an array with join table records so that user can use join table B in input queries

Return value:

Promise which resolves to warnings: an array of strings which represent human-readable warnings

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.

async function generic_run(user_query, input_iterator, output_writer, 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
  • 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

Return value:

Promise which resolves to warnings: an array of strings which represent human-readable warnings

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(exception) { console.log('RBQL finished with error: ' + String(exception)); }
    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).then(success_handler).catch(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:

  1. rbql.csv_run(...)
  2. rbql.table_run(...) - identical to browser version
  3. 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.

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

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)

Return value:

Promise which resolves to warnings: an array of strings which represent human-readable warnings

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(exception) { console.log('Error: ' + String(exception)); }
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).then(success_handler).catch(error_handler);

Example of csv_run() usage:

const rbql_csv = require('rbql_csv');
let user_query = 'SELECT a1, parseInt(a2) % 1000 WHERE a3 != "USA" LIMIT 5';
let error_handler = function(exception) { console.log('Error: ' + String(exception)); }
let success_handler = function(warnings) {
    if (warnings.length)
        console.log('warnings: ' + JSON.stringify(warnings));
    console.log('output table: output.csv');
}
rbql_csv.csv_run(user_query, 'input.csv', ',', 'quoted', 'output.csv', ',', 'quoted', 'utf-8').then(success_handler).catch(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 (non-interactive mode):

$ 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 (record number) identifier
  • Supports all main SQL keywords
  • Supports aggregate functions and GROUP BY queries
  • 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

RBQL variables

RBQL for CSV files provides the following variables which you can use in your queries:

  • a1, a2,..., a{N}
    Variable type: string
    Description: value of i-th field in the current record in input table
  • b1, b2,..., b{N}
    Variable type: string
    Description: value of i-th field in the current record in join table B
  • NR
    Variable type: integer
    Description: Record number (1-based)
  • NF
    Variable type: integer
    Description: Number of fields in the current record
  • a.name, b.Person_age, ... a.{good_alphanumeric_column_name}
    Variable type: string
    Description: Value of the field referenced by it's "name". You can use this notation if the field in the first (header) CSV line has a "good" alphanumeric name
  • _a["object id"]_, _a['9.12341234']_, b["%$ !! 10 20"] ... a["arbitrary column name!"]
    Variable type: string
    Description: Value of the field referenced by it's "name". You can use this notation to reference fields by arbitrary values in the first (header) CSV line, even when there is no header at all

Notes:

  • You can mix all variable types in a single query, example: select a1, b2 JOIN /path/to/b.csv ON a['Item Id'] == b.Identifier WHERE NR > 1 and parseInt(a.Weight) * 100 > parseInt(b["weight of the item"])
  • Referencing fields by header names does not automatically skip the header line (you can use where NR > 1 trick to skip it)
  • If you want to use RBQL as a library for your own app you can define your own custom variables and do not have to support the above mentioned CSV-related variables.

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, ARRAY_AGG, MIN, MAX, SUM, AVG, VARIANCE, MEDIAN

Limitation: aggregate functions inside JavaScript expressions are not supported. Although you can use expressions inside aggregate functions.
E.g. MAX(float(a1) / 1000) - valid; MAX(a1) / 1000 - invalid.
There is a workaround for the limitation above for ARRAY_AGG function which supports an optional parameter - a callback function that can do something with the aggregated array. Example:
select a2, ARRAY_AGG(a1, v => v.sort().slice(0, 5)) group by a2

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".
Limitation: 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.

UNNEST() operator

UNNEST(list) takes a list/array as an argument and repeats the output record multiple times - one time for each value from the list argument.
Example: SELECT a1, UNNEST(a2.split(';'))

User Defined Functions (UDF)

RBQL supports User Defined Functions
You can define custom functions and/or import libraries in a special file: ~/.rbql_init_source.js

Examples of RBQL queries

  • select top 100 a1, a2 * 10, a4.length where a1 == "Buy" order by parseInt(a2) desc
  • select * order by Math.random() where NR > 1 - skip header record and random sort
  • select top 20 a.vehicle_price.length / 10, a2 where NR > 1 and ["car", "plane", "boat"].indexOf(a['Vehicle type']) > -1 limit 20 - referencing columns by names from header record and skipping the header
  • update set a3 = 'NPC' where a3.indexOf('Non-playable character') != -1
  • select NR, * - enumerate records, NR is 1-based
  • select a1, b1, b2 inner join ./countries.txt on a2 == b1 order by a1, a3 - example of join query
  • select MAX(a1), MIN(a1) where a.Name != 'John' group by a2, a3 - example of aggregate query

FAQ

How do I skip header record in CSV files?

You can use the following trick: add ... where NR > 1 ... to your query

And if you are doing math operation you can modify your query like this, example:
select parseInt(a3) * 1000, a2 -> select NR > 1 ? parseInt(a3) * 1000 : a3, a2

References

Metadata

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free