User Resource Quotas

About 8 min

User Resource Quotas

1. Overview

User resource quotas provide resource isolation for SQL users. Administrators can configure separate minimum guarantees or upper limits for each user's query and write resources to keep resource usage controlled and stable when multiple tenants or business workloads share a cluster.

This feature is available from V2.0.12.1.

1.1 Supported Resources

User resource quotas can limit CPU, memory, temporary disk space, and disk I/O resources separately for queries and writes.

Resource	Meaning	Supported quota values
`CPU`	The number of concurrency slots, limiting the number of queries or write tasks that can run simultaneously. This does not represent operating system CPU time or CPU utilization.	`min`, `max`
`MEMORY`	Memory budget, measured by estimated task memory usage and counted in bytes.	`min`, `max`
`TEMP_DISK`	Temporary disk space used during queries or writes, such as spilled data and intermediate sorting results, counted in bytes.	`min`, `max`
`DISK_IO`	Disk I/O rate, expressed as a positive integer in bytes/s. For example, 104857600 represents 100 MiB/s. The current version supports upper limits only.	`max`

READ constrains query resources, while WRITE constrains write resources. For the differences between TEMP_DISK, DISK_IO, and the database space quota disk, see Comparison of Disk-Related Features.

2. Configuration and Syntax

2.1 Configuration Parameters

Set the following parameters in iotdb-system.properties:

Parameter	Default	Description	Effective after
`quota_enable`	`false`	Master switch for user resource quotas and `THROTTLE QUOTA`. `true` enables them; `false` disables them.	Hot reload
`dn_quota_cpu_slots`	`max(4, availableProcessors)`	CPU quota capacity of a single DataNode, measured in concurrency slots.	Hot reload
`dn_quota_memory_bytes`	`Runtime.maxMemory()`	Memory quota capacity of a single DataNode, in bytes.	Hot reload
`dn_quota_temp_disk_bytes`	`min(100GiB, sum of total data directory space / 10)`	Node-level upper limit for temporary disk space usage on a single DataNode, in bytes.	Hot reload

Enable user resource quotas:

quota_enable=true

Explicitly configured node capacities override the defaults. Refer to iotdb-system.properties for the corresponding version for how changes take effect and any modification restrictions. When quota_enable is disabled, neither user resource quotas nor THROTTLE QUOTA checks are performed.

2.2 SET USER QUOTA

Syntax

SET USER QUOTA ON <userName> WITH
  <attribute>=<value> [, <attribute>=<value>]*;

Attributes

Attribute	Meaning	Unit and values	Example
`read_cpu_min` / `read_cpu_max`	Minimum guarantee and upper limit for query CPU	Positive integer representing concurrency slots	`1` / `8`
`write_cpu_min` / `write_cpu_max`	Minimum guarantee and upper limit for write CPU	Same as above	`1` / `4`
`read_memory_min` / `read_memory_max`	Minimum guarantee and upper limit for query memory	Positive integer in bytes	`2147483648` / `17179869184`
`write_memory_min` / `write_memory_max`	Minimum guarantee and upper limit for write memory	Same as above	`536870912` / `8589934592`
`read_temp_disk_min` / `read_temp_disk_max`	Minimum guarantee and upper limit for query temporary disk space usage	Same as above	`1073741824` / `10737418240`
`write_temp_disk_min` / `write_temp_disk_max`	Minimum guarantee and upper limit for write temporary disk space usage	Same as above	`536870912` / `8589934592`
`read_disk_io_max` / `write_disk_io_max`	Upper limit for read/write disk I/O rate	Positive integer in bytes/s	`104857600`
`read_disk_io_min` / `write_disk_io_min`	Read/write disk I/O rate, treated as an upper limit in the current version	Same as above	`104857600`

Notes
- quota_enable must be set to true.
- User resource quotas cannot be configured for root.
- Both min and max can be set in the same statement.
- Only the resource dimensions included in the statement are updated; other dimensions retain their existing settings.

2.3 SHOW USER QUOTA

Syntax

SHOW USER QUOTA [<userName>];

When a username is specified, all quota rows for that user are returned. When the username is omitted, all users with configured quotas are returned.

Result Columns

Column	Meaning
`User`	Username.
`NodeID`	ID of a DataNode currently in the `Running` state.
`Read/Write`	Quota direction: `read` or `write`.
`QuotaType`	Quota type: `cpu`, `memory`, `temp_disk`, or `disk_io`.
`Min`	Minimum guarantee; `-` if not set.
`Max`	Upper limit; `-` if not set.
`Used`	Current usage; `0` if unused, or `-` for `disk_io`.
`MinGap`	Gap to the minimum guarantee, calculated as `max(0, Min - Used)`; `-` if `min` is not set or for `disk_io`.

Min, Max, Used, and MinGap are displayed as integers. Their units depend on QuotaType: concurrency slots for cpu, bytes for memory and temp_disk, and bytes/s for disk_io. For disk_io, Min, Used, and MinGap are all displayed as -.

2.4 DELETE USER QUOTA

Syntax

DELETE USER QUOTA ON <userName>;

Delete all user resource quotas for the specified user, including capacity quotas and DISK_IO quotas mapped to rate limits. Quotas cannot be deleted for root.

2.5 THROTTLE QUOTA Compatibility

Syntax

The existing SET/SHOW THROTTLE QUOTA syntax remains available:

SET THROTTLE QUOTA <attribute>=<value> [, <attribute>=<value>]* ON <userName>;
SHOW THROTTLE QUOTA [<userName>];

Attributes

Attribute	Meaning	Unit and values	Example
`request`	Number of requests per unit of time	Format: `<positive integer>req/<time unit>`. Supported time units: `sec`, `min`, `hour`, `day`. The separator must be `req/`, not a bare `/`. Values containing `/` must be quoted. Use `type` to distinguish reads from writes; without `type`, the limit applies to reads and writes combined, and `Read/Write` is empty in `SHOW` results. Also accepts `unlimited`.	`'1000req/sec'`, `unlimited`
`size`	Request traffic per unit of time	Format: `<size>/<time unit>`. Supported size units: `B`, `K`, `M`, `G`, `T`, `P`. Supported time units: `sec`, `min`, `hour`, `day`. Values containing `/` must be quoted. Use `type` to distinguish reads from writes. Also accepts `unlimited`.	`'10M/sec'`, `unlimited`
`type`	Request type	`read` or `write`. Affects only `request` and `size` in the same statement. Since `type` is an SQL keyword, enclose it in backticks when used as an attribute name.	`type`=read, `type`=write
`cpu`	Query concurrency upper limit (slots)	Positive integer without a unit. Applies only to queries and represents a single upper limit; `min` is not supported. `Read/Write` is `read` in `SHOW` results. Also accepts `unlimited`.	`4`, `unlimited`
`mem`	Query memory upper limit	Format: `<positive integer><unit>`. Supported units: `B`, `K`, `M`, `G`, `T`, `P`; forms such as `GB` and `MB` are not accepted. Applies only to queries and represents a single upper limit; `min` is not supported. `SHOW` converts values to `M`. Also accepts `unlimited`.	`8G`, `512M`, `unlimited`; `8G` is displayed as `8192M` in `SHOW` results.

SHOW Result Columns

Column	Meaning
`User`	Username.
`QuotaType`	Throttle type: `request`, `size`, `cpu`, or `mem`.
`Limit`	Throttle limit. `request` shows the request rate, such as `1000req/sec`; `size` shows the traffic rate, such as `10M/sec`; `cpu` shows query concurrency slots; `mem` is converted to `M`, for example `8G` is displayed as `8192M`.
`Read/Write`	Request type affected by the limit: `read`, `write`, or empty. For `request` and `size`, omitting `type` means reads and writes combined, so this column is empty; specifying `type` shows the corresponding type. `cpu` and `mem` apply only to queries, so this column is always `read`.

Mapping

`THROTTLE QUOTA` attribute	User resource quota semantics
`cpu=4`	`read_cpu_max=4`
`mem=8G`	`read_memory_max=8589934592`
`request`/`size` (optionally with `type`=read/write)	Retained as rate limits

Existing THROTTLE QUOTA settings are preserved when SET USER QUOTA updates other resource dimensions. Legacy quota configurations can be migrated after an upgrade or restart.

3. Enforcement Rules

Quota Checks and Resource Release

Task type	Quota checks	Resource release
Query	Checks query CPU and memory quotas. When temporary files such as spilled data or intermediate sorting results are generated, the query temporary disk quota is also checked.	Allocated query resources are released when the task completes, is canceled, or times out.
Write	Checks write CPU and memory quotas. The write temporary disk quota is also checked when temporary files are generated. Disk I/O is throttled according to the corresponding disk I/O rate quota.	Allocated capacity resources are released when the task completes.

Upper Limits and Quota Updates
- max is a hard resource limit. If a request exceeds the user's upper limit or the DataNode's available capacity, the system may wait briefly for resources. The request fails if resources remain unavailable after waiting.
- New requests are checked against the current quota; running requests use the quota in effect when they started.
- max can be reduced below current resource usage. This does not forcibly terminate existing tasks or immediately release resources. New resource allocations are restricted until Used falls below the new max.
Minimum Guarantee Scheduling
- CPU, memory, and temporary disk space support min scheduling. When DataNode resources are constrained, users whose usage has not reached min receive scheduling priority.
- min is a scheduling guarantee. It does not exclusively allocate or reserve resources in advance, nor does it ensure that the user can always obtain that amount.
- Leaving quotas unconfigured or setting them to unlimited only removes the user-level hard limit. The user remains subject to available DataNode capacity and MinGap scheduling, and their resource consumption is still counted in current usage.
Scope
- Each DataNode independently accounts for and enforces user resource quotas. There is no global accounting or arbitration across nodes.
- SHOW USER QUOTA displays quotas and usage by DataNode. NodeID identifies a DataNode currently in the Running state; unreachable nodes are omitted.
- The node-level capacity limit for temporary disk space is controlled by dn_quota_temp_disk_bytes.
- When quota_enable=false, neither user resource quota checks nor THROTTLE QUOTA checks are performed.
- The root user is exempt from user resource quotas and cannot be the target of SET USER QUOTA or DELETE USER QUOTA.

4. Privileges

SET/SHOW/DELETE USER QUOTA and SET/SHOW THROTTLE QUOTA are system operations and maintenance commands.
The root user or administrators with the SYSTEM privilege can execute quota management statements. When Separation of Powers is enabled, the system administrator configures and views quotas.
Business users subject to quotas do not need additional privileges to read or write data. Operations fail when quotas are exceeded.
When auditing is enabled, privilege checks record OBJECT_AUTHENTICATION events, including the username, user ID, client address cli_hostname, operation type CONTROL, privilege type, and authorization result.
Failed quota allocations, configuration updates, and resource limit violations are recorded in system logs or returned in messages containing the resource type and reason for rejection. When global SQL auditing is enabled, the relevant SQL statements and execution results are also recorded.

5. Examples

Prerequisite: Enable user resource quotas as described in Configuration Parameters. Each example can be executed independently.

Example 1: Limit Query Concurrency

CREATE USER report_user 'RpaSwORD@2342';
SET USER QUOTA ON report_user WITH read_cpu_max=2;
SHOW USER QUOTA report_user;

SHOW results:

+-------------+--------+------------+-----------+-----+-----+------+--------+
|User         |NodeID  |Read/Write  |QuotaType  |Min  |Max  |Used  |MinGap  |
+-------------+--------+------------+-----------+-----+-----+------+--------+
|report_user  |1       |read        |cpu        |-    |2    |0     |-       |
+-------------+--------+------------+-----------+-----+-----+------+--------+

Example 2: Set Query Minimum Guarantees and Upper Limits

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 results:

+---------+------+----------+---------+---+---+----+------+
|     User|NodeID|Read/Write|QuotaType|Min|Max|Used|MinGap|
+---------+------+----------+---------+---+---+----+------+
|core_user|     1|      read|      cpu|  1|  4|   0|     1|
+---------+------+----------+---------+---+---+----+------+

Example 3: Configure Write Memory and Disk 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 results:

-- 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|
+-----------+---------+-------+----------+

Example 4: Configure Temporary Disk Space Usage

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 results:

+----------+------+----------+---------+----------+-----------+----+----------+
|      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|         -|
+----------+------+----------+---------+----------+-----------+----+----------+

Example 5: THROTTLE QUOTA Compatibility

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 results:

-- 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|
+-------+---------+-----+----------+

Example 6: Delete Quotas

DELETE USER QUOTA ON spill_user;
SHOW USER QUOTA spill_user;

SHOW results:

+----+------+----------+---------+---+---+----+------+
|User|NodeID|Read/Write|QuotaType|Min|Max|Used|MinGap|
+----+------+----------+---------+---+---+----+------+
+----+------+----------+---------+---+---+----+------+

6. FAQ

User resource quotas DISK_IO and TEMP_DISK address different requirements from the database-level space quota disk and should not be used interchangeably.

Feature	Scope	Resource type	Purpose	Typical SQL
Database space quota `disk`	database	Persistent disk capacity	Limit the disk space used by persistent database data. Checked before creating metadata or writing data to a DataRegion.	`SET SPACE QUOTA disk=... ON root.db`
User quota `DISK_IO`	user	Disk I/O rate	Limit a specified user's disk I/O rate during queries or writes. The current version supports upper limits only.	`SET USER QUOTA ON username WITH write_disk_io_max=52428800;`
User quota `TEMP_DISK`	user	Temporary disk capacity	Limit temporary disk space used by a specified user during queries or writes, such as spilled data and intermediate sorting results. Supports `min` and `max`.	`SET USER QUOTA ON username WITH write_temp_disk_max=8589934592;`

6.2 Troubleshooting

Issue	Recommended action
`Limit configuration is not enabled`	Check that `quota_enable` is `true` and apply the change as described in the Configuration Parameters manual.
`User resource quota exceeded`	Identify the resource type from the error message and use `SHOW USER QUOTA <userName>` to check `Max` and `Used` on the corresponding DataNode. Adjust the user's upper limit or node capacity if necessary.
`SHOW USER QUOTA` returns no quota rows after configuration	Confirm that `SET USER QUOTA` succeeded, the username is correct, `quota_enable` is enabled, and the DataNode is in the `Running` state.
`Used` or `MinGap` differs from expectations	User resource quotas are accounted for separately on each DataNode. Check each node using `NodeID`. For `disk_io`, `Used` and `MinGap` are always `-`.
Setting or deleting quotas for `root` reports `extraneous input 'root'` or fails	The `root` user is exempt from user resource quotas. Quotas cannot be set with `SET USER QUOTA` or deleted with `DELETE USER QUOTA` for this user.