Metadata-Version: 2.1
Name: rbql
Version: 0.11.2
Summary: Rainbow Query Language
Home-page: https://github.com/mechatroner/RBQL
Author: Dmitry Ignatovich
Author-email: mechatroner@yandex.ru
License: UNKNOWN
Description: RBQL is both a library and a command line tool which provides SQL-like language with Python expressions
        
        [Official Site](https://rbql.org/)
        
        
        ### Using RBQL as Python library
        
        If you want to use rbql module as a python library for your own app - please read [API Documentation](https://github.com/mechatroner/RBQL/blob/master/PYLIBRARY.md#using-rbql-as-python-library)  
        
        
        ### Using RBQL as CLI App
        
        #### Installation:
        ```
        $ pip install rbql
        ```
        
        #### Usage example (non-interactive mode):
        ```
        $ 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 or 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](https://www.w3schools.com/sql/default.asp)  
        
        
        ### 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 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.
        
        
        ### 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 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 _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, 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 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 two special files:  
        * `~/.rbql_init_source.py` - for Python
        * `~/.rbql_init_source.js` - for JavaScript
        
        
        ## Examples of RBQL queries
        
        #### 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"
        * `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
        * `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
        
        #### 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 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 int(a3) * 1000, a2` -> `select int(a3) * 1000 if NR > 1 else a3, a2`  
        
        
        #### How does RBQL work?
        
        RBQL parses SQL-like user query, creates a new python or javascript 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'
        ```
        2. 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'"
        ```
        
        3. 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'"
        ```
        
        4. RBQL has static template script which looks like this:
        ```
            for line in sys.stdin:
                a = line.rstrip('\n').split(',')
                if %%%W_Expression%%%:
                    out_fields = [%%%S_Expression%%%]
                    print ','.join([str(v) for v in out_fields])
        ```
        
        5. 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(',')
                if a[0] != 'SELL':
                    out_fields = [a[2], int(a[3]) + 100, len(a[1])]
                    print ','.join([str(v) for v in out_fields])
        ```
        
        6. 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.  
        Adding support of TOP/LIMIT keywords is trivial and to support "ORDER BY" we can introduce an intermediate array.  
        
        
        
        ### References
        
        * rbql-js library and CLI App for Node.js - [npm](https://www.npmjs.com/package/rbql)  
        * rbql-py library and CLI App in [python](https://pypi.org/project/rbql/)  
        * Rainbow CSV extension with integrated RBQL in [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=mechatroner.rainbow-csv)  
        * Rainbow CSV extension with integrated RBQL in [Vim](https://github.com/mechatroner/rainbow_csv)  
        * Rainbow CSV extension with integrated RBQL in [Sublime Text 3](https://packagecontrol.io/packages/rainbow_csv)  
        
Keywords: SQL SQL-like transpiler RBQL library CLI command-line CSV TSV
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 2.7
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
