Skip to content

Commit 02e9f85

Browse files
NathanSpeidelNathanSpeidel
authored
Add bql (#16)
1 parent d940c54 commit 02e9f85

File tree

5 files changed

+421
-205
lines changed

5 files changed

+421
-205
lines changed

‎docs/releases.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,7 @@ The Web Service implementation that can serve a static schema from a file and ta
127127

128128
| Date | Release | Highlights |
129129
| ------------ | -------------------------------------------------------------------------------------- | ---------- |
130+
| 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 |
130131
| 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 |
131132
| 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 |
132133
| 2018-04-02 | [**0.2.1**](https://github.com/bullet-db/bullet-service/releases/tag/bullet-service-0.2.1) | Moved and renamed settings |

‎docs/ws/api-bql.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Bullet BQL API
2+
3+
This section gives a comprehensive overview of the Web Service API for launching Bullet BQL queries.
4+
5+
For examples of BQL queries, see the [examples page](examples.md).
6+
7+
BQL queries that are received by the Web Service will be detenced and automatically converted to
8+
[the JSON format](api-json.md) before being sent to the backend (which requires the basic JSON format). This converstion
9+
is done in the web service using [the bullet-bql library](../releases/#bullet-bql).
10+
11+
# Overview
12+
13+
Bullet-BQL provides users with a friendly SQL-like API to submit queries to the Web Service.
14+
15+
## Data Types
16+
17+
* **Null**: `NULL`.
18+
19+
* **Boolean**: `TRUE`, `FALSE`.
20+
21+
* **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`.
22+
23+
* **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`.
24+
25+
* **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`.
26+
27+
* **Decimal**: decimal number can be treated as Double, String or ParsingException. This is controlled by `ParsingOptions`. `1.7976931348623157`, `.17976931348623157`.
28+
29+
* **String**: character string which can have escapes. Example: `'this is a string'`, `'this is ''another'' string'`.
30+
31+
* **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"`.
32+
33+
* **Dereference**: representation of a column field. Example: `column_name.field_name`.
34+
35+
* **All**: representation of all columns. Example: `*`. `column_name.*` is interpreted as `column_name`.
36+
37+
## Reserved Keywords
38+
39+
Reserved keywords must be double quoted in order to be used as ColumnReference or Dereference.
40+
41+
| Keyword | SQL:2016 | SQL-92 |
42+
| --------------------- | :-------------: | :-----------: |
43+
| `ALTER` | reserved | reserved |
44+
| `AND` | reserved | reserved |
45+
| `AS` | reserved | reserved |
46+
| `BETWEEN` | reserved | reserved |
47+
| `BY` | reserved | reserved |
48+
| `CASE` | reserved | reserved |
49+
| `CAST` | reserved | reserved |
50+
| `CONSTRAINT` | reserved | reserved |
51+
| `CREATE` | reserved | reserved |
52+
| `CROSS` | reserved | reserved |
53+
| `CUBE` | reserved | |
54+
| `CURRENT_DATE` | reserved | reserved |
55+
| `CURRENT_TIME` | reserved | reserved |
56+
| `CURRENT_TIMESTAMP` | reserved | reserved |
57+
| `CURRENT_USER` | reserved | |
58+
| `DEALLOCATE` | reserved | reserved |
59+
| `DELETE` | reserved | reserved |
60+
| `DESCRIBE` | reserved | reserved |
61+
| `DISTINCT` | reserved | reserved |
62+
| `DROP` | reserved | reserved |
63+
| `ELSE` | reserved | reserved |
64+
| `END` | reserved | reserved |
65+
| `ESCAPE` | reserved | reserved |
66+
| `EXCEPT` | reserved | reserved |
67+
| `EXECUTE` | reserved | reserved |
68+
| `EXISTS` | reserved | reserved |
69+
| `EXTRACT` | reserved | reserved |
70+
| `FALSE` | reserved | reserved |
71+
| `FOR` | reserved | reserved |
72+
| `FROM` | reserved | reserved |
73+
| `FULL` | reserved | reserved |
74+
| `GROUP` | reserved | reserved |
75+
| `GROUPING` | reserved | |
76+
| `HAVING` | reserved | reserved |
77+
| `IN` | reserved | reserved |
78+
| `INNER` | reserved | reserved |
79+
| `INSERT` | reserved | reserved |
80+
| `INTERSECT` | reserved | reserved |
81+
| `INTO` | reserved | reserved |
82+
| `IS` | reserved | reserved |
83+
| `JOIN` | reserved | reserved |
84+
| `LEFT` | reserved | reserved |
85+
| `LIKE` | reserved | reserved |
86+
| `LOCALTIME` | reserved | |
87+
| `LOCALTIMESTAMP` | reserved | |
88+
| `NATURAL` | reserved | reserved |
89+
| `NORMALIZE` | reserved | |
90+
| `NOT` | reserved | reserved |
91+
| `NULL` | reserved | reserved |
92+
| `ON` | reserved | reserved |
93+
| `OR` | reserved | reserved |
94+
| `ORDER` | reserved | reserved |
95+
| `OUTER` | reserved | reserved |
96+
| `PREPARE` | reserved | reserved |
97+
| `RECURSIVE` | reserved | |
98+
| `RIGHT` | reserved | reserved |
99+
| `ROLLUP` | reserved | |
100+
| `SELECT` | reserved | reserved |
101+
| `TABLE` | reserved | reserved |
102+
| `THEN` | reserved | reserved |
103+
| `TRUE` | reserved | reserved |
104+
| `UESCAPE` | reserved | |
105+
| `UNION` | reserved | reserved |
106+
| `UNNEST` | reserved | |
107+
| `USING` | reserved | reserved |
108+
| `VALUES` | reserved | reserved |
109+
| `WHEN` | reserved | reserved |
110+
| `WHERE` | reserved | reserved |
111+
| `WITH` | reserved | reserved |
112+
113+
## Statement Syntax
114+
115+
SELECT DISTINCT? select_clause
116+
FROM from_clause
117+
( WHERE where_clause )?
118+
( GROUP BY groupBy_clause )?
119+
( HAVING having_clause )?
120+
( ORDER BY orderBy_clause )?
121+
( WINDOWING windowing_clause )?
122+
( LIMIT limit_clause )?;
123+
124+
where `select_clause` is one of
125+
126+
*
127+
COUNT( DISTINCT reference_expr ( , reference_expr )? )
128+
group_function ( AS? ColumnReference )? ( , group_function ( AS? ColumnReference )? )? ( , reference_expr ( AS? ColumnReference )? )?
129+
reference_expr ( AS? ColumnReference )? ( , reference_expr ( AS? ColumnReference )? )?
130+
distribution_type( reference_expr, input_mode ) ( AS? ColumnReference )?
131+
TOP ( ( Integer | Long ) ( , Integer | Long ) )? , reference_expr ( , reference_expr )? ) ( AS? ColumnReference )?
132+
133+
134+
`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
135+
136+
LINEAR, ( Integer | Long ) evenly spaced
137+
REGION, ( Integer | Long ), ( Integer | Long ), ( Integer | Long ) evenly spaced in a region
138+
MANUAL, ( Integer | Long ) (, ( Integer | Long ) )* defined points
139+
140+
and `from_clause` is one of
141+
142+
STREAM() default time duration will be set from BQLConfig
143+
STREAM( ( Long | MAX ), TIME ) time based duration control.
144+
STREAM( ( Long | MAX ), TIME, ( Long | MAX ), RECORD ) time and record based duration control.
145+
146+
`RECORD` will be supported in the future.
147+
148+
and `where_clause` is one of
149+
150+
NOT where_clause
151+
where_clause AND where_clause
152+
where_clause OR where_clause
153+
reference_expr IS NOT? NULL
154+
reference_expr IS NOT? EMPTY
155+
reference_expr IS NOT? DISTINCT FROM value_expr
156+
reference_expr NOT? BETWEEN value_expr AND value_expr
157+
reference_expr NOT? IN ( value_expr ( , value_expr )* )
158+
reference_expr NOT? LIKE ( value_expr ( , value_expr )* )
159+
reference_expr ( = | <> | != | < | > | <= | >= ) value_expr
160+
161+
`value_expr` is one of Null, Boolean, Integer, Long, Double, Decimal and String.
162+
163+
and `groupBy_clause` is one of
164+
165+
() group all
166+
reference_expr ( , reference_expr )* group by
167+
( reference_expr ( , reference_expr )* ) group by
168+
169+
and `HAVING` and `ORDER BY` are only supported for TopK. In which case, `having_clause` is
170+
171+
COUNT(*) >= Integer
172+
173+
and `orderBy_clause` is
174+
175+
COUNT(*)
176+
177+
and `windowing_clause` is one of
178+
179+
( EVERY, ( Integer | Long ), ( TIME | RECORD ), include )
180+
( TUMBLING, ( Integer | Long ), ( TIME | RECORD ) )
181+
182+
`include` is one of
183+
184+
ALL
185+
FIRST, ( Integer | Long ), ( TIME | RECORD )
186+
LAST, ( Integer | Long ), ( TIME | RECORD ) will be supported
187+
188+
and `limit_clause` is one of
189+
190+
Integer | Long
191+
ALL will be supported

‎docs/ws/api.md‎ renamed to ‎docs/ws/api-json.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
1-
# API
1+
# Bullet JSON API
22

3-
This section gives a comprehensive overview of the Web Service API for launching Bullet queries.
3+
This section gives a comprehensive overview of the Web Service API for launching Bullet JSON queries.
4+
5+
The JSON API is the actual Query format that is expected by the backend. [The BQL API](api-bql.md) is a more
6+
user-friendly API which can also be used - the Web Service will automatically detect the BQL query and convert the
7+
query to this JSON format before submitting it to the backend.
48

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

8-
The main constituents of a Bullet query are:
12+
The main constituents of a Bullet JSON query are:
913

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

0 commit comments

Comments
 (0)