文档文档

InfluxDB 3 Core

SQL 参考文档

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

标识符

标识符是引用 InfluxDB 数据库对象名称的令牌，例如 **measurement** 或列名（**time**、**tag keys** 或 **field keys**）。

引用

在 标识符 上使用双引号可将其视为大小写敏感。在字符串字面量上使用单引号。

通用引用指南

  • 单引号引用 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"

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

未加引号的标识符不区分大小写，并且会匹配任何具有相同字符（不区分大小写）的 measurement、tag key 或 field key。例如，如果您在一个名为 ph 和 pH 的 measurement 中有两个字段，则未加引号的标识符 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当两个操作数都为真时返回真。否则返回假。
BETWEEN当左操作数在右操作数的范围内时返回真。
EXISTS当操作数不为 null 时返回真。
IN当左操作数在右操作数列表中时返回真。
LIKE当左操作数匹配右操作数模式字符串时返回真。
NOT否定后续表达式。
OR当任何一个操作数为真时返回真。否则返回假。

位运算符

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

运算符含义示例结果
&按位与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 语句从特定 measurement 或多个 measurement 查询数据。FROM 子句始终伴随 SELECT 语句。

示例

SELECT * FROM "h2o_feet"

WHERE 子句

使用 WHERE 子句根据 fields、tags 和 timestamps 过滤结果。使用谓词评估每一行。求值为 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 子句连接来自多个 measurement（表）的数据。有关 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
timeroomtempavg_room_temp
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。

    感谢您的反馈！

    让我们知道我们可以做得更好

    谢谢！

    不用了，谢谢

    选择新日期

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

    更新

    InfluxDB 3.8 新特性

    InfluxDB 3.8 和 InfluxDB 3 Explorer 1.6 的主要增强功能。

    查看博客文章

    InfluxDB 3.8 现已适用于 Core 和 Enterprise 版本，同时发布了 InfluxDB 3 Explorer UI 的 1.6 版本。本次发布着重于操作成熟度，以及如何更轻松地部署、管理和可靠地运行 InfluxDB。

    更多信息，请查看

    InfluxDB Docker 的 latest 标签将指向 InfluxDB 3 Core

    在 **2026 年 2 月 3 日**，InfluxDB Docker 镜像的 latest 标签将指向 InfluxDB 3 Core。为避免意外升级，请在您的 Docker 部署中使用特定的版本标签。

    如果使用 Docker 来安装和运行 InfluxDB，latest 标签将指向 InfluxDB 3 Core。为避免意外升级，请在您的 Docker 部署中使用特定的版本标签。例如，如果使用 Docker 运行 InfluxDB v2，请将 latest 版本标签替换为 Docker pull 命令中的特定版本标签 — 例如

    docker pull influxdb:2