Unleash awesomeness. Private packages, team management tools, and powerful integrations. Get started with npm Orgs »

rbql

0.4.0 • Public • Published

RBQL (RainBow Query Language) Description

RBQL is a technology which provides SQL-like language that supports SELECT and UPDATE queries with JavaScript expressions.

Official Site

Installation:

$ npm install rbql

Usage example:

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

Usage example (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.tsv --output result.tsv

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 2 or more consecutive queries.

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 JavaScript expressions are not supported. Although you can use expressions inside aggregate functions. E.g. MAX(float(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
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.
Example: SELECT a1, UNFOLD(a2.split(';'))
Traditional SQL engines can't operate with lists (arrays) and do not support FOLD() and UNFOLD()

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

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-js CLI App for Node.js - npm
  • rbql-py CLI App in python
  • 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

install

npm i rbql

Downloadsweekly downloads

5

version

0.4.0

license

MIT

homepage

rbql.org

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability