From 1e2f9a56e9bcc69280584f84c034a68a047e275f Mon Sep 17 00:00:00 2001 From: lwandzura <51929958+lwandzura@users.noreply.github.com> Date: Mon, 16 May 2022 17:38:56 -0500 Subject: [PATCH] Into clause link fix (#4024) * fixed formatting on v1.3 * fixed formatting for 1.4 version * fixed formatting for v1.5 * fixed formatting for version 1.6 --- .../v1.3/query_language/data_exploration.md | 447 ++++++++--------- .../v1.4/query_language/data_exploration.md | 426 +++++++---------- .../v1.5/query_language/data_exploration.md | 449 ++++++++---------- .../v1.6/query_language/data_exploration.md | 283 +++++------ 4 files changed, 735 insertions(+), 870 deletions(-) diff --git a/content/influxdb/v1.3/query_language/data_exploration.md b/content/influxdb/v1.3/query_language/data_exploration.md index d604c4436..60c359eef 100644 --- a/content/influxdb/v1.3/query_language/data_exploration.md +++ b/content/influxdb/v1.3/query_language/data_exploration.md @@ -18,29 +18,29 @@ for exploring your data. General Tips on Query Syntax: - The SELECT Statement + The SELECT statement ORDER BY time DESC Time Syntax - The WHERE Clause - The LIMIT and SLIMIT Clauses + The WHERE clause + The LIMIT and SLIMIT clauses Regular Expressions - The GROUP BY Clause - The OFFSET and SOFFSET Clauses - Data Types and Cast Operations + The GROUP BY clause + The OFFSET and SOFFSET clauses + Data types and cast operations - The INTO Clause - The Time Zone Clause - Merge Behavior + The INTO clause + The Time Zone clause + Merge behavior - Multiple Statements + Multiple statements @@ -63,61 +63,19 @@ Connected to http://localhost:8086 version {{< latest-patch >}} InfluxDB shell {{< latest-patch >}} > ``` - Next, get acquainted with this subsample of the data in the `h2o_feet` measurement: -name: h2o_feet -\------------------------------------ -time -           -level description -     -location -     -water_level -   -2015-08-18T00:00:00Z -   -between 6 and 9 feet -      -coyote_creek -   -8.12 -2015-08-18T00:00:00Z -   -below 3 feet -       -santa_monica -      -2.064 -2015-08-18T00:06:00Z -   -between 6 and 9 feet -     -coyote_creek -     -8.005 -2015-08-18T00:06:00Z -   -below 3 feet -       -santa_monica -      -2.116 -2015-08-18T00:12:00Z -   -between 6 and 9 feet -      -coyote_creek -   -7.887 -2015-08-18T00:12:00Z -   -below 3 feet -       -santa_monica -      -2.028 +name: h2o_feet + +| time | level description | location | water_level | +| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| 2015-08-18T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.12 | +| 2015-08-18T00:00:00Z | below 3 feet | santa_monica | 2.064 | +| 2015-08-18T00:06:00Z | between 6 and 9 feet | coyote_creek | 8.005 | +| 2015-08-18T00:06:00Z | below 3 feet | santa_monica | 2.116 | +| 2015-08-18T00:12:00Z | between 6 and 9 feet | coyote_creek | 7.887 | +| 2015-08-18T00:12:00Z | below 3 feet | santa_monica | 2.028 | + The data in the `h2o_feet` [measurement](/influxdb/v1.3/concepts/glossary/#measurement) occur at six-minute time intervals. @@ -131,14 +89,12 @@ All of these data is in the `NOAA_water_database` [database](/influxdb/v1.3/conc > **Disclaimer:** The `level description` field isn't part of the original NOAA data - we snuck it in there for the sake of having a field key with a special character and string field values. -
# The basic SELECT statement The `SELECT` statement queries data from a particular [measurement](/influxdb/v1.3/concepts/glossary/#measurement) or measurements. Tired of reading? Check out this InfluxQL Short: -
-
+ ### Syntax @@ -218,7 +174,7 @@ Please review the [rules for single and double-quoting](/influxdb/v1.3/troublesh ### Examples #### Example 1: Select all fields and tags from a single measurement -``` +```sql > SELECT * FROM "h2o_feet" name: h2o_feet @@ -246,7 +202,7 @@ If you do not set the `rp` query string parameter, the HTTP API automatically queries the database's `DEFAULT` retention policy. #### Example 2: Select specific tags and fields from a single measurement -``` +```sql > SELECT "level description","location","water_level" FROM "h2o_feet" name: h2o_feet @@ -265,7 +221,7 @@ Note that the `SELECT` clause must specify at least one field when it includes a tag. #### Example 3: Select specific tags and fields from a single measurement, and provide their identifier type -``` +```sql > SELECT "level description"::field,"location"::tag,"water_level"::field FROM "h2o_feet" name: h2o_feet @@ -286,7 +242,7 @@ Use `::[field | tag]` to differentiate between [an identical field key and tag k That syntax is not required for most use cases. #### Example 4: Select all fields from a single measurement -``` +```sql > SELECT *::field FROM "h2o_feet" name: h2o_feet @@ -303,7 +259,7 @@ The query selects all fields from the `h2o_feet` measurement. The `SELECT` clause supports combining the `*` syntax with the `::` syntax. #### Example 5: Select a specific field from a measurement and perform basic arithmetic -``` +```sql > SELECT ("water_level" * 2) + 4 from "h2o_feet" name: h2o_feet @@ -323,7 +279,7 @@ See [Mathematical Operators](/influxdb/v1.3/query_language/math_operators/) for more on supported operators. #### Example 6: Select all data from more than one measurement -``` +```sql > SELECT * FROM "h2o_feet","h2o_pH" name: h2o_feet @@ -350,7 +306,7 @@ The query selects all fields and tags from two measurements: `h2o_feet` and Separate multiple measurements with a comma (`,`). #### Example 7: Select all data from a fully qualified measurement -``` +```sql > SELECT * FROM "NOAA_water_database"."autogen"."h2o_feet" name: h2o_feet @@ -373,7 +329,7 @@ In the HTTP API, fully qualify a measurement in place of using the `db` and `rp` query string parameters if desired. #### Example 8: Select all data from a measurement in a particular database -``` +```sql > SELECT * FROM "NOAA_water_database".."h2o_feet" name: h2o_feet @@ -398,6 +354,7 @@ string parameter if desired. ### Common Issues with the SELECT statement #### Issue 1: Selecting tag keys in the SELECT clause + A query requires at least one [field key](/influxdb/v1.3/concepts/glossary/#field-key) in the `SELECT` clause to return data. If the `SELECT` clause only includes a single [tag key](/influxdb/v1.3/concepts/glossary/#tag-key) or several tag keys, the @@ -405,16 +362,17 @@ query returns an empty response. This behavior is a result of how the system stores data. ##### Example -
+ The following query returns no data because it specifies a single tag key (`location`) in the `SELECT` clause: -``` +```sql > SELECT "location" FROM "h2o_feet" > ``` To return any data associated with the `location` tag key, the query's `SELECT` clause must include at least one field key (`water_level`): -``` + +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 name: h2o_feet time water_level location @@ -439,7 +397,7 @@ Tired of reading? Check out this InfluxQL Short: ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` @@ -450,7 +408,7 @@ timestamps. #### fields -``` +```sql field_key ['string' | boolean | float | integer] ``` @@ -477,7 +435,7 @@ Other supported features: #### tags -``` +```sql tag_key ['tag_value'] ``` @@ -507,7 +465,7 @@ details how to specify alternative time ranges in the `WHERE` clause. ### Examples #### Example 1: Select data that have specific field key-values -``` +```sql > SELECT * FROM "h2o_feet" WHERE "water_level" > 8 name: h2o_feet @@ -526,7 +484,7 @@ The query returns data from the `h2o_feet` that are greater than eight. #### Example 2: Select data that have a specific string field key-value -``` +```sql > SELECT * FROM "h2o_feet" WHERE "level description" = 'below 3 feet' name: h2o_feet @@ -545,7 +503,7 @@ InfluxQL requires single quotes around string field values in the `WHERE` clause. #### Example 3: Select data that have a specific field key-value and perform basic arithmetic -``` +```sql > SELECT * FROM "h2o_feet" WHERE "water_level" + 2 > 11.9 name: h2o_feet @@ -570,7 +528,7 @@ for more on supported operators. #### Example 4: Select data that have a specific tag key-value -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' name: h2o_feet @@ -588,7 +546,7 @@ The query returns data from the `h2o_feet` measurement where the InfluxQL requires single quotes around tag values in the `WHERE` clause. #### Example 5: Select data that have specific field key-values and tag key-values -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" <> 'santa_monica' AND (water_level < -0.59 OR water_level > 9.95) name: h2o_feet @@ -609,7 +567,7 @@ The `WHERE` clause supports the operators `AND` and `OR`, and supports separating logic with parentheses. #### Example 6: Select data that have specific timestamps -``` +```sql > SELECT * FROM "h2o_feet" WHERE time > now() - 7d ``` @@ -633,7 +591,7 @@ The first two queries in the code block below attempt to specify the tag value Those queries return no results. The third query single quotes `santa_monica` (this is the supported syntax) and returns the expected results. -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = santa_monica > SELECT "water_level" FROM "h2o_feet" WHERE "location" = "santa_monica" @@ -657,7 +615,7 @@ The second query returns no results. The third query single quotes `at or greater than 9 feet` (this is the supported syntax) and returns the expected results. -``` +```sql > SELECT "level description" FROM "h2o_feet" WHERE "level description" = at or greater than 9 feet ERR: error parsing query: found than, expected ; at line 1, char 86 @@ -674,9 +632,7 @@ time level description 2015-09-15T22:42:00Z at or greater than 9 feet ``` -
-
-# The GROUP BY clause +## The GROUP BY clause The `GROUP BY` clause groups query results by a user-specified set of [tags](/influxdb/v1.3/concepts/glossary/#tag) or a time interval. @@ -709,7 +665,7 @@ Tired of reading? Check out this InfluxQL Short: #### Syntax -``` +```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [, -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet tags: location=coyote_creek time mean ---- ---- -1970-01-01T00:00:00Z 5.359342451341401 +1970-01-01T00:00:00Z 5.359342451341401 name: h2o_feet tags: location=santa_monica time mean ---- ---- -1970-01-01T00:00:00Z 3.530863470081006 +1970-01-01T00:00:00Z 3.530863470081006 ``` The query uses an InfluxQL [function](/influxdb/v1.3/query_language/functions/) @@ -761,8 +717,8 @@ InfluxDB returns results in two [series](/influxdb/v1.3/concepts/glossary/#serie If you request a query that has no timestamp to return, such as an [aggregation function](/influxdb/v1.3/query_language/functions/) with an unbounded time range, InfluxDB returns epoch 0 as the timestamp. ##### Example 2: Group query results by more than one tag -
-``` + +```sql > SELECT MEAN("index") FROM "h2o_quality" GROUP BY location,randtag name: h2o_quality @@ -808,8 +764,8 @@ each combination of the `location` [tag](/influxdb/v1.3/concepts/glossary/#tag) Separate multiple tags with a comma in the `GROUP BY` clause. ##### Example 3: Group query results by all tags -
-``` + +```sql > SELECT MEAN("index") FROM "h2o_quality" GROUP BY * name: h2o_quality @@ -870,7 +826,7 @@ This is because the `h2o_quality` measurement only has two tag keys. ### Basic GROUP BY time() Syntax #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(),[tag_key] [fill()] ``` @@ -882,7 +838,7 @@ in the [`SELECT` clause](#the-basic-select-statement) and a time range in the Note that the `GROUP BY` clause must come after the `WHERE` clause. ##### `time(time_interval)` -
+ The `time_interval` in the `GROUP BY time()` clause is a [duration literal](/influxdb/v1.3/query_language/spec/#durations). It determines how InfluxDB groups query results over time. @@ -890,7 +846,7 @@ For example, a `time_interval` of `5m` groups query results into five-minute time groups across the time range specified in the [`WHERE` clause](#the-where-clause). ##### `fill()` -
+ `fill()` is optional. It changes the value reported for time intervals that have no data. See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill) @@ -905,7 +861,7 @@ and the timestamps returned by the query. #### Examples of Basic Syntax The examples below use the following subsample of the sample data: -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' name: h2o_feet @@ -926,8 +882,8 @@ time water_level location ``` ##### Example 1: Group query results into 12 minute intervals -
-``` + +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: h2o_feet @@ -950,8 +906,8 @@ The count for the second timestamp covers the raw data between `2015-08-18T00:12 and up to, but not including, `2015-08-18T00:24:00Z.` ##### Example 2: Group query results into 12 minutes intervals and by a tag key -
-``` + +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location" name: h2o_feet @@ -988,7 +944,7 @@ and up to, but not including, `2015-08-18T00:24:00Z.` #### Common Issues with Basic Syntax ##### Issue 1: Unexpected timestamps and values in query results -
+ With the basic syntax, InfluxDB relies on the `GROUP BY time()` interval and on the system's preset time boundaries to determine the raw data included in each time interval and the timestamps returned by the query. @@ -998,7 +954,7 @@ In some cases, this can lead to unexpected results. Raw data: -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:18:00Z' name: h2o_feet -------------- @@ -1013,7 +969,7 @@ Query and Results: The following query covers a 12-minute time range and groups results into 12-minute time intervals, but it returns **two** results: -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m) name: h2o_feet @@ -1059,7 +1015,7 @@ in the Advanced Syntax section continues with the query shown here; it shifts forward the preset time boundaries by six minutes such that InfluxDB returns: -``` +```sql name: h2o_feet time count ---- ----- @@ -1070,7 +1026,7 @@ time count #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(,),[tag_key] [fill()] ``` @@ -1082,7 +1038,7 @@ in the [`SELECT` clause](#the-basic-select-statement) and a time range in the Note that the `GROUP BY` clause must come after the `WHERE` clause. ##### `time(time_interval,offset_interval)` -
+ See the [Basic GROUP BY time() Syntax](#basic-group-by-time-syntax) for details on the `time_interval`. @@ -1092,7 +1048,7 @@ It shifts forward or back InfluxDB's preset time boundaries. The `offset_interval` can be positive or negative. ##### `fill()` -
+ `fill()` is optional. It changes the value reported for time intervals that have no data. See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill) @@ -1108,7 +1064,7 @@ and the timestamps returned by the query. The examples below use the following subsample of the sample data: -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:54:00Z' name: h2o_feet @@ -1127,8 +1083,8 @@ time water_level ``` ##### Example 1: Group query results into 18 minute intervals and shift the preset time boundaries forward -
-``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m,6m) name: h2o_feet @@ -1145,7 +1101,7 @@ time intervals, and offsetting the preset time boundaries by six minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m) name: h2o_feet @@ -1205,8 +1161,8 @@ Note that `offset_interval` forces the fourth time boundary to be outside the query's time range so the query returns no results for that last interval. ##### Example 2: Group query results into 12 minute intervals and shift the preset time boundaries back -
-``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m,-12m) name: h2o_feet @@ -1229,7 +1185,8 @@ There are no performance differences between the two queries; feel free to choos intuitive option when deciding between a positive and negative `offset_interval`. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m) name: h2o_feet @@ -1289,10 +1246,10 @@ Note that `offset_interval` forces the first time boundary to be outside the query's time range so the query returns no results for that first interval. ##### Example 3: Group query results into 12 minute intervals and shift the preset time boundaries forward -
+ This example is a continuation of the scenario outlined in [Common Issues with Basic Syntax](#common-issues-with-basic-syntax). -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m,6m) name: h2o_feet @@ -1307,7 +1264,7 @@ time intervals, and offsetting the preset time boundaries by six minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m) name: h2o_feet @@ -1361,7 +1318,7 @@ the query's time range so the query returns no results for that second interval. #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(time_interval,[)] ``` @@ -1374,7 +1331,6 @@ Note that `fill()` must go at the end of the `GROUP BY` clause if you're `GROUP(ing) BY` several things (for example, both [tags](/influxdb/v1.3/concepts/glossary/#tag) and a time interval). ##### fill_option -
Any numerical value               @@ -1415,7 +1371,7 @@ Reports the value from the previous time interval for time intervals with no dat {{% tab-content %}} Without `fill(100)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1428,7 +1384,7 @@ time max ``` With `fill(100)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(100) name: h2o_feet @@ -1448,7 +1404,7 @@ time max Without `fill(linear)`: -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:00:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) name: pond @@ -1463,7 +1419,7 @@ time mean ``` With `fill(linear)`: -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:00:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond @@ -1488,7 +1444,7 @@ We had to create a dataset with less regular data to work with `fill(linear)`. {{% tab-content %}} Without `fill(none)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1501,7 +1457,7 @@ time max ``` With `fill(none)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(none) name: h2o_feet @@ -1519,7 +1475,7 @@ time max {{% tab-content %}} Without `fill(null)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1532,7 +1488,7 @@ time max ``` With `fill(null)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(null) name: h2o_feet @@ -1552,7 +1508,7 @@ That result matches the result of the query without `fill(null)`. {{% tab-content %}} Without `fill(previous)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1565,7 +1521,7 @@ time max ``` With `fill(previous)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1586,7 +1542,7 @@ the value from the previous time interval. #### Common issues with `fill()` ##### Issue 1: `fill()` when no data fall within the query's time range -
+ Currently, queries ignore `fill()` if no data fall within the query's time range. This is the expected behavior. An open [feature request](https://github.com/influxdata/influxdb/issues/6967) on GitHub @@ -1598,13 +1554,14 @@ range covers no data. The following query returns no data because `water_level` has no points within the query's time range. Note that `fill(800)` has no effect on the query results. -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2015-09-18T22:00:00Z' AND time <= '2015-09-18T22:18:00Z' GROUP BY time(12m) fill(800) > ``` ##### Issue 2: `fill(previous)` when the previous result falls outside the query's time range -
+ `fill(previous)` doesn’t fill the result for a time interval if the previous value is outside the query’s time range. @@ -1613,7 +1570,8 @@ value is outside the query’s time range. The following query covers the time range between `2015-09-18T16:24:00Z` and `2015-09-18T16:54:00Z`. Note that `fill(previous)` fills the result for `2015-09-18T16:36:00Z` with the result from `2015-09-18T16:24:00Z`. -``` + +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2015-09-18T16:24:00Z' AND time <= '2015-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1630,7 +1588,7 @@ Note that `fill(previous)` doesn't fill the result for `2015-09-18T16:36:00Z` wi result from `2015-09-18T16:24:00Z`; the result for `2015-09-18T16:24:00Z` is outside the query's shorter time range. -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2015-09-18T16:36:00Z' AND time <= '2015-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1641,7 +1599,7 @@ time max ``` ##### Issue 3: `fill(linear)` when the previous or following result falls outside the query's time range -
+ `fill(linear)` doesn't fill the result for a time interval with no data if the previous result or the following result is outside the query's time range. @@ -1653,7 +1611,7 @@ The following query covers the time range between `2016-11-11T21:24:00Z` and using the values from the `2016-11-11T21:24:00Z` time interval and the `2016-11-11T22:00:00Z` time interval. -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time > '2016-11-11T21:24:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond @@ -1672,7 +1630,7 @@ time interval and the `2016-11-11T21:48:00Z` time interval; the result for `2016-11-11T21:24:00Z` is outside the query's shorter time range and InfluxDB cannot perform the linear interpolation. -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:36:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond time mean @@ -1685,14 +1643,12 @@ time mean > **Note:** The data in Issue 3 are not in `NOAA_water_database`. We had to create a dataset with less regular data to work with `fill(linear)`. -
-
# The INTO clause The `INTO` clause writes query results to a user-specified [measurement](/influxdb/v1.3/concepts/glossary/#measurement). ### Syntax -``` +```sql SELECT_clause INTO FROM_clause [WHERE_clause] [GROUP_BY_clause] ``` @@ -1730,7 +1686,7 @@ retention policy that match the [regular expression](#regular-expressions) in th #### Example 1: Rename a database -``` +```sql > SELECT * INTO "copy_NOAA_water_database"."autogen".:MEASUREMENT FROM "NOAA_water_database"."autogen"./.*/ GROUP BY * name: result @@ -1750,7 +1706,7 @@ for how to manage databases and retention policies. The `GROUP BY *` clause [preserves tags](#issue-1-missing-data) in the source database as tags in the destination database. The following query does not maintain the series context for tags; tags will be stored as fields in the destination database (`copy_NOAA_water_database`): -``` +```sql SELECT * INTO "copy_NOAA_water_database"."autogen".:MEASUREMENT FROM "NOAA_water_database"."autogen"./.*/ ``` @@ -1763,6 +1719,7 @@ Use the [`WHERE` clause](#time-syntax) to define time boundaries for each query. {{% /note %}} ##### Move large amounts of data with sequential queries + ```sql SELECT * INTO .. @@ -1782,7 +1739,7 @@ WHERE time > now() - 80w and time < now() - 70w GROUP BY * #### Example 2: Write the results of a query to a measurement -``` +```sql > SELECT "water_level" INTO "h2o_feet_copy_1" FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: result @@ -1815,7 +1772,7 @@ The timestamp in the response is meaningless; InfluxDB uses epoch 0 #### Example 3: Write the results of a query to a fully qualified measurement -``` +```sql > SELECT "water_level" INTO "where_else"."autogen"."h2o_feet_copy_2" FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: result @@ -1847,7 +1804,7 @@ The timestamp in the response is meaningless; InfluxDB uses epoch 0 #### Example 4: Write aggregated results to a measurement (downsampling) -``` +```sql > SELECT MEAN("water_level") INTO "all_my_averages" FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: result @@ -1881,7 +1838,7 @@ Downsampling is a common use case for the `INTO` clause. #### Example 5: Write aggregated results for more than one measurement to a different database (downsampling with backreferencing) -``` +```sql > SELECT MEAN(*) INTO "where_else"."autogen".:MEASUREMENT FROM /.*/ WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:06:00Z' GROUP BY time(12m) name: result @@ -1964,8 +1921,6 @@ documentation for how to automate `INTO` clause queries on realtime data. Among [other uses](/influxdb/v1.3/query_language/continuous_queries/#continuous-query-use-cases), Continuous Queries automate the downsampling process. -
-
# ORDER BY time DESC By default, InfluxDB returns results in ascending time order; the first [point](/influxdb/v1.3/concepts/glossary/#point) returned has the oldest [timestamp](/influxdb/v1.3/concepts/glossary/#timestamp) and @@ -1974,7 +1929,7 @@ the last point returned has the most recent timestamp. with the most recent timestamps first. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time DESC ``` @@ -1989,7 +1944,7 @@ if the query includes a `WHERE` clause and no `GROUP BY` clause. #### Example 1: Return the newest points first -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' ORDER BY time DESC name: h2o_feet @@ -2008,7 +1963,8 @@ Without `ORDER by time DESC`, the query would return `2015-08-18T00:00:00Z` first and `2015-09-18T21:42:00Z` last. #### Example 2: Return the newest points first and include a GROUP BY time() clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY time(12m) ORDER BY time DESC name: h2o_feet @@ -2030,8 +1986,6 @@ first. Without `ORDER BY time DESC`, the query would return `2015-08-18T00:00:00Z` first and `2015-08-18T00:36:00Z` last. -
-
# The LIMIT and SLIMIT clauses `LIMIT` and `SLIMIT` limit the number of @@ -2042,7 +1996,8 @@ Without `ORDER BY time DESC`, the query would return `LIMIT ` returns the first `N` [points](/influxdb/v1.3/concepts/glossary/#point) from the specified [measurement](/influxdb/v1.3/concepts/glossary/#measurement). ### Syntax -``` + +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT ``` @@ -2057,7 +2012,8 @@ Note that the `LIMIT` clause must appear in the order outlined in the syntax abo ### Examples #### Example 1: Limit the number of points returned -``` + +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 name: h2o_feet @@ -2072,7 +2028,7 @@ The query returns the three oldest [points](/influxdb/v1.3/concepts/glossary/#po `h2o_feet` [measurement](/influxdb/v1.3/concepts/glossary/#measurement). #### Example 2: Limit the number points returned and include a GROUP BY clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 name: h2o_feet @@ -2103,7 +2059,8 @@ one for each twelve-minute interval in the query's time range. `SLIMIT ` returns every [point](/influxdb/v1.3/concepts/glossary/#point) from \ [series](/influxdb/v1.3/concepts/glossary/#series) in the specified [measurement](/influxdb/v1.3/concepts/glossary/#measurement). ### Syntax -``` + +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] SLIMIT ``` @@ -2118,7 +2075,8 @@ Note that the `SLIMIT` clause must appear in the order outlined in the syntax ab ### Examples #### Example 1: Limit the number of series returned -``` + +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 name: h2o_feet @@ -2138,7 +2096,8 @@ The query returns all `water_level` [points](/influxdb/v1.3/concepts/glossary/#p with the `h2o_feet` [measurement](/influxdb/v1.3/concepts/glossary/#measurement). #### Example 2: Limit the number of series returned and include a GROUP BY time() clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) SLIMIT 1 name: h2o_feet @@ -2166,7 +2125,8 @@ associated with the `h2o_feet` measurement: `location=coyote_creek` and `LIMIT ` followed by `SLIMIT ` returns the first \ [points](/influxdb/v1.3/concepts/glossary/#point) from \ [series](/influxdb/v1.3/concepts/glossary/#series) in the specified measurement. ### Syntax -``` + +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] LIMIT SLIMIT ``` @@ -2184,7 +2144,8 @@ Note that the `LIMIT` and `SLIMIT` clauses must appear in the order outlined in ### Examples #### Example 1: Limit the number of points and series returned -``` + +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * LIMIT 3 SLIMIT 1 name: h2o_feet @@ -2201,7 +2162,8 @@ of the [series](/influxdb/v1.3/concepts/glossary/#series) associated with the [measurement](/influxdb/v1.3/concepts/glossary/#measurement) `h2o_feet`. #### Example 2: Limit the number of points and series returned and include a GROUP BY time() clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 SLIMIT 1 name: h2o_feet @@ -2223,8 +2185,6 @@ associated with the `h2o_feet` measurement. Note that without `LIMIT 2 SLIMIT 1`, the query would return four points for each of the two series associated with the `h2o_feet` measurement. -
-
# The OFFSET and SOFFSET Clauses `OFFSET` and `SOFFSET` paginates [points](/influxdb/v1.3/concepts/glossary/#point) and [series](/influxdb/v1.3/concepts/glossary/#series) returned. @@ -2239,7 +2199,8 @@ for each of the two series associated with the `h2o_feet` measurement. `OFFSET ` paginates `N` [points](/influxdb/v1.3/concepts/glossary/#point) in the query results. ### Syntax -``` + +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT_clause OFFSET [SLIMIT_clause] ``` @@ -2256,7 +2217,8 @@ timestamps outside of that time range. ### Examples #### Example 1: Paginate points -``` + +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 OFFSET 3 name: h2o_feet @@ -2272,7 +2234,8 @@ If the query did not include `OFFSET 3`, it would return the first, second, and third points from that measurement. #### Example 2: Paginate points and include several clauses -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 name: h2o_feet @@ -2295,7 +2258,7 @@ The `OFFSET 2` clause excludes the first two averages from the query results. The [`SLIMIT 1` clause](#the-slimit-clause) limits the number of series returned to one. Without `OFFSET 2`, the query would return the first two averages of the query results: -``` +```sql name: h2o_feet tags: location=coyote_creek time mean @@ -2308,7 +2271,7 @@ time mean `SOFFSET ` paginates `N` [series](/influxdb/v1.3/concepts/glossary/#series) in the query results. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time(time_interval)] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] SLIMIT_clause SOFFSET ``` @@ -2325,7 +2288,8 @@ through more than the total number of series. ### Examples #### Example 1: Paginate series -``` + +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 SOFFSET 1 name: h2o_feet @@ -2345,7 +2309,8 @@ Without `SOFFSET 1`, the query returns data for the series associated with the `h2o_feet` measurement and the `location = coyote_creek` tag. #### Example 2: Paginate series and include all clauses -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 SOFFSET 1 name: h2o_feet @@ -2369,7 +2334,7 @@ The [`SLIMIT 1` clause](#the-slimit-clause) limits the number of series returned The `SOFFSET 1` clause paginates the series returned. Without `SOFFSET 1`, the query would return the results for a different series: -``` +```sql name: h2o_feet tags: location=coyote_creek time mean @@ -2378,15 +2343,13 @@ time mean 2015-08-18T00:00:00Z 8.0625 ``` -
-
# The Time Zone Clause The `tz()` clause returns the UTC offset for the specified timezone. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') ``` @@ -2400,7 +2363,8 @@ The `time_zone` parameter follows the TZ syntax in the [Internet Assigned Number ### Examples #### Example 1: Return the UTC offset for Chicago's time zone -``` + +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:18:00Z' tz('America/Chicago') name: h2o_feet @@ -2414,8 +2378,6 @@ time water_level The query results include the UTC offset (`-05:00`) for the `America/Chicago` time zone in the timestamps. -
-
# Time Syntax For most `SELECT` statements, the default time range is between [`1677-09-21 00:12:43.145224194` and `2262-04-11T23:47:16.854775806Z` UTC](/influxdb/v1.3/troubleshooting/frequently-asked-questions/#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store). @@ -2433,8 +2395,7 @@ statement's [`WHERE` clause](#the-where-clause). Tired of reading? Check out this InfluxQL Short: -
-
+ ## Absolute Time @@ -2442,7 +2403,7 @@ Tired of reading? Check out this InfluxQL Short: Specify absolute time with date-time strings and epoch time. ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE time ['' | '' | ] [AND ['' | '' | ] [...]] ``` @@ -2465,7 +2426,7 @@ for more information. #### rfc3339_date_time_string -``` +```sql 'YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ' ``` @@ -2474,7 +2435,7 @@ The [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) date-time string requires si #### rfc3339_like_date_time_string -``` +```sql 'YYYY-MM-DD HH:MM:SS.nnnnnnnnn' ``` @@ -2500,7 +2461,7 @@ duration literal. ### Examples #### Example 1: Specify a time range with RFC3339 date-time strings -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00.000000000Z' AND time <= '2015-08-18T00:12:00Z' name: h2o_feet @@ -2520,7 +2481,7 @@ Note that the single quotes around the RFC3339 date-time strings are required. #### Example 2: Specify a time range with RFC3339-like date-time strings -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18' AND time <= '2015-08-18 00:12:00' name: h2o_feet @@ -2539,9 +2500,9 @@ is 00:00:00. Note that the single quotes around the RFC3339-like date-time strings are required. - #### Example 3: Specify a time range with epoch timestamps -``` + +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1439856000000000000 AND time <= 1439856720000000000 name: h2o_feet @@ -2557,7 +2518,8 @@ at 00:00:00 and August 18, 2015 at 00:12:00. By default InfluxDB assumes epoch timestamps are in nanoseconds. #### Example 4: Specify a time range with second-precision epoch timestamps -``` + +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1439856000s AND time <= 1439856720s name: h2o_feet @@ -2574,7 +2536,7 @@ The `s` [duration literal](/influxdb/v1.3/query_language/spec/#durations) at the end of the epoch timestamps indicate that the epoch timestamps are in seconds. #### Example 5: Perform basic arithmetic on an RFC3339-like date-time string -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > '2015-09-18T21:24:00Z' + 6m name: h2o_feet @@ -2590,7 +2552,7 @@ Note that the whitespace between the `+` and `6m` is required. #### Example 6: Perform basic arithmetic on an epoch timestamp -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > 24043524m - 6m name: h2o_feet @@ -2610,7 +2572,7 @@ Note that the whitespace between the `-` and `6m` is required. Use [`now()`](/influxdb/v1.3/concepts/glossary/#now) to query data with [timestamps](/influxdb/v1.3/concepts/glossary/#timestamp) relative to the server's current timestamp. ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE time now() [[ - | + ] ] [(AND|OR) now() [...]] ``` @@ -2642,7 +2604,7 @@ The whitespace between `-` or `+` and the [duration literal](/influxdb/v1.3/quer ### Examples #### Example 1: Specify a time range with relative time -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > now() - 1h ``` @@ -2650,7 +2612,7 @@ The query returns data with timestamps that occur within the past hour. The whitespace between `-` and `1h` is required. #### Example 2: Specify a time range with absolute time and relative time -``` +```sql > SELECT "level description" FROM "h2o_feet" WHERE time > '2015-09-18T21:18:00Z' AND time < now() + 1000d name: h2o_feet @@ -2661,7 +2623,6 @@ time level description 2015-09-18T21:36:00Z between 3 and 6 feet 2015-09-18T21:42:00Z between 3 and 6 feet ``` - The query returns data with timestamps that occur between September 18, 2015 at 21:18:00 and 1000 days from `now()`. The whitespace between `+` and `1000d` is required. @@ -2689,13 +2650,14 @@ a `GROUP BY time()` clause must provide an alternative upper bound in the #### Example Use the [CLI](/influxdb/v1.3/tools/shell/) to write a point to the `NOAA_water_database` that occurs after `now()`: -``` +```sql > INSERT h2o_feet,location=santa_monica water_level=3.1 1587074400000000000 ``` Run a `GROUP BY time()` query that covers data with timestamps between `2015-09-18T21:30:00Z` and `now()`: -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= '2015-09-18T21:30:00Z' GROUP BY time(12m) fill(none) name: h2o_feet @@ -2707,7 +2669,7 @@ time mean Run a `GROUP BY time()` query that covers data with timestamps between `2015-09-18T21:30:00Z` and 180 weeks from `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= '2015-09-18T21:30:00Z' AND time <= now() + 180w GROUP BY time(12m) fill(none) name: h2o_feet @@ -2722,7 +2684,7 @@ Note that the `WHERE` clause must provide an alternative **upper** bound to override the default `now()` upper bound. The following query merely resets the lower bound to `now()` such that the query's time range is between `now()` and `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= now() GROUP BY time(12m) fill(none) > ``` @@ -2738,8 +2700,6 @@ in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format by default. Specify alternative formats with the [`epoch` query string parameter](/influxdb/v1.3/tools/api/#query-string-parameters). -
-
# Regular Expressions InfluxQL supports using regular expressions when specifying: @@ -2760,7 +2720,7 @@ string comparisons; queries with regular expressions are not as performant as those without. ### Syntax -``` +```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` @@ -2776,7 +2736,7 @@ Supported operators: ### Examples #### Example 1: Use a regular expression to specify field keys and tag keys in the SELECT clause -``` +```sql > SELECT /l/ FROM "h2o_feet" LIMIT 1 name: h2o_feet @@ -2796,7 +2756,7 @@ field keys and regular expressions for tag keys in the `SELECT` clause. The syntax `//::[field | tag]` is not supported. #### Example 2: Use a regular expression to specify field keys with a function in the SELECT clause -``` +```sql > SELECT DISTINCT(/level/) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00.000000000Z' AND time <= '2015-08-18T00:12:00Z' name: h2o_feet @@ -2812,7 +2772,7 @@ to return the distinct [field values](/influxdb/v1.3/concepts/glossary/#field-va for every field key that contains the word `level`. #### Example 3: Use a regular expression to specify measurements in the FROM clause -``` +```sql > SELECT MEAN("degrees") FROM /temperature/ name: average_temperature @@ -2832,7 +2792,7 @@ to calculate the average `degrees` for every [measurement](/influxdb/v1.3/concep #### Example 4: Use a regular expression to specify tag values in the WHERE clause -``` +```sql > SELECT MEAN(water_level) FROM "h2o_feet" WHERE "location" =~ /[m]/ AND "water_level" > 3 name: h2o_feet @@ -2847,7 +2807,7 @@ includes an `m` and `water_level` is greater than three. #### Example 5: Use a regular expression to specify a tag with no value in the WHERE clause -``` +```sql > SELECT * FROM "h2o_feet" WHERE "location" !~ /./ > ``` @@ -2863,7 +2823,7 @@ document for more information. #### Example 6: Use a regular expression to specify a tag with a value in the WHERE clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" =~ /./ name: h2o_feet @@ -2877,7 +2837,8 @@ to calculate the average `water_level` across all data that have a tag value for `location`. #### Example 7: Use a regular expression to specify a field value in the WHERE clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND "level description" =~ /between/ name: h2o_feet @@ -2891,7 +2852,8 @@ to calculate the average `water_level` for all data where the field value of `level description` includes the word `between`. #### Example 8: Use a regular expresssion to specify tag keys in the GROUP BY clause -``` + +```sql > SELECT FIRST("index") FROM "h2o_quality" GROUP BY /l/ name: h2o_quality @@ -2911,8 +2873,6 @@ The query uses an InfluxQL [function](/influxdb/v1.3/query_language/functions/) to select the first value of `index` for every tag that includes the letter `l` in its tag key. -
-
# Data Types and Cast Operations The [`SELECT` clause](#the-basic-select-statement) supports specifying a [field's](/influxdb/v1.3/concepts/glossary/#field) type and basic cast @@ -2943,7 +2903,7 @@ Please see the document for more information on how InfluxDB handles field value type discrepancies. ### Syntax -``` +```sql SELECT_clause :: FROM_clause ``` @@ -2954,7 +2914,7 @@ In most cases, InfluxDB returns no data if the `field_key` does not store data o `type`. See [Cast Operations](#cast-operations) for more information. ### Example -``` +```sql > SELECT "water_level"::float FROM "h2o_feet" LIMIT 4 name: h2o_feet @@ -2975,7 +2935,7 @@ Currently, InfluxDB supports casting [field values](/influxdb/v1.3/concepts/glos floats or from floats to integers. ### Syntax -``` +```sql SELECT_clause :: FROM_clause ``` @@ -2990,7 +2950,7 @@ string or boolean. #### Example 1: Cast float field values to integers -``` +```sql > SELECT "water_level"::integer FROM "h2o_feet" LIMIT 4 name: h2o_feet @@ -3006,7 +2966,7 @@ The query returns the integer form of `water_level`'s float [field values](/infl #### Example 2: Cast float field values to strings (this functionality is not supported) -``` +```sql > SELECT "water_level"::string FROM "h2o_feet" LIMIT 4 > ``` @@ -3014,8 +2974,6 @@ The query returns the integer form of `water_level`'s float [field values](/infl The query returns no data as casting a float field value to a string is not yet supported. -
-
# Merge Behavior In InfluxDB, queries merge [series](/influxdb/v1.3/concepts/glossary/#series) automatically. @@ -3028,7 +2986,7 @@ The second series is made of up the `h2o_feet` measurement and the `location = s The following query automatically merges those two series when it calculates the [average](/influxdb/v1.3/query_language/functions/#mean) `water_level`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" name: h2o_feet @@ -3038,7 +2996,7 @@ time mean ``` If you want the average `water_level` for the first series only, specify the relevant tag in the [`WHERE` clause](#the-where-clause): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: h2o_feet @@ -3049,7 +3007,7 @@ time mean If you want the average `water_level` for each individual series, include a [`GROUP BY` clause](#group-by-tags): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -3065,8 +3023,6 @@ time mean 1970-01-01T00:00:00Z 3.530863470081006 ``` -
-
# Multiple Statements Separate multiple [`SELECT` statements](#the-basic-select-statement) in a query with a semicolon (`;`). @@ -3081,7 +3037,7 @@ Separate multiple [`SELECT` statements](#the-basic-select-statement) in a query In InfluxDB's [CLI](/influxdb/v1.3/tools/shell/): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet"; SELECT "water_level" FROM "h2o_feet" LIMIT 2 name: h2o_feet @@ -3152,8 +3108,6 @@ With InfluxDB's [HTTP API](/influxdb/v1.3/tools/api/): {{% /tab-content %}} {{< /tabs-wrapper >}} -
-
# Subqueries A subquery is a query that is nested in the `FROM` clause of another query. @@ -3162,7 +3116,8 @@ Subqueries offer functionality similar to nested functions and SQL [`HAVING` clauses](https://en.wikipedia.org/wiki/Having_(SQL\)). ### Syntax -``` + +```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` @@ -3178,14 +3133,14 @@ The subquery supports all clauses listed in this document. InfluxQL supports multiple nested subqueries per main query. Sample syntax for multiple subqueries: -``` +```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ``` ### Examples #### Example 1: Calculate the [`SUM()`](/influxdb/v1.3/query_language/functions/#sum) of several [`MAX()`](/influxdb/v1.3/query_language/functions/#max) values -``` +```sql > SELECT SUM("max") FROM (SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location") name: h2o_feet @@ -3197,7 +3152,7 @@ time sum The query returns the sum of the maximum `water_level` values across every tag value of `location`. InfluxDB first performs the subquery; it calculates the maximum value of `water_level` for each tag value of `location`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -3217,7 +3172,7 @@ Next, InfluxDB performs the main query and calculates the sum of those maximum v Notice that the main query specifies `max`, not `water_level`, as the field key in the `SUM()` function. #### Example 2: Calculate the [`MEAN()`](/influxdb/v1.3/query_language/functions/#mean) difference between two fields -``` +```sql > SELECT MEAN("difference") FROM (SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare") name: pet_daycare @@ -3231,7 +3186,7 @@ The query returns the average of the differences between the number of `cats` an InfluxDB first performs the subquery. The subquery calculates the difference between the values in the `cats` field and the values in the `dogs` field, and it names the output column `difference`: -``` +```sql > SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare" name: pet_daycare @@ -3247,7 +3202,7 @@ Next, InfluxDB performs the main query and calculates the average of those diffe Notice that the main query specifies `difference` as the field key in the `MEAN()` function. #### Example 3: Calculate several [`MEAN()`](/influxdb/v1.3/query_language/functions/#mean) values and place a condition on those mean values -``` +```sql > SELECT "all_the_means" FROM (SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) ) WHERE "all_the_means" > 5 name: h2o_feet @@ -3261,7 +3216,7 @@ The query returns all mean values of the `water_level` field that are greater th InfluxDB first performs the subquery. The subquery calculates `MEAN()` values of `water_level` from `2015-08-18T00:00:00Z` through `2015-08-18T00:30:00Z` and groups the results into 12-minute intervals. It also names the output column `all_the_means`: -``` +```sql > SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: h2o_feet @@ -3276,7 +3231,7 @@ Next, InfluxDB performs the main query and returns only those mean values that a Notice that the main query specifies `all_the_means` as the field key in the `SELECT` clause. #### Example 4: Calculate the [`SUM()`](/influxdb/v1.3/query_language/functions/#sum) of several [`DERIVATIVE()`](/influxdb/v1.3/query_language/functions/#derivative) values -``` +```sql > SELECT SUM("water_level_derivative") AS "sum_derivative" FROM (SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location") GROUP BY "location" name: h2o_feet @@ -3297,7 +3252,7 @@ The query returns the sum of the derivative of average `water_level` values for InfluxDB first performs the subquery. The subquery calculates the derivative of average `water_level` values taken at 12-minute intervals. It performs that calculation for each tag value of `location` and names the output column `water_level_derivative`: -``` +```sql > SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location" name: h2o_feet @@ -3323,14 +3278,14 @@ Notice that the main query specifies `water_level_derivative`, not `water_level` #### Issue 1: Multiple SELECT statements in a subquery InfluxQL supports multiple nested subqueries per main query: -``` +```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ------------------ ---------------- Subquery 1 Subquery 2 ``` InfluxQL does not support multiple [`SELECT` statements](#the-basic-select-statement) per subquery: -``` +```sql SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] ``` The system returns a parsing error if a subquery includes multiple `SELECT` statements. diff --git a/content/influxdb/v1.4/query_language/data_exploration.md b/content/influxdb/v1.4/query_language/data_exploration.md index bd37a0f94..164c6d8d7 100644 --- a/content/influxdb/v1.4/query_language/data_exploration.md +++ b/content/influxdb/v1.4/query_language/data_exploration.md @@ -18,29 +18,29 @@ for exploring your data. General Tips on Query Syntax: - The SELECT Statement + The SELECT statement ORDER BY time DESC Time Syntax - The WHERE Clause - The LIMIT and SLIMIT Clauses + The WHERE clause + The LIMIT and SLIMIT clauses Regular Expressions - The GROUP BY Clause - The OFFSET and SOFFSET Clauses - Data Types and Cast Operations + The GROUP BY clause + The OFFSET and SOFFSET clauses + Data types and cast operations - The INTO Clause - The Time Zone Clause - Merge Behavior + The INTO clause + The Time Zone clause + Merge behavior - Multiple Statements + Multiple statements @@ -67,57 +67,16 @@ InfluxDB shell {{< latest-patch >}} Next, get acquainted with this subsample of the data in the `h2o_feet` measurement: name: h2o_feet -\------------------------------------ -time -           -level description -     -location -     -water_level -   -2015-08-18T00:00:00Z -   -between 6 and 9 feet -      -coyote_creek -   -8.12 -2015-08-18T00:00:00Z -   -below 3 feet -       -santa_monica -      -2.064 -2015-08-18T00:06:00Z -   -between 6 and 9 feet -     -coyote_creek -     -8.005 -2015-08-18T00:06:00Z -   -below 3 feet -       -santa_monica -      -2.116 -2015-08-18T00:12:00Z -   -between 6 and 9 feet -      -coyote_creek -   -7.887 -2015-08-18T00:12:00Z -   -below 3 feet -       -santa_monica -      -2.028 + +| time | level description | location | water_level | +| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| 2015-08-18T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.12 | +| 2015-08-18T00:00:00Z | below 3 feet | santa_monica | 2.064 | +| 2015-08-18T00:06:00Z | between 6 and 9 feet | coyote_creek | 8.005 | +| 2015-08-18T00:06:00Z | below 3 feet | santa_monica | 2.116 | +| 2015-08-18T00:12:00Z | between 6 and 9 feet | coyote_creek | 7.887 | +| 2015-08-18T00:12:00Z | below 3 feet | santa_monica | 2.028 + The data in the `h2o_feet` [measurement](/influxdb/v1.4/concepts/glossary/#measurement) occur at six-minute time intervals. @@ -131,14 +90,12 @@ All of these data is in the `NOAA_water_database` [database](/influxdb/v1.4/conc > **Disclaimer:** The `level description` field isn't part of the original NOAA data - we snuck it in there for the sake of having a field key with a special character and string field values. -
# The basic SELECT statement The `SELECT` statement queries data from a specified [measurement](/influxdb/v1.4/concepts/glossary/#measurement) or measurements. Tired of reading? Check out this InfluxQL Short: -
-
+ ### Syntax @@ -218,7 +175,7 @@ Please review the [rules for single and double-quoting](/influxdb/v1.4/troublesh ### Examples #### Example 1: Select all fields and tags from a single measurement -``` +```sql > SELECT * FROM "h2o_feet" name: h2o_feet @@ -246,7 +203,7 @@ If you do not set the `rp` query string parameter, the HTTP API automatically queries the database's `DEFAULT` retention policy. #### Example 2: Select specific tags and fields from a single measurement -``` +```sql > SELECT "level description","location","water_level" FROM "h2o_feet" name: h2o_feet @@ -265,7 +222,7 @@ Note that the `SELECT` clause must specify at least one field when it includes a tag. #### Example 3: Select specific tags and fields from a single measurement, and provide their identifier type -``` +```sql > SELECT "level description"::field,"location"::tag,"water_level"::field FROM "h2o_feet" name: h2o_feet @@ -286,7 +243,7 @@ Use `::[field | tag]` to differentiate between [an identical field key and tag k That syntax is not required for most use cases. #### Example 4: Select all fields from a single measurement -``` +```sql > SELECT *::field FROM "h2o_feet" name: h2o_feet @@ -303,7 +260,7 @@ The query selects all fields from the `h2o_feet` measurement. The `SELECT` clause supports combining the `*` syntax with the `::` syntax. #### Example 5: Select a specific field from a measurement and perform basic arithmetic -``` +```sql > SELECT ("water_level" * 2) + 4 from "h2o_feet" name: h2o_feet @@ -323,7 +280,7 @@ See [Mathematical Operators](/influxdb/v1.4/query_language/math_operators/) for more on supported operators. #### Example 6: Select all data from more than one measurement -``` +```sql > SELECT * FROM "h2o_feet","h2o_pH" name: h2o_feet @@ -350,7 +307,7 @@ The query selects all fields and tags from two measurements: `h2o_feet` and Separate multiple measurements with a comma (`,`). #### Example 7: Select all data from a fully qualified measurement -``` +```sql > SELECT * FROM "NOAA_water_database"."autogen"."h2o_feet" name: h2o_feet @@ -373,7 +330,7 @@ In the HTTP API, fully qualify a measurement in place of using the `db` and `rp` query string parameters if desired. #### Example 8: Select all data from a measurement in a particular database -``` +```sql > SELECT * FROM "NOAA_water_database".."h2o_feet" name: h2o_feet @@ -405,16 +362,16 @@ query returns an empty response. This behavior is a result of how the system stores data. ##### Example -
+ The following query returns no data because it specifies a single tag key (`location`) in the `SELECT` clause: -``` +```sql > SELECT "location" FROM "h2o_feet" > ``` To return any data associated with the `location` tag key, the query's `SELECT` clause must include at least one field key (`water_level`): -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 name: h2o_feet time water_level location @@ -433,13 +390,12 @@ The `WHERE` filters data based on [timestamps](/influxdb/v1.4/concepts/glossary/#timestamp). Tired of reading? Check out this InfluxQL Short: -
-
+ ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` @@ -450,7 +406,7 @@ timestamps. #### fields -``` +```sql field_key ['string' | boolean | float | integer] ``` @@ -477,7 +433,7 @@ Other supported features: #### tags -``` +```sql tag_key ['tag_value'] ``` @@ -507,7 +463,7 @@ details how to specify alternative time ranges in the `WHERE` clause. ### Examples #### Example 1: Select data that have specific field key-values -``` +```sql > SELECT * FROM "h2o_feet" WHERE "water_level" > 8 name: h2o_feet @@ -526,7 +482,7 @@ The query returns data from the `h2o_feet` that are greater than eight. #### Example 2: Select data that have a specific string field key-value -``` +```sql > SELECT * FROM "h2o_feet" WHERE "level description" = 'below 3 feet' name: h2o_feet @@ -545,7 +501,7 @@ InfluxQL requires single quotes around string field values in the `WHERE` clause. #### Example 3: Select data that have a specific field key-value and perform basic arithmetic -``` +```sql > SELECT * FROM "h2o_feet" WHERE "water_level" + 2 > 11.9 name: h2o_feet @@ -570,7 +526,7 @@ for more on supported operators. #### Example 4: Select data that have a specific tag key-value -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' name: h2o_feet @@ -588,7 +544,7 @@ The query returns data from the `h2o_feet` measurement where the InfluxQL requires single quotes around tag values in the `WHERE` clause. #### Example 5: Select data that have specific field key-values and tag key-values -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" <> 'santa_monica' AND (water_level < -0.59 OR water_level > 9.95) name: h2o_feet @@ -609,7 +565,7 @@ The `WHERE` clause supports the operators `AND` and `OR`, and supports separating logic with parentheses. #### Example 6: Select data that have specific timestamps -``` +```sql > SELECT * FROM "h2o_feet" WHERE time > now() - 7d ``` @@ -633,7 +589,7 @@ The first two queries in the code block below attempt to specify the tag value Those queries return no results. The third query single quotes `santa_monica` (this is the supported syntax) and returns the expected results. -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = santa_monica > SELECT "water_level" FROM "h2o_feet" WHERE "location" = "santa_monica" @@ -657,7 +613,7 @@ The second query returns no results. The third query single quotes `at or greater than 9 feet` (this is the supported syntax) and returns the expected results. -``` +```sql > SELECT "level description" FROM "h2o_feet" WHERE "level description" = at or greater than 9 feet ERR: error parsing query: found than, expected ; at line 1, char 86 @@ -674,8 +630,6 @@ time level description 2015-09-15T22:42:00Z at or greater than 9 feet ``` -
-
# The GROUP BY clause The `GROUP BY` clause groups query results by a user-specified @@ -703,13 +657,12 @@ set of [tags](/influxdb/v1.4/concepts/glossary/#tag) or a time interval. `GROUP BY ` queries group query results by a user-specified set of [tags](/influxdb/v1.4/concepts/glossary/#tag). Tired of reading? Check out this InfluxQL Short: -
-
+ #### Syntax -``` +```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [, -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -761,8 +714,8 @@ InfluxDB returns results in two [series](/influxdb/v1.4/concepts/glossary/#serie If you request a query that has no timestamp to return, such as an [aggregation function](/influxdb/v1.4/query_language/functions/) with an unbounded time range, InfluxDB returns epoch 0 as the timestamp. ##### Example 2: Group query results by more than one tag -
-``` + +```sql > SELECT MEAN("index") FROM "h2o_quality" GROUP BY location,randtag name: h2o_quality @@ -808,8 +761,8 @@ each combination of the `location` [tag](/influxdb/v1.4/concepts/glossary/#tag) Separate multiple tags with a comma in the `GROUP BY` clause. ##### Example 3: Group query results by all tags -
-``` + +```sql > SELECT MEAN("index") FROM "h2o_quality" GROUP BY * name: h2o_quality @@ -870,7 +823,7 @@ This is because the `h2o_quality` measurement only has two tag keys. ### Basic GROUP BY time() Syntax #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(),[tag_key] [fill()] ``` @@ -882,7 +835,7 @@ in the [`SELECT` clause](#the-basic-select-statement) and a time range in the Note that the `GROUP BY` clause must come after the `WHERE` clause. ##### `time(time_interval)` -
+ The `time_interval` in the `GROUP BY time()` clause is a [duration literal](/influxdb/v1.4/query_language/spec/#durations). It determines how InfluxDB groups query results over time. @@ -890,7 +843,7 @@ For example, a `time_interval` of `5m` groups query results into five-minute time groups across the time range specified in the [`WHERE` clause](#the-where-clause). ##### `fill()` -
+ `fill()` is optional. It changes the value reported for time intervals that have no data. See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill) @@ -905,7 +858,7 @@ and the timestamps returned by the query. #### Examples of Basic Syntax The examples below use the following subsample of the sample data: -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' name: h2o_feet @@ -926,8 +879,8 @@ time water_level location ``` ##### Example 1: Group query results into 12 minute intervals -
-``` + +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: h2o_feet @@ -950,8 +903,8 @@ The count for the second timestamp covers the raw data between `2015-08-18T00:12 and up to, but not including, `2015-08-18T00:24:00Z.` ##### Example 2: Group query results into 12 minutes intervals and by a tag key -
-``` + +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location" name: h2o_feet @@ -988,7 +941,7 @@ and up to, but not including, `2015-08-18T00:24:00Z.` #### Common Issues with Basic Syntax ##### Issue 1: Unexpected timestamps and values in query results -
+ With the basic syntax, InfluxDB relies on the `GROUP BY time()` interval and on the system's preset time boundaries to determine the raw data included in each time interval and the timestamps returned by the query. @@ -998,7 +951,7 @@ In some cases, this can lead to unexpected results. Raw data: -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:18:00Z' name: h2o_feet -------------- @@ -1013,7 +966,7 @@ Query and Results: The following query covers a 12-minute time range and groups results into 12-minute time intervals, but it returns **two** results: -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m) name: h2o_feet @@ -1059,7 +1012,7 @@ in the Advanced Syntax section continues with the query shown here; it shifts forward the preset time boundaries by six minutes such that InfluxDB returns: -``` +```sql name: h2o_feet time count ---- ----- @@ -1070,7 +1023,7 @@ time count #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(,),[tag_key] [fill()] ``` @@ -1082,7 +1035,7 @@ in the [`SELECT` clause](#the-basic-select-statement) and a time range in the Note that the `GROUP BY` clause must come after the `WHERE` clause. ##### `time(time_interval,offset_interval)` -
+ See the [Basic GROUP BY time() Syntax](#basic-group-by-time-syntax) for details on the `time_interval`. @@ -1092,7 +1045,7 @@ It shifts forward or back InfluxDB's preset time boundaries. The `offset_interval` can be positive or negative. ##### `fill()` -
+ `fill()` is optional. It changes the value reported for time intervals that have no data. See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill) @@ -1108,7 +1061,7 @@ and the timestamps returned by the query. The examples below use the following subsample of the sample data: -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:54:00Z' name: h2o_feet @@ -1127,8 +1080,8 @@ time water_level ``` ##### Example 1: Group query results into 18 minute intervals and shift the preset time boundaries forward -
-``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m,6m) name: h2o_feet @@ -1145,7 +1098,7 @@ time intervals, and offsetting the preset time boundaries by six minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m) name: h2o_feet @@ -1205,8 +1158,8 @@ Note that `offset_interval` forces the fourth time boundary to be outside the query's time range so the query returns no results for that last interval. ##### Example 2: Group query results into 12 minute intervals and shift the preset time boundaries back -
-``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m,-12m) name: h2o_feet @@ -1229,7 +1182,7 @@ There are no performance differences between the two queries; feel free to choos intuitive option when deciding between a positive and negative `offset_interval`. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m) name: h2o_feet @@ -1289,10 +1242,10 @@ Note that `offset_interval` forces the first time boundary to be outside the query's time range so the query returns no results for that first interval. ##### Example 3: Group query results into 12 minute intervals and shift the preset time boundaries forward -
+ This example is a continuation of the scenario outlined in [Common Issues with Basic Syntax](#common-issues-with-basic-syntax). -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m,6m) name: h2o_feet @@ -1307,7 +1260,7 @@ time intervals, and offsetting the preset time boundaries by six minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m) name: h2o_feet @@ -1361,7 +1314,7 @@ the query's time range so the query returns no results for that second interval. #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(time_interval,[)] ``` @@ -1374,7 +1327,6 @@ Note that `fill()` must go at the end of the `GROUP BY` clause if you're `GROUP(ing) BY` several things (for example, both [tags](/influxdb/v1.4/concepts/glossary/#tag) and a time interval). ##### fill_option -
Any numerical value               @@ -1416,7 +1368,7 @@ Reports the value from the previous time interval for time intervals with no dat {{% tab-content %}} Without `fill(100)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1429,7 +1381,7 @@ time max ``` With `fill(100)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(100) name: h2o_feet @@ -1449,7 +1401,7 @@ time max Without `fill(linear)`: -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:00:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) name: pond @@ -1464,7 +1416,7 @@ time mean ``` With `fill(linear)`: -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:00:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond @@ -1489,7 +1441,7 @@ We had to create a dataset with less regular data to work with `fill(linear)`. {{% tab-content %}} Without `fill(none)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1502,7 +1454,7 @@ time max ``` With `fill(none)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(none) name: h2o_feet @@ -1520,7 +1472,7 @@ time max {{% tab-content %}} Without `fill(null)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1533,7 +1485,7 @@ time max ``` With `fill(null)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(null) name: h2o_feet @@ -1553,7 +1505,7 @@ That result matches the result of the query without `fill(null)`. {{% tab-content %}} Without `fill(previous)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1566,7 +1518,7 @@ time max ``` With `fill(previous)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1587,7 +1539,7 @@ the value from the previous time interval. #### Common issues with `fill()` ##### Issue 1: `fill()` when no data fall within the query's time range -
+ Currently, queries ignore `fill()` if no data fall within the query's time range. This is the expected behavior. An open [feature request](https://github.com/influxdata/influxdb/issues/6967) on GitHub @@ -1599,13 +1551,13 @@ range covers no data. The following query returns no data because `water_level` has no points within the query's time range. Note that `fill(800)` has no effect on the query results. -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2015-09-18T22:00:00Z' AND time <= '2015-09-18T22:18:00Z' GROUP BY time(12m) fill(800) > ``` ##### Issue 2: `fill(previous)` when the previous result falls outside the query's time range -
+ `fill(previous)` doesn’t fill the result for a time interval if the previous value is outside the query’s time range. @@ -1614,7 +1566,7 @@ value is outside the query’s time range. The following query covers the time range between `2015-09-18T16:24:00Z` and `2015-09-18T16:54:00Z`. Note that `fill(previous)` fills the result for `2015-09-18T16:36:00Z` with the result from `2015-09-18T16:24:00Z`. -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2015-09-18T16:24:00Z' AND time <= '2015-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1631,7 +1583,7 @@ Note that `fill(previous)` doesn't fill the result for `2015-09-18T16:36:00Z` wi result from `2015-09-18T16:24:00Z`; the result for `2015-09-18T16:24:00Z` is outside the query's shorter time range. -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2015-09-18T16:36:00Z' AND time <= '2015-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1642,7 +1594,7 @@ time max ``` ##### Issue 3: `fill(linear)` when the previous or following result falls outside the query's time range -
+ `fill(linear)` doesn't fill the result for a time interval with no data if the previous result or the following result is outside the query's time range. @@ -1654,7 +1606,7 @@ The following query covers the time range between `2016-11-11T21:24:00Z` and using the values from the `2016-11-11T21:24:00Z` time interval and the `2016-11-11T22:00:00Z` time interval. -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time > '2016-11-11T21:24:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond @@ -1673,7 +1625,7 @@ time interval and the `2016-11-11T21:48:00Z` time interval; the result for `2016-11-11T21:24:00Z` is outside the query's shorter time range and InfluxDB cannot perform the linear interpolation. -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:36:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond time mean @@ -1686,14 +1638,12 @@ time mean > **Note:** The data in Issue 3 are not in `NOAA_water_database`. We had to create a dataset with less regular data to work with `fill(linear)`. -
-
# The INTO clause The `INTO` clause writes query results to a user-specified [measurement](/influxdb/v1.4/concepts/glossary/#measurement). ### Syntax -``` +```sql SELECT_clause INTO FROM_clause [WHERE_clause] [GROUP_BY_clause] ``` @@ -1731,7 +1681,7 @@ retention policy that match the [regular expression](#regular-expressions) in th #### Example 1: Rename a database -``` +```sql > SELECT * INTO "copy_NOAA_water_database"."autogen".:MEASUREMENT FROM "NOAA_water_database"."autogen"./.*/ GROUP BY * name: result @@ -1751,7 +1701,7 @@ for how to manage databases and retention policies. The `GROUP BY *` clause [preserves tags](#issue-1-missing-data) in the source database as tags in the destination database. The following query does not maintain the series context for tags; tags will be stored as fields in the destination database (`copy_NOAA_water_database`): -``` +```sql SELECT * INTO "copy_NOAA_water_database"."autogen".:MEASUREMENT FROM "NOAA_water_database"."autogen"./.*/ ``` @@ -1783,7 +1733,7 @@ WHERE time > now() - 80w and time < now() - 70w GROUP BY * #### Example 2: Write the results of a query to a measurement -``` +```sql > SELECT "water_level" INTO "h2o_feet_copy_1" FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: result @@ -1816,7 +1766,7 @@ The timestamp in the response is meaningless; InfluxDB uses epoch 0 #### Example 3: Write the results of a query to a fully qualified measurement -``` +```sql > SELECT "water_level" INTO "where_else"."autogen"."h2o_feet_copy_2" FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: result @@ -1848,7 +1798,7 @@ The timestamp in the response is meaningless; InfluxDB uses epoch 0 #### Example 4: Write aggregated results to a measurement (downsampling) -``` +```sql > SELECT MEAN("water_level") INTO "all_my_averages" FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: result @@ -1882,7 +1832,7 @@ Downsampling is a common use case for the `INTO` clause. #### Example 5: Write aggregated results for more than one measurement to a different database (downsampling with backreferencing) -``` +```sql > SELECT MEAN(*) INTO "where_else"."autogen".:MEASUREMENT FROM /.*/ WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:06:00Z' GROUP BY time(12m) name: result @@ -1965,8 +1915,6 @@ documentation for how to automate `INTO` clause queries on realtime data. Among [other uses](/influxdb/v1.4/query_language/continuous_queries/#continuous-query-use-cases), Continuous Queries automate the downsampling process. -
-
# ORDER BY time DESC By default, InfluxDB returns results in ascending time order; the first [point](/influxdb/v1.4/concepts/glossary/#point) returned has the oldest [timestamp](/influxdb/v1.4/concepts/glossary/#timestamp) and @@ -1975,7 +1923,7 @@ the last point returned has the most recent timestamp. with the most recent timestamps first. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time DESC ``` @@ -1990,7 +1938,7 @@ if the query includes a `WHERE` clause and no `GROUP BY` clause. #### Example 1: Return the newest points first -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' ORDER BY time DESC name: h2o_feet @@ -2009,7 +1957,7 @@ Without `ORDER by time DESC`, the query would return `2015-08-18T00:00:00Z` first and `2015-09-18T21:42:00Z` last. #### Example 2: Return the newest points first and include a GROUP BY time() clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY time(12m) ORDER BY time DESC name: h2o_feet @@ -2031,8 +1979,6 @@ first. Without `ORDER BY time DESC`, the query would return `2015-08-18T00:00:00Z` first and `2015-08-18T00:36:00Z` last. -
-
# The LIMIT and SLIMIT clauses `LIMIT` and `SLIMIT` limit the number of @@ -2043,7 +1989,7 @@ Without `ORDER BY time DESC`, the query would return `LIMIT ` returns the first `N` [points](/influxdb/v1.4/concepts/glossary/#point) from the specified [measurement](/influxdb/v1.4/concepts/glossary/#measurement). ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT ``` @@ -2058,7 +2004,7 @@ Note that the `LIMIT` clause must appear in the order outlined in the syntax abo ### Examples #### Example 1: Limit the number of points returned -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 name: h2o_feet @@ -2073,7 +2019,7 @@ The query returns the three oldest [points](/influxdb/v1.4/concepts/glossary/#po `h2o_feet` [measurement](/influxdb/v1.4/concepts/glossary/#measurement). #### Example 2: Limit the number points returned and include a GROUP BY clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 name: h2o_feet @@ -2104,7 +2050,7 @@ one for each twelve-minute interval in the query's time range. `SLIMIT ` returns every [point](/influxdb/v1.4/concepts/glossary/#point) from \ [series](/influxdb/v1.4/concepts/glossary/#series) in the specified [measurement](/influxdb/v1.4/concepts/glossary/#measurement). ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] SLIMIT ``` @@ -2119,7 +2065,7 @@ Note that the `SLIMIT` clause must appear in the order outlined in the syntax ab ### Examples #### Example 1: Limit the number of series returned -``` +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 name: h2o_feet @@ -2139,7 +2085,7 @@ The query returns all `water_level` [points](/influxdb/v1.4/concepts/glossary/#p with the `h2o_feet` [measurement](/influxdb/v1.4/concepts/glossary/#measurement). #### Example 2: Limit the number of series returned and include a GROUP BY time() clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) SLIMIT 1 name: h2o_feet @@ -2167,7 +2113,7 @@ associated with the `h2o_feet` measurement: `location=coyote_creek` and `LIMIT ` followed by `SLIMIT ` returns the first \ [points](/influxdb/v1.4/concepts/glossary/#point) from \ [series](/influxdb/v1.4/concepts/glossary/#series) in the specified measurement. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] LIMIT SLIMIT ``` @@ -2185,7 +2131,7 @@ Note that the `LIMIT` and `SLIMIT` clauses must appear in the order outlined in ### Examples #### Example 1: Limit the number of points and series returned -``` +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * LIMIT 3 SLIMIT 1 name: h2o_feet @@ -2202,7 +2148,7 @@ of the [series](/influxdb/v1.4/concepts/glossary/#series) associated with the [measurement](/influxdb/v1.4/concepts/glossary/#measurement) `h2o_feet`. #### Example 2: Limit the number of points and series returned and include a GROUP BY time() clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 SLIMIT 1 name: h2o_feet @@ -2224,8 +2170,6 @@ associated with the `h2o_feet` measurement. Note that without `LIMIT 2 SLIMIT 1`, the query would return four points for each of the two series associated with the `h2o_feet` measurement. -
-
# The OFFSET and SOFFSET Clauses `OFFSET` and `SOFFSET` paginates [points](/influxdb/v1.4/concepts/glossary/#point) and [series](/influxdb/v1.4/concepts/glossary/#series) returned. @@ -2240,7 +2184,7 @@ for each of the two series associated with the `h2o_feet` measurement. `OFFSET ` paginates `N` [points](/influxdb/v1.4/concepts/glossary/#point) in the query results. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT_clause OFFSET [SLIMIT_clause] ``` @@ -2257,7 +2201,7 @@ timestamps outside of that time range. ### Examples #### Example 1: Paginate points -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 OFFSET 3 name: h2o_feet @@ -2273,7 +2217,7 @@ If the query did not include `OFFSET 3`, it would return the first, second, and third points from that measurement. #### Example 2: Paginate points and include several clauses -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 name: h2o_feet @@ -2296,7 +2240,7 @@ The `OFFSET 2` clause excludes the first two averages from the query results. The [`SLIMIT 1` clause](#the-slimit-clause) limits the number of series returned to one. Without `OFFSET 2`, the query would return the first two averages of the query results: -``` +```sql name: h2o_feet tags: location=coyote_creek time mean @@ -2309,7 +2253,7 @@ time mean `SOFFSET ` paginates `N` [series](/influxdb/v1.4/concepts/glossary/#series) in the query results. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time(time_interval)] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] SLIMIT_clause SOFFSET ``` @@ -2326,7 +2270,7 @@ through more than the total number of series. ### Examples #### Example 1: Paginate series -``` +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 SOFFSET 1 name: h2o_feet @@ -2346,7 +2290,7 @@ Without `SOFFSET 1`, the query returns data for the series associated with the `h2o_feet` measurement and the `location = coyote_creek` tag. #### Example 2: Paginate series and include all clauses -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 SOFFSET 1 name: h2o_feet @@ -2370,7 +2314,7 @@ The [`SLIMIT 1` clause](#the-slimit-clause) limits the number of series returned The `SOFFSET 1` clause paginates the series returned. Without `SOFFSET 1`, the query would return the results for a different series: -``` +```sql name: h2o_feet tags: location=coyote_creek time mean @@ -2379,15 +2323,13 @@ time mean 2015-08-18T00:00:00Z 8.0625 ``` -
-
# The Time Zone Clause The `tz()` clause returns the UTC offset for the specified timezone. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') ``` @@ -2401,7 +2343,7 @@ The `time_zone` parameter follows the TZ syntax in the [Internet Assigned Number ### Examples #### Example 1: Return the UTC offset for Chicago's time zone -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:18:00Z' tz('America/Chicago') name: h2o_feet @@ -2415,8 +2357,6 @@ time water_level The query results include the UTC offset (`-05:00`) for the `America/Chicago` time zone in the timestamps. -
-
# Time Syntax For most `SELECT` statements, the default time range is between [`1677-09-21 00:12:43.145224194` and `2262-04-11T23:47:16.854775806Z` UTC](/influxdb/v1.4/troubleshooting/frequently-asked-questions/#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store). @@ -2434,8 +2374,7 @@ statement's [`WHERE` clause](#the-where-clause). Tired of reading? Check out this InfluxQL Short: -
-
+ ## Absolute Time @@ -2443,7 +2382,7 @@ Tired of reading? Check out this InfluxQL Short: Specify absolute time with date-time strings and epoch time. ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE time ['' | '' | ] [AND ['' | '' | ] [...]] ``` @@ -2466,7 +2405,7 @@ for more information. #### rfc3339_date_time_string -``` +```sql 'YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ' ``` @@ -2475,7 +2414,7 @@ The [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) date-time string requires si #### rfc3339_like_date_time_string -``` +```sql 'YYYY-MM-DD HH:MM:SS.nnnnnnnnn' ``` @@ -2501,7 +2440,7 @@ duration literal. ### Examples #### Example 1: Specify a time range with RFC3339 date-time strings -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00.000000000Z' AND time <= '2015-08-18T00:12:00Z' name: h2o_feet @@ -2521,7 +2460,7 @@ Note that the single quotes around the RFC3339 date-time strings are required. #### Example 2: Specify a time range with RFC3339-like date-time strings -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18' AND time <= '2015-08-18 00:12:00' name: h2o_feet @@ -2540,9 +2479,8 @@ is 00:00:00. Note that the single quotes around the RFC3339-like date-time strings are required. - #### Example 3: Specify a time range with epoch timestamps -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1439856000000000000 AND time <= 1439856720000000000 name: h2o_feet @@ -2558,7 +2496,7 @@ at 00:00:00 and August 18, 2015 at 00:12:00. By default InfluxDB assumes epoch timestamps are in nanoseconds. #### Example 4: Specify a time range with second-precision epoch timestamps -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1439856000s AND time <= 1439856720s name: h2o_feet @@ -2575,7 +2513,7 @@ The `s` [duration literal](/influxdb/v1.4/query_language/spec/#durations) at the end of the epoch timestamps indicate that the epoch timestamps are in seconds. #### Example 5: Perform basic arithmetic on an RFC3339-like date-time string -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > '2015-09-18T21:24:00Z' + 6m name: h2o_feet @@ -2591,7 +2529,7 @@ Note that the whitespace between the `+` and `6m` is required. #### Example 6: Perform basic arithmetic on an epoch timestamp -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > 24043524m - 6m name: h2o_feet @@ -2611,7 +2549,7 @@ Note that the whitespace between the `-` and `6m` is required. Use [`now()`](/influxdb/v1.4/concepts/glossary/#now) to query data with [timestamps](/influxdb/v1.4/concepts/glossary/#timestamp) relative to the server's current timestamp. ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE time now() [[ - | + ] ] [(AND|OR) now() [...]] ``` @@ -2643,7 +2581,7 @@ The whitespace between `-` or `+` and the [duration literal](/influxdb/v1.4/quer ### Examples #### Example 1: Specify a time range with relative time -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > now() - 1h ``` @@ -2651,7 +2589,7 @@ The query returns data with timestamps that occur within the past hour. The whitespace between `-` and `1h` is required. #### Example 2: Specify a time range with absolute time and relative time -``` +```sql > SELECT "level description" FROM "h2o_feet" WHERE time > '2015-09-18T21:18:00Z' AND time < now() + 1000d name: h2o_feet @@ -2690,13 +2628,13 @@ a `GROUP BY time()` clause must provide an alternative upper bound in the #### Example Use the [CLI](/influxdb/v1.4/tools/shell/) to write a point to the `NOAA_water_database` that occurs after `now()`: -``` +```sql > INSERT h2o_feet,location=santa_monica water_level=3.1 1587074400000000000 ``` Run a `GROUP BY time()` query that covers data with timestamps between `2015-09-18T21:30:00Z` and `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= '2015-09-18T21:30:00Z' GROUP BY time(12m) fill(none) name: h2o_feet @@ -2708,7 +2646,7 @@ time mean Run a `GROUP BY time()` query that covers data with timestamps between `2015-09-18T21:30:00Z` and 180 weeks from `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= '2015-09-18T21:30:00Z' AND time <= now() + 180w GROUP BY time(12m) fill(none) name: h2o_feet @@ -2723,7 +2661,7 @@ Note that the `WHERE` clause must provide an alternative **upper** bound to override the default `now()` upper bound. The following query merely resets the lower bound to `now()` such that the query's time range is between `now()` and `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= now() GROUP BY time(12m) fill(none) > ``` @@ -2739,8 +2677,6 @@ in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format by default. Specify alternative formats with the [`epoch` query string parameter](/influxdb/v1.4/tools/api/#query-string-parameters). -
-
# Regular Expressions InfluxQL supports using regular expressions when specifying: @@ -2761,7 +2697,7 @@ string comparisons; queries with regular expressions are not as performant as those without. ### Syntax -``` +```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` @@ -2777,7 +2713,7 @@ Supported operators: ### Examples #### Example 1: Use a regular expression to specify field keys and tag keys in the SELECT clause -``` +```sql > SELECT /l/ FROM "h2o_feet" LIMIT 1 name: h2o_feet @@ -2797,7 +2733,7 @@ field keys and regular expressions for tag keys in the `SELECT` clause. The syntax `//::[field | tag]` is not supported. #### Example 2: Use a regular expression to specify field keys with a function in the SELECT clause -``` +```sql > SELECT DISTINCT(/level/) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00.000000000Z' AND time <= '2015-08-18T00:12:00Z' name: h2o_feet @@ -2813,7 +2749,7 @@ to return the distinct [field values](/influxdb/v1.4/concepts/glossary/#field-va for every field key that contains the word `level`. #### Example 3: Use a regular expression to specify measurements in the FROM clause -``` +```sql > SELECT MEAN("degrees") FROM /temperature/ name: average_temperature @@ -2833,7 +2769,7 @@ to calculate the average `degrees` for every [measurement](/influxdb/v1.4/concep #### Example 4: Use a regular expression to specify tag values in the WHERE clause -``` +```sql > SELECT MEAN(water_level) FROM "h2o_feet" WHERE "location" =~ /[m]/ AND "water_level" > 3 name: h2o_feet @@ -2848,7 +2784,7 @@ includes an `m` and `water_level` is greater than three. #### Example 5: Use a regular expression to specify a tag with no value in the WHERE clause -``` +```sql > SELECT * FROM "h2o_feet" WHERE "location" !~ /./ > ``` @@ -2864,7 +2800,7 @@ document for more information. #### Example 6: Use a regular expression to specify a tag with a value in the WHERE clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" =~ /./ name: h2o_feet @@ -2878,7 +2814,8 @@ to calculate the average `water_level` across all data that have a tag value for `location`. #### Example 7: Use a regular expression to specify a field value in the WHERE clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND "level description" =~ /between/ name: h2o_feet @@ -2892,7 +2829,8 @@ to calculate the average `water_level` for all data where the field value of `level description` includes the word `between`. #### Example 8: Use a regular expresssion to specify tag keys in the GROUP BY clause -``` + +```sql > SELECT FIRST("index") FROM "h2o_quality" GROUP BY /l/ name: h2o_quality @@ -2912,8 +2850,6 @@ The query uses an InfluxQL [function](/influxdb/v1.4/query_language/functions/) to select the first value of `index` for every tag that includes the letter `l` in its tag key. -
-
# Data Types and Cast Operations The [`SELECT` clause](#the-basic-select-statement) supports specifying a [field's](/influxdb/v1.4/concepts/glossary/#field) type and basic cast @@ -2944,7 +2880,7 @@ Please see the document for more information on how InfluxDB handles field value type discrepancies. ### Syntax -``` +```sql SELECT_clause :: FROM_clause ``` @@ -2955,7 +2891,7 @@ In most cases, InfluxDB returns no data if the `field_key` does not store data o `type`. See [Cast Operations](#cast-operations) for more information. ### Example -``` +```sql > SELECT "water_level"::float FROM "h2o_feet" LIMIT 4 name: h2o_feet @@ -2976,7 +2912,7 @@ Currently, InfluxDB supports casting [field values](/influxdb/v1.4/concepts/glos floats or from floats to integers. ### Syntax -``` +```sql SELECT_clause :: FROM_clause ``` @@ -2991,7 +2927,7 @@ string or Boolean. #### Example 1: Cast float field values to integers -``` +```sql > SELECT "water_level"::integer FROM "h2o_feet" LIMIT 4 name: h2o_feet @@ -3007,7 +2943,7 @@ The query returns the integer form of `water_level`'s float [field values](/infl #### Example 2: Cast float field values to strings (this functionality is not supported) -``` +```sql > SELECT "water_level"::string FROM "h2o_feet" LIMIT 4 > ``` @@ -3015,8 +2951,6 @@ The query returns the integer form of `water_level`'s float [field values](/infl The query returns no data as casting a float field value to a string is not yet supported. -
-
# Merge Behavior In InfluxDB, queries merge [series](/influxdb/v1.4/concepts/glossary/#series) automatically. @@ -3029,7 +2963,7 @@ The second series is made of up the `h2o_feet` measurement and the `location = s The following query automatically merges those two series when it calculates the [average](/influxdb/v1.4/query_language/functions/#mean) `water_level`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" name: h2o_feet @@ -3039,7 +2973,7 @@ time mean ``` If you want the average `water_level` for the first series only, specify the relevant tag in the [`WHERE` clause](#the-where-clause): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: h2o_feet @@ -3050,7 +2984,7 @@ time mean If you want the average `water_level` for each individual series, include a [`GROUP BY` clause](#group-by-tags): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -3066,8 +3000,6 @@ time mean 1970-01-01T00:00:00Z 3.530863470081006 ``` -
-
# Multiple Statements Separate multiple [`SELECT` statements](#the-basic-select-statement) in a query with a semicolon (`;`). @@ -3083,7 +3015,7 @@ Separate multiple [`SELECT` statements](#the-basic-select-statement) in a query In InfluxDB's [CLI](/influxdb/v1.4/tools/shell/): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet"; SELECT "water_level" FROM "h2o_feet" LIMIT 2 name: h2o_feet @@ -3154,8 +3086,6 @@ With InfluxDB's [HTTP API](/influxdb/v1.4/tools/api/): {{% /tab-content %}} {{< /tabs-wrapper >}} -
-
# Subqueries A subquery is a query that is nested in the `FROM` clause of another query. @@ -3164,7 +3094,7 @@ Subqueries offer functionality similar to nested functions and SQL [`HAVING` clauses](https://en.wikipedia.org/wiki/Having_(SQL\)). ### Syntax -``` +```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` @@ -3180,14 +3110,15 @@ The subquery supports all clauses listed in this document. InfluxQL supports multiple nested subqueries per main query. Sample syntax for multiple subqueries: -``` +```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ``` ### Examples #### Example 1: Calculate the [`SUM()`](/influxdb/v1.4/query_language/functions/#sum) of several [`MAX()`](/influxdb/v1.4/query_language/functions/#max) values -``` + +```sql > SELECT SUM("max") FROM (SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location") name: h2o_feet @@ -3199,7 +3130,8 @@ time sum The query returns the sum of the maximum `water_level` values across every tag value of `location`. InfluxDB first performs the subquery; it calculates the maximum value of `water_level` for each tag value of `location`: -``` + +```sql > SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -3219,7 +3151,8 @@ Next, InfluxDB performs the main query and calculates the sum of those maximum v Notice that the main query specifies `max`, not `water_level`, as the field key in the `SUM()` function. #### Example 2: Calculate the [`MEAN()`](/influxdb/v1.4/query_language/functions/#mean) difference between two fields -``` + +```sql > SELECT MEAN("difference") FROM (SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare") name: pet_daycare @@ -3233,7 +3166,8 @@ The query returns the average of the differences between the number of `cats` an InfluxDB first performs the subquery. The subquery calculates the difference between the values in the `cats` field and the values in the `dogs` field, and it names the output column `difference`: -``` + +```sql > SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare" name: pet_daycare @@ -3249,7 +3183,8 @@ Next, InfluxDB performs the main query and calculates the average of those diffe Notice that the main query specifies `difference` as the field key in the `MEAN()` function. #### Example 3: Calculate several [`MEAN()`](/influxdb/v1.4/query_language/functions/#mean) values and place a condition on those mean values -``` + +```sql > SELECT "all_the_means" FROM (SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) ) WHERE "all_the_means" > 5 name: h2o_feet @@ -3263,7 +3198,8 @@ The query returns all mean values of the `water_level` field that are greater th InfluxDB first performs the subquery. The subquery calculates `MEAN()` values of `water_level` from `2015-08-18T00:00:00Z` through `2015-08-18T00:30:00Z` and groups the results into 12-minute intervals. It also names the output column `all_the_means`: -``` + +```sql > SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: h2o_feet @@ -3278,7 +3214,8 @@ Next, InfluxDB performs the main query and returns only those mean values that a Notice that the main query specifies `all_the_means` as the field key in the `SELECT` clause. #### Example 4: Calculate the [`SUM()`](/influxdb/v1.4/query_language/functions/#sum) of several [`DERIVATIVE()`](/influxdb/v1.4/query_language/functions/#derivative) values -``` + +```sql > SELECT SUM("water_level_derivative") AS "sum_derivative" FROM (SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location") GROUP BY "location" name: h2o_feet @@ -3299,7 +3236,8 @@ The query returns the sum of the derivative of average `water_level` values for InfluxDB first performs the subquery. The subquery calculates the derivative of average `water_level` values taken at 12-minute intervals. It performs that calculation for each tag value of `location` and names the output column `water_level_derivative`: -``` + +```sql > SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location" name: h2o_feet @@ -3325,14 +3263,14 @@ Notice that the main query specifies `water_level_derivative`, not `water_level` #### Issue 1: Multiple SELECT statements in a subquery InfluxQL supports multiple nested subqueries per main query: -``` +```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ------------------ ---------------- Subquery 1 Subquery 2 ``` InfluxQL does not support multiple [`SELECT` statements](#the-basic-select-statement) per subquery: -``` +```sql SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] ``` The system returns a parsing error if a subquery includes multiple `SELECT` statements. diff --git a/content/influxdb/v1.5/query_language/data_exploration.md b/content/influxdb/v1.5/query_language/data_exploration.md index 6d601ab67..a009101f5 100644 --- a/content/influxdb/v1.5/query_language/data_exploration.md +++ b/content/influxdb/v1.5/query_language/data_exploration.md @@ -19,29 +19,29 @@ for exploring your data. General Tips on Query Syntax: - The SELECT Statement + The SELECT statement ORDER BY time DESC Time Syntax - The WHERE Clause - The LIMIT and SLIMIT Clauses + The WHERE clause + The LIMIT and SLIMIT clauses Regular Expressions - The GROUP BY Clause - The OFFSET and SOFFSET Clauses - Data Types and Cast Operations + The GROUP BY clause + The OFFSET and SOFFSET clauses + Data types and cast operations - The INTO Clause - The Time Zone Clause - Merge Behavior + The INTO clause + The Time Zone clause + Merge behavior - Multiple Statements + Multiple statements @@ -68,57 +68,16 @@ InfluxDB shell {{< latest-patch >}} Next, get acquainted with this subsample of the data in the `h2o_feet` measurement: name: h2o_feet -\------------------------------------ -time -           -level description -     -location -     -water_level -   -2015-08-18T00:00:00Z -   -between 6 and 9 feet -      -coyote_creek -   -8.12 -2015-08-18T00:00:00Z -   -below 3 feet -       -santa_monica -      -2.064 -2015-08-18T00:06:00Z -   -between 6 and 9 feet -     -coyote_creek -     -8.005 -2015-08-18T00:06:00Z -   -below 3 feet -       -santa_monica -      -2.116 -2015-08-18T00:12:00Z -   -between 6 and 9 feet -      -coyote_creek -   -7.887 -2015-08-18T00:12:00Z -   -below 3 feet -       -santa_monica -      -2.028 + +| time | level description | location | water_level | +| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| 2015-08-18T00:00:00Z | between 6 and 9 feet | coyote_creek | 8.12 | +| 2015-08-18T00:00:00Z | below 3 feet | santa_monica | 2.064 | +| 2015-08-18T00:06:00Z | between 6 and 9 feet | coyote_creek | 8.005 | +| 2015-08-18T00:06:00Z | below 3 feet | santa_monica | 2.116 | +| 2015-08-18T00:12:00Z | between 6 and 9 feet | coyote_creek | 7.887 | +| 2015-08-18T00:12:00Z | below 3 feet | santa_monica | 2.028 + The data in the `h2o_feet` [measurement](/influxdb/v1.5/concepts/glossary/#measurement) occur at six-minute time intervals. @@ -132,7 +91,6 @@ All of these data is in the `NOAA_water_database` [database](/influxdb/v1.5/conc > **Disclaimer:** The `level description` field isn't part of the original NOAA data - we snuck it in there for the sake of having a field key with a special character and string field values. -
# The basic SELECT statement The `SELECT` statement queries data from a particular [measurement](/influxdb/v1.5/concepts/glossary/#measurement) or measurements. @@ -214,7 +172,8 @@ Please review the [rules for single and double-quoting](/influxdb/v1.5/troublesh ### Examples #### Example 1: Select all fields and tags from a single measurement -``` + +```sql > SELECT * FROM "h2o_feet" name: h2o_feet @@ -242,7 +201,8 @@ If you do not set the `rp` query string parameter, the HTTP API automatically queries the database's `DEFAULT` retention policy. #### Example 2: Select specific tags and fields from a single measurement -``` + +```sql > SELECT "level description","location","water_level" FROM "h2o_feet" name: h2o_feet @@ -261,7 +221,8 @@ Note that the `SELECT` clause must specify at least one field when it includes a tag. #### Example 3: Select specific tags and fields from a single measurement, and provide their identifier type -``` + +```sql > SELECT "level description"::field,"location"::tag,"water_level"::field FROM "h2o_feet" name: h2o_feet @@ -282,7 +243,8 @@ Use `::[field | tag]` to differentiate between [an identical field key and tag k That syntax is not required for most use cases. #### Example 4: Select all fields from a single measurement -``` + +```sql > SELECT *::field FROM "h2o_feet" name: h2o_feet @@ -299,7 +261,8 @@ The query selects all fields from the `h2o_feet` measurement. The `SELECT` clause supports combining the `*` syntax with the `::` syntax. #### Example 5: Select a specific field from a measurement and perform basic arithmetic -``` + +```sql > SELECT ("water_level" * 2) + 4 from "h2o_feet" name: h2o_feet @@ -319,7 +282,8 @@ See [Mathematical Operators](/influxdb/v1.5/query_language/math_operators/) for more on supported operators. #### Example 6: Select all data from more than one measurement -``` + +```sql > SELECT * FROM "h2o_feet","h2o_pH" name: h2o_feet @@ -346,7 +310,8 @@ The query selects all fields and tags from two measurements: `h2o_feet` and Separate multiple measurements with a comma (`,`). #### Example 7: Select all data from a fully qualified measurement -``` + +```sql > SELECT * FROM "NOAA_water_database"."autogen"."h2o_feet" name: h2o_feet @@ -369,7 +334,8 @@ In the HTTP API, fully qualify a measurement in place of using the `db` and `rp` query string parameters if desired. #### Example 8: Select all data from a measurement in a particular database -``` + +```sql > SELECT * FROM "NOAA_water_database".."h2o_feet" name: h2o_feet @@ -401,16 +367,17 @@ query returns an empty response. This behavior is a result of how the system stores data. ##### Example -
+ The following query returns no data because it specifies a single tag key (`location`) in the `SELECT` clause: -``` + +```sql > SELECT "location" FROM "h2o_feet" > ``` To return any data associated with the `location` tag key, the query's `SELECT` clause must include at least one field key (`water_level`): -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 name: h2o_feet time water_level location @@ -429,13 +396,12 @@ The `WHERE` filters data based on [timestamps](/influxdb/v1.5/concepts/glossary/#timestamp). Tired of reading? Check out this InfluxQL Short: -
-
+ ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` @@ -446,7 +412,7 @@ timestamps. #### fields -``` +```sql field_key ['string' | boolean | float | integer] ``` @@ -473,7 +439,7 @@ Other supported features: #### tags -``` +```sql tag_key ['tag_value'] ``` @@ -503,7 +469,8 @@ details how to specify alternative time ranges in the `WHERE` clause. ### Examples #### Example 1: Select data that have specific field key-values -``` + +```sql > SELECT * FROM "h2o_feet" WHERE "water_level" > 8 name: h2o_feet @@ -522,7 +489,8 @@ The query returns data from the `h2o_feet` that are greater than eight. #### Example 2: Select data that have a specific string field key-value -``` + +```sql > SELECT * FROM "h2o_feet" WHERE "level description" = 'below 3 feet' name: h2o_feet @@ -541,7 +509,8 @@ InfluxQL requires single quotes around string field values in the `WHERE` clause. #### Example 3: Select data that have a specific field key-value and perform basic arithmetic -``` + +```sql > SELECT * FROM "h2o_feet" WHERE "water_level" + 2 > 11.9 name: h2o_feet @@ -566,7 +535,7 @@ for more on supported operators. #### Example 4: Select data that have a specific tag key-value -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' name: h2o_feet @@ -584,7 +553,8 @@ The query returns data from the `h2o_feet` measurement where the InfluxQL requires single quotes around tag values in the `WHERE` clause. #### Example 5: Select data that have specific field key-values and tag key-values -``` + +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" <> 'santa_monica' AND (water_level < -0.59 OR water_level > 9.95) name: h2o_feet @@ -605,7 +575,8 @@ The `WHERE` clause supports the operators `AND` and `OR`, and supports separating logic with parentheses. #### Example 6: Select data that have specific timestamps -``` + +```sql > SELECT * FROM "h2o_feet" WHERE time > now() - 7d ``` @@ -629,7 +600,7 @@ The first two queries in the code block below attempt to specify the tag value Those queries return no results. The third query single quotes `santa_monica` (this is the supported syntax) and returns the expected results. -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = santa_monica > SELECT "water_level" FROM "h2o_feet" WHERE "location" = "santa_monica" @@ -653,7 +624,7 @@ The second query returns no results. The third query single quotes `at or greater than 9 feet` (this is the supported syntax) and returns the expected results. -``` +```sql > SELECT "level description" FROM "h2o_feet" WHERE "level description" = at or greater than 9 feet ERR: error parsing query: found than, expected ; at line 1, char 86 @@ -670,8 +641,6 @@ time level description 2015-09-15T22:42:00Z at or greater than 9 feet ``` -
-
# The GROUP BY clause The `GROUP BY` clause groups query results by a user-specified @@ -699,13 +668,12 @@ set of [tags](/influxdb/v1.5/concepts/glossary/#tag) or a time interval. `GROUP BY ` queries group query results by a user-specified set of [tags](/influxdb/v1.5/concepts/glossary/#tag). Tired of reading? Check out this InfluxQL Short: -
-
+ #### Syntax -``` +```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [, -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -757,8 +725,8 @@ InfluxDB returns results in two [series](/influxdb/v1.5/concepts/glossary/#serie If you request a query that has no timestamp to return, such as an [aggregation function](/influxdb/v1.5/query_language/functions/) with an unbounded time range, InfluxDB returns epoch 0 as the timestamp. ##### Example 2: Group query results by more than one tag -
-``` + +```sql > SELECT MEAN("index") FROM "h2o_quality" GROUP BY location,randtag name: h2o_quality @@ -804,8 +772,8 @@ each combination of the `location` [tag](/influxdb/v1.5/concepts/glossary/#tag) Separate multiple tags with a comma in the `GROUP BY` clause. ##### Example 3: Group query results by all tags -
-``` + +```sql > SELECT MEAN("index") FROM "h2o_quality" GROUP BY * name: h2o_quality @@ -866,7 +834,7 @@ This is because the `h2o_quality` measurement only has two tag keys. ### Basic GROUP BY time() Syntax #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(),[tag_key] [fill()] ``` @@ -878,7 +846,7 @@ in the [`SELECT` clause](#the-basic-select-statement) and a time range in the Note that the `GROUP BY` clause must come after the `WHERE` clause. ##### `time(time_interval)` -
+ The `time_interval` in the `GROUP BY time()` clause is a [duration literal](/influxdb/v1.5/query_language/spec/#durations). It determines how InfluxDB groups query results over time. @@ -886,7 +854,7 @@ For example, a `time_interval` of `5m` groups query results into five-minute time groups across the time range specified in the [`WHERE` clause](#the-where-clause). ##### `fill()` -
+ `fill()` is optional. It changes the value reported for time intervals that have no data. See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill) @@ -901,7 +869,8 @@ and the timestamps returned by the query. #### Examples of Basic Syntax The examples below use the following subsample of the sample data: -``` + +```sql > SELECT "water_level","location" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' name: h2o_feet @@ -922,8 +891,8 @@ time water_level location ``` ##### Example 1: Group query results into 12 minute intervals -
-``` + +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: h2o_feet @@ -946,8 +915,8 @@ The count for the second timestamp covers the raw data between `2015-08-18T00:12 and up to, but not including, `2015-08-18T00:24:00Z.` ##### Example 2: Group query results into 12 minutes intervals and by a tag key -
-``` + +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location" name: h2o_feet @@ -984,7 +953,7 @@ and up to, but not including, `2015-08-18T00:24:00Z.` #### Common Issues with Basic Syntax ##### Issue 1: Unexpected timestamps and values in query results -
+ With the basic syntax, InfluxDB relies on the `GROUP BY time()` interval and on the system's preset time boundaries to determine the raw data included in each time interval and the timestamps returned by the query. @@ -994,7 +963,7 @@ In some cases, this can lead to unexpected results. Raw data: -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:18:00Z' name: h2o_feet -------------- @@ -1009,7 +978,7 @@ Query and Results: The following query covers a 12-minute time range and groups results into 12-minute time intervals, but it returns **two** results: -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m) name: h2o_feet @@ -1055,7 +1024,7 @@ in the Advanced Syntax section continues with the query shown here; it shifts forward the preset time boundaries by six minutes such that InfluxDB returns: -``` +```sql name: h2o_feet time count ---- ----- @@ -1066,7 +1035,7 @@ time count #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(,),[tag_key] [fill()] ``` @@ -1078,7 +1047,7 @@ in the [`SELECT` clause](#the-basic-select-statement) and a time range in the Note that the `GROUP BY` clause must come after the `WHERE` clause. ##### `time(time_interval,offset_interval)` -
+ See the [Basic GROUP BY time() Syntax](#basic-group-by-time-syntax) for details on the `time_interval`. @@ -1088,7 +1057,7 @@ It shifts forward or back InfluxDB's preset time boundaries. The `offset_interval` can be positive or negative. ##### `fill()` -
+ `fill()` is optional. It changes the value reported for time intervals that have no data. See [GROUP BY time intervals and `fill()`](#group-by-time-intervals-and-fill) @@ -1104,7 +1073,7 @@ and the timestamps returned by the query. The examples below use the following subsample of the sample data: -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:54:00Z' name: h2o_feet @@ -1123,8 +1092,8 @@ time water_level ``` ##### Example 1: Group query results into 18 minute intervals and shift the preset time boundaries forward -
-``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m,6m) name: h2o_feet @@ -1141,7 +1110,7 @@ time intervals, and offsetting the preset time boundaries by six minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m) name: h2o_feet @@ -1201,8 +1170,8 @@ Note that `offset_interval` forces the fourth time boundary to be outside the query's time range so the query returns no results for that last interval. ##### Example 2: Group query results into 12 minute intervals and shift the preset time boundaries back -
-``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m,-12m) name: h2o_feet @@ -1225,7 +1194,8 @@ There are no performance differences between the two queries; feel free to choos intuitive option when deciding between a positive and negative `offset_interval`. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m) name: h2o_feet @@ -1285,10 +1255,10 @@ Note that `offset_interval` forces the first time boundary to be outside the query's time range so the query returns no results for that first interval. ##### Example 3: Group query results into 12 minute intervals and shift the preset time boundaries forward -
+ This example is a continuation of the scenario outlined in [Common Issues with Basic Syntax](#common-issues-with-basic-syntax). -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m,6m) name: h2o_feet @@ -1303,7 +1273,7 @@ time intervals, and offsetting the preset time boundaries by six minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m) name: h2o_feet @@ -1357,7 +1327,7 @@ the query's time range so the query returns no results for that second interval. #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(time_interval,[)] ``` @@ -1370,7 +1340,6 @@ Note that `fill()` must go at the end of the `GROUP BY` clause if you're `GROUP(ing) BY` several things (for example, both [tags](/influxdb/v1.5/concepts/glossary/#tag) and a time interval). ##### fill_option -
Any numerical value               @@ -1412,7 +1381,8 @@ Reports the value from the previous time interval for time intervals with no dat {{% tab-content %}} Without `fill(100)`: -``` + +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1425,7 +1395,7 @@ time max ``` With `fill(100)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(100) name: h2o_feet @@ -1445,7 +1415,7 @@ time max Without `fill(linear)`: -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:00:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) name: pond @@ -1460,7 +1430,7 @@ time mean ``` With `fill(linear)`: -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:00:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond @@ -1485,7 +1455,7 @@ We had to create a dataset with less regular data to work with `fill(linear)`. {{% tab-content %}} Without `fill(none)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1498,7 +1468,7 @@ time max ``` With `fill(none)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(none) name: h2o_feet @@ -1516,7 +1486,7 @@ time max {{% tab-content %}} Without `fill(null)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1529,7 +1499,7 @@ time max ``` With `fill(null)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(null) name: h2o_feet @@ -1549,7 +1519,7 @@ That result matches the result of the query without `fill(null)`. {{% tab-content %}} Without `fill(previous)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1562,7 +1532,7 @@ time max ``` With `fill(previous)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1583,7 +1553,7 @@ the value from the previous time interval. #### Common issues with `fill()` ##### Issue 1: `fill()` when no data fall within the query's time range -
+ Currently, queries ignore `fill()` if no data fall within the query's time range. This is the expected behavior. An open [feature request](https://github.com/influxdata/influxdb/issues/6967) on GitHub @@ -1595,13 +1565,13 @@ range covers no data. The following query returns no data because `water_level` has no points within the query's time range. Note that `fill(800)` has no effect on the query results. -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2015-09-18T22:00:00Z' AND time <= '2015-09-18T22:18:00Z' GROUP BY time(12m) fill(800) > ``` ##### Issue 2: `fill(previous)` when the previous result falls outside the query's time range -
+ `fill(previous)` doesn’t fill the result for a time interval if the previous value is outside the query’s time range. @@ -1610,7 +1580,7 @@ value is outside the query’s time range. The following query covers the time range between `2015-09-18T16:24:00Z` and `2015-09-18T16:54:00Z`. Note that `fill(previous)` fills the result for `2015-09-18T16:36:00Z` with the result from `2015-09-18T16:24:00Z`. -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2015-09-18T16:24:00Z' AND time <= '2015-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1627,7 +1597,7 @@ Note that `fill(previous)` doesn't fill the result for `2015-09-18T16:36:00Z` wi result from `2015-09-18T16:24:00Z`; the result for `2015-09-18T16:24:00Z` is outside the query's shorter time range. -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2015-09-18T16:36:00Z' AND time <= '2015-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1638,7 +1608,7 @@ time max ``` ##### Issue 3: `fill(linear)` when the previous or following result falls outside the query's time range -
+ `fill(linear)` doesn't fill the result for a time interval with no data if the previous result or the following result is outside the query's time range. @@ -1650,7 +1620,7 @@ The following query covers the time range between `2016-11-11T21:24:00Z` and using the values from the `2016-11-11T21:24:00Z` time interval and the `2016-11-11T22:00:00Z` time interval. -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time > '2016-11-11T21:24:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond @@ -1669,7 +1639,7 @@ time interval and the `2016-11-11T21:48:00Z` time interval; the result for `2016-11-11T21:24:00Z` is outside the query's shorter time range and InfluxDB cannot perform the linear interpolation. -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:36:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond time mean @@ -1682,14 +1652,12 @@ time mean > **Note:** The data in Issue 3 are not in `NOAA_water_database`. We had to create a dataset with less regular data to work with `fill(linear)`. -
-
# The INTO clause The `INTO` clause writes query results to a user-specified [measurement](/influxdb/v1.5/concepts/glossary/#measurement). ### Syntax -``` +```sql SELECT_clause INTO FROM_clause [WHERE_clause] [GROUP_BY_clause] ``` @@ -1727,7 +1695,7 @@ retention policy that match the [regular expression](#regular-expressions) in th #### Example 1: Rename a database -``` +```sql > SELECT * INTO "copy_NOAA_water_database"."autogen".:MEASUREMENT FROM "NOAA_water_database"."autogen"./.*/ GROUP BY * name: result @@ -1747,7 +1715,7 @@ for how to manage databases and retention policies. The `GROUP BY *` clause [preserves tags](#issue-1-missing-data) in the source database as tags in the destination database. The following query does not maintain the series context for tags; tags will be stored as fields in the destination database (`copy_NOAA_water_database`): -``` +```sql SELECT * INTO "copy_NOAA_water_database"."autogen".:MEASUREMENT FROM "NOAA_water_database"."autogen"./.*/ ``` @@ -1779,7 +1747,7 @@ WHERE time > now() - 80w and time < now() - 70w GROUP BY * #### Example 2: Write the results of a query to a measurement -``` +```sql > SELECT "water_level" INTO "h2o_feet_copy_1" FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: result @@ -1812,7 +1780,7 @@ The timestamp in the response is meaningless; InfluxDB uses epoch 0 #### Example 3: Write the results of a query to a fully qualified measurement -``` +```sql > SELECT "water_level" INTO "where_else"."autogen"."h2o_feet_copy_2" FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: result @@ -1844,7 +1812,7 @@ The timestamp in the response is meaningless; InfluxDB uses epoch 0 #### Example 4: Write aggregated results to a measurement (downsampling) -``` +```sql > SELECT MEAN("water_level") INTO "all_my_averages" FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: result @@ -1878,7 +1846,7 @@ Downsampling is a common use case for the `INTO` clause. #### Example 5: Write aggregated results for more than one measurement to a different database (downsampling with backreferencing) -``` +```sql > SELECT MEAN(*) INTO "where_else"."autogen".:MEASUREMENT FROM /.*/ WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:06:00Z' GROUP BY time(12m) name: result @@ -1961,8 +1929,6 @@ documentation for how to automate `INTO` clause queries on realtime data. Among [other uses](/influxdb/v1.5/query_language/continuous_queries/#continuous-query-use-cases), Continuous Queries automate the downsampling process. -
-
# ORDER BY time DESC By default, InfluxDB returns results in ascending time order; the first [point](/influxdb/v1.5/concepts/glossary/#point) returned has the oldest [timestamp](/influxdb/v1.5/concepts/glossary/#timestamp) and @@ -1971,7 +1937,7 @@ the last point returned has the most recent timestamp. with the most recent timestamps first. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time DESC ``` @@ -1986,7 +1952,7 @@ if the query includes a `WHERE` clause and no `GROUP BY` clause. #### Example 1: Return the newest points first -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' ORDER BY time DESC name: h2o_feet @@ -2005,7 +1971,8 @@ Without `ORDER by time DESC`, the query would return `2015-08-18T00:00:00Z` first and `2015-09-18T21:42:00Z` last. #### Example 2: Return the newest points first and include a GROUP BY time() clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY time(12m) ORDER BY time DESC name: h2o_feet @@ -2027,8 +1994,6 @@ first. Without `ORDER BY time DESC`, the query would return `2015-08-18T00:00:00Z` first and `2015-08-18T00:36:00Z` last. -
-
# The LIMIT and SLIMIT clauses `LIMIT` and `SLIMIT` limit the number of @@ -2039,7 +2004,7 @@ Without `ORDER BY time DESC`, the query would return `LIMIT ` returns the first `N` [points](/influxdb/v1.5/concepts/glossary/#point) from the specified [measurement](/influxdb/v1.5/concepts/glossary/#measurement). ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT ``` @@ -2054,7 +2019,8 @@ Note that the `LIMIT` clause must appear in the order outlined in the syntax abo ### Examples #### Example 1: Limit the number of points returned -``` + +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 name: h2o_feet @@ -2069,7 +2035,8 @@ The query returns the three oldest [points](/influxdb/v1.5/concepts/glossary/#po `h2o_feet` [measurement](/influxdb/v1.5/concepts/glossary/#measurement). #### Example 2: Limit the number points returned and include a GROUP BY clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 name: h2o_feet @@ -2100,7 +2067,8 @@ one for each twelve-minute interval in the query's time range. `SLIMIT ` returns every [point](/influxdb/v1.5/concepts/glossary/#point) from \ [series](/influxdb/v1.5/concepts/glossary/#series) in the specified [measurement](/influxdb/v1.5/concepts/glossary/#measurement). ### Syntax -``` + +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] SLIMIT ``` @@ -2115,7 +2083,8 @@ Note that the `SLIMIT` clause must appear in the order outlined in the syntax ab ### Examples #### Example 1: Limit the number of series returned -``` + +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 name: h2o_feet @@ -2135,7 +2104,8 @@ The query returns all `water_level` [points](/influxdb/v1.5/concepts/glossary/#p with the `h2o_feet` [measurement](/influxdb/v1.5/concepts/glossary/#measurement). #### Example 2: Limit the number of series returned and include a GROUP BY time() clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) SLIMIT 1 name: h2o_feet @@ -2163,7 +2133,7 @@ associated with the `h2o_feet` measurement: `location=coyote_creek` and `LIMIT ` followed by `SLIMIT ` returns the first \ [points](/influxdb/v1.5/concepts/glossary/#point) from \ [series](/influxdb/v1.5/concepts/glossary/#series) in the specified measurement. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] LIMIT SLIMIT ``` @@ -2181,7 +2151,7 @@ Note that the `LIMIT` and `SLIMIT` clauses must appear in the order outlined in ### Examples #### Example 1: Limit the number of points and series returned -``` +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * LIMIT 3 SLIMIT 1 name: h2o_feet @@ -2198,7 +2168,7 @@ of the [series](/influxdb/v1.5/concepts/glossary/#series) associated with the [measurement](/influxdb/v1.5/concepts/glossary/#measurement) `h2o_feet`. #### Example 2: Limit the number of points and series returned and include a GROUP BY time() clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 SLIMIT 1 name: h2o_feet @@ -2208,7 +2178,6 @@ time mean 2015-08-18T00:00:00Z 8.0625 2015-08-18T00:12:00Z 7.8245 ``` - The query uses an InfluxQL [function](/influxdb/v1.5/query_language/functions) and a time interval in the [GROUP BY clause](#group-by-time-intervals) to calculate the average `water_level` for each twelve-minute @@ -2220,8 +2189,6 @@ associated with the `h2o_feet` measurement. Note that without `LIMIT 2 SLIMIT 1`, the query would return four points for each of the two series associated with the `h2o_feet` measurement. -
-
# The OFFSET and SOFFSET Clauses `OFFSET` and `SOFFSET` paginates [points](/influxdb/v1.5/concepts/glossary/#point) and [series](/influxdb/v1.5/concepts/glossary/#series) returned. @@ -2236,7 +2203,7 @@ for each of the two series associated with the `h2o_feet` measurement. `OFFSET ` paginates `N` [points](/influxdb/v1.5/concepts/glossary/#point) in the query results. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT_clause OFFSET [SLIMIT_clause] ``` @@ -2253,7 +2220,7 @@ timestamps outside of that time range. ### Examples #### Example 1: Paginate points -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 OFFSET 3 name: h2o_feet @@ -2269,7 +2236,7 @@ If the query did not include `OFFSET 3`, it would return the first, second, and third points from that measurement. #### Example 2: Paginate points and include several clauses -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 name: h2o_feet @@ -2292,7 +2259,7 @@ The `OFFSET 2` clause excludes the first two averages from the query results. The [`SLIMIT 1` clause](#the-slimit-clause) limits the number of series returned to one. Without `OFFSET 2`, the query would return the first two averages of the query results: -``` +```sql name: h2o_feet tags: location=coyote_creek time mean @@ -2305,7 +2272,7 @@ time mean `SOFFSET ` paginates `N` [series](/influxdb/v1.5/concepts/glossary/#series) in the query results. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time(time_interval)] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] SLIMIT_clause SOFFSET ``` @@ -2322,7 +2289,7 @@ through more than the total number of series. ### Examples #### Example 1: Paginate series -``` +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 SOFFSET 1 name: h2o_feet @@ -2342,7 +2309,7 @@ Without `SOFFSET 1`, the query returns data for the series associated with the `h2o_feet` measurement and the `location = coyote_creek` tag. #### Example 2: Paginate series and include all clauses -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 SOFFSET 1 name: h2o_feet @@ -2366,7 +2333,7 @@ The [`SLIMIT 1` clause](#the-slimit-clause) limits the number of series returned The `SOFFSET 1` clause paginates the series returned. Without `SOFFSET 1`, the query would return the results for a different series: -``` +```sql name: h2o_feet tags: location=coyote_creek time mean @@ -2375,15 +2342,13 @@ time mean 2015-08-18T00:00:00Z 8.0625 ``` -
-
# The Time Zone Clause The `tz()` clause returns the UTC offset for the specified timezone. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') ``` @@ -2397,7 +2362,7 @@ The `time_zone` parameter follows the TZ syntax in the [Internet Assigned Number ### Examples #### Example 1: Return the UTC offset for Chicago's time zone -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:18:00Z' tz('America/Chicago') name: h2o_feet @@ -2411,8 +2376,6 @@ time water_level The query results include the UTC offset (`-05:00`) for the `America/Chicago` time zone in the timestamps. -
-
# Time Syntax For most `SELECT` statements, the default time range is between [`1677-09-21 00:12:43.145224194` and `2262-04-11T23:47:16.854775806Z` UTC](/influxdb/v1.5/troubleshooting/frequently-asked-questions/#what-are-the-minimum-and-maximum-timestamps-that-influxdb-can-store). @@ -2430,8 +2393,7 @@ statement's [`WHERE` clause](#the-where-clause). Tired of reading? Check out this InfluxQL Short: -
-
+ ## Absolute Time @@ -2439,7 +2401,7 @@ Tired of reading? Check out this InfluxQL Short: Specify absolute time with date-time strings and epoch time. ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE time ['' | '' | ] [AND ['' | '' | ] [...]] ``` @@ -2462,7 +2424,7 @@ for more information. #### rfc3339_date_time_string -``` +```sql 'YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ' ``` @@ -2471,7 +2433,7 @@ The [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) date-time string requires si #### rfc3339_like_date_time_string -``` +```sql 'YYYY-MM-DD HH:MM:SS.nnnnnnnnn' ``` @@ -2497,7 +2459,8 @@ duration literal. ### Examples #### Example 1: Specify a time range with RFC3339 date-time strings -``` + +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00.000000000Z' AND time <= '2015-08-18T00:12:00Z' name: h2o_feet @@ -2517,7 +2480,7 @@ Note that the single quotes around the RFC3339 date-time strings are required. #### Example 2: Specify a time range with RFC3339-like date-time strings -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18' AND time <= '2015-08-18 00:12:00' name: h2o_feet @@ -2538,7 +2501,8 @@ required. #### Example 3: Specify a time range with epoch timestamps -``` + +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1439856000000000000 AND time <= 1439856720000000000 name: h2o_feet @@ -2554,7 +2518,8 @@ at 00:00:00 and August 18, 2015 at 00:12:00. By default InfluxDB assumes epoch timestamps are in nanoseconds. #### Example 4: Specify a time range with second-precision epoch timestamps -``` + +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1439856000s AND time <= 1439856720s name: h2o_feet @@ -2571,7 +2536,8 @@ The `s` [duration literal](/influxdb/v1.5/query_language/spec/#durations) at the end of the epoch timestamps indicate that the epoch timestamps are in seconds. #### Example 5: Perform basic arithmetic on an RFC3339-like date-time string -``` + +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > '2015-09-18T21:24:00Z' + 6m name: h2o_feet @@ -2587,7 +2553,7 @@ Note that the whitespace between the `+` and `6m` is required. #### Example 6: Perform basic arithmetic on an epoch timestamp -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > 24043524m - 6m name: h2o_feet @@ -2607,7 +2573,7 @@ Note that the whitespace between the `-` and `6m` is required. Use [`now()`](/influxdb/v1.5/concepts/glossary/#now) to query data with [timestamps](/influxdb/v1.5/concepts/glossary/#timestamp) relative to the server's current timestamp. ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE time now() [[ - | + ] ] [(AND|OR) now() [...]] ``` @@ -2639,7 +2605,7 @@ The whitespace between `-` or `+` and the [duration literal](/influxdb/v1.5/quer ### Examples #### Example 1: Specify a time range with relative time -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > now() - 1h ``` @@ -2647,7 +2613,7 @@ The query returns data with timestamps that occur within the past hour. The whitespace between `-` and `1h` is required. #### Example 2: Specify a time range with absolute time and relative time -``` +```sql > SELECT "level description" FROM "h2o_feet" WHERE time > '2015-09-18T21:18:00Z' AND time < now() + 1000d name: h2o_feet @@ -2686,13 +2652,13 @@ a `GROUP BY time()` clause must provide an alternative upper bound in the #### Example Use the [CLI](/influxdb/v1.5/tools/shell/) to write a point to the `NOAA_water_database` that occurs after `now()`: -``` +```sql > INSERT h2o_feet,location=santa_monica water_level=3.1 1587074400000000000 ``` Run a `GROUP BY time()` query that covers data with timestamps between `2015-09-18T21:30:00Z` and `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= '2015-09-18T21:30:00Z' GROUP BY time(12m) fill(none) name: h2o_feet @@ -2704,7 +2670,7 @@ time mean Run a `GROUP BY time()` query that covers data with timestamps between `2015-09-18T21:30:00Z` and 180 weeks from `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= '2015-09-18T21:30:00Z' AND time <= now() + 180w GROUP BY time(12m) fill(none) name: h2o_feet @@ -2719,7 +2685,7 @@ Note that the `WHERE` clause must provide an alternative **upper** bound to override the default `now()` upper bound. The following query merely resets the lower bound to `now()` such that the query's time range is between `now()` and `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= now() GROUP BY time(12m) fill(none) > ``` @@ -2735,8 +2701,7 @@ in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) format by default. Specify alternative formats with the [`epoch` query string parameter](/influxdb/v1.5/tools/api/#query-string-parameters). -
-
+ # Regular Expressions InfluxQL supports using regular expressions when specifying: @@ -2757,7 +2722,7 @@ string comparisons; queries with regular expressions are not as performant as those without. ### Syntax -``` +```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` @@ -2773,7 +2738,7 @@ Supported operators: ### Examples #### Example 1: Use a regular expression to specify field keys and tag keys in the SELECT clause -``` +```sql > SELECT /l/ FROM "h2o_feet" LIMIT 1 name: h2o_feet @@ -2793,7 +2758,8 @@ field keys and regular expressions for tag keys in the `SELECT` clause. The syntax `//::[field | tag]` is not supported. #### Example 2: Use a regular expression to specify field keys with a function in the SELECT clause -``` + +```sql > SELECT DISTINCT(/level/) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00.000000000Z' AND time <= '2015-08-18T00:12:00Z' name: h2o_feet @@ -2809,7 +2775,8 @@ to return the distinct [field values](/influxdb/v1.5/concepts/glossary/#field-va for every field key that contains the word `level`. #### Example 3: Use a regular expression to specify measurements in the FROM clause -``` + +```sql > SELECT MEAN("degrees") FROM /temperature/ name: average_temperature @@ -2829,7 +2796,7 @@ to calculate the average `degrees` for every [measurement](/influxdb/v1.5/concep #### Example 4: Use a regular expression to specify tag values in the WHERE clause -``` +```sql > SELECT MEAN(water_level) FROM "h2o_feet" WHERE "location" =~ /[m]/ AND "water_level" > 3 name: h2o_feet @@ -2844,7 +2811,7 @@ includes an `m` and `water_level` is greater than three. #### Example 5: Use a regular expression to specify a tag with no value in the WHERE clause -``` +```sql > SELECT * FROM "h2o_feet" WHERE "location" !~ /./ > ``` @@ -2860,7 +2827,7 @@ document for more information. #### Example 6: Use a regular expression to specify a tag with a value in the WHERE clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" =~ /./ name: h2o_feet @@ -2874,7 +2841,8 @@ to calculate the average `water_level` across all data that have a tag value for `location`. #### Example 7: Use a regular expression to specify a field value in the WHERE clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND "level description" =~ /between/ name: h2o_feet @@ -2888,7 +2856,8 @@ to calculate the average `water_level` for all data where the field value of `level description` includes the word `between`. #### Example 8: Use a regular expresssion to specify tag keys in the GROUP BY clause -``` + +```sql > SELECT FIRST("index") FROM "h2o_quality" GROUP BY /l/ name: h2o_quality @@ -2908,8 +2877,6 @@ The query uses an InfluxQL [function](/influxdb/v1.5/query_language/functions/) to select the first value of `index` for every tag that includes the letter `l` in its tag key. -
-
# Data Types and Cast Operations The [`SELECT` clause](#the-basic-select-statement) supports specifying a [field's](/influxdb/v1.5/concepts/glossary/#field) type and basic cast @@ -2940,7 +2907,7 @@ Please see the document for more information on how InfluxDB handles field value type discrepancies. ### Syntax -``` +```sql SELECT_clause :: FROM_clause ``` @@ -2951,7 +2918,7 @@ In most cases, InfluxDB returns no data if the `field_key` does not store data o `type`. See [Cast Operations](#cast-operations) for more information. ### Example -``` +```sql > SELECT "water_level"::float FROM "h2o_feet" LIMIT 4 name: h2o_feet @@ -2972,7 +2939,7 @@ Currently, InfluxDB supports casting [field values](/influxdb/v1.5/concepts/glos floats or from floats to integers. ### Syntax -``` +```sql SELECT_clause :: FROM_clause ``` @@ -2987,7 +2954,7 @@ string or boolean. #### Example 1: Cast float field values to integers -``` +```sql > SELECT "water_level"::integer FROM "h2o_feet" LIMIT 4 name: h2o_feet @@ -3003,7 +2970,7 @@ The query returns the integer form of `water_level`'s float [field values](/infl #### Example 2: Cast float field values to strings (this functionality is not supported) -``` +```sql > SELECT "water_level"::string FROM "h2o_feet" LIMIT 4 > ``` @@ -3011,8 +2978,6 @@ The query returns the integer form of `water_level`'s float [field values](/infl The query returns no data as casting a float field value to a string is not yet supported. -
-
# Merge Behavior In InfluxDB, queries merge [series](/influxdb/v1.5/concepts/glossary/#series) automatically. @@ -3025,7 +2990,7 @@ The second series is made of up the `h2o_feet` measurement and the `location = s The following query automatically merges those two series when it calculates the [average](/influxdb/v1.5/query_language/functions/#mean) `water_level`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" name: h2o_feet @@ -3035,7 +3000,7 @@ time mean ``` If you want the average `water_level` for the first series only, specify the relevant tag in the [`WHERE` clause](#the-where-clause): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: h2o_feet @@ -3046,7 +3011,7 @@ time mean If you want the average `water_level` for each individual series, include a [`GROUP BY` clause](#group-by-tags): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -3062,8 +3027,6 @@ time mean 1970-01-01T00:00:00Z 3.530863470081006 ``` -
-
# Multiple Statements Separate multiple [`SELECT` statements](#the-basic-select-statement) in a query with a semicolon (`;`). @@ -3079,7 +3042,7 @@ Separate multiple [`SELECT` statements](#the-basic-select-statement) in a query In InfluxDB's [CLI](/influxdb/v1.5/tools/shell/): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet"; SELECT "water_level" FROM "h2o_feet" LIMIT 2 name: h2o_feet @@ -3150,8 +3113,7 @@ With InfluxDB's [HTTP API](/influxdb/v1.5/tools/api/): {{% /tab-content %}} {{< /tabs-wrapper >}} -
-
+ # Subqueries A subquery is a query that is nested in the `FROM` clause of another query. @@ -3160,7 +3122,7 @@ Subqueries offer functionality similar to nested functions and SQL [`HAVING` clauses](https://en.wikipedia.org/wiki/Having_(SQL\)). ### Syntax -``` +```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` @@ -3176,14 +3138,15 @@ The subquery supports all clauses listed in this document. InfluxQL supports multiple nested subqueries per main query. Sample syntax for multiple subqueries: -``` +```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ``` ### Examples #### Example 1: Calculate the [`SUM()`](/influxdb/v1.5/query_language/functions/#sum) of several [`MAX()`](/influxdb/v1.5/query_language/functions/#max) values -``` + +```sql > SELECT SUM("max") FROM (SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location") name: h2o_feet @@ -3195,7 +3158,7 @@ time sum The query returns the sum of the maximum `water_level` values across every tag value of `location`. InfluxDB first performs the subquery; it calculates the maximum value of `water_level` for each tag value of `location`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -3215,7 +3178,8 @@ Next, InfluxDB performs the main query and calculates the sum of those maximum v Notice that the main query specifies `max`, not `water_level`, as the field key in the `SUM()` function. #### Example 2: Calculate the [`MEAN()`](/influxdb/v1.5/query_language/functions/#mean) difference between two fields -``` + +```sql > SELECT MEAN("difference") FROM (SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare") name: pet_daycare @@ -3229,7 +3193,7 @@ The query returns the average of the differences between the number of `cats` an InfluxDB first performs the subquery. The subquery calculates the difference between the values in the `cats` field and the values in the `dogs` field, and it names the output column `difference`: -``` +```sql > SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare" name: pet_daycare @@ -3245,7 +3209,7 @@ Next, InfluxDB performs the main query and calculates the average of those diffe Notice that the main query specifies `difference` as the field key in the `MEAN()` function. #### Example 3: Calculate several [`MEAN()`](/influxdb/v1.5/query_language/functions/#mean) values and place a condition on those mean values -``` +```sql > SELECT "all_the_means" FROM (SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) ) WHERE "all_the_means" > 5 name: h2o_feet @@ -3259,7 +3223,7 @@ The query returns all mean values of the `water_level` field that are greater th InfluxDB first performs the subquery. The subquery calculates `MEAN()` values of `water_level` from `2015-08-18T00:00:00Z` through `2015-08-18T00:30:00Z` and groups the results into 12-minute intervals. It also names the output column `all_the_means`: -``` +```sql > SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: h2o_feet @@ -3274,7 +3238,8 @@ Next, InfluxDB performs the main query and returns only those mean values that a Notice that the main query specifies `all_the_means` as the field key in the `SELECT` clause. #### Example 4: Calculate the [`SUM()`](/influxdb/v1.5/query_language/functions/#sum) of several [`DERIVATIVE()`](/influxdb/v1.5/query_language/functions/#derivative) values -``` + +```sql > SELECT SUM("water_level_derivative") AS "sum_derivative" FROM (SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location") GROUP BY "location" name: h2o_feet @@ -3295,7 +3260,7 @@ The query returns the sum of the derivative of average `water_level` values for InfluxDB first performs the subquery. The subquery calculates the derivative of average `water_level` values taken at 12-minute intervals. It performs that calculation for each tag value of `location` and names the output column `water_level_derivative`: -``` +```sql > SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location" name: h2o_feet @@ -3321,14 +3286,14 @@ Notice that the main query specifies `water_level_derivative`, not `water_level` #### Issue 1: Multiple SELECT statements in a subquery InfluxQL supports multiple nested subqueries per main query: -``` +```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ------------------ ---------------- Subquery 1 Subquery 2 ``` InfluxQL does not support multiple [`SELECT` statements](#the-basic-select-statement) per subquery: -``` +```sql SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] ``` The system returns a parsing error if a subquery includes multiple `SELECT` statements. diff --git a/content/influxdb/v1.6/query_language/data_exploration.md b/content/influxdb/v1.6/query_language/data_exploration.md index fcab301f4..68c826745 100644 --- a/content/influxdb/v1.6/query_language/data_exploration.md +++ b/content/influxdb/v1.6/query_language/data_exploration.md @@ -174,7 +174,7 @@ Please review the [rules for single and double-quoting](/influxdb/v1.6/troublesh ### Examples #### Select all fields and tags from a single measurement -``` +```sql > SELECT * FROM "h2o_feet" name: h2o_feet @@ -203,7 +203,7 @@ queries the database's `DEFAULT` retention policy. #### Select specific tags and fields from a single measurement -``` +```sql > SELECT "level description","location","water_level" FROM "h2o_feet" name: h2o_feet @@ -223,7 +223,7 @@ a tag. #### Select specific tags and fields from a single measurement, and provide their identifier type -``` +```sql > SELECT "level description"::field,"location"::tag,"water_level"::field FROM "h2o_feet" name: h2o_feet @@ -245,7 +245,7 @@ That syntax is not required for most use cases. #### Select all fields from a single measurement -``` +```sql > SELECT *::field FROM "h2o_feet" name: h2o_feet @@ -262,7 +262,7 @@ The query selects all fields from the `h2o_feet` measurement. The `SELECT` clause supports combining the `*` syntax with the `::` syntax. #### Select a specific field from a measurement and perform basic arithmetic -``` +```sql > SELECT ("water_level" * 2) + 4 from "h2o_feet" name: h2o_feet @@ -282,7 +282,7 @@ See [Mathematical Operators](/influxdb/v1.6/query_language/math_operators/) for more on supported operators. #### Select all data from more than one measurement -``` +```sql > SELECT * FROM "h2o_feet","h2o_pH" name: h2o_feet @@ -309,7 +309,7 @@ The query selects all fields and tags from two measurements: `h2o_feet` and Separate multiple measurements with a comma (`,`). #### Select all data from a fully qualified measurement -``` +```sql > SELECT * FROM "NOAA_water_database"."autogen"."h2o_feet" name: h2o_feet @@ -332,7 +332,7 @@ In the HTTP API, fully qualify a measurement in place of using the `db` and `rp` query string parameters if desired. #### Select all data from a measurement in a particular database -``` +```sql > SELECT * FROM "NOAA_water_database".."h2o_feet" name: h2o_feet @@ -368,13 +368,13 @@ This behavior is a result of how the system stores data. The following query returns no data because it specifies a single tag key (`location`) in the `SELECT` clause: -``` +```sql > SELECT "location" FROM "h2o_feet" > ``` To return any data associated with the `location` tag key, the query's `SELECT` clause must include at least one field key (`water_level`): -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 name: h2o_feet time water_level location @@ -394,13 +394,12 @@ The `WHERE` filters data based on [timestamps](/influxdb/v1.6/concepts/glossary/#timestamp). Tired of reading? Check out this InfluxQL Short: -
-
+ ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE [(AND|OR) [...]] ``` @@ -410,12 +409,13 @@ The `WHERE` clause supports `conditional_expression`s on fields, tags, and timestamps. >**Note** InfluxDB does not support using OR in the WHERE clause to specify multiple time ranges. For example, InfluxDB will return an empty response for the following query: -
-`> SELECT * FROM "absolutismus" WHERE time = '2016-07-31T20:07:00Z' OR time = '2016-07-31T23:07:17Z'` +```sql +> SELECT * FROM "absolutismus" WHERE time = '2016-07-31T20:07:00Z' OR time = '2016-07-31T23:07:17Z'` +``` #### Fields -``` +```sql field_key ['string' | boolean | float | integer] ``` @@ -442,7 +442,7 @@ Other supported features: #### Tags -``` +```sql tag_key ['tag_value'] ``` @@ -472,7 +472,7 @@ details how to specify alternative time ranges in the `WHERE` clause. ### Examples #### Select data that have specific field key-values -``` +```sql > SELECT * FROM "h2o_feet" WHERE "water_level" > 8 name: h2o_feet @@ -491,7 +491,7 @@ The query returns data from the `h2o_feet` that are greater than eight. #### Select data that have a specific string field key-value -``` +```sql > SELECT * FROM "h2o_feet" WHERE "level description" = 'below 3 feet' name: h2o_feet @@ -510,7 +510,7 @@ InfluxQL requires single quotes around string field values in the `WHERE` clause. #### Select data that have a specific field key-value and perform basic arithmetic -``` +```sql > SELECT * FROM "h2o_feet" WHERE "water_level" + 2 > 11.9 name: h2o_feet @@ -535,7 +535,7 @@ for more on supported operators. #### Select data that have a specific tag key-value -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' name: h2o_feet @@ -553,7 +553,7 @@ The query returns data from the `h2o_feet` measurement where the InfluxQL requires single quotes around tag values in the `WHERE` clause. #### Select data that have specific field key-values and tag key-values -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" <> 'santa_monica' AND (water_level < -0.59 OR water_level > 9.95) name: h2o_feet @@ -574,7 +574,7 @@ The `WHERE` clause supports the operators `AND` and `OR`, and supports separating logic with parentheses. #### Select data that have specific timestamps -``` +```sql > SELECT * FROM "h2o_feet" WHERE time > now() - 7d ``` @@ -598,7 +598,7 @@ The first two queries in the code block below attempt to specify the tag value Those queries return no results. The third query single quotes `santa_monica` (this is the supported syntax) and returns the expected results. -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = santa_monica > SELECT "water_level" FROM "h2o_feet" WHERE "location" = "santa_monica" @@ -622,7 +622,7 @@ The second query returns no results. The third query single quotes `at or greater than 9 feet` (this is the supported syntax) and returns the expected results. -``` +```sql > SELECT "level description" FROM "h2o_feet" WHERE "level description" = at or greater than 9 feet ERR: error parsing query: found than, expected ; at line 1, char 86 @@ -672,7 +672,7 @@ Tired of reading? Check out this InfluxQL Short: #### Syntax -``` +```sql SELECT_clause FROM_clause [WHERE_clause] GROUP BY [* | [, SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -725,7 +725,7 @@ If you request a query that has no timestamp to return, such as an [aggregation ##### Group query results by more than one tag -``` +```sql > SELECT MEAN("index") FROM "h2o_quality" GROUP BY location,randtag name: h2o_quality @@ -772,7 +772,7 @@ Separate multiple tags with a comma in the `GROUP BY` clause. ##### Group query results by all tags -``` +```sql > SELECT MEAN("index") FROM "h2o_quality" GROUP BY * name: h2o_quality @@ -834,7 +834,7 @@ This is because the `h2o_quality` measurement only has two tag keys. #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(),[tag_key] [fill()] ``` @@ -869,7 +869,7 @@ and the timestamps returned by the query. #### Examples of basic syntax The examples below use the following subsample of the sample data: -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' name: h2o_feet @@ -891,7 +891,7 @@ time water_level location ##### Group query results into 12 minute intervals -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: h2o_feet @@ -915,7 +915,7 @@ and up to, but not including, `2015-08-18T00:24:00Z.` ##### Group query results into 12 minutes intervals and by a tag key -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location" name: h2o_feet @@ -962,7 +962,7 @@ In some cases, this can lead to unexpected results. Raw data: -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:18:00Z' name: h2o_feet -------------- @@ -977,7 +977,7 @@ Query and results: The following query covers a 12-minute time range and groups results into 12-minute time intervals, but it returns **two** results: -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m) name: h2o_feet @@ -1023,7 +1023,7 @@ in the Advanced Syntax section continues with the query shown here; it shifts forward the preset time boundaries by six minutes such that InfluxDB returns: -``` +```sql name: h2o_feet time count ---- ----- @@ -1034,7 +1034,7 @@ time count #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(,),[tag_key] [fill()] ``` @@ -1072,7 +1072,7 @@ and the timestamps returned by the query. The examples below use the following subsample of the sample data: -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:54:00Z' name: h2o_feet @@ -1092,7 +1092,7 @@ time water_level ##### Group query results into 18 minute intervals and shift the preset time boundaries forward -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m,6m) name: h2o_feet @@ -1109,7 +1109,7 @@ time intervals, and offsetting the preset time boundaries by six minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m) name: h2o_feet @@ -1170,7 +1170,7 @@ the query's time range so the query returns no results for that last interval. ##### Group query results into 12 minute intervals and shift the preset time boundaries back -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m,-12m) name: h2o_feet @@ -1192,7 +1192,7 @@ the query in Example 2 uses a negative `offset_interval` instead of a positive intuitive option when deciding between a positive and negative `offset_interval`. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time <= '2015-08-18T00:54:00Z' GROUP BY time(18m) name: h2o_feet @@ -1255,7 +1255,7 @@ the query's time range so the query returns no results for that first interval. This example is a continuation of the scenario outlined in [Common Issues with Basic Syntax](#common-issues-with-basic-syntax). -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m,6m) name: h2o_feet @@ -1270,7 +1270,7 @@ time intervals, and offsetting the preset time boundaries by six minutes. The time boundaries and returned timestamps for the query **without** the `offset_interval` adhere to InfluxDB's preset time boundaries. Let's first examine the results without the offset: -``` +```sql > SELECT COUNT("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-08-18T00:06:00Z' AND time < '2015-08-18T00:18:00Z' GROUP BY time(12m) name: h2o_feet @@ -1324,7 +1324,7 @@ the query's time range so the query returns no results for that second interval. #### Syntax -``` +```sql SELECT () FROM_clause WHERE GROUP BY time(time_interval,[)] ``` @@ -1377,7 +1377,7 @@ Reports the value from the previous time interval for time intervals with no dat {{% tab-content %}} Without `fill(100)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1390,7 +1390,7 @@ time max ``` With `fill(100)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(100) name: h2o_feet @@ -1410,7 +1410,7 @@ time max Without `fill(linear)`: -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:00:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) name: pond @@ -1425,7 +1425,7 @@ time mean ``` With `fill(linear)`: -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:00:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond @@ -1450,7 +1450,7 @@ We had to create a dataset with less regular data to work with `fill(linear)`. {{% tab-content %}} Without `fill(none)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1463,7 +1463,7 @@ time max ``` With `fill(none)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(none) name: h2o_feet @@ -1481,7 +1481,7 @@ time max {{% tab-content %}} Without `fill(null)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1494,7 +1494,7 @@ time max ``` With `fill(null)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(null) name: h2o_feet @@ -1514,7 +1514,7 @@ That result matches the result of the query without `fill(null)`. {{% tab-content %}} Without `fill(previous)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) name: h2o_feet @@ -1527,7 +1527,7 @@ time max ``` With `fill(previous)`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE "location"='coyote_creek' AND time >= '2015-09-18T16:00:00Z' AND time <= '2015-09-18T16:42:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1560,7 +1560,7 @@ range covers no data. The following query returns no data because `water_level` has no points within the query's time range. Note that `fill(800)` has no effect on the query results. -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2015-09-18T22:00:00Z' AND time <= '2015-09-18T22:18:00Z' GROUP BY time(12m) fill(800) > ``` @@ -1575,7 +1575,7 @@ value is outside the query’s time range. The following query covers the time range between `2015-09-18T16:24:00Z` and `2015-09-18T16:54:00Z`. Note that `fill(previous)` fills the result for `2015-09-18T16:36:00Z` with the result from `2015-09-18T16:24:00Z`. -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2015-09-18T16:24:00Z' AND time <= '2015-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1592,7 +1592,7 @@ Note that `fill(previous)` doesn't fill the result for `2015-09-18T16:36:00Z` wi result from `2015-09-18T16:24:00Z`; the result for `2015-09-18T16:24:00Z` is outside the query's shorter time range. -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" WHERE location = 'coyote_creek' AND time >= '2015-09-18T16:36:00Z' AND time <= '2015-09-18T16:54:00Z' GROUP BY time(12m) fill(previous) name: h2o_feet @@ -1615,7 +1615,7 @@ The following query covers the time range between `2016-11-11T21:24:00Z` and using the values from the `2016-11-11T21:24:00Z` time interval and the `2016-11-11T22:00:00Z` time interval. -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time > '2016-11-11T21:24:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond @@ -1634,7 +1634,7 @@ time interval and the `2016-11-11T21:48:00Z` time interval; the result for `2016-11-11T21:24:00Z` is outside the query's shorter time range and InfluxDB cannot perform the linear interpolation. -``` +```sql > SELECT MEAN("tadpoles") FROM "pond" WHERE time >= '2016-11-11T21:36:00Z' AND time <= '2016-11-11T22:06:00Z' GROUP BY time(12m) fill(linear) name: pond time mean @@ -1652,7 +1652,7 @@ time mean The `INTO` clause writes query results to a user-specified [measurement](/influxdb/v1.6/concepts/glossary/#measurement). ### Syntax -``` +```sql SELECT_clause INTO FROM_clause [WHERE_clause] [GROUP_BY_clause] ``` @@ -1690,7 +1690,7 @@ retention policy that match the [regular expression](#regular-expressions) in th #### Rename a database -``` +```sql > SELECT * INTO "copy_NOAA_water_database"."autogen".:MEASUREMENT FROM "NOAA_water_database"."autogen"./.*/ GROUP BY * name: result @@ -1710,7 +1710,7 @@ for how to manage databases and retention policies. The `GROUP BY *` clause [preserves tags](#missing-data) in the source database as tags in the destination database. The following query does not maintain the series context for tags; tags will be stored as fields in the destination database (`copy_NOAA_water_database`): -``` +```sql SELECT * INTO "copy_NOAA_water_database"."autogen".:MEASUREMENT FROM "NOAA_water_database"."autogen"./.*/ ``` @@ -1742,7 +1742,7 @@ WHERE time > now() - 80w and time < now() - 70w GROUP BY * #### Write the results of a query to a measurement -``` +```sql > SELECT "water_level" INTO "h2o_feet_copy_1" FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: result @@ -1775,7 +1775,7 @@ The timestamp in the response is meaningless; InfluxDB uses epoch 0 #### Write the results of a query to a fully qualified measurement -``` +```sql > SELECT "water_level" INTO "where_else"."autogen"."h2o_feet_copy_2" FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: result @@ -1807,7 +1807,7 @@ The timestamp in the response is meaningless; InfluxDB uses epoch 0 #### Write aggregated results to a measurement (downsampling) -``` +```sql > SELECT MEAN("water_level") INTO "all_my_averages" FROM "h2o_feet" WHERE "location" = 'coyote_creek' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: result @@ -1841,7 +1841,7 @@ Downsampling is a common use case for the `INTO` clause. #### Write aggregated results for more than one measurement to a different database (downsampling with backreferencing) -``` +```sql > SELECT MEAN(*) INTO "where_else"."autogen".:MEASUREMENT FROM /.*/ WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:06:00Z' GROUP BY time(12m) name: result @@ -1934,7 +1934,7 @@ the last point returned has the most recent timestamp. with the most recent timestamps first. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] ORDER BY time DESC ``` @@ -1949,7 +1949,7 @@ if the query includes a `WHERE` clause and no `GROUP BY` clause. #### Return the newest points first -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' ORDER BY time DESC name: h2o_feet @@ -1969,7 +1969,7 @@ first and `2015-09-18T21:42:00Z` last. #### Return the newest points first and include a GROUP BY time() clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY time(12m) ORDER BY time DESC name: h2o_feet @@ -2003,7 +2003,7 @@ Without `ORDER BY time DESC`, the query would return `LIMIT ` returns the first `N` [points](/influxdb/v1.6/concepts/glossary/#point) from the specified [measurement](/influxdb/v1.6/concepts/glossary/#measurement). ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT ``` @@ -2019,7 +2019,7 @@ Note that the `LIMIT` clause must appear in the order outlined in the syntax abo #### Limit the number of points returned -``` +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 name: h2o_feet @@ -2034,7 +2034,7 @@ The query returns the three oldest [points](/influxdb/v1.6/concepts/glossary/#po #### Limit the number points returned and include a GROUP BY clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 name: h2o_feet @@ -2067,7 +2067,7 @@ one for each twelve-minute interval in the query's time range. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] SLIMIT ``` @@ -2084,7 +2084,7 @@ Note that the `SLIMIT` clause must appear in the order outlined in the syntax ab #### Limit the number of series returned -``` +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 name: h2o_feet @@ -2104,7 +2104,7 @@ The query returns all `water_level` [points](/influxdb/v1.6/concepts/glossary/#p with the `h2o_feet` [measurement](/influxdb/v1.6/concepts/glossary/#measurement). #### Limit the number of series returned and include a GROUP BY time() clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) SLIMIT 1 name: h2o_feet @@ -2133,7 +2133,7 @@ associated with the `h2o_feet` measurement: `location=coyote_creek` and `LIMIT ` followed by `SLIMIT ` returns the first \ [points](/influxdb/v1.6/concepts/glossary/#point) from \ [series](/influxdb/v1.6/concepts/glossary/#series) in the specified measurement. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time()] [ORDER_BY_clause] LIMIT SLIMIT ``` @@ -2151,7 +2151,7 @@ Note that the `LIMIT` and `SLIMIT` clauses must appear in the order outlined in ### Examples #### Limit the number of points and series returned -``` +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * LIMIT 3 SLIMIT 1 name: h2o_feet @@ -2168,7 +2168,8 @@ of the [series](/influxdb/v1.6/concepts/glossary/#series) associated with the [measurement](/influxdb/v1.6/concepts/glossary/#measurement) `h2o_feet`. #### Limit the number of points and series returned and include a GROUP BY time() clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) LIMIT 2 SLIMIT 1 name: h2o_feet @@ -2207,7 +2208,7 @@ for each of the two series associated with the `h2o_feet` measurement. `OFFSET ` paginates `N` [points](/influxdb/v1.6/concepts/glossary/#point) in the query results. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] LIMIT_clause OFFSET [SLIMIT_clause] ``` @@ -2225,7 +2226,8 @@ timestamps outside of that time range. ### Examples #### Paginate points -``` + +```sql > SELECT "water_level","location" FROM "h2o_feet" LIMIT 3 OFFSET 3 name: h2o_feet @@ -2241,7 +2243,8 @@ If the query did not include `OFFSET 3`, it would return the first, second, and third points from that measurement. #### Paginate points and include several clauses -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 name: h2o_feet @@ -2264,7 +2267,7 @@ The `OFFSET 2` clause excludes the first two averages from the query results. The [`SLIMIT 1` clause](#the-slimit-clause) limits the number of series returned to one. Without `OFFSET 2`, the query would return the first two averages of the query results: -``` +```sql name: h2o_feet tags: location=coyote_creek time mean @@ -2279,7 +2282,7 @@ time mean ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] GROUP BY *[,time(time_interval)] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] SLIMIT_clause SOFFSET ``` @@ -2298,7 +2301,7 @@ through more than the total number of series. #### Paginate series -``` +```sql > SELECT "water_level" FROM "h2o_feet" GROUP BY * SLIMIT 1 SOFFSET 1 name: h2o_feet @@ -2319,7 +2322,7 @@ Without `SOFFSET 1`, the query returns data for the series associated with the #### Paginate series and include all clauses -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:42:00Z' GROUP BY *,time(12m) ORDER BY time DESC LIMIT 2 OFFSET 2 SLIMIT 1 SOFFSET 1 name: h2o_feet @@ -2343,7 +2346,7 @@ The [`SLIMIT 1` clause](#the-slimit-clause) limits the number of series returned The `SOFFSET 1` clause paginates the series returned. Without `SOFFSET 1`, the query would return the results for a different series: -``` +```sql name: h2o_feet tags: location=coyote_creek time mean @@ -2352,15 +2355,13 @@ time mean 2015-08-18T00:00:00Z 8.0625 ``` -
-
# The Time Zone clause The `tz()` clause returns the UTC offset for the specified timezone. ### Syntax -``` +```sql SELECT_clause [INTO_clause] FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('') ``` @@ -2374,7 +2375,7 @@ The `time_zone` parameter follows the TZ syntax in the [Internet Assigned Number ### Examples #### Return the UTC offset for Chicago's time zone -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:18:00Z' tz('America/Chicago') name: h2o_feet @@ -2414,7 +2415,7 @@ Tired of reading? Check out this InfluxQL Short: Specify absolute time with date-time strings and epoch time. ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE time ['' | '' | ] [AND ['' | '' | ] [...]] ``` @@ -2437,7 +2438,7 @@ for more information. #### rfc3339_date_time_string -``` +```sql 'YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ' ``` @@ -2446,7 +2447,7 @@ The [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) date-time string requires si #### rfc3339_like_date_time_string -``` +```sql 'YYYY-MM-DD HH:MM:SS.nnnnnnnnn' ``` @@ -2472,7 +2473,7 @@ duration literal. ### Examples #### Specify a time range with RFC3339 date-time strings -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00.000000000Z' AND time <= '2015-08-18T00:12:00Z' name: h2o_feet @@ -2492,7 +2493,7 @@ Note that the single quotes around the RFC3339 date-time strings are required. #### Specify a time range with RFC3339-like date-time strings -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18' AND time <= '2015-08-18 00:12:00' name: h2o_feet @@ -2513,7 +2514,8 @@ required. #### Specify a time range with epoch timestamps -``` + +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1439856000000000000 AND time <= 1439856720000000000 name: h2o_feet @@ -2529,7 +2531,7 @@ at 00:00:00 and August 18, 2015 at 00:12:00. By default InfluxDB assumes epoch timestamps are in nanoseconds. #### Specify a time range with second-precision epoch timestamps -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= 1439856000s AND time <= 1439856720s name: h2o_feet @@ -2546,7 +2548,7 @@ The `s` [duration literal](/influxdb/v1.6/query_language/spec/#durations) at the end of the epoch timestamps indicate that the epoch timestamps are in seconds. #### Perform basic arithmetic on an RFC3339-like date-time string -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > '2015-09-18T21:24:00Z' + 6m name: h2o_feet @@ -2562,7 +2564,7 @@ Note that the whitespace between the `+` and `6m` is required. #### Perform basic arithmetic on an epoch timestamp -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > 24043524m - 6m name: h2o_feet @@ -2582,7 +2584,7 @@ Note that the whitespace between the `-` and `6m` is required. Use [`now()`](/influxdb/v1.6/concepts/glossary/#now) to query data with [timestamps](/influxdb/v1.6/concepts/glossary/#timestamp) relative to the server's current timestamp. ### Syntax -``` +```sql SELECT_clause FROM_clause WHERE time now() [[ - | + ] ] [(AND|OR) now() [...]] ``` @@ -2614,7 +2616,7 @@ The whitespace between `-` or `+` and the [duration literal](/influxdb/v1.6/quer ### Examples #### Specify a time range with relative time -``` +```sql > SELECT "water_level" FROM "h2o_feet" WHERE time > now() - 1h ``` @@ -2622,7 +2624,7 @@ The query returns data with timestamps that occur within the past hour. The whitespace between `-` and `1h` is required. #### Specify a time range with absolute time and relative time -``` +```sql > SELECT "level description" FROM "h2o_feet" WHERE time > '2015-09-18T21:18:00Z' AND time < now() + 1000d name: h2o_feet @@ -2659,13 +2661,13 @@ a `GROUP BY time()` clause must provide an alternative upper bound in the #### Example Use the [CLI](/influxdb/v1.6/tools/shell/) to write a point to the `NOAA_water_database` that occurs after `now()`: -``` +```sql > INSERT h2o_feet,location=santa_monica water_level=3.1 1587074400000000000 ``` Run a `GROUP BY time()` query that covers data with timestamps between `2015-09-18T21:30:00Z` and `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= '2015-09-18T21:30:00Z' GROUP BY time(12m) fill(none) name: h2o_feet @@ -2677,7 +2679,7 @@ time mean Run a `GROUP BY time()` query that covers data with timestamps between `2015-09-18T21:30:00Z` and 180 weeks from `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= '2015-09-18T21:30:00Z' AND time <= now() + 180w GROUP BY time(12m) fill(none) name: h2o_feet @@ -2692,7 +2694,7 @@ Note that the `WHERE` clause must provide an alternative **upper** bound to override the default `now()` upper bound. The following query merely resets the lower bound to `now()` such that the query's time range is between `now()` and `now()`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location"='santa_monica' AND time >= now() GROUP BY time(12m) fill(none) > ``` @@ -2729,7 +2731,7 @@ string comparisons; queries with regular expressions are not as performant as those without. ### Syntax -``` +```sql SELECT // FROM // WHERE [ // | //] GROUP BY // ``` @@ -2745,7 +2747,7 @@ Supported operators: ### Examples #### Use a regular expression to specify field keys and tag keys in the SELECT clause -``` +```sql > SELECT /l/ FROM "h2o_feet" LIMIT 1 name: h2o_feet @@ -2765,7 +2767,7 @@ field keys and regular expressions for tag keys in the `SELECT` clause. The syntax `//::[field | tag]` is not supported. #### Use a regular expression to specify field keys with a function in the SELECT clause -``` +```sql > SELECT DISTINCT(/level/) FROM "h2o_feet" WHERE "location" = 'santa_monica' AND time >= '2015-08-18T00:00:00.000000000Z' AND time <= '2015-08-18T00:12:00Z' name: h2o_feet @@ -2781,7 +2783,7 @@ to return the distinct [field values](/influxdb/v1.6/concepts/glossary/#field-va for every field key that contains the word `level`. #### Use a regular expression to specify measurements in the FROM clause -``` +```sql > SELECT MEAN("degrees") FROM /temperature/ name: average_temperature @@ -2801,7 +2803,7 @@ to calculate the average `degrees` for every [measurement](/influxdb/v1.6/concep #### Use a regular expression to specify tag values in the WHERE clause -``` +```sql > SELECT MEAN(water_level) FROM "h2o_feet" WHERE "location" =~ /[m]/ AND "water_level" > 3 name: h2o_feet @@ -2816,7 +2818,7 @@ includes an `m` and `water_level` is greater than three. #### Use a regular expression to specify a tag with no value in the WHERE clause -``` +```sql > SELECT * FROM "h2o_feet" WHERE "location" !~ /./ > ``` @@ -2832,7 +2834,7 @@ document for more information. #### Use a regular expression to specify a tag with a value in the WHERE clause -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" =~ /./ name: h2o_feet @@ -2846,7 +2848,8 @@ to calculate the average `water_level` across all data that have a tag value for `location`. #### Use a regular expression to specify a field value in the WHERE clause -``` + +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'santa_monica' AND "level description" =~ /between/ name: h2o_feet @@ -2860,7 +2863,8 @@ to calculate the average `water_level` for all data where the field value of `level description` includes the word `between`. #### Use a regular expression to specify tag keys in the GROUP BY clause -``` + +```sql > SELECT FIRST("index") FROM "h2o_quality" GROUP BY /l/ name: h2o_quality @@ -2911,7 +2915,7 @@ document for more information on how InfluxDB handles field value type discrepan ### Syntax -``` +```sql SELECT_clause :: FROM_clause ``` @@ -2922,7 +2926,8 @@ In most cases, InfluxDB returns no data if the `field_key` does not store data o `type`. See [Cast Operations](#cast-operations) for more information. ### Example -``` + +```sql > SELECT "water_level"::float FROM "h2o_feet" LIMIT 4 name: h2o_feet @@ -2943,7 +2948,7 @@ Currently, InfluxDB supports casting [field values](/influxdb/v1.6/concepts/glos floats or from floats to integers. ### Syntax -``` +```sql SELECT_clause :: FROM_clause ``` @@ -2958,7 +2963,7 @@ string or boolean. #### Cast float field values to integers -``` +```sql > SELECT "water_level"::integer FROM "h2o_feet" LIMIT 4 name: h2o_feet @@ -2974,7 +2979,7 @@ The query returns the integer form of `water_level`'s float [field values](/infl #### Cast float field values to strings (this functionality is not supported) -``` +```sql > SELECT "water_level"::string FROM "h2o_feet" LIMIT 4 > ``` @@ -2982,7 +2987,6 @@ The query returns the integer form of `water_level`'s float [field values](/infl The query returns no data as casting a float field value to a string is not yet supported. - # Merge behavior In InfluxDB, queries merge [series](/influxdb/v1.6/concepts/glossary/#series) @@ -2996,7 +3000,7 @@ The second series is made of up the `h2o_feet` measurement and the `location = s The following query automatically merges those two series when it calculates the [average](/influxdb/v1.6/query_language/functions/#mean) `water_level`: -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" name: h2o_feet @@ -3006,7 +3010,7 @@ time mean ``` If you want the average `water_level` for the first series only, specify the relevant tag in the [`WHERE` clause](#the-where-clause): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" WHERE "location" = 'coyote_creek' name: h2o_feet @@ -3017,7 +3021,7 @@ time mean If you want the average `water_level` for each individual series, include a [`GROUP BY` clause](#group-by-tags): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -3049,7 +3053,7 @@ Separate multiple [`SELECT` statements](#the-basic-select-statement) in a query In InfluxDB's [CLI](/influxdb/v1.6/tools/shell/): -``` +```sql > SELECT MEAN("water_level") FROM "h2o_feet"; SELECT "water_level" FROM "h2o_feet" LIMIT 2 name: h2o_feet @@ -3129,7 +3133,7 @@ Subqueries offer functionality similar to nested functions and SQL [`HAVING` clauses](https://en.wikipedia.org/wiki/Having_(SQL\)). ### Syntax -``` +```sql SELECT_clause FROM ( SELECT_statement ) [...] ``` @@ -3146,14 +3150,15 @@ The subquery supports all clauses listed in this document. InfluxQL supports multiple nested subqueries per main query. Sample syntax for multiple subqueries: -``` +```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ``` ### Examples #### Calculate the [`SUM()`](/influxdb/v1.6/query_language/functions/#sum) of several [`MAX()`](/influxdb/v1.6/query_language/functions/#max) values -``` + +```sql > SELECT SUM("max") FROM (SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location") name: h2o_feet @@ -3165,7 +3170,7 @@ time sum The query returns the sum of the maximum `water_level` values across every tag value of `location`. InfluxDB first performs the subquery; it calculates the maximum value of `water_level` for each tag value of `location`: -``` +```sql > SELECT MAX("water_level") FROM "h2o_feet" GROUP BY "location" name: h2o_feet @@ -3185,7 +3190,8 @@ Next, InfluxDB performs the main query and calculates the sum of those maximum v Notice that the main query specifies `max`, not `water_level`, as the field key in the `SUM()` function. #### Calculate the [`MEAN()`](/influxdb/v1.6/query_language/functions/#mean) difference between two fields -``` + +```sql > SELECT MEAN("difference") FROM (SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare") name: pet_daycare @@ -3199,7 +3205,7 @@ The query returns the average of the differences between the number of `cats` an InfluxDB first performs the subquery. The subquery calculates the difference between the values in the `cats` field and the values in the `dogs` field, and it names the output column `difference`: -``` +```sql > SELECT "cats" - "dogs" AS "difference" FROM "pet_daycare" name: pet_daycare @@ -3215,7 +3221,7 @@ Next, InfluxDB performs the main query and calculates the average of those diffe Notice that the main query specifies `difference` as the field key in the `MEAN()` function. #### Calculate several [`MEAN()`](/influxdb/v1.6/query_language/functions/#mean) values and place a condition on those mean values -``` +```sql > SELECT "all_the_means" FROM (SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) ) WHERE "all_the_means" > 5 name: h2o_feet @@ -3229,7 +3235,7 @@ The query returns all mean values of the `water_level` field that are greater th InfluxDB first performs the subquery. The subquery calculates `MEAN()` values of `water_level` from `2015-08-18T00:00:00Z` through `2015-08-18T00:30:00Z` and groups the results into 12-minute intervals. It also names the output column `all_the_means`: -``` +```sql > SELECT MEAN("water_level") AS "all_the_means" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m) name: h2o_feet @@ -3244,7 +3250,8 @@ Next, InfluxDB performs the main query and returns only those mean values that a Notice that the main query specifies `all_the_means` as the field key in the `SELECT` clause. #### Calculate the [`SUM()`](/influxdb/v1.6/query_language/functions/#sum) of several [`DERIVATIVE()`](/influxdb/v1.6/query_language/functions/#derivative) values -``` + +```sql > SELECT SUM("water_level_derivative") AS "sum_derivative" FROM (SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location") GROUP BY "location" name: h2o_feet @@ -3265,7 +3272,7 @@ The query returns the sum of the derivative of average `water_level` values for InfluxDB first performs the subquery. The subquery calculates the derivative of average `water_level` values taken at 12-minute intervals. It performs that calculation for each tag value of `location` and names the output column `water_level_derivative`: -``` +```sql > SELECT DERIVATIVE(MEAN("water_level")) AS "water_level_derivative" FROM "h2o_feet" WHERE time >= '2015-08-18T00:00:00Z' AND time <= '2015-08-18T00:30:00Z' GROUP BY time(12m),"location" name: h2o_feet @@ -3291,14 +3298,14 @@ Notice that the main query specifies `water_level_derivative`, not `water_level` #### Multiple SELECT statements in a subquery InfluxQL supports multiple nested subqueries per main query: -``` +```sql SELECT_clause FROM ( SELECT_clause FROM ( SELECT_statement ) [...] ) [...] ------------------ ---------------- Subquery 1 Subquery 2 ``` InfluxQL does not support multiple [`SELECT` statements](#the-basic-select-statement) per subquery: -``` +```sql SELECT_clause FROM (SELECT_statement; SELECT_statement) [...] ``` The system returns a parsing error if a subquery includes multiple `SELECT` statements.