文档文档

InfluxDB 3 Core

SQL 参考文档

InfluxDB 3 Core 使用 Apache Arrow DataFusion 的 SQL 实现。

标识符

标识符是一个令牌，它引用 InfluxDB 数据库对象的名称，例如测量或列名（时间、标签键或字段键）。

引号

在 标识符 上使用双引号以将其视为区分大小写。在字符串字面量上使用单引号。

通用引号准则

  • 单引号引用 RFC3339 和类 RFC3339 时间值。
  • 不要引号引用 Unix 纪元时间值（转换为时间戳的整数）。
  • 双引号引用混合大小写、驼峰式命名或区分大小写的标识符。
  • 双引号引用包含特殊字符或空格字符的标识符。
引号示例
-- 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"

注意： 我们建议始终使用双引号引用标识符，无论是否区分大小写。

未加引号的标识符不区分大小写，并且匹配任何具有相同字符的测量、标签键或字段键，无论大小写如何。例如，如果您在名为 ph 和 pH 的测量中有两个字段，则未加引号的标识符 pH 将同时匹配两者。要以区分大小写的方式查询，请使用双引号引用标识符。

字面量

字面量是一个显式值，不通过标识符表示。

字符串字面量

字符串字面量用单引号括起来。

'santa_monica'
'pH'
'average temperature'

数值字面量

数字字面量是正数或负数，可以是精确数字或浮点数。

-- Integers
10
+10
-10

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

-- Floats
10.78654
-100.56

日期和时间字面量

支持以下日期和时间字面量

'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)

布尔字面量

布尔字面量为 TRUE 或 FALSE。

持续时间单位

间隔字面量指定时间的长度或单位。

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

支持以下时间单位

  • 纳秒
  • 微秒
  • 毫秒
  • 秒
  • 分钟
  • 小时
  • 天
  • 周
  • 月
  • 年
  • 世纪

运算符

运算符是执行特定操作（包括比较和算术运算）的保留字或字符。

算术运算符

算术运算符接受两个数值（字面量或变量），并执行返回单个数值的计算。

运算符描述示例结果
+加法2 + 24
-减法4 - 22
*乘法2 * 36
/除法6 / 32
%取模7 % 21

比较运算符

比较运算符评估左右操作数之间的关系，并返回 TRUE 或 FALSE。

运算符含义示例
=等于123 = 123
<>不等于123 <> 456
!=不等于123 != 456
>大于3 > 2
>=大于或等于3 >= 2
<小于1 < 2
<=小于或等于1 <= 2
~匹配正则表达式'abc' ~ 'a.*'
~\*匹配正则表达式（不区分大小写）'Abc' ~\* 'A.*'
!~不匹配正则表达式'abc' !~ 'd.*'
!~\*不匹配正则表达式（不区分大小写）'Abc' !~\* 'a.*'

逻辑运算符

运算符含义
AND如果两个操作数都为 true，则返回 true。否则，返回 false。
BETWEEN如果左操作数在右操作数的范围内，则返回 true。
EXISTS如果操作数不为 null，则返回 true。
IN如果左操作数在右操作数列表中，则返回 true。
LIKE如果左操作数与右操作数模式字符串匹配，则返回 true。
NOT否定后续表达式。
OR如果任何操作数为 true，则返回 true。否则，返回 false。

位运算符

位运算符对位模式或二进制数字执行位运算。

运算符含义示例结果
&按位与5 & 31
|按位或5 | 37
^按位异或5 ^ 36
>>按位右移5 >> 30
<<按位左移5 << 340

其他运算符

运算符含义示例结果
||连接字符串'Hello' || ' world'Hello world
AT TIME ZONE应用时区偏移查看示例

关键字

以下保留关键字不能用作标识符。

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

条件表达式

条件表达式基于输入值评估条件。支持以下条件表达式

表达式描述
CASE允许使用 WHEN-THEN-ELSE 语句。
COALESCE返回指定列表中第一个非 NULL 表达式。
NULLIF如果 value1 = value2，则返回 NULL 值。否则返回 value1。

语句和子句

InfluxDB SQL 支持以下基本查询语法

[ 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 语句和 FROM 子句

使用 SQL SELECT 语句从特定测量或多个测量中查询数据。 FROM 子句始终伴随 SELECT 语句。

示例

SELECT * FROM "h2o_feet"

WHERE 子句

使用 WHERE 子句根据 字段、标签 和 时间戳 过滤结果。使用谓词评估每一行。评估结果为 TRUE 的行将返回在结果集中。评估结果为 FALSE 的行将从结果集中省略。

示例

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

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

JOIN 子句

使用 JOIN 子句连接来自多个测量（表）的数据。有关连接的更多信息，请参阅 JOIN 子句。支持以下连接类型

INNER JOIN

LEFT [OUTER] JOIN

RIGHT [OUTER] JOIN

FULL [OUTER] JOIN

INNER JOIN

LEFT [OUTER] JOIN

RIGHT [OUTER] JOIN

FULL [OUTER] JOIN

GROUP BY 子句

使用 GROUP BY 子句根据指定的列值对查询结果进行分组。 GROUP BY 需要 SELECT 语句中的聚合函数或选择器函数。

示例

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

HAVING 子句

使用 HAVING 子句根据指定的条件过滤查询结果。 HAVING 子句必须位于 GROUP BY 子句之后，但位于 ORDER BY 子句之前。

示例

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

UNION 子句

UNION 子句组合两个或多个 SELECT 语句的结果，而不返回任何重复行。 UNION ALL 返回所有结果，包括重复项。

示例

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

ORDER BY 子句

ORDER BY 子句按指定的列和顺序对结果进行排序。根据字段、标签和时间戳对数据进行排序。支持以下顺序

  • ASC：升序（默认）
  • DESC：降序

示例

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

LIMIT 子句

LIMIT 子句限制要返回的行数。定义的限制应为非负整数。

示例

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

WITH 子句

WITH 子句提供了一种编写辅助语句以供较大查询使用的方法。它可以帮助将大型复杂的查询分解为更简单的形式。

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

OVER 子句

OVER 子句与 SQL 窗口函数一起使用。窗口函数对一组与当前行以某种方式相关的表行执行计算。虽然与聚合函数类似，但窗口函数将结果输出到行中，同时保留其单独的标识。

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;

注释

使用注释来描述查询并添加详细信息或注释。

  • 单行注释使用双连字符 -- 符号。单行注释以换行符结尾。
  • 多行注释以 /* 开头，以 */ 结尾。
-- Single-line comment

/* 
 * Multi-line comment
 */

模式信息

InfluxDB 3 Core 支持以下元数据模式查询

SHOW tables

SHOW columns FROM <measurement>

函数

以下是按类型列出的支持函数。

聚合函数

聚合函数对列中的一组数据值执行计算或运算，并返回单个值。

函数描述
COUNT()返回字段或标签键的行数
AVG()返回列的平均值
SUM()返回列的总和值
MEAN()返回列的平均值
MIN()返回所选列的最小值
MAX()返回所选列的最大值

示例


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"

窗口聚合函数

窗口函数允许您计算运行总计、移动平均值或其他类似聚合的结果，而无需将行折叠成组（与非窗口聚合函数不同）。

窗口聚合函数包括所有聚合函数和排名函数。SQL OVER 子句在语法上区分窗口
函数与非窗口函数或聚合函数，并定义如何对窗口操作的行进行分组和排序。

示例

SELECT
  time,
  room,
  temp,
  avg(temp) OVER (PARTITION BY room) AS avg_room_temp
FROM
  home
WHERE
  time >= '2022-01-01T08:00:00Z'
  AND time <= '2022-01-01T09:00:00Z'
ORDER BY
  room,
  time
时间房间温度平均房间温度
2022-01-01T08:00:00厨房21.022.0
2022-01-01T09:00:00厨房23.022.0
2022-01-01T08:00:00客厅21.121.25
2022-01-01T09:00:00客厅21.421.25

排名函数

函数描述
CUME_DIST()返回一组值中值的累积分布
DENSE_RANK()返回每行的排名，编号中没有间隙
NTILE()将有序分区中的行分配到指定数量的组中
PERCENT_RANK()返回当前行在其分区中的百分比排名
RANK()返回当前行在其分区中的排名，允许排名之间存在间隙
ROW_NUMBER()返回当前行在其分区中的位置

选择器函数

选择器函数是 InfluxDB 独有的。它们的行为类似于聚合函数，因为它们接受一行数据并将其计算为一个值。但是，选择器的独特之处在于，除了计算值之外，它们还返回时间值。简而言之，选择器返回聚合值以及时间戳。

函数描述
SELECTOR_FIRST()返回所选列的第一个值和时间戳。
SELECTOR_LAST()返回所选列的最后一个值和时间戳。
SELECTOR_MIN()返回所选列的最小值和时间戳。
SELECTOR_MAX()返回所选列的最大值和时间戳。

示例

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_BIN()将输入时间戳分箱到指定的时间间隔。
DATE_TRUNC()根据指定的日期部分（例如小时、天或月）截断时间戳表达式。
DATE_PART()返回日期的指定部分。
NOW()返回当前时间 (UTC)。

示例

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

近似函数

函数描述
APPROX_MEDIAN返回输入值的近似中位数。
APPROX_DISTINCT返回不同值数量的近似计数。仅针对字符串实现。
APPROX_PERCENTILE_CONT返回输入值的近似百分位数。
APPROX_PERCENTILE_CONT_WITH_WEIGHT返回带权重的输入值的近似百分位数。

数学函数

函数描述
ABS()绝对值
ACOS()反余弦
ASIN()反正弦
ATAN()反正切
ATAN2()y / x 的反正切
CEIL()返回大于或等于指定数字的最小整数值
COS()余弦
EXP()指数
FLOOR()最接近且小于或等于指定数字的整数
LN()自然对数
LOG10()以 10 为底的对数
LOG2()以 2 为底的对数
POWER()返回数字的幂值
ROUND()四舍五入到最接近的整数
SIGNUM()参数的符号 (-1, 0, +1)
SINE()正弦
SQRT()返回数字的平方根
TAN()正切
TRUNC()将数字截断为指定的小数位数

条件函数

函数描述
COALESCE返回第一个非 null 参数。如果所有参数都为 null，则 COALESCE 将返回 null。
NULLIF如果 value1 等于 value2，则返回 null 值，否则返回 value1。

正则表达式函数

函数描述
REGEXP_MATCH将正则表达式与字符串匹配，并返回匹配的子字符串。
REGEXP_REPLACE用新的子字符串替换与正则表达式匹配的子字符串。

    此页是否对您有帮助？

    感谢您的反馈！

    © 2025 InfluxData, Inc.

    您的 InfluxDB 3 Core URL 是什么？

    自定义您的 InfluxDB 3 Core URL，我们将为您更新代码示例。

    默认
    自定义

    有关更多信息，请参阅InfluxDB Cloud 区域或InfluxDB OSS URL。

    感谢您的反馈！

    请告诉我们如何做得更好

    谢谢！

    不用了，谢谢

    选择新日期

    在数据库的保留期内选择一个日期。

    更新

    Flux 的未来

    Flux 即将进入维护模式。您可以继续像现在一样使用它，而无需对代码进行任何更改。

    阅读更多

    现已全面上市

    InfluxDB 3 Core 和 Enterprise

    快速启动。更快扩展。

    获取更新

    InfluxDB 3 Core 是一个开源、高速、近实时数据引擎，可实时收集和处理数据，并将其持久化到本地磁盘或对象存储。InfluxDB 3 Enterprise 构建在 Core 的基础上，增加了高可用性、读取副本、增强的安全性以及数据压缩，从而实现更快的查询和优化的存储。InfluxDB 3 Enterprise 的免费层可供非商业家用或业余爱好者使用。

    有关更多信息，请查看