Influxdata
/
influxdb
mirror of https://github.com/influxdata/influxdb.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

update InfluxQL spec

pull/1491/head
David Norton 2015-02-02 21:33:17 -05:00
parent c9f29a85a7
commit 729be5ef36
1 changed files with 288 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

304
influxql/INFLUXQL.md
View File

@ -4,7 +4,7 @@
This is a reference for the Influx Query Language ("InfluxQL"). This is a reference for the Influx Query Language ("InfluxQL").
InfluxQL is a SQL-like query language for interacting with InfluxDB. It was lovingly crafted to feel familiar to those coming from other InfluxQL is a SQL-like query language for interacting with InfluxDB. It has been lovingly crafted to feel familiar to those coming from other
SQL or SQL-like environments while providing features specific to storing SQL or SQL-like environments while providing features specific to storing
and analyzing time series data. and analyzing time series data.
@ -44,56 +44,123 @@ decimal_digit = "0" .. "9" .
Database names are more limited than other identifiers because they appear in URLs. Database names are more limited than other identifiers because they appear in URLs.
The rules:
- must start with an upper or lowercase ASCII letter
- may contain only ASCII leters, decimal digits, "_", and "-"
``` ```
db_name = ascii_letter { ascii_letter | decimal_digit | "_" | "-" } . db_name = ascii_letter { ascii_letter | decimal_digit | "_" | "-" } .
``` ```
#### Examples:
```
mydb
MyDB
my-db_3
```
## Identifiers ## Identifiers
Identifiers are things like measurement names, retention policy names, tag keys, etc.
The rules:
- double quoted identifiers can contain any unicode character other than a new line
- unquoted identifiers must start with an upper or lowercase ASCII character
- unquoted identifiers may contain only ASCII letters, decimal digits, "_", and "."
``` ```
identifier = unquoted_identifier | quoted_identifier . identifier = unquoted_identifier | quoted_identifier .
unquoted_identifier = ascii_letter { ascii_letter | decimal_digit | "_" | "." } . unquoted_identifier = ascii_letter { ascii_letter | decimal_digit | "_" | "." } .
quoted_identifier = `"` unicode_char { unicode_char } `"` . quoted_identifier = `"` unicode_char { unicode_char } `"` .
``` ```
#### Examples:
```
cpu
"1h.cpu"
"1_Crazy-1337.identifer>NAME"
```
## Keywords ## Keywords
``` ```
ALL ALTER AS ASC BEGIN BY ALL ALTER AS ASC BEGIN BY
CREATE CONTINUOUS DATABASE DATABASES DEFAULT DELETE CREATE CONTINUOUS DATABASE DATABASES DEFAULT DELETE
DESC DROP DURATION END EXISTS EXPLAIN DESC DROP DURATION END EXISTS EXPLAIN
FIELD FROM GRANT GROUP IF INNER FIELD FROM GRANT GROUP IF IN
INSERT INTO KEYS LIMIT SHOW MEASUREMENT INNER INSERT INTO KEY KEYS LIMIT
MEASUREMENTS OFFSET ON ORDER PASSWORD POLICY SHOW MEASUREMENT MEASUREMENTS OFFSET ON ORDER
POLICIES PRIVILEGES QUERIES QUERY READ REPLICATION PASSWORD POLICY POLICIES PRIVILEGES QUERIES QUERY
RETENTION REVOKE SELECT SERIES TAG TO READ REPLICATION RETENTION REVOKE SELECT SERIES
USER USERS VALUES WHERE WITH WRITE TAG TO USER USERS VALUES WHERE
WITH WRITE
``` ```
## Literals ## Literals
### Numbers ### Numbers
InfluxQL supports decimal integer literals and float literals. Hex, octal, etc. are not
currently supported.
``` ```
int_lit = decimal_lit . int_lit = decimal_lit .
decimal_lit = ( "1" .. "9" ) { decimal_digit } . decimal_lit = ( "1" .. "9" ) { decimal_digit } .
float_lit = decimals "." decimals . float_lit = decimals "." decimals .
decimals = decimal_digit { decimal_digit } .
``` ```
### Strings ### Strings
String literals must be surrounded by single quotes.
``` ```
string_lit = '"' { unicode_char } '"' . string_lit = `'` { unicode_char } `'`' .
``` ```
### Durations ### Durations
Duration literals specify a length of time and are specified by an integer
followed by (without spaces) the duration units.
| Units | Meaning |
|--------|-----------------------------------------|
| u or µ | microseconds (1 millionth of a second) |
| ms | milliseconds (1 thousandth of a second) |
| s | second |
| m | minute |
| h | hour |
| d | day |
| w | week |
``` ```
duration_lit = decimals duration_unit . duration_lit = decimals duration_unit .
duration_unit = "u" | "µ" | "s" | "h" | "d" | "w" | "ms" . duration_unit = "u" | "µ" | "s" | "h" | "d" | "w" | "ms" .
``` ```
### Dates & Times
The date & time literal format is not specified in EBNF like the rest of this
document. It is specified using Go's date / time parsing format, which is
a reference date written in the format required by InfluxQL. The reference
date time is:
January 2nd, 2006 at 3:04:05 PM
```
time_lit = "2006-01-02 15:04:05.999999" | "2006-01-02"
```
### Boolean
```
bool_lit = TRUE | FALSE .
```
## Queries ## Queries
A query is composed of one or more statements separated by a semicolon. A query is composed of one or more statements separated by a semicolon.
@ -115,13 +182,12 @@ statement = alter_retention_policy_stmt |
grant_stmt | grant_stmt |
show_continuous_queries_stmt | show_continuous_queries_stmt |
show_databases_stmt | show_databases_stmt |
show_field_key_stmt | show_field_keys_stmt |
show_field_value_stmt |
show_measurements_stmt | show_measurements_stmt |
show_retention_policies | show_retention_policies |
show_series_stmt | show_series_stmt |
show_tag_key_stmt | show_tag_keys_stmt |
show_tag_value_stmt | show_tag_values_stmt |
show_users_stmt | show_users_stmt |
revoke_stmt | revoke_stmt |
select_stmt . select_stmt .
@ -252,6 +318,26 @@ delete_stmt = "DELETE" from_clause where_clause .
DELETE FROM cpu WHERE region = 'uswest'; DELETE FROM cpu WHERE region = 'uswest';
``` ```
### DROP CONTINUOUS QUERY
drop_continuous_query_stmt = "DROP CONTINUOUS QUERY" query_name .
#### Example:
```sql
DROP CONTINUOUS QUERY myquery;
```
### DROP DATABASE
drop_database_stmt = "DROP DATABASE" db_name .
#### Example:
```sql
DROP DATABASE mydb;
```
### DROP RETENTION POLICY ### DROP RETENTION POLICY
``` ```
@ -265,8 +351,35 @@ drop_retention_policy_stmt = "DROP RETENTION POLICY" policy_name "ON" db_name .
DROP RETENTION POLICY "1h.cpu" ON mydb; DROP RETENTION POLICY "1h.cpu" ON mydb;
``` ```
### DROP SERIES
```
drop_series_stmt =
```
#### Example:
```sql
```
### DROP USER
```
drop_user_stmt =
```
#### Example:
```sql
```
### GRANT ### GRANT
NOTE: Users can be granted privileges on databases that do not exist.
``` ```
grant_stmt = "GRANT" privilege [ on_clause ] to_clause grant_stmt = "GRANT" privilege [ on_clause ] to_clause
``` ```
@ -281,6 +394,17 @@ GRANT ALL TO jdoe;
GRANT READ ON mydb TO jdoe; GRANT READ ON mydb TO jdoe;
``` ```
### SHOW CONTINUOUS QUERIES
show_continuous_queries_stmt = "SHOW CONTINUOUS QUERIES"
#### Example:
```sql
-- show all continuous queries
SHOW CONTINUOUS QUERIES;
```
### SHOW DATABASES ### SHOW DATABASES
``` ```
@ -294,6 +418,29 @@ show_databases_stmt = "SHOW DATABASES" .
SHOW DATABASES; SHOW DATABASES;
``` ```
### SHOW FIELD
show_field_keys_stmt =
#### Examples:
```sql
```
### SHOW MEASUREMENTS
show_measurements_stmt = [ where_clause ] [ group_by_clause ] [ limit_clause ]
[ offset_clause ] .
```sql
-- show all measurements
SHOW MEASUREMENTS;
-- show measurements where region tag = 'uswest' AND host tag = 'serverA'
SHOW MEASUREMENTS WHERE region = 'uswest' AND host = 'serverA';
```
### SHOW RETENTION POLICIES ### SHOW RETENTION POLICIES
``` ```
@ -307,6 +454,62 @@ show_retention_policies = "SHOW RETENTION POLICIES" db_name .
SHOW RETENTION POLICIES mydb; SHOW RETENTION POLICIES mydb;
``` ```
### SHOW SERIES
```
show_series_stmt = [ from_clause ] [ where_clause ] [ group_by_clause ]
[ limit_clause ] [ offset_clause ] .
```
#### Example:
```sql
```
### SHOW TAG KEYS
```
show_tag_keys_stmt = [ from_clause ] [ where_clause ] [ group_by_clause ]
[ limit_clause ] [ offset_clause ] .
```
#### Examples:
```sql
-- show all tag keys
SHOW TAG KEYS;
-- show all tag keys from the cpu measurement
SHOW TAG KEYS FROM cpu;
-- show all tag keys from the cpu measurement where the region key = 'uswest'
SHOW TAG KEYS FROM cpu WHERE region = 'uswest';
-- show sll tag keys where the host key = 'serverA'
SHOW TAG KEYS WHERE host = 'serverA';
```
### SHOW TAG VALUES
```
show_tag_values_stmt = [ from_clause ] with_tag_clause [ where_clause ]
[ group_by_clause ] [ limit_clause ] [ offset_clause ] .
```
#### Examples:
```sql
-- show all tag values across all measurements for the region tag
SHOW TAG VALUES WITH TAG = 'region';
-- show tag values from the cpu measurement for the region tag
SHOW TAG VALUES FROM cpu WITH TAG = 'region';
-- show tag values from the cpu measurement for region & host tag keys where service = 'redis'
SHOW TAG VALUES FROM cpu WITH TAG IN (region, host) WHERE service = 'redis';
```
### SHOW USERS ### SHOW USERS
``` ```
@ -320,30 +523,93 @@ show_users_stmt = "SHOW USERS" .
SHOW USERS; SHOW USERS;
``` ```
### REVOKE
```
revoke_stmt = privilege [ "ON" db_name ] "FROM" user_name
```
#### Examples:
```sql
-- revoke cluster admin from jdoe
REVOKE ALL PRIVILEGES FROM jdoe;
-- revoke read privileges from jdoe on mydb
REVOKE READ ON mydb FROM jdoe;
```
### SELECT
```
select_stmt = fields from_clause [ into_clause ] [ where_clause ]
[ group_by_clause ] [ order_by_clause ] [ limit_clause ]
[ offset_clause ] .
```
#### Examples:
```sql
-- select mean value from the cpu measurement where region = 'uswest' grouped by 10 minute intervals
SELECT mean(value) FROM cpu WHERE region = 'uswest' GROUP BY time(10m);
```
## Clauses ## Clauses
``` ```
from_clause = "FROM" measurements . from_clause = "FROM" measurements .
where_clause = "WHERE" expr . group_by_clause = "GROUP BY" dimensions .
limit_clause = "LIMIT" int_lit .
offset_clause = "OFFSET" int_lit .
on_clause = db_name . on_clause = db_name .
order_by_clause = "ORDER BY" sort_fields .
to_clause = user_name . to_clause = user_name .
where_clause = "WHERE" expr .
``` ```
## Expressions
```
binary_op = "+" | "-" | "*" | "/" | "AND" | "OR" | "=" | "!=" | "<" |
"<=" | ">" | ">=" .
expr = unary_expr { binary_op unary_expr } .
unary_expr = "(" expr ")" | var_ref | time_lit | string_lit |
number_lit | bool_lit | duration_lit .
## Other ## Other
``` decimals = decimal_digit { decimal_digit } .
expr =
measurements = dimenson = expr .
dimensons = dimenson { "," dimenson } .
field = expr [ alias ] .
fields = field { "," field } .
measurement = [ db_name "." [ policy_name ] "." ]
measurements = measurement { "," measurement } .
password = identifier . password = identifier .
policy_name = identifier . policy_name = identifier .
user_name = identifier .
privilege = "ALL" [ "PRIVILEGES" ] | "READ" | "WRITE" . privilege = "ALL" [ "PRIVILEGES" ] | "READ" | "WRITE" .
sort_field = field_name [ ASC | DESC ] .
sort_fields = sort_field { "," sort_field } .
user_name = identifier .
``` ```