From 09fa51886258ce2b634296aea452ff90d0f40255 Mon Sep 17 00:00:00 2001 From: mechatroner Date: Sat, 12 Jun 2021 22:41:53 -0400 Subject: [PATCH] update readme --- README.md | 54 ++++++++++++++++++++---------------------------------- 1 file changed, 20 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 4302f5f..5b05781 100644 --- a/README.md +++ b/README.md @@ -132,25 +132,23 @@ Supported values: _"latin-1"_, _"utf-8"_ # RBQL (Rainbow Query Language) Description -RBQL is a technology for (not only) CSV file processing. It provides SQL-like language that supports SELECT queries with Python or JavaScript expressions. -RBQL is distributed with CLI apps, text editor plugins, Python and JS libraries and can work in web browsers. -RBQL core module is very generic and can process all kinds of objects and record formats, but the most popular RBQL implementation works with CSV files. +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, Python and JS libraries. [Official Site](https://rbql.org/) ### Main Features * Use Python or JavaScript expressions inside _SELECT_, _UPDATE_, _WHERE_ and _ORDER BY_ statements +* Supports multiple input formats * Result set of any query immediately becomes a first-class table on its own -* Supports input tables with an 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 +* No need to provide FROM statement in the query - input table is defined by the current context * 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 +* Provides some new useful query modes which traditional SQL engines do not have +* Lightweight, dependency-free, works out of the box #### Limitations: @@ -189,17 +187,10 @@ RBQL for CSV files provides the following variables which you can use in your qu 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 its "name". You can use this notation if the field in the first (header) CSV line has a "good" alphanumeric name + Description: Value of the field referenced by it's "name". You can use this notation if the field in the header 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 its "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 int(a.Weight) * 100 > int(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. + Description: Value of the field referenced by it's "name". You can use this notation to reference fields by arbitrary values in the header ### UPDATE statement @@ -222,7 +213,7 @@ There is a workaround for the limitation above for _ARRAY_AGG_ function which su ### JOIN statements 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 left table "A" doesn't have exactly one matching key in the right table "B". +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". Limitation: _JOIN_ statements can't contain Python/JS expressions and must have the following form: _ (/path/to/table.tsv | table_name ) ON a... == b... [AND a... == b... [AND ... ]]_ @@ -242,6 +233,12 @@ RBQL does not support LIKE operator, instead it provides "like()" function which `SELECT * where like(a1, 'foo%bar')` +### WITH (header) and WITH (noheader) statements +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)` + + ### User Defined Functions (UDF) RBQL supports User Defined Functions @@ -255,8 +252,8 @@ You can define custom functions and/or import libraries in two special files: #### With Python expressions * `select top 100 a1, int(a2) * 10, len(a4) where a1 == "Buy" order by int(a2) desc` -* `select * order by random.random() where NR > 1` - skip header record and random sort -* `select len(a.vehicle_price) / 10, a2 where NR > 1 and a['Vehicle type'] in ["car", "plane", "boat"] limit 20` - referencing columns by names from header record, skipping the header and using Python's "in" to emulate SQL's "in" +* `select * order by random.random()` - random sort +* `select 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-based * `select * where re.match(".*ab.*", a1) is not None` - select entries where first column has "ab" pattern @@ -267,8 +264,8 @@ You can define custom functions and/or import libraries in two special files: #### With JavaScript expressions * `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 && ["car", "plane", "boat"].indexOf(a['Vehicle type']) > -1 limit 20` - referencing columns by names from header record and skipping the header +* `select * order by Math.random()` - random sort +* `select 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 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 @@ -276,17 +273,6 @@ You can define custom functions and/or import libraries in two special files: * `select ...a1.split(':')` - Using JS "destructuring assignment" syntax to split one column into many. Do not try this with other SQL engines! -### FAQ - -#### How do I skip the header record in a CSV file? - -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 int(a3) * 1000, a2` -> `select int(a3) * 1000 if NR > 1 else a3, a2` - - - ### References #### Rainbow CSV and similar plugins in other editors: