RBQL is an eval-based SQL-like query engine for (not only) CSV file processing. It provides SQL-like language that supports SELECT queries with Python or JavaScript expressions.
RBQL is best suited for data transformation, data cleaning, and analytical queries.
RBQL is distributed with CLI apps, text editor plugins, IPython/Jupyter magic command, Python and JS libraries.
Matrix of data formats that RBQL supports out of the box. R=Read, W=Write
Data Format | Python | JS |
---|---|---|
CSV, TSV, etc | RW | RW |
Native 2D arrays/lists | RW | RW |
Pandas dataframe | RW | |
Sqlite databases | R |
If you use RBQL as a library it is possible to support additional formats with some customizations.
All keywords have the same meaning as in SQL queries. You can check them online
RBQL for CSV files provides the following variables which you can use in your queries:
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.
RBQL supports the following aggregate functions, which can also be used with GROUP BY keyword:
COUNT, _ARRAYAGG, MIN, MAX, _ANYVALUE, SUM, AVG, VARIANCE, MEDIAN
Limitation: aggregate functions inside Python (or JS) 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 _ARRAYAGG function which supports an optional parameter - a callback function that can do something with the aggregated array. Example:
SELECT a2, ARRAY_AGG(a1, lambda v: sorted(v)[:5]) GROUP BY a2
- Python; SELECT a2, ARRAY_AGG(a1, v => v.sort().slice(0, 5)) GROUP BY a2
- JS
Join table B can be referenced either by its file path or by its name - an arbitrary string which the 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 the left table "A" doesn't have exactly one matching key in the right table "B".
Table B path can be either relative to the working dir, relative to the main table or absolute.
Limitation: JOIN statements can't contain Python/JS expressions and must have the following form: _<JOIN_KEYWORD> (/path/to/table.tsv | tablename ) ON a... == b... [AND a... == b... [AND ... ]]
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(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(';'))
RBQL does not support LIKE operator, instead it provides "like()" function which can be used like this:
SELECT * where like(a1, 'foo%bar')
You can set whether the input (and join) CSV file has a header or not using the environment configuration parameters which could be --with_headers
CLI flag or GUI checkbox or something else.
But it is also possible to override this selection directly in the query by adding either WITH (header)
or WITH (noheader)
statement at the end of the query.
Example: select top 5 NR, * with (header)
RBQL supports User Defined Functions
You can define custom functions and/or import libraries in two special files:
~/.rbql_init_source.py
- for Python~/.rbql_init_source.js
- for JavaScriptSELECT TOP 100 a1, int(a2) * 10, len(a4) WHERE a1 == "Buy" ORDER BY int(a2) DESC
SELECT a.id, a.weight / 1000 AS weight_kg
SELECT * ORDER BY random.random()
- random sortSELECT len(a.vehicle_price) / 10, a2 WHERE int(a.vehicle_price) < 500 and a['Vehicle type'] in ["car", "plane", "boat"] limit 20
- referencing columns by names from header and using Python's "in" to emulate SQL's "in"UPDATE SET a3 = 'NPC' WHERE a3.find('Non-playable character') != -1
SELECT NR, *
- enumerate records, NR is 1-basedSELECT * WHERE re.match(".*ab.*", a1) is not None
- select entries where first column has "ab" patternSELECT a1, b1, b2 INNER JOIN ./countries.txt ON a2 == b1 ORDER BY a1, a3
- example of join querySELECT MAX(a1), MIN(a1) WHERE a.Name != 'John' GROUP BY a2, a3
- example of aggregate querySELECT *a1.split(':')
- Using Python3 unpack operator to split one column into many. Do not try this with other SQL engines!SELECT TOP 100 a1, a2 * 10, a4.length WHERE a1 == "Buy" ORDER BY parseInt(a2) DESC
SELECT a.id, a.weight / 1000 AS weight_kg
SELECT * ORDER BY Math.random()
- random sortSELECT TOP 20 a.vehicle_price.length / 10, a2 WHERE parseInt(a.vehicle_price) < 500 && ["car", "plane", "boat"].indexOf(a['Vehicle type']) > -1 limit 20
- referencing columns by names from headerUPDATE SET a3 = 'NPC' WHERE a3.indexOf('Non-playable character') != -1
SELECT NR, *
- enumerate records, NR is 1-basedSELECT a1, b1, b2 INNER JOIN ./countries.txt ON a2 == b1 ORDER BY a1, a3
- example of join querySELECT MAX(a1), MIN(a1) WHERE a.Name != 'John' GROUP BY a2, a3
- example of aggregate querySELECT ...a1.split(':')
- Using JS "destructuring assignment" syntax to split one column into many. Do not try this with other SQL engines!RBQL core idea is based on dynamic code generation and execution with exec and eval functions. Here are the main steps that RBQL engine performs when processing a query:
Here you can find a very basic working script (only 15 lines of Python code) which implements this idea: mini_rbql.py
The diagram below gives an overview of the main RBQL components and data flow:
$ npm install -g rbql
$ pip install rbql
- the module also provides %rbql
magic command for IPython/Jupyter.