用户资源配额
用户资源配额
1. 功能概述
用户资源配额是面向 SQL 用户的资源隔离机制。管理员可以为不同用户分别设置查询和写入资源的保底值或上限，使多个租户或业务线共用集群时仍能保持资源使用的可控性和稳定性。
V2.0.12.1 起支持该功能
1.1 支持的配额资源
用户资源配额可从查询和写入两个方向限制 CPU、内存、临时磁盘及磁盘 I/O 资源。
| 资源 | 含义 | 支持的配额值 |
|---|---|---|
CPU | 并发槽位数，用于限制同时执行的查询或写入任务数量，不表示操作系统层面的 CPU 时间或 CPU 使用率。 | min、max |
MEMORY | 内存预算，按任务的估算内存占用计量，实际使用 Byte 计数。 | min、max |
TEMP_DISK | 用户在查询或写入过程中使用的临时磁盘空间，例如数据溢出、排序中间结果等，实际使用 Byte 计数。 | min、max |
DISK_IO | 磁盘 I/O 速率，使用正整数表示，单位为 Byte/s。例如 104857600 表示 100 MiB/s。当前版本仅支持上限控制。 | max |
READ 表示约束查询侧资源，WRITE 表示约束写入侧资源。TEMP_DISK、DISK_IO 与数据库空间配额 disk 的区别，请参见磁盘相关能力对比。
2. 配置与语法
2.1 配置参数
在 iotdb-system.properties 中设置以下参数：
| 参数 | 默认值 | 说明 | 生效方式 |
|---|---|---|---|
quota_enable | false | 用户资源配额和 THROTTLE QUOTA 的总开关。true 表示启用，false 表示关闭。 | 热加载 |
dn_quota_cpu_slots | max(4, availableProcessors) | 单个 DataNode 的 CPU 配额容量，以并发槽位计。 | 热加载 |
dn_quota_memory_bytes | Runtime.maxMemory() | 单个 DataNode 的内存配额容量，单位为 Byte。 | 热加载 |
dn_quota_temp_disk_bytes | min(100GiB, 数据目录总空间之和 / 10) | 单个 DataNode 的临时磁盘占用配额上限，单位为 Byte。 | 热加载 |
开启用户资源配额：
quota_enable=true显式配置的节点容量会覆盖默认值。配置的生效方式和修改限制以对应版本的 iotdb-system.properties 为准。关闭 quota_enable 后，用户资源配额和 THROTTLE QUOTA 均不参与检查。
2.2 SET USER QUOTA
- 语法定义
SET USER QUOTA ON <userName> WITH
<attribute>=<value> [, <attribute>=<value>]*;- 属性介绍
| 属性 | 含义 | 单位和取值 | 示例 |
|---|---|---|---|
read_cpu_min / read_cpu_max | 查询 CPU 保底值和上限 | 正整数，表示并发槽位数 | 1 / 8 |
write_cpu_min / write_cpu_max | 写入 CPU 保底值和上限 | 同上 | 1 / 4 |
read_memory_min / read_memory_max | 查询内存保底值和上限 | 正整数，单位为 Byte | 2147483648 / 17179869184 |
write_memory_min / write_memory_max | 写入内存保底值和上限 | 同上 | 536870912 / 8589934592 |
read_temp_disk_min / read_temp_disk_max | 查询临时磁盘占用保底值和上限 | 同上 | 1073741824 / 10737418240 |
write_temp_disk_min / write_temp_disk_max | 写入临时磁盘占用保底值和上限 | 同上 | 536870912 / 8589934592 |
read_disk_io_max / write_disk_io_max | 读写磁盘 I/O 速率上限 | 正整数，单位为 Byte/s | 104857600 |
read_disk_io_min / write_disk_io_min | 读写磁盘 I/O 速率，当前版本按上限处理 | 同上 | 104857600 |
注意事项
需要将
quota_enable设置为true。不能对
root设置用户资源配额。同一语句可同时设置 min 与 max。
只覆盖更新本次出现的维度，未提及的资源维度保持原配置。
2.3 SHOW USER QUOTA
- 语法定义
SHOW USER QUOTA [<userName>];指定用户名时，返回该用户的全部配额行；省略用户名时，返回所有已配置用户。
- 返回结果
| 列名 | 含义 |
|---|---|
User | 用户名。 |
NodeID | 当前处于 Running 状态的 DataNode ID。 |
Read/Write | 配额方向，显示 read 或 write。 |
QuotaType | 配额类型，显示 cpu、memory、temp_disk 或 disk_io。 |
Min | 保底值；未设置时为 -。 |
Max | 上限；未设置时为 -。 |
Used | 当前占用；无占用时为 0，disk_io 为 -。 |
MinGap | 保底缺口，计算方式为 max(0, Min - Used)；未设置 min 或 disk_io 时为 -。 |
Min、Max、Used 和 MinGap 均以整数展示，单位由 QuotaType 决定：cpu 为并发槽位数，memory 和 temp_disk 为 Byte，disk_io 为 Byte/s。disk_io 的 Min、Used 和 MinGap 均显示为 -。
2.4 DELETE USER QUOTA
- 语法定义
DELETE USER QUOTA ON <userName>;删除指定用户的全部用户资源配额，包括容量型配额以及映射到速率限流的 DISK_IO 配额。不能对 root 删除配额。
2.5 兼容 THROTTLE QUOTA
- 语法定义
现有 SET/SHOW THROTTLE QUOTA 语法继续可用：
SET THROTTLE QUOTA <attribute>=<value> [, <attribute>=<value>]* ON <userName>;
SHOW THROTTLE QUOTA [<userName>];- 属性介绍
| 属性 | 含义 | 单位和取值 | 示例 |
|---|---|---|---|
request | 单位时间内的请求次数 | 格式为 <正整数>req/<时间单位>，时间单位支持 sec、min、hour、day；中间必须为 req/，不能使用裸 /；含 / 的值须加引号。可配合 type 区分读写；未设置 type 时表示读写合计，SHOW 结果中的 Read/Write 为空。也可取 unlimited | '1000req/sec'、unlimited |
size | 单位时间内的请求流量 | 格式为 <容量>/<时间单位>；容量单位支持 B、K、M、G、T、P，时间单位支持 sec、min、hour、day；含 / 的值须加引号。可配合 type 区分读写。也可取 unlimited | '10M/sec'、unlimited |
type | 请求类型 | 可取 read 或 write，仅影响同一语句中的 request 和 size。type 是 SQL 关键字，因此用作属性名时须加反引号 | `type`=read、`type`=write |
cpu | 查询并发上限（槽位） | 无单位正整数，仅作用于查询侧；表示单值上限，不支持 min。SHOW 结果中的 Read/Write 为 read。也可取 unlimited | 4、unlimited |
mem | 查询内存上限 | 格式为 <正整数><单位>，单位支持 B、K、M、G、T、P，不能写成 GB、MB 等形式；仅作用于查询侧，表示单值上限，不支持 min。SHOW 时统一换算为 M 展示。也可取 unlimited | 8G、512M、unlimited；8G 在 SHOW 中显示为 8192M |
- SHOW 结果列
| 列名 | 含义 |
|---|---|
User | 用户名。 |
QuotaType | 限流类型，可取 request、size、cpu 或 mem。 |
Limit | 限流值。request 显示请求速率，如 1000req/sec；size 显示流量速率，如 10M/sec；cpu 显示查询并发槽位数；mem 统一换算为 M 展示，如 8G 显示为 8192M。 |
Read/Write | 限流作用的请求类型，显示 read、write 或空值。request 和 size 未指定 type 时表示读写合计，此列为空；指定 type 时显示相应类型。cpu 和 mem 仅作用于查询侧，因此固定显示 read。 |
- 映射关系
THROTTLE QUOTA 属性 | 用户资源配额语义 |
|---|---|
cpu=4 | read_cpu_max=4 |
mem=8G | read_memory_max=8589934592 |
request/size（可带 `type`=read/write） | 继续作为速率限流保留 |
使用 SET USER QUOTA 更新其他资源维度时，已有的 THROTTLE QUOTA 配置会保留。升级或重启后，旧配额配置可迁移。
3. 生效规则
- 配额检查与资源释放
| 任务类型 | 配额检查 | 资源释放 |
|---|---|---|
| 查询任务 | 检查查询侧的 CPU 和内存配额。产生数据溢出、排序中间结果等临时文件时，还会检查查询侧的临时磁盘配额。 | 任务结束、取消或超时后，释放已经占用的查询资源。 |
| 写入任务 | 检查写入侧的 CPU 和内存配额。产生临时文件时，还会检查写入侧的临时磁盘配额。涉及磁盘 I/O 时，按照对应的磁盘 I/O 速率配额进行限流。 | 任务结束后，释放已经占用的容量型资源。 |
上限控制与配额更新
max是资源硬上限。请求超过用户上限或 DataNode 可用容量时，系统可能短暂等待资源；等待后仍无法取得资源时，请求执行失败。新请求按照当前配额进行检查；正在运行的请求按照请求开始时的配额处理。
可以将
max调整为低于当前资源使用量的值。调整后，系统不会强制终止已有任务或立即释放资源，但会限制新的资源申请，直至Used下降到新的max以下。
保底调度
CPU、内存和临时磁盘支持
min调度。DataNode 资源紧张时，系统优先调度尚未达到min的用户。min表示调度保底额度，不表示系统会为用户预先独占或预留资源，也不保证用户始终能够获得对应额度。未配置配额或将配额设置为
unlimited，仅表示不设置用户级硬上限。该用户仍受 DataNode 可用容量及MinGap调度约束，其资源占用也会计入当前使用量。
生效范围
用户资源配额由各 DataNode 独立计数和执行，不进行跨节点的全局计数或仲裁。
SHOW USER QUOTA按 DataNode 展示配额和使用量。NodeID为当前处于Running状态的 DataNode ID，失联节点不展示。临时磁盘的节点级容量上限由
dn_quota_temp_disk_bytes控制。当
quota_enable=false时，系统不执行用户资源配额及THROTTLE QUOTA检查。root用户不受用户资源配额约束，也不能作为SET USER QUOTA或DELETE USER QUOTA的操作对象。
4. 权限说明
SET/SHOW/DELETE USER QUOTA和SET/SHOW THROTTLE QUOTA属于系统运维类操作。root用户或具有SYSTEM权限的管理员可以执行配额管理语句；三权分立开启后，由系统管理员负责配额配置和查看。被配额约束的业务用户无需额外权限即可读写数据，超过配额时操作失败。
开启审计后，权限检查记录
OBJECT_AUTHENTICATION事件及用户名、用户 ID、客户端地址cli_hostname、操作类型CONTROL、权限类型和鉴权结果。配额申请失败、配置更新和资源超限会记录系统日志或返回包含资源类型和拒绝原因的信息；开启全局 SQL 审计后还会记录相关 SQL 及执行结果。
5. 使用示例
前置条件：已按配置参数启用用户资源配额。以下示例可独立执行。
- 示例1：限制查询并发
CREATE USER report_user 'RpaSwORD@2342';
SET USER QUOTA ON report_user WITH read_cpu_max=2;
SHOW USER QUOTA report_user;SHOW 结果
+-------------+--------+------------+-----------+-----+-----+------+--------+
|User |NodeID |Read/Write |QuotaType |Min |Max |Used |MinGap |
+-------------+--------+------------+-----------+-----+-----+------+--------+
|report_user |1 |read |cpu |- |2 |0 |- |
+-------------+--------+------------+-----------+-----+-----+------+--------+- 示例2：设置查询保底和上限
CREATE USER core_user 'CpaSwORD@2342';
SET USER QUOTA ON core_user WITH read_cpu_min=1, read_cpu_max=4;
SHOW USER QUOTA core_user;SHOW 结果
+---------+------+----------+---------+---+---+----+------+
| User|NodeID|Read/Write|QuotaType|Min|Max|Used|MinGap|
+---------+------+----------+---------+---+---+----+------+
|core_user| 1| read| cpu| 1| 4| 0| 1|
+---------+------+----------+---------+---+---+----+------+- 示例3：设置写入内存和磁盘 I/O
CREATE USER ingest_user 'IpaSwORD@2342';
SET USER QUOTA ON ingest_user WITH
write_memory_max=1073741824,
write_disk_io_max=10485760;
SHOW USER QUOTA ingest_user;
SHOW THROTTLE QUOTA ingest_user;SHOW 结果
-- SHOW USER QUOTA ingest_user
+-----------+------+----------+---------+---+----------+----+------+
| User|NodeID|Read/Write|QuotaType|Min| Max|Used|MinGap|
+-----------+------+----------+---------+---+----------+----+------+
|ingest_user| 1| write| memory| -|1073741824| 0| -|
|ingest_user| 1| write| disk_io| -| 10485760| -| -|
+-----------+------+----------+---------+---+----------+----+------+
-- SHOW THROTTLE QUOTA ingest_user
+-----------+---------+-------+----------+
| User|QuotaType| Limit|Read/Write|
+-----------+---------+-------+----------+
|ingest_user| size|10M\sec| write|
+-----------+---------+-------+----------+- 示例4：设置临时磁盘占用
CREATE USER spill_user 'SpaSwORD@2342';
SET USER QUOTA ON spill_user WITH
read_temp_disk_min=1073741824,
read_temp_disk_max=17179869184,
write_temp_disk_max=8589934592;
SHOW USER QUOTA spill_user;SHOW 结果
+----------+------+----------+---------+----------+-----------+----+----------+
| User|NodeID|Read/Write|QuotaType| Min| Max|Used| MinGap|
+----------+------+----------+---------+----------+-----------+----+----------+
|spill_user| 1| read|temp_disk|1073741824|17179869184| 0|1073741824|
|spill_user| 1| write|temp_disk| -| 8589934592| 0| -|
+----------+------+----------+---------+----------+-----------+----+----------+- 示例5：兼容 THROTTLE QUOTA
CREATE USER doc_mix 'DpaSwORD@2342';
SET THROTTLE QUOTA cpu=4 ON doc_mix;
SET USER QUOTA ON doc_mix WITH write_cpu_max=2;
SHOW USER QUOTA doc_mix;
SHOW THROTTLE QUOTA doc_mix;SHOW 结果
-- SHOW USER QUOTA doc_mix
+-------+------+----------+---------+---+---+----+------+
| User|NodeID|Read/Write|QuotaType|Min|Max|Used|MinGap|
+-------+------+----------+---------+---+---+----+------+
|doc_mix| 1| read| cpu| -| 4| 0| -|
|doc_mix| 1| write| cpu| -| 2| 0| -|
+-------+------+----------+---------+---+---+----+------+
--SHOW THROTTLE QUOTA doc_mix
+-------+---------+-----+----------+
| User|QuotaType|Limit|Read/Write|
+-------+---------+-----+----------+
|doc_mix| cpu| 4| read|
+-------+---------+-----+----------+- 示例6：删除配额
DELETE USER QUOTA ON spill_user;
SHOW USER QUOTA spill_user;SHOW 结果
+----+------+----------+---------+---+---+----+------+
|User|NodeID|Read/Write|QuotaType|Min|Max|Used|MinGap|
+----+------+----------+---------+---+---+----+------+
+----+------+----------+---------+---+---+----+------+6. 常见问题
6.1 磁盘相关能力对比
用户资源配额中的 DISK_IO 和 TEMP_DISK 与数据库级空间配额 disk 分别解决不同的问题，不应混用。
| 能力 | 作用粒度 | 资源类型 | 用途 | 典型 SQL |
|---|---|---|---|---|
数据库空间配额 disk | database | 持久化磁盘容量 | 限制数据库持久化数据的落盘空间。在创建元数据或向 DataRegion 写入数据前进行检查。 | SET SPACE QUOTA disk=... ON root.db |
用户配额 DISK_IO | user | 磁盘 I/O 速率 | 限制指定用户在查询或写入过程中的磁盘 I/O 速率。当前版本仅支持上限语义。 | SET USER QUOTA ON username WITH write_disk_io_max=52428800; |
用户配额 TEMP_DISK | user | 临时磁盘容量 | 限制指定用户在查询或写入过程中占用的临时磁盘空间，例如数据溢出和排序中间结果。支持 min 和 max。 | SET USER QUOTA ON username WITH write_temp_disk_max=8589934592; |
6.2 常见问题处理
| 问题 | 处理建议 |
|---|---|
提示 Limit configuration is not enabled | 检查 quota_enable 是否为 true，并按照配置参数手册要求使配置生效。 |
提示 User resource quota exceeded | 根据错误信息确认超限的资源类型，并通过 SHOW USER QUOTA <userName> 查看对应 DataNode 上的 Max 和 Used。必要时调整用户上限或节点容量。 |
配置后 SHOW USER QUOTA 没有配额行 | 确认 SET USER QUOTA 已成功执行、用户名正确、quota_enable 未关闭，且 DataNode 处于 Running 状态。 |
Used 或 MinGap 与预期不一致 | 用户资源配额按 DataNode 分别统计，请结合 NodeID 逐节点查看。disk_io 的 Used 和 MinGap 固定显示为 -。 |
设置或删除 root 配额时提示 extraneous input 'root' 或操作失败 | root 用户默认豁免用户资源配额，不能通过 SET USER QUOTA 设置，也不能通过 DELETE USER QUOTA 删除。 |