SQL reference documentation

InfluxDB Clustered uses the Apache Arrow DataFusion implementation of SQL.

• Identifiers
• Quoting and case sensitivity
• Literals
• Duration units
• Operators
• Keywords
• Conditional expressions
• Statements and clauses
• Comments
• Functions

Identifiers

An identifier is a token which refers to the name of an InfluxDB database object, such as a measurement or a column name (time, tag keys, or field keys).

Quoting

Use double quotes on identifiers to treat them as case-sensitive. Use single quotes on string literals.

General quoting guidelines:

• Single quote RFC3339 and RFC3339-like time values.
• Do not quote Unix epoch time values (integers cast to a timestamp).
• Double-quote mixed case, camel case or case-sensitive identifiers.
• Double-quote identifiers that contain special characters or whitespace characters.

Quoting examples

-- Double-quote identifiers that contain whitespace
SELECT "water temperature", "buoy location" FROM buoy

-- Double-quote measurement names with special characters
SELECT * FROM "h2o-temperature"

-- Double-quote identifiers that should be treated as case-sensitive
SELECT "pH" FROM "Water"

Unquoted identifiers are not case-sensitive and match any measurement, tag key, or field key with the same characters, despite case. For example, if you have two fields in a measurement named ph and pH, the unquoted identifier, pH will match both. To query in a case-sensitive manner, double-quote identifiers.

Literals

A literal is an explicit value not represented by an identifier.

String literals

String literals are surrounded by single quotes.

'santa_monica'
'pH'
'average temperature'

Numeric literals

Number literals are positive or negative numbers that are either exact numbers or floats.

-- Integers
10
+10
-10

-- Unsigned integers
10::BIGINT UNSIGNED
+10::BIGINT UNSIGNED

-- Floats
10.78654
-100.56

Date and time literals

The following date and time literals are supported:

'2022-01-31T06:30:30.123Z'     -- (RFC3339) 
'2022-01-31T06:30:30.123'      -- (RFC3339-like)
'2022-01-31 06:30:30.123'      -- (RFC3339-like)
'2022-01-31 06:30:30'          -- ((RFC3339-like, no fractional seconds) 
1643610630123000000::TIMESTAMP -- (Unix epoch nanosecond cast to a timestamp)

Boolean literals

Boolean literals are either TRUE or FALSE.

Duration units

Interval literals specify a length or unit of time.

INTERVAL '4 minutes'
INTERVAL '12 days 6 hours 30 minutes'

The following units of time are supported:

• nanoseconds
• microseconds
• milliseconds
• seconds
• minutes
• hours
• days
• weeks
• months
• years
• century

Operators

Operators are reserved words or characters which perform certain operations, including comparisons and arithmetic.

Arithmetic operators

Arithmetic operators take two numeric values (either literals or variables) and perform a calculation that returns a single numeric value.

Comparison operators

Comparison operators evaluate the relationship between the left and right operands and TRUE or FALSE.

Logical operators

Bitwise operators

Bitwise operators perform bitwise operations on bit patterns or binary numerals.

Other operators

Keywords

The following reserved keywords cannot be used as identifiers.

AND
ALL
ANALYZE
AS
ASC
AT TIME ZONE
BETWEEN
BOTTOM
CASE
DESC
DISTINCT
EXISTS
EXPLAIN
FROM
GROUP BY
HAVING
IN
INNER JOIN
JOIN
LEFT JOIN
LIKE
LIMIT
NOT
EXISTS
NOT IN
OR
ORDER BY
FULL OUTER JOIN
RIGHT JOIN
SELECT
TOP
TYPE
UNION
UNION ALL
WHERE
WITH

Conditional expressions

Conditional expressions evaluate conditions based on input values. The following conditional expressions are supported:

Statements and clauses

InfluxDB SQL supports the following basic syntax for queries:

[ WITH with_query [, …] ]  
SELECT [ ALL | DISTINCT ] select_expr [, …]  
[ FROM from_item [, …] ]  
[ JOIN join_item [, …] ]  
[ WHERE condition ]  
[ GROUP BY grouping_element [, …] ]  
[ HAVING condition]  
[ UNION [ ALL ] ]
[ ORDER BY expression [ ASC | DESC ][, …] ]  
[ LIMIT count ]  

SELECT statement and FROM clause

Use the SQL SELECT statement to query data from a specific measurement or measurements. The FROM clause always accompanies the SELECT statement.

Examples

SELECT * FROM "h2o_feet"

WHERE clause

Use the WHERE clause to filter results based on fields, tags, and timestamps. Use predicates to evaluate each row. Rows that evaluate as TRUE are returned in the result set. Rows that evaluate as FALSE are omitted from the result set.

Examples

SELECT * FROM "h2o_feet" WHERE "water_level" <= 9

SELECT 
  * 
FROM 
  "h2o_feet" 
WHERE 
  "location" = 'santa_monica' 
  AND "level description" = 'below 3 feet'

JOIN clause

Use the JOIN clause to join data from multiple measurements (tables). For more information about joins, see JOIN clause. The following join types are supported:

SELECT
  *
FROM
  home
INNER JOIN home_actions ON
  home.room = home_actions.room
  AND home.time = home_actions.time;

SELECT
  *
FROM
  home
LEFT OUTER JOIN home_actions ON
  home.room = home_actions.room
  AND home.time = home_actions.time;

SELECT
  *
FROM
  home
RIGHT OUTER JOIN home_actions ON
  home.room = home_actions.room
  AND home.time = home_actions.time;

SELECT
  *
FROM
  home
FULL OUTER JOIN home_actions ON
  home.room = home_actions.room
  AND home.time = home_actions.time;

GROUP BY clause

Use the GROUP BY clause to group query results based on specified column values. GROUP BY requires an aggregate or selector function in the SELECT statement.

Examples

SELECT 
  MEAN("water_level"), 
  "location" 
FROM 
  "h2o_feet" 
GROUP BY 
  "location"

HAVING clause

Use the HAVING clause to filter query results based on a specified condition. The HAVING clause must follow the GROUP BY clause, but precede the ORDER BY clause.

Examples

SELECT 
  MEAN("water_level"), 
  "location" 
FROM 
  "h2o_feet" 
GROUP BY 
  "location" 
HAVING 
  MEAN("water_level") > 4
ORDER BY
  "location"

UNION clause

The UNION clause combines the results of two or more SELECT statements without returning any duplicate rows. UNION ALL returns all results, including duplicates.

Examples

SELECT 
  'pH' 
FROM 
  "h2o_pH" 
UNION ALL 
SELECT 
  "location" 
FROM 
  "h2o_quality"

ORDER BY clause

The ORDER BY clause orders results by specified columns and order. Sort data based on fields, tags, and timestamps. The following orders are supported:

• ASC: ascending (default)
• DESC: descending

Examples

SELECT 
  "water_level", 
  "location" 
FROM 
  "h2o_feet" 
ORDER BY 
  "location", 
  "time" DESC

LIMIT clause

The LIMIT clause limits the number of rows to return. The defined limit should be a non-negative integer.

Examples

SELECT 
  "water_level", 
  "location" 
FROM 
  "h2o_feet" 
LIMIT 
  10

WITH clause

The WITH clause provides a way to write auxiliary statements for use in a larger query. It can help break down large, complicated queries into simpler forms.

WITH summary_data as
(SELECT degrees, location, time 
  FROM average_temperature)
SELECT * FROM summary_data

OVER clause

The OVER clause is used with SQL window functions. A window function performs a calculation across a set of table rows that are related in some way to the current row. While similar to aggregate functions, window functions output results into rows retaining their separate identities.

SELECT 
  time, 
  water_level 
FROM 
  (
    SELECT 
      time, 
      "water_level", 
      row_number() OVER (
        order by 
          water_level desc
      ) as rn 
    FROM 
      h2o_feet
  ) 
WHERE 
  rn <= 3;

Comments

Use comments to describe and add detail or notes to your queries.

• Single line comments use the double hyphen -- symbol. Single line comments end with a line break.
• Multi-line comments begin with /* and end with */.

-- Single-line comment

/* 
 * Multi-line comment
 */

Schema information

InfluxDB Clustered supports the following metadata schema queries:

SHOW tables

SHOW columns FROM <measurement>

Functions

Following is a list of supported functions by type.

Aggregate functions

An aggregate function performs a calculation or computation on a set of data values in a column and returns a single value.

Examples

SELECT COUNT("water_level") 
FROM "h2o_feet"

SELECT AVG("water_level"), "location"
FROM "h2o_feet" 
GROUP BY "location"

SELECT SUM("water_level"), "location"
FROM "h2o_feet" 
GROUP BY "location"

Selector functions

Selector functions are unique to InfluxDB. They behave like aggregate functions in that they take a row of data and compute it down to a single value. However, selectors are unique in that they return a time value in addition to the computed value. In short, selectors return an aggregated value along with a timestamp.

Examples

SELECT 
SELECTOR_MAX("pH", time)['value'],
SELECTOR_MAX("pH", time)['time']
FROM "h2o_pH"

SELECT 
SELECTOR_LAST("water_level", time)['value'],
SELECTOR_LAST("water_level", time)['time']
FROM "h2o_feet"
WHERE time >= timestamp '2019-09-10T00:00:00Z' AND time <= timestamp '2019-09-19T00:00:00Z'

Date and time functions

Examples

SELECT DATE_BIN(INTERVAL '1 hour', time, '2019-09-18T00:00:00Z') AS "_time",
SUM(water_level)
FROM "h2o_feet"
GROUP BY "_time"

SELECT DATE_TRUNC('month',time) AS "date",
SUM(water_level)
FROM "h2o_feet"
GROUP BY time

Approximate functions

Math functions

Conditional functions

Regular expression functions