Skip to content

Add bql #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 19, 2018
Merged

Add bql #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
13635f3
Added bullet-service 0.4.0 release
Jul 19, 2018
8649f6f
Added examples and API for BQL
Jul 19, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,7 @@ The Web Service implementation that can serve a static schema from a file and ta

| Date | Release | Highlights |
| ------------ | -------------------------------------------------------------------------------------- | ---------- |
| 2018-07-17 | [**0.4.0**](https://github.com/bullet-db/bullet-service/releases/tag/bullet-service-0.4.0) | Enhanced Web Service to support BQL queries |
| 2018-06-25 | [**0.3.0**](https://github.com/bullet-db/bullet-service/releases/tag/bullet-service-0.3.0) | Upgrades to Netty-less Bullet Core for the RESTPubsub |
| 2018-06-14 | [**0.2.2**](https://github.com/bullet-db/bullet-service/releases/tag/bullet-service-0.2.2) | Adding settings to configure Websocket |
| 2018-04-02 | [**0.2.1**](https://github.com/bullet-db/bullet-service/releases/tag/bullet-service-0.2.1) | Moved and renamed settings |
Expand Down
191 changes: 191 additions & 0 deletions docs/ws/api-bql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
# Bullet BQL API

This section gives a comprehensive overview of the Web Service API for launching Bullet BQL queries.

For examples of BQL queries, see the [examples page](examples.md).

BQL queries that are received by the Web Service will be detenced and automatically converted to
[the JSON format](api-json.md) before being sent to the backend (which requires the basic JSON format). This converstion
is done in the web service using [the bullet-bql library](../releases/#bullet-bql).

# Overview

Bullet-BQL provides users with a friendly SQL-like API to submit queries to the Web Service.

## Data Types

* **Null**: `NULL`.

* **Boolean**: `TRUE`, `FALSE`.

* **Integer**: 32-bit signed two’s complement integer with a minimum value of `-2^31` and a maximum value of `2^31 - 1`. Example: `65`.

* **Long**: 64-bit signed two’s complement integer with a minimum value of `-2^63 + 1` and a maximum value of `2^63 - 1`. Example: `9223372036854775807`, `-9223372036854775807`.

* **Double**: 64-bit inexact, variable-precision with a minimum value of `2^-1074` and a maximum value of `(2-2^-52)·2^1023`. Example: `1.7976931348623157E+308`, `.17976931348623157E+309`, `4.9E-324`.

* **Decimal**: decimal number can be treated as Double, String or ParsingException. This is controlled by `ParsingOptions`. `1.7976931348623157`, `.17976931348623157`.

* **String**: character string which can have escapes. Example: `'this is a string'`, `'this is ''another'' string'`.

* **ColumnReference**: representation of a single column. Unquoted ColumnReference must start with a letter or `_`. Quoted ColumnReference can have escape. Example: `column_name`, `"#column""with""escape"`.

* **Dereference**: representation of a column field. Example: `column_name.field_name`.

* **All**: representation of all columns. Example: `*`. `column_name.*` is interpreted as `column_name`.

## Reserved Keywords

Reserved keywords must be double quoted in order to be used as ColumnReference or Dereference.

| Keyword | SQL:2016 | SQL-92 |
| --------------------- | :-------------: | :-----------: |
| `ALTER` | reserved | reserved |
| `AND` | reserved | reserved |
| `AS` | reserved | reserved |
| `BETWEEN` | reserved | reserved |
| `BY` | reserved | reserved |
| `CASE` | reserved | reserved |
| `CAST` | reserved | reserved |
| `CONSTRAINT` | reserved | reserved |
| `CREATE` | reserved | reserved |
| `CROSS` | reserved | reserved |
| `CUBE` | reserved | |
| `CURRENT_DATE` | reserved | reserved |
| `CURRENT_TIME` | reserved | reserved |
| `CURRENT_TIMESTAMP` | reserved | reserved |
| `CURRENT_USER` | reserved | |
| `DEALLOCATE` | reserved | reserved |
| `DELETE` | reserved | reserved |
| `DESCRIBE` | reserved | reserved |
| `DISTINCT` | reserved | reserved |
| `DROP` | reserved | reserved |
| `ELSE` | reserved | reserved |
| `END` | reserved | reserved |
| `ESCAPE` | reserved | reserved |
| `EXCEPT` | reserved | reserved |
| `EXECUTE` | reserved | reserved |
| `EXISTS` | reserved | reserved |
| `EXTRACT` | reserved | reserved |
| `FALSE` | reserved | reserved |
| `FOR` | reserved | reserved |
| `FROM` | reserved | reserved |
| `FULL` | reserved | reserved |
| `GROUP` | reserved | reserved |
| `GROUPING` | reserved | |
| `HAVING` | reserved | reserved |
| `IN` | reserved | reserved |
| `INNER` | reserved | reserved |
| `INSERT` | reserved | reserved |
| `INTERSECT` | reserved | reserved |
| `INTO` | reserved | reserved |
| `IS` | reserved | reserved |
| `JOIN` | reserved | reserved |
| `LEFT` | reserved | reserved |
| `LIKE` | reserved | reserved |
| `LOCALTIME` | reserved | |
| `LOCALTIMESTAMP` | reserved | |
| `NATURAL` | reserved | reserved |
| `NORMALIZE` | reserved | |
| `NOT` | reserved | reserved |
| `NULL` | reserved | reserved |
| `ON` | reserved | reserved |
| `OR` | reserved | reserved |
| `ORDER` | reserved | reserved |
| `OUTER` | reserved | reserved |
| `PREPARE` | reserved | reserved |
| `RECURSIVE` | reserved | |
| `RIGHT` | reserved | reserved |
| `ROLLUP` | reserved | |
| `SELECT` | reserved | reserved |
| `TABLE` | reserved | reserved |
| `THEN` | reserved | reserved |
| `TRUE` | reserved | reserved |
| `UESCAPE` | reserved | |
| `UNION` | reserved | reserved |
| `UNNEST` | reserved | |
| `USING` | reserved | reserved |
| `VALUES` | reserved | reserved |
| `WHEN` | reserved | reserved |
| `WHERE` | reserved | reserved |
| `WITH` | reserved | reserved |

## Statement Syntax

SELECT DISTINCT? select_clause
FROM from_clause
( WHERE where_clause )?
( GROUP BY groupBy_clause )?
( HAVING having_clause )?
( ORDER BY orderBy_clause )?
( WINDOWING windowing_clause )?
( LIMIT limit_clause )?;

where `select_clause` is one of

*
COUNT( DISTINCT reference_expr ( , reference_expr )? )
group_function ( AS? ColumnReference )? ( , group_function ( AS? ColumnReference )? )? ( , reference_expr ( AS? ColumnReference )? )?
reference_expr ( AS? ColumnReference )? ( , reference_expr ( AS? ColumnReference )? )?
distribution_type( reference_expr, input_mode ) ( AS? ColumnReference )?
TOP ( ( Integer | Long ) ( , Integer | Long ) )? , reference_expr ( , reference_expr )? ) ( AS? ColumnReference )?


`group_function` is one of `SUM(reference_expr)`, `MIN(reference_expr)`, `MAX(reference_expr)`, `AVG(reference_expr)` and `COUNT(*)`. `reference_expr` is one of ColumnReference and Dereference. `distribution_type` is one of `QUANTILE`, `FREQ` and `CUMFREQ`. The 1st number in `TOP` is K, and the 2nd number is an optional threshold. The `input_mode` is one of

LINEAR, ( Integer | Long ) evenly spaced
REGION, ( Integer | Long ), ( Integer | Long ), ( Integer | Long ) evenly spaced in a region
MANUAL, ( Integer | Long ) (, ( Integer | Long ) )* defined points

and `from_clause` is one of

STREAM() default time duration will be set from BQLConfig
STREAM( ( Long | MAX ), TIME ) time based duration control.
STREAM( ( Long | MAX ), TIME, ( Long | MAX ), RECORD ) time and record based duration control.

`RECORD` will be supported in the future.

and `where_clause` is one of

NOT where_clause
where_clause AND where_clause
where_clause OR where_clause
reference_expr IS NOT? NULL
reference_expr IS NOT? EMPTY
reference_expr IS NOT? DISTINCT FROM value_expr
reference_expr NOT? BETWEEN value_expr AND value_expr
reference_expr NOT? IN ( value_expr ( , value_expr )* )
reference_expr NOT? LIKE ( value_expr ( , value_expr )* )
reference_expr ( = | <> | != | < | > | <= | >= ) value_expr

`value_expr` is one of Null, Boolean, Integer, Long, Double, Decimal and String.

and `groupBy_clause` is one of

() group all
reference_expr ( , reference_expr )* group by
( reference_expr ( , reference_expr )* ) group by

and `HAVING` and `ORDER BY` are only supported for TopK. In which case, `having_clause` is

COUNT(*) >= Integer

and `orderBy_clause` is

COUNT(*)

and `windowing_clause` is one of

( EVERY, ( Integer | Long ), ( TIME | RECORD ), include )
( TUMBLING, ( Integer | Long ), ( TIME | RECORD ) )

`include` is one of

ALL
FIRST, ( Integer | Long ), ( TIME | RECORD )
LAST, ( Integer | Long ), ( TIME | RECORD ) will be supported

and `limit_clause` is one of

Integer | Long
ALL will be supported
10 changes: 7 additions & 3 deletions docs/ws/api.md → docs/ws/api-json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
# API
# Bullet JSON API

This section gives a comprehensive overview of the Web Service API for launching Bullet queries.
This section gives a comprehensive overview of the Web Service API for launching Bullet JSON queries.

The JSON API is the actual Query format that is expected by the backend. [The BQL API](api-bql.md) is a more
user-friendly API which can also be used - the Web Service will automatically detect the BQL query and convert the
query to this JSON format before submitting it to the backend.

* For info on how to use the UI, see the [UI Usage section](../ui/usage.md)
* For examples of specific queries see the [Examples](examples.md) section

The main constituents of a Bullet query are:
The main constituents of a Bullet JSON query are:

* __filters__, which determine which records will be consumed by your query
* __projection__, which determines which fields will be projected in the resulting output from Bullet
Expand Down
Loading