Skip to main content

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

Official Site

Using RBQL as Python library

If you want to use rbql module as a python library for your own app - read the API and integration Documentation

Using RBQL as CLI App

Installation:

$ pip install rbql

Usage example:

$ rbql-py --query "select a1, a2 order by a1" --delim , < input.csv

Usage example (interactive mode):

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

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

Main Features

  • Use Python 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 Python 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 and "array_agg" in PostgreSQL
Example: select a2, FOLD(a1, lambda v: ';'.join(sorted(v))) 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 a special file: ~/.rbql_init_source.py

Examples of RBQL queries

  • select top 100 a1, int(a2) * 10, len(a4) where a1 == "Buy" order by int(a2)
  • select * order by random.random() - random sort, this is an equivalent of bash command sort -R
  • select top 20 len(a1) / 10, a2 where a2 in ["car", "plane", "boat"] - use Python's "in" to emulate SQL's "in"
  • select len(a1) / 10, a2 where a2 in ["car", "plane", "boat"] limit 20
  • update set a3 = 'US' where a3.find('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 int(a2) desc - this is an equivalent of bash command "sort -k2,2 -r -n"
  • select NR, * - enumerate lines, NR is 1-based
  • select * where re.match(".*ab.*", a1) is not None - select entries where first column has "ab" pattern
  • select a1, b1, b2 inner join ./countries.txt on a2 == b1 order by a1, a3 - an example of join query
  • select distinct count len(a1) where a2 != 'US'
  • select MAX(a1), MIN(a1) where a2 != 'US' group by a2, a3

FAQ

How does RBQL work?

RBQL parses SQL-like user query, creates a new python worker module, then imports and executes it.

Explanation of simplified Python version of RBQL algorithm by example.

  1. User enters the following query, which is stored as a string Q:
    SELECT a3, int(a4) + 100, len(a2) WHERE a1 != 'SELL'
  1. RBQL replaces all a{i} substrings in the query string Q with a[{i - 1}] substrings. The result is the following string:
    Q = "SELECT a[2], int(a[3]) + 100, len(a[1]) WHERE a[0] != 'SELL'"
  1. RBQL searches for "SELECT" and "WHERE" keywords in the query string Q, throws the keywords away, and puts everything after these keywords into two variables S - select part and W - where part, so we will get:
    S = "a[2], int(a[3]) + 100, len(a[1])"
    W = "a[0] != 'SELL'"
  1. RBQL has static template script which looks like this:
    for line in sys.stdin:
        a = line.rstrip('\n').split('\t')
        if %%%W_Expression%%%:
            out_fields = [%%%S_Expression%%%]
            print '\t'.join([str(v) for v in out_fields])
  1. RBQL replaces %%%W_Expression%%% with W and %%%S_Expression%%% with S so we get the following script:
    for line in sys.stdin:
        a = line.rstrip('\n').split('\t')
        if a[0] != 'SELL':
            out_fields = [a[2], int(a[3]) + 100, len(a[1])]
            print '\t'.join([str(v) for v in out_fields])
  1. RBQL runs the patched script against user's data file:
    ./tmp_script.py < data.tsv > result.tsv

Result set of the original query (SELECT a3, int(a4) + 100, len(a2) WHERE a1 != 'SELL') is in the "result.tsv" file. It is clear that this simplified version can only work with tab-separated files.

Is this technology reliable?

It should be: RBQL scripts have only 1000 - 2000 lines combined (depending on how you count them) and there are no external dependencies. There is no complex logic, even query parsing functions are very simple. If something goes wrong RBQL will show an error instead of producing incorrect output, also there are currently 5 different warning types.

References

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

Metadata

Release files for rbql 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rbql 0.7.0
File Size Uploaded Provenance Actions
rbql-0.7.0.tar.gz 25.1 kB Without provenance Details for rbql-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rbql 0.7.0
File Interpreter ABI Platform Actions
rbql-0.7.0-py3-none-any.whl Python 3 none any Details for rbql-0.7.0-py3-none-any.whl

Total release size: 49.6 kB

Release files / rbql-0.7.0.tar.gz

Download URL rbql-0.7.0.tar.gz
Size 25.1 kB
Tags Source
SHA-256 checksum
How to use checksums
61688d666f85878f8bb1defa43b398ca47affb2e88fbe7a7c0eb25fd9a1c9f01
BLAKE2b-256 checksum
How to use checksums
8dbc824db4eac6f008401541d93f7e21f88de5c9049c5913056a6b5a340099b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.12.1 pkginfo/1.4.2 requests/2.22.0 setuptools/41.0.1 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.5.2

Release files / rbql-0.7.0-py3-none-any.whl

Download URL rbql-0.7.0-py3-none-any.whl
Size 24.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c7dec382461aa4f28168564e6801bafcd5ffac552a3aa4ee8600cd75ab6875c0
BLAKE2b-256 checksum
How to use checksums
2758050b87c3057ffe2191c0420ac0d53fa199d4cd0134654a771c8c2b2f12dc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.12.1 pkginfo/1.4.2 requests/2.22.0 setuptools/41.0.1 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.5.2

Security for rbql 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.7.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page